picrin/README.md

165 lines
6.1 KiB
Markdown
Raw Normal View History

2014-01-17 07:11:43 -05:00
# Picrin [![Build Status](https://travis-ci.org/wasabiz/picrin.png)](https://travis-ci.org/wasabiz/picrin)
2014-01-17 07:16:26 -05:00
Picrin is a lightweight scheme implementation intended to comply with full R7RS specification. Its code is written in pure C99 and does not requires any special external libraries installed on the platform.
2013-10-17 01:09:39 -04:00
2013-11-07 08:16:04 -05:00
## Features
2013-10-17 01:09:39 -04:00
- R7RS compatibility (but partial support)
- reentrant design (all VM states are stored in single global state object)
2013-11-14 21:53:33 -05:00
- bytecode interpreter (based on Stack VM)
2013-10-17 08:03:23 -04:00
- direct threaded VM
2013-11-05 07:16:17 -05:00
- Internal representation by Nan-Boxing
- conservative call/cc implementation (users can freely interleave native stack with VM stack)
2013-11-14 21:58:48 -05:00
- exact GC (simple mark and sweep, partially reference count is used as well)
2013-12-10 06:43:03 -05:00
- support full set hygienic macro transformers, including implicit renaming macros
2013-12-10 12:10:07 -05:00
- extended library syntax
2013-10-17 07:53:39 -04:00
- advanced REPL support (multi-line input, etc)
2013-10-20 08:44:31 -04:00
- tiny & portable library (all functions will be in `libpicrin.so`)
2013-10-17 01:09:39 -04:00
2014-02-14 22:50:17 -05:00
## Libraries
- `(scheme base)`
- `(scheme write)`
- `(scheme cxr)`
- `(scheme file)`
- `(scheme inexact)`
- `(scheme time)`
- `(scheme process-context)`
- `(scheme load)`
- `(picrin macro)`
- `define-macro`
- `gensym`
2014-02-14 23:02:42 -05:00
- `macroexpand`
2014-02-14 22:50:17 -05:00
Old-fashioned macro facility.
- `make-syntactic-closure`
- `identifier?`
- `identifier=?`
Syntactic closures.
- `er-macro-transformer`
- `ir-macro-transformer`
Explicit renaming macro families.
- `(srfi 1)`
List manipulation library.
2013-11-14 04:27:12 -05:00
## Compliance with R7RS
2013-11-13 23:57:53 -05:00
2014-01-17 07:21:21 -05:00
| section | status | comments |
| --- | --- | --- |
2013-11-13 23:57:53 -05:00
| 2.2 Whitespace and comments | incomplete | block comments are not implemented |
2014-01-17 07:21:21 -05:00
| 2.3 Other notations | incomplete | #e #i #b #o #d #x |
| 2.4 Datum labels | no | unsupported |
2013-11-13 23:57:53 -05:00
| 3.1 Variables, syntactic keywords, and regions | | |
2014-01-17 07:21:21 -05:00
| 3.2 Disjointness of types | yes | |
2013-11-13 23:57:53 -05:00
| 3.3 External representations | | |
| 3.4 Storage model | yes | |
2014-02-06 20:19:35 -05:00
| 3.5 Proper tail recursion | yes | As the report specifies, `apply`, `call/cc`, and `call-with-values` perform tail calls |
2013-11-13 23:57:53 -05:00
| 4.1.1 Variable references | yes | |
| 4.1.2 Literal expressions | yes | |
2013-11-13 23:57:53 -05:00
| 4.1.3 Procedure calls | yes | In picrin `()` is self-evaluating |
| 4.1.4 Procedures | yes | |
| 4.1.5 Conditionals | yes | In picrin `(if #f #f)` returns `#f` |
| 4.1.6 Assignments | yes | |
2014-02-08 01:13:28 -05:00
| 4.1.7 Inclusion | incomplete | `include-ci`. TODO: Once `read` is implemented rewrite `include` macro with it. |
2013-11-13 23:57:53 -05:00
| 4.2.1 Conditionals | incomplete | TODO: `cond-expand` |
2013-12-10 11:52:17 -05:00
| 4.2.2 Binding constructs | yes | |
2013-11-13 23:57:53 -05:00
| 4.2.3 Sequencing | yes | |
2013-12-10 09:06:44 -05:00
| 4.2.4 Iteration | yes | |
2013-11-13 23:57:53 -05:00
| 4.2.5 Delayed evaluation | N/A | |
2014-01-08 10:43:03 -05:00
| 4.2.6 Dynamic bindings | yes | |
2013-11-13 23:57:53 -05:00
| 4.2.7 Exception handling | no | `guard` syntax. |
| 4.2.8 Quasiquotation | yes | can be safely nested |
2013-12-10 11:52:17 -05:00
| 4.2.9 Case-lambda | N/A | |
2013-12-10 11:00:29 -05:00
| 4.3.1 Bindings constructs for syntactic keywords | incomplete | (*1) |
2013-12-10 06:30:41 -05:00
| 4.3.2 Pattern language | no | `syntax-rules` |
| 4.3.3 Signaling errors in macro transformers | yes | |
2013-11-13 23:57:53 -05:00
| 5.1 Programs | yes | |
2013-12-10 06:30:41 -05:00
| 5.2 Import declarations | incomplete | only simple import declarations, no support for import with renaming. |
2013-11-13 23:57:53 -05:00
| 5.3.1 Top level definitions | yes | |
2013-11-14 04:17:50 -05:00
| 5.3.2 Internal definitions | yes | TODO: interreferential definitions |
2013-12-10 11:52:17 -05:00
| 5.3.3 Multiple-value definitions | yes | |
2013-12-10 06:30:41 -05:00
| 5.4 Syntax definitions | yes | TODO: internal macro definition is not supported. |
2013-11-13 23:57:53 -05:00
| 5.5 Recored-type definitions | no | |
| 5.6.1 Library Syntax | incomplete | In picrin, libraries can be reopend and can be nested. |
2013-11-13 23:57:53 -05:00
| 5.6.2 Library example | N/A | |
| 5.7 The REPL | yes | |
2014-02-09 00:08:40 -05:00
| 6.1 Equivalence predicates | yes | TODO: equal? must terminate if circular structure is given |
2013-11-14 00:17:41 -05:00
| 6.2.1 Numerical types | yes | picrin has only two types of internal representation of numbers: fixnum and double float. It still comforms the R7RS spec. |
| 6.2.2 Exactness | yes | |
| 6.2.3 Implementation restrictions | yes | |
| 6.2.4 Implementation extensions | yes | |
| 6.2.5 Syntax of numerical constants | yes | |
| 6.2.6 Numerical operations | yes | `denominator`, `numerator`, and `rationalize` are not supported for now. Also, picrin does not provide complex library procedures. |
2013-11-14 00:17:41 -05:00
| 6.2.7 Numerical input and output | no | |
2013-11-14 00:31:57 -05:00
| 6.3 Booleans | yes | |
2013-11-14 00:17:41 -05:00
| 6.4 Pairs and lists | yes | |
2013-11-14 02:52:10 -05:00
| 6.5 Symbols | yes | |
| 6.6 Characters | yes | |
2013-11-17 11:26:03 -05:00
| 6.7 Strings | yes | `substring` is not provided |
2013-11-17 11:29:54 -05:00
| 6.8 Vectors | yes | |
2013-12-10 10:58:45 -05:00
| 6.9 Bytevectors | yes | |
2013-11-28 22:13:57 -05:00
| 6.10 Control features | yes | |
2013-11-17 04:18:11 -05:00
| 6.11 Exceptions | yes | TODO: native error handling |
| 6.12 Environments and evaluation | N/A | |
2014-02-09 00:30:34 -05:00
| 6.13.1 Ports | yes | |
2014-02-08 05:54:18 -05:00
| 6.13.2 Input | incomplete | |
| 6.13.3 Output | yes | TODO: `write`, `write-shared` and `display` are unsafe against circular objects |
2013-12-08 23:51:52 -05:00
| 6.14 System interface | yes | |
2013-11-13 23:57:53 -05:00
2013-12-10 11:00:29 -05:00
1. Picrin provides hygienic macros in addition to so-called legacy macro (`define-macro`), such as syntactic closure, explicit renaming macro, and implicit renaming macro. As of now let-syntax and letrec-syntax are not provided.
2013-10-19 14:20:41 -04:00
## Homepage
Currently picrin is hosted on Github. You can freely send a bug report or pull-request, and fork the repository.
https://github.com/wasabiz/picrin
2013-10-17 01:09:39 -04:00
## How to use it
- build
2013-11-28 10:15:10 -05:00
A built executable binary will be under bin/ directory and a shared library `libpicrin.so` under lib/.
2013-11-15 02:16:34 -05:00
2013-11-28 10:15:10 -05:00
$ make
2013-11-15 02:48:02 -05:00
If you want to build picrin on other systems than x86_64, make sure PIC_NAN_BOXING flag is turned off (see include/config.h for detail).
2013-10-17 01:09:39 -04:00
- run
Simply directly run the binary `bin/picrin` from terminal, or you can use `make` to execute it like this.
$ make run
2013-11-13 23:57:28 -05:00
2013-11-28 10:15:10 -05:00
- debug-run
2013-10-17 01:09:39 -04:00
2013-11-28 10:15:10 -05:00
When `make` command is called with an argument `debug`, it builds the binary with all debug flags enabled (PIC_GC_STRESS, VM_DEBUG, DEBUG).
$ make debug
2013-10-20 08:44:31 -04:00
- install
As of now picrin does not provide a command automatically installs the binary. If you want to place picrin library and binary in a parmanent directory, please do it by hand.
2013-10-17 07:58:01 -04:00
## Requirement
picrin scheme depends on some external libraries to build the binary:
- bison
- yacc
- make
- gcc
- readline
The compilation is tested only on Mac OSX. I think (or hope) it'll be ok to compile and run on other operating systems such as Linux or Windows, but there's no guarantee :(
2013-10-17 01:09:39 -04:00
## Authors
2014-01-17 07:02:31 -05:00
See `AUTHORS`