{"id":13739594,"url":"https://github.com/ikskuh/LoLa","last_synced_at":"2025-05-08T19:34:49.884Z","repository":{"id":44925814,"uuid":"197437910","full_name":"ikskuh/LoLa","owner":"ikskuh","description":"LoLa is a small programming language meant to be embedded into games.","archived":false,"fork":false,"pushed_at":"2024-07-03T13:56:05.000Z","size":13508,"stargazers_count":192,"open_issues_count":14,"forks_count":10,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-11-12T04:34:42.784Z","etag":null,"topics":["compiler","interpreter","language","lola-language","programming-language","script-language","zig","zig-package"],"latest_commit_sha":null,"homepage":"https://lola.random-projects.net/","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ikskuh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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},"funding":{"github":"MasterQ32"}},"created_at":"2019-07-17T17:56:20.000Z","updated_at":"2024-10-29T18:21:24.000Z","dependencies_parsed_at":"2023-02-09T10:46:09.709Z","dependency_job_id":"8bd27de0-c053-445d-a3fb-39788e6ab966","html_url":"https://github.com/ikskuh/LoLa","commit_stats":null,"previous_names":["ikskuh/lola"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikskuh%2FLoLa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikskuh%2FLoLa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikskuh%2FLoLa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikskuh%2FLoLa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ikskuh","download_url":"https://codeload.github.com/ikskuh/LoLa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224758192,"owners_count":17364969,"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":["compiler","interpreter","language","lola-language","programming-language","script-language","zig","zig-package"],"created_at":"2024-08-03T04:00:35.608Z","updated_at":"2024-11-15T09:30:43.473Z","avatar_url":"https://github.com/ikskuh.png","language":"Zig","funding_links":["https://github.com/sponsors/MasterQ32"],"categories":["Applications"],"sub_categories":[],"readme":"# LoLa Programming Language\n\n![LoLa Logo](design/logo.png)\n\nLoLa is a small programming language meant to be embedded into games to be programmed by the players. The compiler and runtime are implemented in Zig and C++.\n\n## Short Example\n```js\nvar list = [ \"Hello\", \"World\" ];\nfor(text in list) {\n\tPrint(text);\n}\n```\n\nYou can find more examples in the [examples](examples/lola) folder.\n\n## Why LoLa when there is *X*?\nLoLa isn't meant to be your next best day-to-day scripting language. Its design is focused on embedding the language in environments where the users want/need/should write some small scripts like games or scriptable applications. In most script languages, you as a script host don't have control over the execution time of the scripts you're executing. LoLa protects you against programming errors like endless loops and such:\n\n### Controlled Execution Environment\n\nEvery script invocation gets a limit of instructions it might execute. When either this limit is reached or the script yields for other reasons (asynchronous functions), the execution is returned to the host.\n\nThis means, you can execute the following script \"in parallel\" to your application main loop without blocking your application *and* without requiring complex multithreading setups:\n\n```js\nvar timer = 0;\nwhile(true) {\n\tPrint(\"Script running for \", timer, \" seconds.\");\n\ttimer += 1;\n\tSleep(1.0);\n}\n```\n\n### Native Asynchronous Design\n\nLoLa features both synchronous and asynchronous host functions. Synchronous host function calls are short-lived and will be executed in-place. Asynchronous functions, in contrast, will be executed multiple times until they yield a value. When they don't yield a value, control will be returned to the script host.\n\nThis script will not exhaust the instruction limit, but will only increment the counter, then return control back to the host:\n```js\nvar counter = 0;\nwhile(true) {\n\tcounter += 1;\n\tYield();\n}\n```\n\nThis behaviour can be utilized to wait for certain events in the host environment, for example to react to key presses, a script could look like this:\n```js\nwhile(true) {\n\tvar input = WaitForKey();\n\tif(input == \" \") {\n\t\tPrint(\"Space was pressed!\");\n\t}\n}\n```\n\n*Note that the current implementation is not thread-safe, but requires to use the limited execution for running scripts in parallel.*\n\n### Native \"RPC\" Design\n\nLoLa also allows executing multiple scripts on the same *environment*, meaning that you can easily create cross-script communications:\n\n```js\n// script a:\nvar buffer;\nfunction Set(val) { buffer = val; }\nfunction Get() { return val; }\n\n// script b:\n// GetBuffer() returns a object referencing a environment for \"script a\"\nvar buffer = GetBuffer();\nbuffer.Set(\"Hello, World!\");\n\n// script c:\n// GetBuffer() returns a object referencing a environment for \"script a\"\nvar buffer = GetBuffer(); \nPrint(\"Buffer contains: \", buffer.Get());\n```\n\nWith a fitting network stack and library, this can even be utilized cross-computer.\n\nThis example implements a small chat client and server that could work with LoLa RPC capabilities:\n```js\n// Chat client implementation:\nvar server = Connect(\"lola-rpc://random-projects.net/chat\");\nif(server == void) {\n\tPrint(\"Could not connect to chat server!\");\n\tExit(1);\n}\n\nwhile(true) {\n\tvar list = server.GetMessages(GetUser());\n\tfor(msg in list) {\n\t\tPrint(\"\u003c \", msg);\n\t}\n\t\n\tPrint(\"\u003e \");\n\tvar msg = ReadLine();\n\tif(msg == void)\n\t\tbreak;\n\tif(msg == \"\")\n\t\tcontinue;\n\tserver.Send(GetUser(), msg);\n}\n```\n\n```js\n// Chat server implementation\nvar messages = CreateDictionary();\n\nfunction Send(user, msg)\n{\n\tfor(other in messages.GetKeys())\n\t{\n\t\tif(other != user) {\n\t\t\tvar log = messages.Get(other);\n\t\t\tif(log != void) {\n\t\t\t\tlog = log ++ [ user + \": \" + msg ];\n\t\t\t} else {\n\t\t\t\tlog = [];\n\t\t\t}\n\t\t\tmessages.Set(other, log);\n\t\t}\n\t}\n}\n\nfunction GetMessages(user)\n{\n\tvar log = messages.Get(user);\n\tif(log != void) {\n\t\tmessages.Set(user, []);\n\t\treturn log;\n\t} else {\n\t\treturn [];\n\t}\n}\n```\n\n### Serializable State\n\nAs LoLa has no reference semantics except for objects, it is easy to understand and learn. It is also simple in its implementation and does not require a complex garbage collector or advanced programming knowledge. Each LoLa value can be serialized/deserialized into a sequence of bytes (only exception are object handles, those require some special attention), so saving the current state of a environment/vm to disk and loading it at a later point is a first-class supported use case.\n\nThis is especially useful for games where it is favourable to save your script state into a save game as well without having any drawbacks.\n\n### Simple Error Handling\n\nLoLa provides little to no in-language error handling, as it's not designed to be robust against user programming errors. Each error is passed to the host as a panic, so it can show the user that there was an error (like `OutOfMemory` or `TypeMismatch`).\n\nIn-language error handling is based on the dynamic typing: Functions that allow in-language error handling just return `void` instead of a actual return value or `true`/`false` for *success* or *failure*. \n\nThis allows simple error checking like this:\n```js\nvar string = ReadFile(\"demo.data\");\nif(string != void) {\n\tPrint(\"File contained \", string);\n}\n```\n\nThis design decision was made with the idea in mind that most LoLa programmers won't write the next best security critical software, but just do a quick hack in game to reach their next item unlock.\n\n### Smart compiler\n\nAs LoLa isn't the most complex language, the compiler can support the programmer. Even though the language has fully dynamic typing, the compiler can do some type checking at compile time already:\n\n```js\n// warning: Possible type mismatch detected: Expected number|string|array, found boolean\nif(a \u003c true) { }\n```\n\nRight now, this is only used for validating expressions, but it is planned to extend this behaviour to annotate variables as well, so even more type errors can be found during compile time.\n\nNote that this is a fairly new feature, it does not catch all your type mismatches, but can prevent the obvious ones.\n\n## Starting Points\n\nTo get familiar with LoLa, you can check out these starting points:\n\n- [Documentation](documentation/README.md)\n- [LoLa Examples](examples/lola/README.md)\n- [Script Host Examples](examples/host)\n\nWhen you want to contribute to the compiler, check out the following documents:\n\n- [Source Code](src/)\n- [Bison Grammar](src/library/compiler/grammar.yy)\n- [Flex Tokenizer](src/library/compiler/yy.l)\n- [Issue List](https://github.com/MasterQ32/LoLa/issues)\n\n## Visual Studio Code Extension\nIf you want syntax highlighting in VSCode, you can install the [`lola-vscode`](https://github.com/MasterQ32/lola-vscode) extension.\n\nRight now, it's not published in the gallery, so to install the extension, you have to sideload it. [See the VSCode documentation for this](https://vscode-docs.readthedocs.io/en/stable/extensions/install-extension/).\n\n## Building\n\n### Continous Integration\n\n[![Build](https://github.com/MasterQ32/LoLa/actions/workflows/build.yml/badge.svg)](https://github.com/MasterQ32/LoLa/actions/workflows/build.yml) [![Render Website](https://github.com/MasterQ32/LoLa/actions/workflows/website.yml/badge.svg)](https://github.com/MasterQ32/LoLa/actions/workflows/website.yml)\n\n### Requirements\n\n- The [Zig Compiler](https://ziglang.org/) (Version 0.12.0-dev.3438+5c628312b or newer)\n\n### Building\n\n```sh\nzig build\n./zig-cache/bin/lola\n```\n\n### Examples\n\nTo compile the host examples, you can use `zig build examples` to build all provided examples. These will be available in `./zig-cache/bin` then.\n\n### Running the test suite\n\nWhen you change things in the compiler or VM implementation, run the test suite:\n\n```sh\nzig build test\n```\n\nThis will execute all zig tests, and also runs a set of predefined tests within the [`src/test/`](src/test/) folder. These tests will verify that the compiler and language runtime behave correctly.\n\n### Building the website\n\nThe website generator is gated behind `-Denable-website` which removes a lot of dependencies for people not wanting to render a new version of the website.\nIf you still want to update/change the website or documentation, use the following command:\n\n```sh\nzig build -Denable-website \"-Dversion=$(git describe --tags || git rev-parse --short HEAD)\" website\n```\n\nIt will depend on [koino](https://github.com/kivikakk/koino), which is included as a git submodule. Adding new pages to the documentation is done by modifying the `menu_items` array in `src/tools/render-md-page.zig`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikskuh%2FLoLa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fikskuh%2FLoLa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikskuh%2FLoLa/lists"}