Skip to content

Commit 15007bb

Browse files
lthibaultlthibault
authored
Improvements to README.md (#13)
* Add copy to README.md. - Add a 'Why Slurp' section near the top that contains a positioning statement. - Add installation instructions under 'Usage' - Link to examples in use-cases under 'Usage' * Add Go interop to 'Features' section in README. * Add link to tutorial on GitHub wiki. * Punctuation fix. * Move README section about extending Slurp to Wiki. Add 'Documentation' section
1 parent 5f063d8 commit 15007bb

File tree

1 file changed

+47
-50
lines changed

1 file changed

+47
-50
lines changed

‎README.md

Lines changed: 47 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,42 @@
1-
# slurp
1+
# Slurp
2+
23

34
[![GoDoc](https://godoc.org/github.com/spy16/slurp?status.svg)](https://godoc.org/github.com/spy16/slurp) [![Go Report Card](https://goreportcard.com/badge/github.com/spy16/slurp)](https://goreportcard.com/report/github.com/spy16/slurp) ![Go](https://github.com/spy16/slurp/workflows/Go/badge.svg?branch=master)
45

56
Slurp is a highly customisable, embeddable LISP toolkit for `Go` applications.
67

8+
- [Slurp](#slurp)
9+
- [Why Slurp](#why-slurp)
10+
- [Features](#features)
11+
- [Usage](#usage)
12+
- [Documentation](#documentation)
13+
14+
## Why Slurp
15+
16+
![I've just received word that the Emperor has dissolved the MIT computer science program permanently.](https://imgs.xkcd.com/comics/lisp_cycles.png)
17+
18+
Slurp is for developers who want to design and embed an interpreted language inside of a Go program.
19+
20+
Slurp provides composable building-blocks that make it easy to design a custom lisp, even if you've never written an interpreter before. Since Slurp is written in pure Go, your new language can be embedded into any Go program by importing it — just like any other library.
21+
22+
> **NOTE:** Slurp is _NOT_ an implementation of a particular LISP dialect.
23+
>
24+
> It provides pieces that can be used to build a LISP dialect or can be used as a scripting layer.
25+
26+
Slurp is designed around three core values:
27+
28+
1. **Simplicity:** The library is small and has few moving parts.
29+
2. **Batteries Included:** There are no external dependencies and little configuration required.
30+
3. **Go Interoperability:** Slurp can call Go code and fully supports Go's concurrency features.
31+
32+
We hope that you will find Slurp to be powerful, useful and fun to use. We look forward to seeing what you build with it!
33+
34+
735
## Features
836

937
* Highly customizable, safe and powerful reader/parser through
1038
a read table (Inspired by [Clojure](https://github.com/clojure/clojure/blob/master/src/jvm/clojure/lang/LispReader.java)) (See [Reader](#reader))
11-
* Built-in data types: nil, bool, string, numbers (int & float),
39+
* Immutable datatypes including: nil, bool, string, int & float,
1240
character, keyword, symbol, list, vector & map.
1341
* Multiple number formats supported: decimal, octal, hexadecimal,
1442
radix and scientific notations.
@@ -19,65 +47,34 @@ Slurp is a highly customisable, embeddable LISP toolkit for `Go` applications.
1947
1. simple literals (e.g., `\a` for `a`)
2048
2. special literals (e.g., `\newline`, `\tab` etc.)
2149
3. unicode literals (e.g., `\u00A5` for `¥` etc.)
50+
* Full interoperability with Go: call native Go functions/libraries, and manipulate native Go datatypes from your language.
2251
* Support for macros.
2352
* Easy to extend. See [Extending](#extending).
2453
* Tiny & powerful REPL package.
2554
* Zero dependencies (outside of tests).
2655

2756
## Usage
2857

29-
> Slurp requires Go 1.14 or higher.
58+
Slurp requires Go 1.14 or higher. It can be installed using `go get`:
59+
60+
```bash
61+
go get -u github.com/spy16/slurp
62+
```
3063

3164
What can you use it for?
3265

33-
1. Embedded script engine to provide dynamic behavior without requiring re-compilation
34-
of your application.
35-
2. Business rule engine by exposing very specific & composable rule functions.
66+
1. Embedded script engine to provide dynamic behavior without requiring re-compilation of your application ([example](./examples/simple/main.go)).
67+
2. Business rule engine exposing specific, composable rules ([example](./examples/rule-engine/main.go)).
3668
3. To build DSLs.
37-
4. To build your own LISP dialect.
69+
4. To build your own LISP dialect ([example](https://github.com/wetware/ww)).
3870

39-
> Please note that slurp is _NOT_ an implementation of a particular LISP dialect. It provides
40-
> pieces that can be used to build a LISP dialect or can be used as a scripting layer.
71+
Refer [./examples](./examples) for more usage examples.
4172

42-
![I've just received word that the Emperor has dissolved the MIT computer science program permanently.](https://imgs.xkcd.com/comics/lisp_cycles.png)
73+
## Documentation
74+
75+
In addition to the GoDocs, we maintain in-depth tutorials on the GitHub wiki. The following
76+
pages are good starting points:
4377

44-
Refer [./examples](./examples) for usage examples.
45-
46-
## Extending
47-
48-
### Reader
49-
50-
slurp reader is inspired by Clojure reader and uses a _read table_. Reader can be extended
51-
to add new syntactical features by adding _reader macros_ to the _read table_. _Reader Macros_
52-
are implementations of `reader.Macro` function type. All syntax that reader can read are
53-
implemented using _Reader Macros_. Use `SetMacro()` method of `reader.Reader` to override or
54-
add a custom reader or dispatch macro.
55-
56-
Reader returned by `reader.New(...)`, is configured to support following forms:
57-
58-
* Numbers:
59-
* Integers use `int64` Go representation and can be specified using decimal, binary
60-
hexadecimal or radix notations. (e.g., 123, -123, 0b101011, 0xAF, 2r10100, 8r126 etc.)
61-
* Floating point numbers use `float64` Go representation and can be specified using
62-
decimal notation or scientific notation. (e.g.: 3.1412, -1.234, 1e-5, 2e3, 1.5e3 etc.)
63-
* You can override number reader using `WithNumReader()`.
64-
* Characters: Characters use `rune` or `uint8` Go representation and can be written in 3 ways:
65-
* Simple: `\a`, `\λ`, `\β` etc.
66-
* Special: `\newline`, `\tab` etc.
67-
* Unicode: `\u1267`
68-
* Boolean: `true` or `false` are converted to `Bool` type.
69-
* Nil: `nil` is represented as a zero-allocation empty struct in Go.
70-
* Keywords: Keywords represent symbolic data and start with `:`. (e.g., `:foo`)
71-
* Symbols: Symbols can be used to name a value and can contain any Unicode symbol.
72-
* Lists: Lists are zero or more forms contained within parentheses. (e.g., `(1 2 3)`, `(1 :hello ())`).
73-
74-
### Evaluation
75-
76-
Slurp uses implementation of `core.Env` as the environment for evaluating
77-
forms. A form is first analyzed using a `core.Analyzer` to produce `core.Expr`
78-
that can be evaluated against an Env. Custom implementations for all of
79-
these can be provided to optimise performance, customise evaluation rules
80-
or support additional features.
81-
82-
A builtin Analyzer is provided which supports pure lisp forms with support
83-
for macros as well.
78+
1. [Getting Started](https://github.com/spy16/slurp/wiki/Getting-Started)
79+
2. [Customizing Syntax](https://github.com/spy16/slurp/wiki/Customizing-Syntax#Custom-Parsing)
80+
3. [Customizing Evaluation](https://github.com/spy16/slurp/wiki/Customizing-Syntax#Custom-Evaluation)

0 commit comments

Comments
 (0)