diff options
| -rw-r--r-- | .gitmodules | 3 | ||||
| -rw-r--r-- | Doxyfile | 8 | ||||
| -rw-r--r-- | MAINPAGE.md | 45 | ||||
| m--------- | doxygen-awesome-css | 0 | ||||
| -rw-r--r-- | examples/fib.stem | 19 | ||||
| -rw-r--r-- | src/builtins.c | 2 |
6 files changed, 70 insertions, 7 deletions
diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..d8da1e4 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "doxygen-awesome-css"] + path = doxygen-awesome-css + url = https://github.com/jothepro/doxygen-awesome-css.git @@ -949,7 +949,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = include/ src/ +INPUT = include/ src/ MAINPAGE.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -1365,7 +1365,7 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1388,7 +1388,7 @@ HTML_EXTRA_FILES = # The default value is: AUTO_LIGHT. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE = AUTO_LIGHT +HTML_COLORSTYLE = LIGHT # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to @@ -1716,7 +1716,7 @@ DISABLE_INDEX = NO # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the # FULL_SIDEBAR option determines if the side bar is limited to only the treeview diff --git a/MAINPAGE.md b/MAINPAGE.md index de5bdce..0ba8c25 100644 --- a/MAINPAGE.md +++ b/MAINPAGE.md @@ -1,3 +1,44 @@ -# Introduction +# Introduction {#mainpage} Stem aims to be a minimal interpreted stack based programming language -that allows for metaprogramming and a foreign language interface. +that allows for metaprogramming and a foreign language interface. It features +a C API that is elegant and simple. Additionally, garbage collection is +not needed in this language as the responsibility of writing memory safe +operations is put in the hands of the maintainers of the builtin functions +and FLI library maintainers. Therefore, the end user does not need to worry +about memory allocation while the implementation remains extremely simple. + +# Installation +`make` and `sudo make install`. To generate the html documentation, one must first +install `doxygen` as an optional dependency. If you are on a BSD or MacOS, you +must use `gmake`. + +# Quickstart +Because this is a stack based language, all operations are done in reverse polish. For example, to add two numbers together: +``` +3 4 + +``` +would return the result `7`. `3` and `4` get pushed onto the stack when they are written out as literals in the language, and `+` is a builtin +that adds the top two elements of the stack. In this language, there are two kinds of objects: literals +(strings, ints, floats, words, and literals of type `VERROR` are built in), and quotes that contain these literals (arrays of valid statements that can be evaluated). +Words might be new to you if you're coming from another language. If you're coming from lisp, a words are analogous to symbols. If you're coming from another +language, a word is a literal that has the special property that they can be bound to functions. For example, the `+` symbol is a word, which is bound +to the action of adding two numbers when called. + +Let's look at a real example of a REPL implementation in this language: +``` +repl [ "> " . read strquote eval repl ] func +repl +``` +`repl` is a word, which means it is a literal, and everything that is a literal gets pushed onto the stack. +Everything between the `[` and `]` is an element in a quote. Then, we see the `func` word. If a word is already bound to a function, +the function gets called instead of getting pushed to the stack, so the `func` function gets called, which takes the top two +elements off the stack, and creates a function called `repl` where now every time `repl` is called in the future, the quote is evaluated +instead. + +Let's take a closer look at the quote: +``` +"> " . read strquote eval repl +``` +`.` takes the first thing off the stack and prints it. In this case, it would print a prompt `> ` every REPL loop. `read` reads a value from stdin, +then `strquote` turns that string into a quote. `eval` pops the first thing off the stack and evaluates the quote in the same way calling a function +does, and then finally `repl` gets called again at the end so we can loop forever. diff --git a/doxygen-awesome-css b/doxygen-awesome-css new file mode 160000 +Subproject df88fe4fdd97714fadfd3ef17de0b4401f80405 diff --git a/examples/fib.stem b/examples/fib.stem new file mode 100644 index 0000000..4104a36 --- /dev/null +++ b/examples/fib.stem @@ -0,0 +1,19 @@ +fib [ + dup 1 <= [ ] [ + dup 1 - fib + swap + dup 2 - fib + swap + dsc + + + ] if +] func + +main [ + dup 10 <= [ + dup fib . + 1 + main + ] [ exit ] if +] func + +0 main diff --git a/src/builtins.c b/src/builtins.c index f801028..31981c3 100644 --- a/src/builtins.c +++ b/src/builtins.c @@ -548,7 +548,7 @@ void dip(value_t *v) { eval(value_copy(v2->quote->items[i])); } value_free(array_pop(EVAL_STACK)); - value_free(array_pop(EVAL_STACK)); + array_pop(EVAL_STACK); } else { eval(v1); } |