2018-09-06 02:18:42 +00:00
|
|
|
# janet
|
2017-02-09 20:02:59 +00:00
|
|
|
|
2018-09-06 02:18:42 +00:00
|
|
|
[![Build Status](https://travis-ci.org/bakpakin/janet.svg?branch=master)](https://travis-ci.org/bakpakin/janet)
|
|
|
|
[![Appveyor Status](https://ci.appveyor.com/api/projects/status/32r7s2skrgm9ubva?svg=true)](https://ci.appveyor.com/project/bakpakin/janet)
|
2017-06-25 23:56:17 +00:00
|
|
|
|
2018-09-06 02:18:42 +00:00
|
|
|
Janet is a functional and imperative programming language and bytecode interpreter. It is a
|
2018-05-19 01:31:46 +00:00
|
|
|
modern lisp, but lists are replaced
|
2018-02-06 06:25:48 +00:00
|
|
|
by other data structures with better utility and performance (arrays, tables, structs, tuples).
|
2018-10-23 17:54:55 +00:00
|
|
|
The language also bridging bridging to native code written in C, meta-programming with macros, and bytecode assembly.
|
2017-04-25 22:22:43 +00:00
|
|
|
|
2017-07-02 02:46:56 +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
|
2018-10-23 17:54:55 +00:00
|
|
|
janet could be embedded into other programs. Try janet in your browser at
|
|
|
|
[https://janet-lang.org](https://janet-lang.org).
|
2017-04-25 22:22:43 +00:00
|
|
|
|
2018-09-06 02:18:42 +00:00
|
|
|
Implemented in mostly standard C99, janet runs on Windows, Linux and macOS.
|
2018-02-06 06:25:48 +00:00
|
|
|
The few features that are not standard C (dynamic library loading, compiler specific optimizations),
|
2018-09-06 02:18:42 +00:00
|
|
|
are fairly straight forward. Janet can be easily ported to new platforms.
|
2018-02-06 06:25:48 +00:00
|
|
|
|
2018-09-06 02:18:42 +00:00
|
|
|
For syntax highlighting, there is some preliminary vim syntax highlighting in [janet.vim](https://github.com/bakpakin/janet.vim).
|
2018-07-04 04:17:34 +00:00
|
|
|
Generic lisp syntax highlighting should, however, provide good results.
|
2018-05-19 01:31:46 +00:00
|
|
|
|
2018-09-06 02:18:42 +00:00
|
|
|
## Use Cases
|
|
|
|
|
|
|
|
Janet makes a good system scripting language, or a language to embed in other programs. Think Lua or Guile.
|
|
|
|
|
2018-01-12 15:41:27 +00:00
|
|
|
## Features
|
|
|
|
|
2018-10-23 17:54:55 +00:00
|
|
|
* Minimal setup - one binary and you are good to go!
|
2018-01-24 22:59:00 +00:00
|
|
|
* First class closures
|
|
|
|
* Garbage collection
|
|
|
|
* First class green threads (continuations)
|
|
|
|
* Mutable and immutable arrays (array/tuple)
|
|
|
|
* Mutable and immutable hashtables (table/struct)
|
|
|
|
* Mutable and immutable strings (buffer/string)
|
2018-07-04 04:17:34 +00:00
|
|
|
* Lisp Macros
|
2018-01-24 22:59:00 +00:00
|
|
|
* Byte code interpreter with an assembly interface, as well as bytecode verification
|
2018-10-23 17:54:55 +00:00
|
|
|
* Tailcall Optimization
|
2018-01-27 20:15:09 +00:00
|
|
|
* Direct interop with C via abstract types and C functions
|
|
|
|
* Dynamically load C libraries
|
2018-06-02 23:16:13 +00:00
|
|
|
* Functional and imperative standard library
|
2018-02-06 06:25:48 +00:00
|
|
|
* 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
|
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
|
|
|
|
|
|
|
API documentation and design documents can be found in the
|
2018-10-23 17:54:55 +00:00
|
|
|
[wiki](https://github.com/bakpakin/janet/wiki). There is an introduction
|
|
|
|
section in the wiki that contains a good overview of the language.
|
2018-01-24 22:59:00 +00:00
|
|
|
|
2018-11-17 03:36:47 +00:00
|
|
|
For individual bindings, use the `(doc symbol-name)` macro to get API
|
|
|
|
documentation for the core library. For example,
|
|
|
|
```
|
|
|
|
(doc doc)
|
|
|
|
```
|
|
|
|
Shows documentation for the doc macro.
|
|
|
|
|
|
|
|
To get a list of all bindings in the default
|
|
|
|
environment, use the `(all-symbols)` function.
|
|
|
|
|
2018-03-16 19:52:56 +00:00
|
|
|
## Usage
|
|
|
|
|
|
|
|
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
|
|
|
|
by entering the command `(all-symbols)` into the repl.
|
|
|
|
|
2018-03-16 19:52:56 +00:00
|
|
|
```
|
2018-09-06 02:18:42 +00:00
|
|
|
$ ./janet
|
|
|
|
Janet 0.0.0 alpha Copyright (C) 2017-2018 Calvin Rose
|
|
|
|
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
|
2018-09-06 02:18:42 +00:00
|
|
|
janet:3:> (os.exit)
|
|
|
|
$ ./janet -h
|
|
|
|
usage: ./janet [options] scripts...
|
2018-03-16 19:52:56 +00:00
|
|
|
Options are:
|
2018-07-04 04:17:34 +00:00
|
|
|
-h Show this help
|
|
|
|
-v Print the version string
|
|
|
|
-s Use raw stdin instead of getline like functionality
|
2018-09-06 02:18:42 +00:00
|
|
|
-e Execute a string of janet
|
2018-07-04 04:17:34 +00:00
|
|
|
-r Enter the repl after running all scripts
|
|
|
|
-p Keep on executing if there is a top level error (persistent)
|
|
|
|
-- Stop handling option
|
2018-03-16 19:52:56 +00:00
|
|
|
$
|
|
|
|
```
|
|
|
|
|
2017-04-25 22:22:43 +00:00
|
|
|
## Compiling and Running
|
|
|
|
|
2018-09-06 02:18:42 +00:00
|
|
|
Janet only uses Make and batch files to compile on Posix and windows
|
|
|
|
respectively. To configure janet, edit the header file src/include/janet/janet.h
|
2018-08-06 01:13:14 +00:00
|
|
|
before compilation.
|
2018-01-29 20:46:26 +00:00
|
|
|
|
2018-08-06 01:13:14 +00:00
|
|
|
### Posix
|
|
|
|
|
2018-10-23 17:54:55 +00:00
|
|
|
On most platforms, use Make to build janet.
|
2018-03-18 13:13:21 +00:00
|
|
|
|
|
|
|
```sh
|
2018-09-06 02:18:42 +00:00
|
|
|
cd somewhere/my/projects/janet
|
2018-03-18 13:13:21 +00:00
|
|
|
make
|
|
|
|
make test
|
|
|
|
```
|
|
|
|
|
2018-09-10 02:22:21 +00:00
|
|
|
After building, run `make install` to install the janet binary and libs.
|
|
|
|
Will install in `/usr/local` by default, see the Makefile to customize.
|
|
|
|
|
|
|
|
It's also recommended to set the `JANET_PATH` variable in your profile.
|
|
|
|
This is where janet will look for imported libraries after the current directory.
|
|
|
|
|
2018-08-06 01:13:14 +00:00
|
|
|
### Windows
|
2018-03-18 13:13:21 +00:00
|
|
|
|
2018-08-06 01:13:14 +00:00
|
|
|
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#)
|
2018-09-06 02:18:42 +00:00
|
|
|
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.
|
2018-08-16 01:36:32 +00:00
|
|
|
4. Run `build_win test` to make sure everything is working.
|
2018-03-13 20:40:56 +00:00
|
|
|
|
2018-10-18 02:01:48 +00:00
|
|
|
### Emscripten
|
|
|
|
|
|
|
|
To build janet for the web via [Emscripten](https://kripken.github.io/emscripten-site/), make sure you
|
|
|
|
have `emcc` installed and on your path. On a linux or macOS system, use `make janet.js` to build
|
|
|
|
`janet.js` and `janet.wasm` - both are needed to run janet in a browser or in node.
|
|
|
|
The JavaScript build is what runs the repl on the main website,
|
|
|
|
but really serves mainly as a proof of concept. Janet will run much slower in a browser.
|
|
|
|
Building with emscripten on windows is currently unsupported.
|
|
|
|
|
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-07-04 04:17:34 +00:00
|
|
|
|
|
|
|
## SQLite bindings
|
|
|
|
|
|
|
|
There are some sqlite3 bindings in the directory natives/sqlite3. They serve mostly as a
|
|
|
|
proof of concept external c library. To use, first compile the module with Make.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
make natives
|
|
|
|
```
|
|
|
|
|
|
|
|
Next, enter the repl and create a database and a table.
|
|
|
|
|
|
|
|
```
|
2018-09-06 02:18:42 +00:00
|
|
|
janet:1:> (import natives.sqlite3 :as sql)
|
2018-07-04 04:17:34 +00:00
|
|
|
nil
|
2018-09-06 02:18:42 +00:00
|
|
|
janet:2:> (def db (sql.open "test.db"))
|
2018-07-04 04:17:34 +00:00
|
|
|
<sqlite3.connection 0x5561A138C470>
|
2018-09-06 02:18:42 +00:00
|
|
|
janet:3:> (sql.eval db `CREATE TABLE customers(id INTEGER PRIMARY KEY, name TEXT);`)
|
2018-07-04 04:17:34 +00:00
|
|
|
@[]
|
2018-09-06 02:18:42 +00:00
|
|
|
janet:4:> (sql.eval db `INSERT INTO customers VALUES(:id, :name);` {:name "John" :id 12345})
|
2018-07-04 04:17:34 +00:00
|
|
|
@[]
|
2018-09-06 02:18:42 +00:00
|
|
|
janet:5:> (sql.eval db `SELECT * FROM customers;`)
|
2018-07-04 04:17:34 +00:00
|
|
|
@[{"id" 12345 "name" "John"}]
|
|
|
|
```
|
|
|
|
|
|
|
|
Finally, close the database connection when done with it.
|
|
|
|
|
|
|
|
```
|
2018-09-06 02:18:42 +00:00
|
|
|
janet:6:> (sql.close db)
|
2018-07-04 04:17:34 +00:00
|
|
|
nil
|
|
|
|
```
|