1
0
mirror of https://github.com/janet-lang/janet synced 2024-10-31 22:16:16 +00:00
janet/README.md

306 lines
12 KiB
Markdown
Raw Normal View History

2019-02-02 07:30:15 +00:00
[![Join the chat](https://badges.gitter.im/janet-language/community.svg)](https://gitter.im/janet-language/community)
 
2022-05-28 17:22:28 +00:00
[![builds.sr.ht status](https://builds.sr.ht/~bakpakin/janet/commits/master/freebsd.yml.svg)](https://builds.sr.ht/~bakpakin/janet/commits/master/freebsd.yml?)
[![builds.sr.ht status](https://builds.sr.ht/~bakpakin/janet/commits/master/openbsd.yml.svg)](https://builds.sr.ht/~bakpakin/janet/commits/master/openbsd.yml?)
[![Actions Status](https://github.com/janet-lang/janet/actions/workflows/test.yml/badge.svg)](https://github.com/janet-lang/janet/actions/workflows/test.yml)
2017-06-25 23:56:17 +00:00
2018-12-29 18:13:57 +00:00
<img src="https://raw.githubusercontent.com/janet-lang/janet/master/assets/janet-w200.png" alt="Janet logo" width=200 align="left">
2018-12-13 17:57:55 +00:00
**Janet** is a functional and imperative programming language and bytecode interpreter. It is a
lisp-like language, but lists are replaced
2020-03-14 01:00:32 +00:00
by other data structures (arrays, tables (hash table), struct (immutable hash table), tuples).
2019-02-17 19:00:15 +00:00
The language also supports bridging to native code written in C, meta-programming with macros, and bytecode assembly.
2017-04-25 22:22:43 +00:00
2020-10-26 13:44:17 +00:00
There is a REPL for trying out the language, as well as the ability
2017-04-25 22:22:43 +00:00
to run script files. This client program is separate from the core runtime, so
2020-10-26 13:44:17 +00:00
Janet can be embedded in other programs. Try Janet in your browser at
2018-10-23 17:54:55 +00:00
[https://janet-lang.org](https://janet-lang.org).
2017-04-25 22:22:43 +00:00
2021-04-01 01:27:03 +00:00
If you'd like to financially support the ongoing development of Janet, consider
[sponsoring its primary author](https://github.com/sponsors/bakpakin) through GitHub.
2021-04-01 01:27:03 +00:00
2019-03-31 22:15:28 +00:00
<br>
2018-09-06 02:18:42 +00:00
## Use Cases
2020-03-14 01:00:32 +00:00
Janet makes a good system scripting language, or a language to embed in other programs.
It's like Lua and Guile in that regard. It has more built-in functionality and a richer core language than
Lua, but smaller than GNU Guile or Python.
2018-09-06 02:18:42 +00:00
## Features
2021-09-28 02:20:06 +00:00
* Configurable at build time - turn features on or off for a smaller or more featureful build
2018-10-23 17:54:55 +00:00
* Minimal setup - one binary and you are good to go!
2020-10-26 13:44:17 +00:00
* First-class closures
* Garbage collection
2020-10-26 13:44:17 +00:00
* First-class green threads (continuations)
* 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)
* Macros
2021-09-28 02:20:06 +00:00
* Multithreading
* Per-thread event loop for efficient evented IO
* Byte code interpreter with an assembly interface, as well as bytecode verification
2020-10-26 13:44:17 +00:00
* Tail call Optimization
* Direct interop with C via abstract types and C functions
* Dynamically load C libraries
* Functional and imperative standard library
* Lexical scoping
2018-07-04 04:17:34 +00:00
* Imperative programming as well as functional
2018-01-29 20:46:26 +00:00
* REPL
2020-10-26 13:44:17 +00:00
* Parsing Expression Grammars built into the core library
2020-03-14 01:00:32 +00:00
* 400+ functions and macros in the core library
* Embedding Janet in other programs
2018-07-04 04:17:34 +00:00
* Interactive environment with detailed stack traces
2018-05-19 01:31:46 +00:00
2018-06-26 18:06:38 +00:00
## Documentation
2018-05-19 01:31:46 +00:00
2019-04-29 22:35:09 +00:00
* 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)
2020-10-26 13:44:17 +00:00
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,
2018-11-17 03:36:47 +00:00
```
(doc apply)
2018-11-17 03:36:47 +00:00
```
Shows documentation for the `apply` function.
2018-11-17 03:36:47 +00:00
To get a list of all bindings in the default
2020-03-07 15:49:25 +00:00
environment, use the `(all-bindings)` function. You
2020-10-26 13:44:17 +00:00
can also use the `(doc)` macro with no arguments if you are in the REPL
2020-03-07 15:49:25 +00:00
to show bound symbols.
2018-11-17 03:36:47 +00:00
## Source
You can get the source on [GitHub](https://github.com/janet-lang/janet) or
2019-05-01 15:06:20 +00:00
[SourceHut](https://git.sr.ht/~bakpakin/janet). While the GitHub repo is the official repo,
the SourceHut mirror is actively maintained.
## Building
2020-05-18 06:32:00 +00:00
### macOS and Unix-like
2019-06-30 14:57:49 +00:00
The Makefile is non-portable and requires GNU-flavored make.
```
cd somewhere/my/projects/janet
make
make test
make repl
make install
make install-jpm-git
```
2020-05-15 06:51:21 +00:00
Find out more about the available make targets by running `make help`.
2019-05-15 01:23:38 +00:00
### 32-bit Haiku
2020-10-26 13:44:17 +00:00
32-bit Haiku build instructions are the same as the UNIX-like build instructions,
2019-05-15 01:23:38 +00:00
but you need to specify an alternative compiler, such as `gcc-x86`.
```
cd somewhere/my/projects/janet
make CC=gcc-x86
make test
make repl
make install
make install-jpm-git
2019-05-15 01:23:38 +00:00
```
### FreeBSD
2020-10-26 13:44:17 +00:00
FreeBSD build instructions are the same as the UNIX-like build instructions,
but you need `gmake` to compile. Alternatively, install directly from
packages, using `pkg install lang/janet`.
```
cd somewhere/my/projects/janet
gmake
gmake test
gmake repl
gmake install
gmake install-jpm-git
```
### NetBSD
2020-10-26 13:44:17 +00:00
NetBSD build instructions are the same as the FreeBSD build instructions.
Alternatively, install directly from packages, using `pkgin install janet`.
### 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 the 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.
2020-05-23 12:15:19 +00:00
To build an `.msi` installer executable, in addition to the above steps, you will have to:
2020-05-22 21:53:31 +00:00
5. Install, or otherwise add to your PATH the [WiX 3.11 Toolset](https://github.com/wixtoolset/wix3/releases)
2020-05-23 12:15:19 +00:00
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.
2020-05-22 21:53:31 +00:00
### Meson
2020-10-26 13:44:17 +00:00
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
2019-06-30 14:57:49 +00:00
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
2020-10-26 13:44:17 +00:00
for cross-compilation.
2020-03-07 15:49:25 +00:00
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 \
2020-06-14 17:12:41 +00:00
--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
2019-12-15 21:41:58 +00:00
for Janet's C API right out of the box, which is very useful for exploring. VSCode, Vim,
Emacs, and Atom will have syntax packages for the Janet language, though.
## Installation
2021-04-08 07:10:24 +00:00
See the [Introduction](https://janet-lang.org/docs/index.html) for more details. If you just want
2020-03-07 15:49:25 +00:00
to try out the language, you don't need to install anything. You can also move the `janet` executable wherever you want on your system and run it.
2018-03-16 19:52:56 +00:00
## Usage
2020-10-26 13:44:17 +00:00
A REPL is launched when the binary is invoked with no arguments. Pass the -h flag
2018-09-06 02:18:42 +00:00
to display the usage information. Individual scripts can be run with `./janet myscript.janet`
2018-03-16 19:52:56 +00:00
2018-07-04 04:17:34 +00:00
If you are looking to explore, you can print a list of all available macros, functions, and constants
2020-10-26 13:44:17 +00:00
by entering the command `(all-bindings)` into the REPL.
2018-07-04 04:17:34 +00:00
2018-03-16 19:52:56 +00:00
```
2020-03-07 15:49:25 +00:00
$ janet
Janet 1.7.1-dev-951e10f Copyright (C) 2017-2020 Calvin Rose
2018-09-06 02:18:42 +00:00
janet:1:> (+ 1 2 3)
2018-03-16 19:52:56 +00:00
6
2018-09-06 02:18:42 +00:00
janet:2:> (print "Hello, World!")
2018-03-16 19:52:56 +00:00
Hello, World!
nil
2019-02-27 19:39:00 +00:00
janet:3:> (os/exit)
2020-03-07 15:49:25 +00:00
$ janet -h
usage: build/janet [options] script args...
2018-03-16 19:52:56 +00:00
Options are:
2020-03-07 15:49:25 +00:00
-h : Show this help
-v : Print the version string
-s : Use raw stdin instead of getline like functionality
-e code : Execute a string of janet
2020-10-26 13:44:17 +00:00
-r : Enter the REPL after running all scripts
-p : Keep on executing if there is a top-level error (persistent)
-q : Hide prompt, logo, and REPL output (quiet)
2020-03-07 15:49:25 +00:00
-k : Compile scripts but do not execute (flycheck)
-m syspath : Set system path for loading global modules
-c source output : Compile janet source code into an image
2020-10-26 13:44:17 +00:00
-n : Disable ANSI color output in the REPL
2020-03-07 15:49:25 +00:00
-l path : Execute code in a file before running the main script
-- : Stop handling options
2018-03-16 19:52:56 +00:00
```
If installed, you can also run `man janet` to get usage information.
## Embedding
2020-03-07 15:49:25 +00:00
Janet can be embedded in a host program very easily. The normal build
will create a file `build/janet.c`, which is a single C file
that contains all the 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 the project. 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.
2020-03-07 15:49:25 +00:00
See the [Embedding Section](https://janet-lang.org/capi/embedding.html) on the website for more information.
2018-03-18 19:05:31 +00:00
## Examples
2018-03-16 19:52:56 +00:00
2018-09-06 02:18:42 +00:00
See the examples directory for some example janet code.
2018-12-29 18:13:57 +00:00
2019-02-01 18:43:16 +00:00
## Discussion
2020-10-26 13:44:17 +00:00
Feel free to ask questions and join the discussion on the [Janet Gitter Channel](https://gitter.im/janet-language/community).
Gitter provides Matrix and irc bridges as well.
## FAQ
### Where is (favorite feature from other language)?
2018-12-29 18:13:57 +00:00
It may exist, it may not. If you want to propose major language features, go ahead and open an issue, but
they will likely by closed as "will not implement". Often, such features make one usecase simpler at the expense
of 5 others by making the language more complicated.
2021-09-28 02:20:06 +00:00
### Is there a language spec?
There is not currently a spec besides the documentation at https://janet-lang.org.
2021-09-28 02:20:06 +00:00
### Is this Scheme/Common Lisp? Where are the cons cells?
Nope. There are no cons cells here.
### Is this a Clojure port?
2021-11-14 19:19:04 +00:00
No. It's similar to Clojure superficially because I like Lisps and I like the aesthetics.
Internally, Janet is not at all like Clojure.
### Are the immutable data structures (tuples and structs) implemented as hash tries?
2018-12-29 18:20:13 +00:00
No. They are immutable arrays and hash tables. Don't try and use them like Clojure's vectors
and maps, instead they work well as table keys or other identifiers.
2021-09-28 02:20:06 +00:00
### Can I do Object Oriented programming with Janet?
To some extent, yes. However, it is not the recommended method of abstraction, and performance may suffer.
That said, tables can be used to make mutable objects with inheritance and polymorphism, where object
methods are implemeted with keywords.
```
(def Car @{:honk (fn [self msg] (print "car " self " goes " msg)) })
(def my-car (table/setproto @{} Car))
(:honk my-car "Beep!")
```
### Why can't we add (feature from Clojure) into the core?
Usually, one of a few reasons:
- Often, it already exists in a different form and the Clojure port would be redundant.
- Clojure programs often generate a lot of garbage and rely on the JVM to clean it up.
2021-09-28 02:20:06 +00:00
Janet does not run on the JVM, and has a more primitive garbage collector.
- We want to keep the Janet core small. With Lisps, usually a feature can be added as a library
2021-09-28 02:20:06 +00:00
without feeling "bolted on", especially when compared to ALGOL like languages. Adding features
2022-03-12 22:54:44 +00:00
to the core also makes it a bit more difficult to keep Janet maximally portable.
2021-09-28 02:20:06 +00:00
### Why is my terminal spitting out junk when I run the REPL?
Make sure your terminal supports ANSI escape codes. Most modern terminals will
support these, but some older terminals, Windows consoles, or embedded terminals
will not. If your terminal does not support ANSI escape codes, run the REPL with
the `-n` flag, which disables color output. You can also try the `-s` if further issues
ensue.
## Why is it called "Janet"?
Janet is named after the almost omniscient and friendly artificial being in [The Good Place](https://en.wikipedia.org/wiki/The_Good_Place).