From b4862ee196441e7c42e9816e5ce79e85bfdc55fa Mon Sep 17 00:00:00 2001 From: VaclavT Date: Mon, 8 Mar 2021 00:15:02 +0100 Subject: [PATCH] doc updates --- Readme.md | 11 ++-- doc/Doc.md | 6 +-- doc/Wisp.md | 151 ---------------------------------------------------- 3 files changed, 8 insertions(+), 160 deletions(-) delete mode 100644 doc/Wisp.md diff --git a/Readme.md b/Readme.md index 9fcf0e2..ac7337b 100644 --- a/Readme.md +++ b/Readme.md @@ -7,21 +7,21 @@ - some performance functionality (at least counting how many times symbol was evaluated) - download 10 years of data from api.nasdaq.com into test dir - documentation -- rename data.csv and add more tickers - add url of source/inspiration to clib/*.cpp - add stdtest - to test every functionality - rename ivaluize - add benchmark - add instrumentation (time, nr of evals, num of atoms, debug info, debug environment etc) -- in casting functions (as_string..) better exception description -- add better print (syntax high-lighting) +- in casting functions (as_string..) +- better exception description +- add better print (coloring output) - add command line options -h for help, -v for version, -b for no stdlib.lsp on startup - add readline like functionality (libnoise) - multiline editting (kilo editor) - execute system command should capture stderr -- add builtin sleep +- add builtin or lib function sleep - add built in for and, or -- add some debug support +- add debug support - file functions - name it here - string functions @@ -39,7 +39,6 @@ - format (printf) - setq - mapcar (funcall, apply) -- delete UNIT (replace it by nil) #### Performance - push_back - repeatedly without reserving size diff --git a/doc/Doc.md b/doc/Doc.md index 33ab2bc..84edeb8 100644 --- a/doc/Doc.md +++ b/doc/Doc.md @@ -29,7 +29,7 @@ |`(/ a b)`|Divide two values|result of division| |`(% a b)`|Remainder of division|result of operation| |`(list ..)`|Create a list of values|| -|`(insert list index element)`|Insert an element into a lis.Indexed from 0|new list with value inserted| +|`(insert list index element)`|Insert an element into a list. Indexed from 0|new list with value inserted| |`(index list index)`|Return element at index in list|Element at index| |`(remove list index)`|Remove a value at an index from a list|List with element removed| |`(len list)`|Get the length of a list|list length| @@ -58,8 +58,8 @@ |`(read-url ..)`||| |`(system-cmd ..)`||| |`(ls-dir ..)`||| -|`(is-file? ..)`||| -|`(is-dir? ..)`||| +|`(is-file? ..)`|Returns true if passed filename is a file|| +|`(is-dir? ..)`|Returns true if passed filename is a directory|| |`(parse-csv ..)`||| |`(parse-json ..)`||| |`(save-csv ..)`||| diff --git a/doc/Wisp.md b/doc/Wisp.md deleted file mode 100644 index dcd03b8..0000000 --- a/doc/Wisp.md +++ /dev/null @@ -1,151 +0,0 @@ -# wisp - -A light lisp written in C++ -![Wisp](./wisp.png) - -## Why write a lisp? - -Lisp is one of those niche, beautiful languages that people only really use to either - -1. Write a lisp interpreter -2. Show off how "code is data!!!" - -_So why add to the list of infinite lisp interpreters?_ - -The answer is simple: _**I'm bored out of my mind in quarantine.**_ If you were looking to find out why _this particular_ lisp is special, you're fresh out of luck. - - -## Syntax and Special Forms - -Like every other lisp, this language uses s-expressions for code syntax and data syntax. So, for example, the s-expression `(print 5)` is both a valid code snippet, and a valid list containing the items `print` and `5`. - -When the data `(print 5)` is evaluated by the interpreter, it evaluates `print` and `5`, and then applies `print` to `5`. - -Here's the result. - -```lisp ->>> (print 5) -5 - => 5 -``` - -That's super cool! But what if we want to define our own functions? _We can use the builtin function `defun`!_ - -```lisp -; define a function `fact` that takes an argument `n` -(defun fact (n) - (if (<= n 1) - 1 - (* n (fact (- n 1))) - )) -``` - -Thats awesome! But did you notice anything different about the `defun` function? _It doesn't evaluate its arguments._ If the atom `fact` were evaluated, it would throw an error like so: - -```lisp ->>> fact -error: the expression `fact` failed in scope { } with message "atom not defined" -``` - -This is known as a special form, where certain functions "quote" their arguments. We can quote things ourselves too, but the language _automatically_ quotes arguments to special forms itself. - -If you want to "quote" a value yourself, you can do it like this. - -```lisp -; quote the s-expression (1 2 3) so it's not evaluated ->>> (print '(1 2 3)) -(1 2 3) - => (1 2 3) -``` - -As you can see, quote negates an evaluation. For example, whenever the expression `''a` is evaluated, it becomes `'a`. This can be useful for when you want to write long lists of data or variable names without wanting to evaluate them as code. - -|Special Form|Argument Evaluations|Purpose| -|:-|-|-| -|`(if cond a b)`|`if` only evaluates its `cond` argument. If `cond` is truthy (non-zero), then `a` is evaluated. Otherwise, `b` is evaluated.|This special form is the main method of control flow.| -|`(do a b c ...)`|`do` takes a list of s-expressions and evaluates them in the order they were given (in the current scope), and then returns the result of the last s-expression.|This special form allows lambda functions to have multi-step bodies.| -|`(scope a b c ...)`|`scope` takes a list of s-expressions and evaluates them in the order they were given _in a new scope_, and then returns the result of the last s-expression.|This special form allows the user to evaluate blocks of code in new scopes.| -|`(defun name params body)`|`defun` evaluates none of its arguments.|This special form allows the user to conveniently define functions.| -|`(define name value)`|`define` evaluates the `value` argument, which is then assigned to `name` in the current scope.|This special form allows the user to bind atoms to values in a scope.| -|`(lambda params body)`|`lambda` evaluates none of its arguments.|This special form allows the user to define anonymous functions.| -|`(quote x)`|`quote` evaluates none of its arguments.|This is equivalent to the `'expr` syntactic sugar.| -|`(for x list ...)`|`for` evaluates only its list argument.|`for` iterates through the list storing each element in `x`, and then evaluating all of the rest of the values in the `for` body. It then returns the last value evaluated.| -|`(while cond ...)`|`while` evaluates only its cond argument.|`while` evaluates its condition expression every iteration before running. If it is true, it continues to evaluate every expression in the `while` body. It then returns the last value evaluated.| - - -## Examples - -Here are some example math-y functions to wrap your head around. - -```lisp -; quicksort -(defun qs (l) - (if (<= (len l) 1) - l - (do - (define pivot (first l)) - (+ - (qs (filter (lambda (n) (> pivot n)) l)) - (list pivot) - (qs (tail (filter (lambda (n) (<= pivot n)) l))) - )) - )) - -; decrement a number -(defun dec (n) (- n 1)) -; increment a number -(defun inc (n) (+ n 1)) -; not a bool -(defun not (x) (if x 0 1)) - -; negate a number -(defun neg (n) (- 0 n)) - -; is a number positive? -(defun is-pos? (n) (> n 0)) -; is a number negative? -(defun is-neg? (n) (< n 0)) -``` - -## Usage - -Using and compiling wisp - -#### Dependencies - -Compile with your C++ compiler of choice. This is compatible with all standard versions of C++ since ANSI C++. - -```bash -$ git clone https://github.com/adam-mcdaniel/wisp -$ cd wisp -$ g++ wisp.cpp -o wisp -``` - -#### Using the binary - -Run wisp in interactive mode: - -```bash -$ ./wisp ->>> (print "Hello world!") -Hello world! - => "Hello world!" -``` - -Interpret a file: - -```bash -$ ./wisp -f "examples/hello_world.lisp" -Hello world! -``` - -Interpret from command line argument: - -```bash -$ ./wisp -c '(print "Hello world!")' -Hello world! -``` - - -source from : -https://github.com/adam-mcdaniel/wisp