{"id":16923477,"url":"https://github.com/kroepke/luna","last_synced_at":"2025-04-11T17:05:49.997Z","repository":{"id":57739095,"uuid":"92990268","full_name":"kroepke/luna","owner":"kroepke","description":"Lua 5.3 implementation for the JVM","archived":false,"fork":false,"pushed_at":"2017-07-27T16:07:05.000Z","size":3853,"stargazers_count":22,"open_issues_count":1,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-04T01:35:10.795Z","etag":null,"topics":["jvm-languages","lua","lua53","scripting"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kroepke.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-31T21:28:39.000Z","updated_at":"2024-11-06T03:38:57.000Z","dependencies_parsed_at":"2022-08-24T17:40:19.471Z","dependency_job_id":null,"html_url":"https://github.com/kroepke/luna","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kroepke%2Fluna","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kroepke%2Fluna/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kroepke%2Fluna/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kroepke%2Fluna/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kroepke","download_url":"https://codeload.github.com/kroepke/luna/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239731628,"owners_count":19687868,"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","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":["jvm-languages","lua","lua53","scripting"],"created_at":"2024-10-13T19:59:13.521Z","updated_at":"2025-02-19T20:31:22.597Z","avatar_url":"https://github.com/kroepke.png","language":"Java","readme":"[![Build Status](https://travis-ci.org/kroepke/luna.svg?branch=master)](https://travis-ci.org/kroepke/luna)\n[![Runtime Javadocs](https://javadoc.io/badge/org.classdump.luna/luna-runtime.svg?label=Runtime-Javadocs)](https://javadoc.io/doc/org.classdump.luna/luna-runtime)\n[![Stdlib Javadocs](https://javadoc.io/badge/org.classdump.luna/luna-stdlib.svg?label=Stdlib-Javadocs)](https://javadoc.io/doc/org.classdump.luna/luna-stdlib)\n[![Javadocs](https://javadoc.io/badge/org.classdump.luna/luna-compiler.svg?label=Compiler-Javadocs)](https://javadoc.io/doc/org.classdump.luna/luna-compiler)\n\n\n# Luna\n\n(*Luna* is Spanish for *Moon*.)\n\n## About\n\nLuna is an implementation of Lua 5.3 for the Java Virtual Machine (JVM), written in\npure Java with minimal dependencies.\nThe goal of the Luna project is to develop a correct, complete and scalable Lua\nimplementation for running sandboxed Lua programs on the JVM.\n\nLuna implements Lua 5.3 as specified by the\n[Lua Reference Manual](http://www.lua.org/manual/5.3/manual.html), explicitly attempting to mimic\nthe behaviour of PUC-Lua whenever possible. This includes language-level features (such\nas metamethods and coroutines) and the standard library.\n\n## Credits\n\nLuna is a fork of [Rembulan](https://github.com/mjanicek/rembulan) created by Miroslav Janíček.\nSadly his excellent project seems to be abandoned and is also not published on Maven Central.\n\nIn order to make Lua 5.3 useful in JVM projects, I decided to fork and publish the project\nso that his great work does not get lost.\n\n## Status\n\nThe majority of language-level features is implemented, and may be expected\nto work. If you find behaviour that does not conform to Lua 5.3 as defined by the Lua Reference\nManual, please [open a new issue](https://github.com/kroepke/luna/issues).\n\nSee also the [completeness table](doc/CompletenessTable.md) that maps out the current\ncompleteness status of Luna with regard to PUC-Lua, in particular the standard library.\n\n## Frequently asked questions (FAQ)\n\n#### What is Luna good for?\n\nLua is a small, beautifully-designed and simple-yet-powerful programming language.\nLua has been traditionally used as an embedded scripting language. Luna aims to serve\na similar purpose on the JVM, with an explicit focus on sandboxing the client Lua programs.\n\nThere are two main use-cases for Luna: running untrusted Lua scripts on the JVM,\nand enhancing Java applications by adding the ability to script them with Lua.\n\n#### Does Luna implement the Lua C API?\n\nNo, at this point Luna requires libraries to be written against its Java interface.\n \n#### Does Luna work with Lua bytecode?\n\nNo. The Lua bytecode (i.e., the bytecode generated by PUC-Lua's `luac`) is considered\nan implementation detail by both Luna and the Lua Reference Manual. Luna implements\nits own compiler and compiles to Java bytecode directly. It uses its own\nintermediate representation (IR) annotated with statically-inferred type information,\nbut does not expose it to the user, and the IR has no serialisable form.\n \nFor more information about the Luna compiler, see the [compiler overview](doc/CompilerOverview.md). \n \n#### How are coroutines implemented?\n \nSee [How are coroutines implemented?](doc/CoroutinesOverview.md)  \n\n## Using Luna\n\nLuna requires a Java Runtime Environment (JRE) version 8 or higher.\n\n### Documentation\n\nGenerated JavaDocs are available online:\n\n * [![Runtime Javadocs](https://javadoc.io/badge/org.classdump.luna/luna-runtime.svg?label=Runtime-Javadocs)](https://javadoc.io/doc/org.classdump.luna/luna-runtime)\n * [![Stdlib Javadocs](https://javadoc.io/badge/org.classdump.luna/luna-stdlib.svg?label=Stdlib-Javadocs)](https://javadoc.io/doc/org.classdump.luna/luna-stdlib)\n * [![Javadocs](https://javadoc.io/badge/org.classdump.luna/luna-compiler.svg?label=Compiler-Javadocs)](https://javadoc.io/doc/org.classdump.luna/luna-compiler)\n \nThere are also a few short texts in the `doc` folder:\n\n * [How are coroutines implemented?](doc/CoroutinesOverview.md)\n * [Overview of the Luna compiler](doc/CompilerOverview.md)\n * [Luna completeness table](doc/CompletenessTable.md)\n\n### Building from source\n\nTo build Luna, you will need the following:\n\n * Java Development Kit (JDK) version 8 or higher\n * Maven version 3 or higher\n\nMaven will pull in the remaining dependencies as part of the build process.\n\nTo fetch the latest code on the `master` branch and build it, run\n\n```sh\ngit clone https://github.com/kroepke/luna.git\ncd luna    \nmvn install\n```\n\nThis will build all modules, run tests and finally install all artifacts into your local\nMaven repository.    \n\n#### Standalone REPL\n\nMuch like PUC-Lua, Luna contains a standalone REPL. This is provided in the module\n`luna-standalone`. To build the REPL, run\n\n```sh\nmvn package -DskipTests -Dmaven.javadoc.skip=true -DstandaloneFinalName=luna\n```\n\nThe standalone REPL is packaged as a self-contained, executable [Capsule](http://www.capsule.io)\nand is placed in the directory `luna-standalone/target`.\n \nTo run the REPL:\n\n```sh\ncd luna-standalone/target\n./luna-capsule.x\n```\n\nThe standalone REPL mimics the behaviour or the standalone PUC-Lua interpreter and may be\nused as its drop-in replacement.\n\n```\n$ ./luna-capsule.x\nLuna 0.3-SNAPSHOT (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_60)\n\u003e print(\"hello world!\")\nhello world!\n```\n\n### Using Luna from Maven\n\n[![Maven Central](https://img.shields.io/maven-central/v/org.classdump.luna/luna-all-shaded.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.classdump.luna%22)\n\nRelease are published to [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.classdump.luna%22).\n\nTypically, if you plan to embed Luna, the safest way of doing so is to use the **luna-all-shaded** module. It renames\nthe ASM library, which is often required by other projects in incompatible versions, leading to problems.\nThis module combines **runtime**, **compiler** and **stdlib**, because those are all typically required.\n\nTo include the **luna-all-shaded** as a dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.classdump.luna\u003c/groupId\u003e\n  \u003cartifactId\u003eluna-all-shaded\u003c/artifactId\u003e\n  \u003cversion\u003e0.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\nTo include the **runtime** as a dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.classdump.luna\u003c/groupId\u003e\n  \u003cartifactId\u003eluna-runtime\u003c/artifactId\u003e\n  \u003cversion\u003e0.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nTo include the **compiler** as a dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.classdump.luna\u003c/groupId\u003e\n  \u003cartifactId\u003eluna-compiler\u003c/artifactId\u003e\n  \u003cversion\u003e0.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nTo include the **standard library** as a dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.classdump.luna\u003c/groupId\u003e\n  \u003cartifactId\u003eluna-stdlib\u003c/artifactId\u003e\n  \u003cversion\u003e0.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nNote that `luna-compiler` and `luna-stdlib` both pull in `luna-runtime` as\na dependency, but are otherwise independent. (I.e., to use the compiler and the standard\nlibrary, you need to declare both `-compiler` and `-stdlib` as dependencies, but do not need\nto include `-runtime`).\n\n## Getting started\n\nLuna compiles Lua functions into Java classes and loads them into the JVM;\nthe compiler performs a type analysis of the Lua programs in order to generate a more\ntightly-typed code whenever feasible.\n\nSince the JVM does not directly support coroutines, Luna treats Lua functions as state\nmachines and controls their execution (i.e., yields, resumes and pauses) using exceptions.\nSince the Luna runtime retains control of the control state, this technique is also used\nto implement CPU accounting and scheduling of asynchronous operations.\n\n#### Example: Hello world  \n\nThe following snippet loads the Lua program `print('hello world!')`, compiles it, loads\nit into a (non-sandboxed) state, and runs it:\n\n(From [`luna-examples/.../HelloWorld.java`](luna-examples/src/main/java/org/classdump/luna/examples/HelloWorld.java))\n\n```java\npublic class Main {\n    public static void main(String[] args) {\n  \n        String program = \"print('hello world!')\";\n    \n        // initialise state\n        StateContext state = StateContexts.newDefaultInstance();\n        Table env = StandardLibrary.in(RuntimeEnvironments.system()).installInto(state);\n        \n        // compile\n        ChunkLoader loader = CompilerChunkLoader.of(\"hello_world\");\n        LuaFunction main = loader.loadTextChunk(new Variable(env), \"hello\", program);\n        \n        // execute\n        DirectCallExecutor.newExecutor().call(state, main);\n    }\n}\n```\n\nThe output (printed to `System.out`) is:\n\n```\nhello world!\n```\n\n#### Example: CPU accounting\n\nLua functions can be called in a mode that automatically pauses their execution once the\ngiven number of operations has been performed:\n\n(From [`luna-examples/.../InfiniteLoop.java`](luna-examples/src/main/java/org/classdump/luna/examples/InfiniteLoop.java))\n\n```java\npublic class Main {\n    public static void main(String[] args) {\n\n        String program = \"n = 0; while true do n = n + 1 end\";\n        \n        // initialise state\n        StateContext state = StateContexts.newDefaultInstance();\n        Table env = StandardLibrary.in(RuntimeEnvironments.system()).installInto(state);\n        \n        // compile\n        ChunkLoader loader = CompilerChunkLoader.of(\"infinite_loop\");\n        LuaFunction main = loader.loadTextChunk(new Variable(env), \"loop\", program);\n        \n        // execute at most one million ops\n        DirectCallExecutor executor = DirectCallExecutor.newExecutorWithTickLimit(1000000);\n        \n        try {\n            executor.call(state, main);\n            throw new AssertionError();  // never reaches this point!\n        }\n        catch (CallPausedException ex) {\n            System.out.println(\"n = \" + env.rawget(\"n\"));\n        }\n    }\n}\n```\n\nPrints:\n\n```\nn = 199999\n```\n\nThe [`CallPausedException`](https://static.javadoc.io/org.classdump.luna/luna-runtime/0.2/org/classdump/luna/exec/Continuation.html) contains a *continuation* of the call. The call can be resumed:\nthe pause is transparent to the Lua code, and the loop does not end with an error (it is merely\npaused).\n\n#### Further examples\n\nFor further examples, see the classes in\n[`luna-examples/src/main/java/org/classdump/luna/examples`](luna-examples/src/main/java/org/classdump/luna/examples).\n\n### Project structure\n\nLuna is a multi-module Maven build, consisting of the following modules that are deployed\nto Sonatype OSSRH:\n\n * `luna-runtime` ... the core classes and runtime;\n * `luna-compiler` ... a compiler of Lua sources to Java bytecode;\n * `luna-stdlib` ... the Lua standard library;\n * `luna-standalone` ... standalone REPL, a (mostly) drop-in replacement\n                             for the `lua` command from PUC-Lua.\n\nThere are also auxiliary modules that are not deployed:\n\n * `luna-tests` ... project test suite, including benchmarks from\n                        the Benchmarks Game;\n * `luna-examples` ... examples of the Luna API.                       \n\n\n## Contributing\n\nContributions of all kinds are welcome!\n\n\n## License\n\nLuna is licensed under the Apache License Version 2.0. See the file\n[LICENSE.txt](LICENSE.txt) for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkroepke%2Fluna","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkroepke%2Fluna","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkroepke%2Fluna/lists"}