1
0
mirror of https://github.com/janet-lang/janet synced 2024-12-23 23:10:26 +00:00
janet/README.md

162 lines
6.1 KiB
Markdown
Raw Normal View History

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-12-13 17:23:31 +00:00
<img src="https://raw.githubusercontent.com/honix/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
2018-05-19 01:31:46 +00:00
modern lisp, but lists are replaced
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-12-13 17:23:31 +00:00
#
2018-09-06 02:18:42 +00:00
Implemented in mostly standard C99, janet runs on Windows, Linux and macOS.
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-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-12-16 23:00:18 +00:00
Generic lisp syntax highlighting should, however, provide good results. There is also a janet.tmLanguage file
that should provide good syntax highlighting for many editors.
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.
## Features
2018-10-23 17:54:55 +00:00
* Minimal setup - one binary and you are good to go!
* First class closures
* Garbage collection
* 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)
2018-07-04 04:17:34 +00:00
* Lisp Macros
* Byte code interpreter with an assembly interface, as well as bytecode verification
2018-10-23 17:54:55 +00:00
* Tailcall 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
* 300+ functions and macros in the core library
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
Documentation can be found in the doc directory of
the repository. There is an introduction
section contains a good overview of the language.
2018-12-17 06:57:09 +00:00
API documentation for all bindings can also be generated
with `make docs`, which will create `build/doc.html`, which
can be viewed with any web browser. This
includes all forms in the core library except special forms.
For individual bindings from within the REPL, use the `(doc symbol-name)` macro to get API
2018-11-17 03:36:47 +00:00
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.
## Installation
Install a stable version of janet from the [releases page](https://github.com/bakpakin/janet/releases).
Janet is prebuilt for a few systems, but if you want to develop janet, run janet on a non-x86 system, or
get the latest, you must build janet from source.
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-11-29 00:52:37 +00:00
### Unix-like
2018-08-06 01:13:14 +00:00
On most platforms, use Make to build janet. The resulting binary will be in `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-11-29 00:52:37 +00:00
### FreeBSD
FreeBSD build instructions are the same as the unix-like build instuctions,
but you need `gmake` and `gcc` to compile.
```
cd somewhere/my/projects/janet
gmake CC=gcc
gmake test CC=gcc
```
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-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 emscripten` to build
2018-10-18 02:01:48 +00:00
`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 slower in a browser.
2018-10-18 02:01:48 +00:00
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.