{"id":31057089,"url":"https://github.com/itsmeforlua/inline-lua","last_synced_at":"2026-05-07T00:32:25.558Z","repository":{"id":306382671,"uuid":"1018736065","full_name":"ItsMeForLua/Inline-Lua","owner":"ItsMeForLua","description":" Perl extension for embedding Lua scripts into Perl code","archived":false,"fork":false,"pushed_at":"2025-07-25T07:27:28.000Z","size":134,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-25T11:56:22.521Z","etag":null,"topics":["cpan","inline","lua","perl"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ItsMeForLua.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-12T23:28:21.000Z","updated_at":"2025-07-25T05:04:28.000Z","dependencies_parsed_at":"2025-07-25T12:06:33.307Z","dependency_job_id":null,"html_url":"https://github.com/ItsMeForLua/Inline-Lua","commit_stats":null,"previous_names":["itsmeforlua/inline-lua"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ItsMeForLua/Inline-Lua","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsMeForLua%2FInline-Lua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsMeForLua%2FInline-Lua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsMeForLua%2FInline-Lua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsMeForLua%2FInline-Lua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ItsMeForLua","download_url":"https://codeload.github.com/ItsMeForLua/Inline-Lua/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsMeForLua%2FInline-Lua/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275219501,"owners_count":25425888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpan","inline","lua","perl"],"created_at":"2025-09-15T06:48:16.246Z","updated_at":"2026-05-07T00:32:25.488Z","avatar_url":"https://github.com/ItsMeForLua.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"=pod\n\n=encoding UTF-8\n\n=head1 NAME\n\nInline::Lua - Perl extension for embedding Lua scripts into Perl code\n\n=head1 VERSION\n\nversion 0.17\n\n=head1 SYNOPSIS\n\n    use Inline 'Lua';\n    print \"The answer to life, the universe and everything is \", answer(6, 7), \"\\n\";\n\n    __END__\n    __Lua__\n    function answer (a, b)\n\treturn a*b \n    end\n\n=head1 DESCRIPTION\n\nInline::Lua allows you to write functions in Lua. Those of you who are not yet\nfamiliar with Lua should have a cursory glance at L\u003chttp://www.lua.org/\u003e to get\na taste of this language. In short:\n\nLua was designed to be embedded into other applications and not so much as a\nlanguage on its own.  However, despite its small set of language features, it\nis an extremely powerful and expressive language. Its strong areas are an\nelegant and yet concise syntax, good overall performance and a beautiful\nimplementation of some concepts from the world of functional programming.\n\n=head1 USING Inline::Lua\n\nLua code can be included in the usual Inline style. Pass it as string at C\u003cuse\u003e time:\n\n    use Inline Lua =\u003e 'function pow (a, b) return a^b end';\n    print pow(2, 8);  # prints 256\n\nHeredocs may come in handy for that:\n\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function pow (a, b)\n\treturn a^b\n    end\n    EOLUA\n\n    print pow(2, 8);\n\nOr append it to your script after the C\u003c__END__\u003e token:\n\n    use Inline 'Lua';\n\n    print pow(2, 8)\n\n    __END__\n    __Lua__\n    function pow (a, b)\n\treturn a^b \n    end\n\nAll of those are equivalent.\n\n=head2 Exchanging values with Lua functions\n\nLua datatypes map exceptionally well onto Perl types and vice versa. Lua knows\nabout eight distinct types:\n\n=over 4\n\n=item * B\u003cnil\u003e\n\nThis is Perl's C\u003cundef\u003e\n\n=item * B\u003cnumber\u003e\n\nA Perl scalar with a, guess what, number in it.\n\n=item * B\u003cstring\u003e\n\nA Perl scalar with a string in it.\n\n=item * B\u003cfunction\u003e\n\nLua functions act as first class data types. The Perl equivalent is a\ncode-reference.\n\n=item * B\u003cuserdata\u003e\n\nLua being an embeddable language uses this one to handle generic C types. As of\nnow, this is not yet supported by Inline::Lua.\n\n=item * B\u003cthread\u003e\n\nUsed to implement coroutines. Not yet handled by Inline::Lua\n\n=item * B\u003ctable\u003e\n\nLua tables act as arrays or hashes depending on what you put into them.\nInline::Lua can handle that transparently.\n\n=back\n\n=head1 PASSING VALUES TO LUA FUNCTIONS\n\nWhenever you call a Lua function, Inline::Lua looks at the arguments you passed\nto the function and converts them accordingly before executing the Lua code. \n\n=head2 Plain Perl scalars\n\nScalars either holding a number, a string or C\u003cundef\u003e are converted to the\ncorresponding Lua types. Considering that those are all very basic types, this\nis not a very deep concept:\n\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function luaprint (a)\n\tio.write(a)\n    end\n    EOLUA\n    \n    lua_print(\"foobar\");\n    lua_print(42);\n\nCare must be taken with C\u003cundef\u003e. Lua is less forgiving than Perl in this\nrespect. In particular, C\u003cnil\u003e is not silently transformed into a useful value and\nyou'll get a fatal error from Lua when you try\n\n    lua_print(undef);\n\nInline::Lua offers some means to deal with this problem. See L\u003c\"DEALING WITH\nUNDEF AND NIL\"\u003e further below.\n\n=head2 Array and hash references\n\nThose are turned into Lua tables:\n\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function print_table (t)\n      for k, v in pairs(t) do\n        print(k, v)\n      end\n    end\n    EOLUA\n    \n    print_table( [1, 2, 3] );\n    print_table( { key1 =\u003e 'val1',\n                   key2 =\u003e 'val2' } );\n\nThis should print:\n\n    array:\n    1       1\n    2       2\n    3       3\n    hash:\n    key1    val1\n    key2    val2\n\nNested Perl arrays are handled as well:\n\n    print_table( [1, 2, 3, { key1 =\u003e 'val' } ] );\n\nwill result in\n\n    1       1\n    2       2\n    3       3\n    4       table: 0x8148128\n\n=head2 Function references\n\nThat's the real interesting stuff. You are allowed to call Lua functions with\nfunction references as arguments and the Lua code will do the right thing:\n\n    use Inline Lua =\u003e EOLUA\n    function table_foreach (func, tab)\n        for k, v in pairs(tab) do\n          func(k, v)\n        end\n    end\n    EOLUA\n\n    sub dump {\n        my ($key, $val) = @_;\n\tprint \"$key =\u003e $val\\n\";\n    }\n    \n    table_foreach( \\\u0026dump, { key1 =\u003e 1, key2 =\u003e 2 } );\n\nHere's a bit of currying. The Lua code calls the code-reference passed to it.\nThis code-reference itself returns a reference to a Perl functions which eventually\nis triggered by Lua and its result is printed:\n\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function lua_curry (f, a, b) \n\tlocal g = f(a)\n\tio.write( g(b) )\n\t-- or simply: io.write( f(a)(b) )\n    end\n    EOLUA\n\n    sub curry {\n\tmy $arg = shift;\n\treturn sub { return $arg * shift };\n    }\n\n    lua_curry( \\\u0026curry, 6, 7);\t# prints 42\n\nIt should be obvious that you are also allowed to pass references to anonymous functions, so\n\n    lua_curry( sub { my $arg = shift; ... }, 6, 7);\n\nwill work just as well.\n\n=head2 Filehandles\n\nFrom a technical point of view, Lua doesn't have a distinct type for that. It uses\nthe I\u003cuserdata\u003e type for it. If you pass a reference to a filehandle to your Lua \nfunction, Inline::Lua will turn it into the thingy that Lua can deal with:\n\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function dump_fh (fh)\n\tfor line in fh:lines() do\n\t    io.write(line, \"\\n\")\n\tend\n    end\n    EOLUA\n\n    open F, \"file\" or die $!;\n    dump_fh(\\*F);\n\n=head2 Things you must not pass to Lua\n\nYou must not pass a reference to a scalar to any Lua function. Lua doesn't know\nabout call-by-reference, hence trying it doesn't make much sense. You get a\nfatal runtime-error when you try for instance this:\n\n    function_defined_in_lua (\\$var);\n\n=head1 RETURNING VALUES FROM LUA FUNCTIONS\n\nReturning stuff from your inlined functions is as trivial as passing them into\nthem.\n\n=head2 Numbers, strings, nil and boolean values\n\nThose can be translated 1:1 into Perl:\n\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function return_basic ()\n\tlocal num = 42\n\tlocal str = \"twenty-four\"\n\tlocal boo = true\n\treturn num, str, boo, nil\n    end\n    EOLUA\n\n    my ($num, $str, $boo, $undef) = return_basic();\n\n=head2 Tables\n\nWhenever you return a Lua table, it gets returned as either a reference to a\nhash or a reference to an array. This depends on the values in the table. If all\nkeys are numbers, then an array-ref is returned. Otherwise a hash-ref:\n\n    use Data::Dumper;\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function return_tab () \n        local ary  = { 1, 2, 3, [5] = 5 }\n        local hash = { 1, 2, 3, key = 5 }\n        return ary, hash\n    end\n    EOLUA\n\n    my ($ary, $hash) = return_tab();\n    print Dumper $ary;\n    print Dumper $hash;\n\n    __END__\n    $VAR1 = [\n              '1',\n              '2',\n              '3',\n              undef,\n              '5'\n            ];\n    $VAR1 = {\n              '1' =\u003e '1',\n              '3' =\u003e '3',\n              '2' =\u003e '2',\n              'key' =\u003e 'val'\n            };\n\nA couple of things worthy mention: Lua table indexes start at 1 as opposed to 0\nin Perl. Inline::Lua will substract 1 from the index if the table is returned\nas an array so your Perl array will be 0-based. This does not happen for tables\nthat get returned as a hash-reference as you can see in the above example.\n\nAnother thing you have to be aware of is potential holes in the array. You can\ncreate a Lua table where only the, say, 10000th element is set. Since 10000 is\na number, it gets returned as an array. This array naturally will have 9999\nundefined elements. In this case it might be better to forcefully turn this key\ninto a string:\n\n    local ary = { [ tostring(10000) ] = 1 }\n\nThe tables you return can be arbitrarily deeply nested. The returned Perl\nstructure will then also be nested.\n\nWhat you cannot do is return a Lua table which uses values other than strings\nor numbers as keys. In Lua, a key can be any object, including a table, a\nfunction or whatever. There is no sensible way to mimick this behaviour in Perl\nso you will get a runtime error if you try something like this:\n\n    return { [{1, 2, 3}] = 1 }\n\nThere is no limitation on the values you put into a Lua table, though.\n\n=head2 Functions\n\nIf your Lua function returns a function, the function is turned into a Perl function\nreference. If you are tired of having Perl calulcate the n-th Fibonacci number, let \nLua do the hard work. This snippet below shows how a Lua function can return a Fibonacci\nnumber generator to Perl:\n\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function fib ()\n        local f\n        f = function (n)\n            if n \u003c 2 then return 1 end\n            return f(n-1) + f(n-2)\n        end\n        return f\n    end\n    EOLUA\n\n    my $fib = fib();\n    print $fib-\u003e(11);\n    __END__\n    144\n\nYou can get as fancy as you want. Return a Lua function that itself returns a\nLua function that returns another Lua function and so on. There should be no\nlimitations at all.\n\n=head2 Filehandles\n\nJust as you can pass filehandles to Lua functions, you may also return them:\n\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function open_file (filename)\n\treturn io.open(filename, \"r\")\n    end\n    EOLUA\n\n    my $fh = open_file(\".bashrc\");\n    while (\u003c$fh\u003e) {\n\t...\n    }\n\nIt's a fatal error if your Lua code tries to return a closed filehandle.\n\n=head1 DEALING WITH UNDEF AND NIL\n\nYou can change C\u003cundef\u003e's default conversion so that Inline::Lua wont transform it to C\u003cnil\u003e\nwhen passing the value to Lua:\n\n    use Inline Lua\t=\u003e 'DATA',\t# source code after the __END__ token\n\t       Undef\t=\u003e 0;\n\nWith the above, every C\u003cundef\u003e value is turned into a Lua number with the value 0. Likewise\n\n    use Inline Lua      =\u003e 'DATA', \n\t       Undef\t=\u003e '';\n\nThis will turn C\u003cundef\u003e into the empty string. Any valid Perl scalar can be\nspecified for I\u003cUndef\u003e, this includes references to hashes, arrays, functions\netc. A basic example:\n\n    use Inline Lua   =\u003e 'DATA',\n\t       Undef =\u003e 'Undefined value';\n    \n    print_values(1, 2, 3, undef, 4, 5);\n\n    __END__\n    __Lua__\n    function print_values (...)\n        for k, v in pairs {...} do\n            print(k, v)\n        end\n    end\n\nThis would come out as\n\n    1       1\n    2       2\n    3       3\n    4       Undefined value\n    5       5\n    6       6\n\nSometimes however it is important to return a real C\u003cnil\u003e to Lua.  Inline::Lua\nprovides a Perl value which is always converted to C\u003cnil\u003e:\nC\u003c$Inline::Lua::Nil\u003e.\n\n=head1 LUA FUNCTION PROTOTYPES\n\nLua functions have prototypes. When compiling those functions to bytecode,\nInline::Lua looks at their prototype. When calling one of those functions\nlater, it makes sure that the function arguments are padded with C\u003cundef\u003e if\nyou supply less arguments than mentioned in the prototype:\n\n    use Inline Lua =\u003e \u003c\u003cEOLUA;\n    function foo (a, b, c, ...)\n\tprint(a, b, c)\n    end\n    EOLUA\n\n    foo(1);\t# actually: foo(1, undef, undef)\n\nThose padded C\u003cundef\u003es are also handled accordingly to the value of I\u003cUndef\u003e.\nAlso note that C\u003c...\u003e in a prototype is never padded (as you can see in the above).\n\n=head1 LUA SCRIPTS AS INLINE CODE\n\nYou are allowed to provide whole Lua scripts in your Inline section. Anything outside\na function is then run at compile-time:\n\n    use Inline 'Lua';\n\n    __END__\n    __Lua__\n    print(1, 2)\n\nMoreover, Lua scripts may return values to their caller. You can get these values at\nany point with C\u003c\"Inline::Lua-\u003emain_returns\"\u003e:\n\n    use Inline 'Lua';\n\n    my @ret = Inline::Lua-\u003emain_returns;\n\n    __END__\n    __Lua__\n\n    print(\"I return a list of values\")\n    return 1, 2, 3\n\nNote that a Lua script's return value is only retrieved once at compile-time. Hence\nsomething like this might B\u003cnot\u003e do what you expect:\n\n    use Inline 'Lua';\n\n    print join \"+\", Inline::Lua-\u003emain_returns;\n    \n    luafunc();\n    \n    print \"\\n\";\n    print join \"+\", Inline::Lua-\u003emain_returns;\n\n    __END__\n    __Lua__\n    a = 1\n    b = 2\n    \n    function luafunc ()\n\ta = a + 1\n\tb = b + 1\n    end\n\n    return a, b\n\nThis will print\n\n    1+2\n    1+2\n\nand not\n\n    1+2\n    2+3\n\nas you might expect.\n\n=head1 BUGS\n\nThere must be some. My first suspicion is memory leaks that may hide somewhere in the code.\nChecking for memory leaks is on my agenda for the next release.\n\nOther than that, you might enjoy an occasional segfault.\n\nIf you encounter any of the above, please report it to me.\n\n=head1 TODO\n\n=over 4\n\n=item * Check for memory leaks.\n\n=item * Find a smart way to handle objects elegantly.\n\n=item * Look closer at the I\u003cthread\u003e type and figure out whether a sensible conversion exists.\n\n=item * Improve error messages. So far you get messages such as\n\n    Attempt to pass unsupported reference type (SCALAR) to Lua at (eval 3) line 6.\n\n=item * In general: Have Inline::Lua croak less often.\n\n=back\n\n=head1 FAQ\n\n=head2 What do I do if I want to sandbox my code?\n\nMany solutions exist for this, and determining which one to use depends on\nyour needs.  Please consult http://lua-users.org/wiki/SandBoxes for more\ninformation.\n\n=head1 SEE ALSO\n\nL\u003cInline\u003e\n\nLua's home can be found at L\u003chttp://www.lua.org/\u003e.\n\n=head1 AUTHOR\n\nRob Hoelz \u003crob@hoelz.ro\u003e\n\n=head1 COPYRIGHT AND LICENSE\n\nThis software is copyright (c) 2014 by Rob Hoelz.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n\n=head1 BUGS\n\nPlease report any bugs or feature requests on the bugtracker website\nL\u003chttps://github.com/hoelzro/inline-lua/issues\u003e\n\nWhen submitting a bug or request, please include a test-file or a\npatch to an existing test-file that illustrates the bug or desired\nfeature.\n\n=cut\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsmeforlua%2Finline-lua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsmeforlua%2Finline-lua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsmeforlua%2Finline-lua/lists"}