diff --git a/Readme.org b/Readme.org index 1596c93..4ec705b 100644 --- a/Readme.org +++ b/Readme.org @@ -20,25 +20,43 @@ https://gitlab.com/whom/shs https://matrix.to/#/#vomitorium:matrix.sunnypup.io * How to use +** Syntax +*** Basic data types +TODO +*** S-Expressions +TODO +**** calling a function +TODO +*** Control flow +TODO +*** Defining variables and functions +TODO +**** Undefining variables and functions +TODO +*** Builtin functions +TODO + ** Configuration By default Relish will read from ~/.relishrc for configuration, but the default shell will also accept a filename from the RELISH_CFG_FILE environment variable. +See file:snippets/basic_minimal_configuration.rls for an example of a basic minimal configuration file. *** The configuration file The configuration file is a script containing arbitrary Relish code. On start, any shell which leverages the configuration code in the config module (file:src/config.rs) will create a clean seperate context, including default configuration values, within which the standard library will be initialized. The configuration file is evaluated and run as a standalone script and may include arbitrary executable code. Afterwards, configuration values found in the variable map will be used to configure the standard library function mappings that the shell will use. -Errors during configuration are non-terminal and will result in default values being returned. +Errors during configuration are non-terminal. In such a case any defaults which have not been overwritten will remain present. **** Important points to note - When the configuration file is run, it will be run with default configuration values. -- The user/script interpreter will be run with a *re-instantiation* of the standard library, using the previously defined configuration variables. +- The user/script interpreter will be run with the standard library configured to use the previously defined configuration variables. +- The standard library will then be re-processed and re-added to the symbol table with new configuration. - Variables and functions defined during configuration will carry over to the user/script interpreter, allowing the user to load any number of custom functions and variables. *** Configuration Values - CFG_RELISH_POSIX (default 0): when on, enables POSIX style job control. - CFG_RELISH_ENV (default 1): when on, interpreter's variable table and environment variable table are kept in sync. - CFG_RELISH_PROMPT (default (echo "λ ")): A *function* definition which is called in order to output the prompt for each loop of the REPL. -Note: CFG_RELISH_PROMPT is only loaded once and will be ignored after initial configuration. + This function will be reloaded each REPL loop and will be called by the interpreter with no arguments. ** Compilation #+BEGIN_SRC sh @@ -88,16 +106,24 @@ It includes the core interpreter mechanisms, full stdlib, and the configuration Your project can use or not use any number of these components. They can certainly be used to support language development for other LISP machines, or even other languages. +*** config: file:src/config.rs +This file contains default configuration values as well as functions which load and run the configuration file script. +For more information see the configuraiton section above in this Readme. + *** stl: file:src/stl.rs -This defines the ~get_stdlib~ function. -This function takes in a Variable Table (likely containing custom configuration) and returns a Function Table for use in an interpreter. +This defines the ~static_stdlib~ function and the ~dynamic_stdlib~ function. +The ~static_stdlib~ function loads all symbols in the standard library which do not need further configuration into the symbol table. +The ~dyanmic_stdlib~ function loads all symbols in the standard library which *do* need configuration into the symbol table. +The ~dynamic_stdlib~ function uses variables saved in the symbol table to configure the functions and variables it loads. +For more information see file:src/config. Any new addition to the stdlib must make its way here to be included in the main shell (and any other shell using the included ~get_stdlib~ function). -You may choose to override this function if you would like to include your own special functions in your own special interpreter, or if you would like to pare down the stdlib to a small minimal subet of what it is. +You may choose to override these functions if you would like to include your own special functions in your own special interpreter, or if you would like to pare down the stdlib to a small minimal subet of what it is. + +You can view the code for standard library functions in file:src/stl/. *** bin: file:src/bin/ This contains any executable target of this project. Notably the main shell file:src/bin/main.rs. - * Current Status / TODO list Note: this section will not show the status of each item unless you are viewing it with a proper orgmode viewer *** TODO Rudimentary Control Flow @@ -105,33 +131,36 @@ Note: this section will not show the status of each item unless you are viewing **** TODO loop clause **** TODO while clause **** TODO circuit clause -*** TODO Configuration -**** DONE get_stdlibphase1 -> configuration -> get_stdlibphase2 -**** DONE Function to load configuration into Variable and Function tables -**** DONE Configure in main shell -**** DONE manual verification of config settings -**** DONE manual verification of config defaults *** TODO Help function +*** TODO Eval function +*** TODO Input function *** TODO Env function -*** TODO User variable declaration tests -*** TODO User function declaration tests *** TODO Load (load a script) function Pull/Refactor the logic out of the configure functions. Optionally return a list of new variables and/or functions? -Will need a concatenate function for func tables +Will need a concatenate function for tables *** TODO Main shell calls Load function on arg and exits -*** TODO Custom error printing +*** TODO Custom error struct with pretty printing *** TODO Custom ast pretty print *** TODO Shell module **** TODO Process launching with environment variables **** TODO Foreground process TTY **** TODO Background processes -**** DONE append +*** TODO list operations +**** TODO head (returns (head rest)) +**** TODO tail (returns (rest tail)) +**** TODO queue (append to front) +*** TODO boolean operations +**** TODO and +**** TODO or +**** TODO xor +**** TODO not +**** TODO toggle *** TODO string operations -**** TODO concatenate +**** TODO concat **** TODO substr by index -**** TODO tokenize by delimiter -**** TODO sprintf / string build +**** TODO split (on delimiter) +**** TODO strcons (sprintf but its all string tokens under the hood) *** TODO arithmetic operations **** TODO add **** TODO sub @@ -139,6 +168,9 @@ Will need a concatenate function for func tables **** TODO mul **** TODO exp **** TODO mod +**** TODO inc +**** TODO dec +**** TODO int (float to int) *** TODO file operations **** TODO read-to-string **** TODO write-to-file