janet

  **Janet** is a programming language for system scripting, expressive automation, and extending programs written in C or C++ with user scripting capabilities. Janet makes a good system scripting language, or a language to embed in other programs. It's like Lua and GNU Guile in that regard. It has more built-in functionality and a richer core language than Lua, but smaller than GNU Guile or Python. However, it is much easier to embed and port than Python or Guile. There is a REPL for trying out the language, as well as the ability to run script files. This client program is separate from the core runtime, so Janet can be embedded in other programs. Try Janet in your browser at .
## Examples See the examples directory for all provided example programs. ### Game of Life ``` … ``` ### TCP Echo Server ```janet # A simple TCP echo server using the built-in socket networking and event loop. (defn handler "Simple handler for connections." [stream] (defer (:close stream) (def id (gensym)) (def b @"") (print "Connection " id "!") (while (:read stream 1024 b) (printf " %v -> %v" id b) (:write stream b) (buffer/clear b)) (printf "Done %v!" id) (ev/sleep 0.5))) (net/server "127.0.0.1" "8000" handler) ``` ### Windows FFI Hello, World! ```janet # Use the FFI to popup a Windows message box - no C required (ffi/context "user32.dll") (ffi/defbind MessageBoxA :int [w :ptr text :string cap :string typ :int]) (MessageBoxA nil "Hello, World!" "Test" 0) ``` ## Language Features * 600+ functions and macros in the core library * Built-in socket networking, threading, subprocesses, and file system functions. * Parsing Expression Grammars (PEG) engine as a more robust Regex alternative * Macros and compile-time computation * Per-thread event loop for efficient IO (epoll/IOCP/kqueue) * First-class green threads (continuations) as well as OS threads * Erlang-style supervision trees that integrate with the event loop * First-class closures * Garbage collection * Distributed as janet.c and janet.h for embedding into a larger program. * Python-style generators (implemented as a plain macro) * Mutable and immutable arrays (array/tuple) * Mutable and immutable hashtables (table/struct) * Mutable and immutable strings (buffer/string) * Tail recursion * Interface with C functions and dynamically load plugins ("natives"). * Built-in C FFI for when the native bindings are too much work * REPL development with debugger and inspectable runtime ## Documentation * For a quick tutorial, see [the introduction](https://janet-lang.org/docs/index.html) for more details. * For the full API for all functions in the core library, see [the core API doc](https://janet-lang.org/api/index.html). Documentation is also available locally in the REPL. Use the `(doc symbol-name)` macro to get API documentation for symbols in the core library. For example, ``` (doc apply) ``` shows documentation for the `apply` function. To get a list of all bindings in the default environment, use the `(all-bindings)` function. You can also use the `(doc)` macro with no arguments if you are in the REPL to show bound symbols. ## Source You can get the source on [GitHub](https://github.com/janet-lang/janet) or [SourceHut](https://git.sr.ht/~bakpakin/janet). While the GitHub repo is the official repo, the SourceHut mirror is actively maintained. ## Spork and JPM Spork and JPM are two companion projects to Janet. They are optional, especially in an embedding use case. Spork is a collection of common utility modules, and several packaged scripts like `janet-format` for code formatting, `janet-netrepl` for a socket-based REPL, and `janet-pm` for a comprehensive Janet project manager tool. The modules in `spork` are less stable than the interfaces in core Janet, although we try to prevent breaking changes to existing modules, with a preference to add new modules and functions. Spork requires a C compiler to build and install various extenstion components such as miniz and JSON utilities. Many spork sub-modules, for example spork/path, are independent and can be manually vendored in programmer projects without fully installing spork. When install Spork, scripts will be installed to $JANET_PATH/bin/ on POSIX systems by default. This likely needs to be added to the path to use these scripts. JPM is the older, more opinionated, project manager tool, which has it's pros and cons. It does not require a C compiler to build and install, but is less flexible and is not receiving many changes and improvements going forward. It may also be harder to configure correctly on new systems. In that sense, it may be more stable. JPM will install to /usr/local/bin/ on posix systems by default, which may or may not be on your PATH. ## Building When building from source, for stability, please use the latest tagged release. For example, run `git checkout $(git describe --tags --abbrev=0)` after cloning but before building. For the latest development, build directly on the master branch. The master branch is not-necessarily stable as most Janet development happens directly on the master branch. ### macOS and Unix-like The Makefile is non-portable and requires GNU-flavored make. ```sh cd somewhere/my/projects/janet make make test make repl make install make install-spork-git # optional make install-jpm-git # optional ``` Find out more about the available make targets by running `make help`. ### Alpine Linux To build a statically-linked build of Janet, Alpine Linux + MUSL is a good combination. Janet can also be built inside a docker container or similar in this manner. This is a great way to try Janet without committing to a full install or needing to customize the default install. ```sh docker run -it --rm alpine /bin/ash $ apk add make gcc musl-dev git $ git clone https://github.com/janet-lang/janet.git $ cd janet $ make -j10 $ make test $ make install $ make install-spork-git # optional $ make install-jpm-git # optional ``` Note that for a true statically-linked binary with MUSL, one needs to add `-static` to the Makefile flags. This will also disable runtime loading of native modules (plugins) as well as the FFI. ### 32-bit Haiku 32-bit Haiku build instructions are the same as the UNIX-like build instructions, but you need to specify an alternative compiler, such as `gcc-x86`. ```sh cd somewhere/my/projects/janet make CC=gcc-x86 make test make repl make install make install-spork-git # optional make install-jpm-git # optional ``` ### FreeBSD FreeBSD build instructions are the same as the UNIX-like build instructions, but you need `gmake` to compile. Alternatively, install the package directly with `pkg install lang/janet`. ```sh cd somewhere/my/projects/janet gmake gmake test gmake repl gmake install gmake install-spork-git # optional gmake install-jpm-git # optional ``` ### NetBSD NetBSD build instructions are the same as the FreeBSD build instructions. Alternatively, install the package directly with `pkgin install janet`. ### illumos Building on illumos is exactly the same as building on FreeBSD. ### Windows 1. Install [Visual Studio](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=15#) or [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15#). 2. Run a Visual Studio Command Prompt (`cl.exe` and `link.exe` need to be on your PATH) and `cd` to the directory with Janet. 3. Run `build_win` to compile Janet. 4. Run `build_win test` to make sure everything is working. To build an `.msi` installer executable, in addition to the above steps, you will have to: 5. Install, or otherwise add to your PATH the [WiX 3.14 Toolset](https://github.com/wixtoolset/wix3/releases). 6. Run `build_win dist`. Now you should have an `.msi`. You can run `build_win install` to install the `.msi`, or execute the file itself. ### Meson Janet also has a build file for [Meson](https://mesonbuild.com/), a cross-platform build system. Although Meson has a Python dependency, Meson is a very complete build system that is maybe more convenient and flexible for integrating into existing pipelines. Meson also provides much better IDE integration than Make or batch files, as well as support for cross-compilation. For the impatient, building with Meson is as follows. The options provided to `meson setup` below emulate Janet's Makefile. ```sh git clone https://github.com/janet-lang/janet.git cd janet meson setup build \ --buildtype release \ --optimization 2 \ --libdir /usr/local/lib \ -Dgit_hash=$(git log --pretty=format:'%h' -n 1) ninja -C build # Run the binary build/janet # Installation ninja -C build install ``` ## Development Janet can be hacked on with pretty much any environment you like, but for IDE lovers, [Gnome Builder](https://wiki.gnome.org/Apps/Builder) is probably the best option, as it has excellent Meson integration. It also offers code completion for Janet's C API right out of the box, which is very useful for exploring. VSCode, Vim, Emacs, and Atom each have syntax packages for the Janet language, though. ## Installation If you just want to try out the language, you don't need to install anything. In this case you can also move the `janet` executable wherever you want on your system and run it. However, for a fuller setup, please see the [Introduction](https://janet-lang.org/docs/index.html) for more details. ## Usage A REPL is launched when the binary is invoked with no arguments. Pass the `-h` flag to display the usage information. Individual scripts can be run with `./janet myscript.janet`. If you are looking to explore, you can print a list of all available macros, functions, and constants by entering the command `(all-bindings)` into the REPL. ``` … ``` If installed, you can also run `man janet` to get usage information. ## Embedding Janet can be embedded in a host program very easily. The normal build will create a file `build/c/janet.c`, a C source code file that that contains the amalgamated source to Janet. This file, along with `src/include/janet.h` and `src/conf/janetconf.h`, can be dragged into any C project and compiled into it. Janet should be compiled with `-std=c99` on most compilers, and will need to be linked to the math library, `-lm`, and the dynamic linker, `-ldl`, if one wants to be able to load dynamic modules. If there is no need for dynamic modules, add the define `-DJANET_NO_DYNAMIC_MODULES` to the compiler options. See the [Embedding Section](https://janet-lang.org/capi/embedding.html) on the website for more information. ## Discussion Feel free to ask questions and join the discussion on the [Janet Zulip Instance](https://janet.zulipchat.com/) ## FAQ ### How fast is it? It is about the same speed as most interpreted languages without a JIT compiler. Tight, critical loops should probably be written in C or C++ . Programs tend to be a bit faster than they would be in a language like Python due to the discouragement of slow Object-Oriented abstraction with lots of hash-table lookups, and making late-binding explicit. All values are boxed in an 8-byte representation by default and allocated on the heap, with the exception of numbers, nils and booleans. The PEG engine is a specialized interpreter that can efficiently process string and buffer data. The GC is simple and stop-the-world, but GC knobs are exposed in the core library and separate threads have isolated heaps and garbage collectors. Data that is shared between threads is reference counted. YMMV. ### Where is (favorite feature from other language)? It may exist, it may not. If you want to propose a major language feature, go ahead and open an issue, but it will likely be closed as "will not implement". Often, such features make one usecase simpler at the expense of 5 others by making the langua