{"id":13610365,"url":"https://github.com/bamless/jstar","last_synced_at":"2026-04-09T12:18:47.382Z","repository":{"id":40796504,"uuid":"126866164","full_name":"bamless/jstar","owner":"bamless","description":"A lightweight embeddable scripting language","archived":false,"fork":false,"pushed_at":"2025-03-29T13:22:03.000Z","size":24638,"stargazers_count":119,"open_issues_count":2,"forks_count":9,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-30T02:09:09.710Z","etag":null,"topics":["bytecode-interpreter","c","c99","compiler","intepreter","interpreted-language","jstar","language-dynamic","programming-language","scripting-language","virtual-machine"],"latest_commit_sha":null,"homepage":"https://bamless.github.io/jstar/demo","language":"C","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/bamless.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}},"created_at":"2018-03-26T17:39:21.000Z","updated_at":"2025-03-29T13:22:08.000Z","dependencies_parsed_at":"2023-12-12T23:22:42.151Z","dependency_job_id":"8187c0a0-df70-44a6-a4c5-d46aab93fd90","html_url":"https://github.com/bamless/jstar","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamless%2Fjstar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamless%2Fjstar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamless%2Fjstar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamless%2Fjstar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bamless","download_url":"https://codeload.github.com/bamless/jstar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427012,"owners_count":20937214,"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":["bytecode-interpreter","c","c99","compiler","intepreter","interpreted-language","jstar","language-dynamic","programming-language","scripting-language","virtual-machine"],"created_at":"2024-08-01T19:01:44.026Z","updated_at":"2026-04-09T12:18:47.374Z","avatar_url":"https://github.com/bamless.png","language":"C","readme":"# J*: A Lightweight Embeddable Scripting Language\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://bamless.github.io/jstar/assets/images/jstar350.png\" alt=\"J* Programming Language\" title=\"J* Programming Language\"\u003e\n\u003c/p\u003e\n\n![linux-build](https://github.com/bamless/jstar/workflows/linux-build/badge.svg)\n![windows-build](https://github.com/bamless/jstar/workflows/windows-build/badge.svg)\n![macos-build](https://github.com/bamless/jstar/workflows/macos-build/badge.svg)\n\n**J\\*** is a dynamic embeddable scripting language designed to be as easy as possible to embed into\nanother program. It arises from the need of having a modern scripting language with built-in\nsupport for OOP whilst mantaning simplicity of use and a low memory footprint. It can be viewed as\na middle ground between Python, a more complete scripting language with lots of features and\nlibraries, and Lua, a small and compact language that is simple to embed but doesn't  provide OOP\nfunctionalities out of the box.\nJ* tries to take the best of both worlds, implementing a fully featured class system while\nmaintaining a small footprint and employing the use of a stack based API for communication\namong the language and host program, rendering embedding simple.\n\n**J\\*** is:\n - **Small**. The implementation spans only a handful of files and the memory footprint is low\n   thanks to a minimal standard library that provides only essential functionalities\n - **Easy to use**. The API is contained in a single header file and employs a stack based approach\n   similar to the one of Lua, freeing the user from the burden of keeping track of memory owned by\n   the language\n - **Fully object oriented**. Every entity, from numbers to class instances, is an object in **J\\***\n - **Modular**. A fully fledged module system makes it easy to split your code across multiple files\n - **Easily extensible**. The language can be easily extended by creating C functions callable from\n   **J\\*** using the API, or by importing [C extensions](https://github.com/bamless/jsocket)\n   provided as dynamic libraries.\n\nTo get a feel of the language, [try it in your browser](https://bamless.github.io/jstar/demo)!\n\n# The **jstar** command line interface\n\nBesides the language implementation, a simple command line interface called `jstar` is provided to\nstart using the language without embedding it into another program.\nIf the `jstar` binary is executed without\narguments it behaves like your usual read-eval-print loop, accepting a line at a time and executing\nit:\n```lua\nJ*\u003e\u003e var helloWorld = 'Hello, World!'\nJ*\u003e\u003e print(helloWorld)\nHello, World!\nJ*\u003e\u003e _\n```\nYou can even write multiline code, it will look like this:\n```lua\nJ*\u003e\u003e for var i = 0; i \u003c 3; i += 1\n....     print('Hello, World!')\n.... end\nHello, World!\nHello, World!\nHello, World!\nJ*\u003e\u003e _\n```\nWhen you eventually get bored, simply press Ctrl+d or Ctrl+c to exit the interpreter.\n\nIf you instead want to execute code written in some file, you can pass it as an argument to `jstar`.\nAll arguments after the first will be passed to the language as script arguments, you can then read\nthem from the script this way:\n```lua\nif #argv \u003e 0\n    print(\"First argument: \", argv[0])\nelse\n    raise Exception(\"No args provided\")\nend\n```\nThe `jstar` executable can also accept various options that modify the behaviour of the command line\napp. To see all of them alongside a description, simply pass the `-h` option to the executable.\n\nIn addition to being a useful tool to directly use the programming language, the command line\ninterface is also a good starting point to learn how **J\\*** can be embedded in a program, as it\nuses the API to implement all of its functionalities. You can find the code in\n[**apps/jstar/**](https://github.com/bamless/jstar/blob/master/apps/jstar/).\n\n# The **jstarc** compiler\nAnother application, called `jstarc`, is provided alongside the cli and the language runtime. As the\nname implies, this is a compiler that takes in **J\\*** source files, compiles them to bytecode\nand stores them on file.\n\nBelow is a typical usage of `jstarc`:\n```bash\njstarc src/file.jsr -o file.jsc\n```\nYou can even pass in a directory if you want to compile all `jsr` files contained in it:\n```bash\n# This compiles all *.jsr files in `dir` and stores them in a directory `out`\n# Both directories have to exist\n\njstarc dir/ -o out/\n```\n\nThe output `.jsc` files behave in the same way as normal `.jsr` source files. You can pass them\nto the `jstar` cli app to execute them and can be even imported by other **J\\*** files.\n\nCompiled files are not faster to execute than normal source files, as the **J\\*** vm will always\ncompile source to bytecote before execution, but have nonetheless some nice advantages:\n - **Compactness**. compiled files are more compact than source files and generally take up less\n   space\n - **Faster startup**. Reading a compiled file is orders of magnitude faster than parsing and\n   compiling source code, so there's almost no delay between importing and actual execution\n - **Obfuscation**. If you don't want your source to be viewed, compiled files are a nice option\n   since all the source and almost all debug information are stripped\n - **Platform indipendence**. Compiled files are cross-platform, just like normal source files. This\n   means that they can be compiled once and shared across all systems that have a J* interpreter.\n\n# Linting and IDE support\n\nCheck out the [Pulsar](https://github.com/bamless/pulsar) static analyzer for code linting and\nstatic analysis from the command line.\nCheck the [VSCode J* extension](https://marketplace.visualstudio.com/items?itemName=bamless.vsc-jstar-extension\u0026utm_source=VSCode.pro\u0026utm_campaign=AhmadAwais)\nfor linting and syntax highlighting support in VSCode.\n\n# Special thanks\nSpecial thanks to Bob Nystrom and the invaluable [crafting interpreters](https://craftinginterpreters.com/)\nbook, on which the VM is based.\n\nMy gratitude goes to the [Lua](http://www.lua.org/) project as well, for inspiring the stack-based\nC API and its amazing [pattern matching](https://www.lua.org/pil/20.2.html) library, on which the\n`re` module is based on.\nAlso, the [closures in Lua](https://www.cs.tufts.edu/~nr/cs257/archive/roberto-ierusalimschy/closures-draft.pdf)\nand [implementation of Lua 5](https://www.lua.org/doc/jucs05.pdf) articles were crucial for some\nparts of the implementation.\n\n# Building from source\n\nThe **J\\*** library requires a C99 compiler and CMake (\u003e= 3.9) to be built, and is known to compile\non OSX (Apple clang), Windows (both MSVC and MinGW-w64) and Linux (GCC, clang).\n\nTo build the provided **command line interface** `jstar`, a C++11 compiler is required as one of its\ndependencies is written in C++.\n\nYou can clone the latest **J\\*** sources using git:\n\n```bash\ngit clone --recurse-submodules https://github.com/bamless/jstar.git\n```\n\nAfter cloning, use CMake to generate build files for your build system of choice and build the `all`\ntarget to generate the language dynamic/static libraries and the command line interface. On\nUNIX-like systems this can be simply achieved by issuing this in the command line:\n\n```bash\ncd jstar; mkdir build; cd build; cmake ..; make -j\n```\n\nOnce the build process is complete, you can install **J\\*** by typing:\n\n```bash\nsudo make install\n```\n\nVarious CMake options are available to switch on or off certain functionalities of the interpreter:\n\n|    Option name       | Default | Description |\n| :------------------: | :-----: | :---------- |\n| JSTAR_NAN_TAGGING    |   ON    | Use the NaN tagging technique for storing the VM internal type. Decrases the memory footprint of the interpreter and increases speed |\n| JSTAR_COMPUTED_GOTOS |   ON    | Use computed gotos to implement the VM eval loop. Branch predictor friendly, increases performance. Not all compilers support computed gotos (MSVC for example), so if you're using one of them disable this option |\n|   JSTAR_INSTALL      |   ON    | Generate install targets for the chosen build system. Turn this off if including J* from another CMake project |\n|       JSTAR_SYS      |   ON    | Include the 'sys' module in the language |\n|       JSTAR_IO       |   ON    | Include the 'io' module in the language |\n|      JSTAR_MATH      |   ON    | Include the 'math' module in the language |\n|      JSTAR_DEBUG     |   ON    | Include the 'debug' module in the language |\n|       JSTAR_RE       |   ON    | Include the 're' module in the language |\n| JSTAR_DBG_PRINT_EXEC |   OFF   | Trace the execution of instructions of the virtual machine |\n| JSTAR_DBG_STRESS_GC  |   OFF   | Stress the garbage collector by calling it on every allocation |\n| JSTAR_DBG_PRINT_GC   |   OFF   | Trace the execution of the garbage collector |\n| JSTAR_INSTRUMENT     |   OFF   | Enable instrumentation timers scattered throughout the code. Running J* will then produce 3 json files importable from `chrome://tracing` to view a timeline of executed functions. Supported only when using the GCC compiler on POSIX systems |\n\n# Building without CMake\n\nOn unixes, an hand-written Makefile is also provided if you don't want to use cmake.  \nTo build a debug build using it:\n```sh\n    make -j\n    make install\n```\nFor a release build:\n```sh\n    # USE_LTO optionally enables link-time optimizations\n    RELEASE=1 USE_LTO=1 make -j\n    make install\n```\n\nTo configure the build using the options reported above, you can directly modify\n`./include/jstar/conf.h`\n\n# Binaries\n\nPrecompiled binaries are provided for Windows and Linux for every major release. You can find them\n[here](https://github.com/bamless/jstar/releases).\n","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbamless%2Fjstar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbamless%2Fjstar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbamless%2Fjstar/lists"}