affine/flesh
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

rename relish to flesh

Browse source
This commit is contained in:
Ava Apples Affine 2024-02-06 22:39:08 +00:00
parent 415b1181fa
commit 9b447eb5b7
58 changed files with 252 additions and 245 deletions
Download patch file Download diff file Expand all files Collapse all files

47
Writing.org
View file

@ -1,27 +1,28 @@
#+Title: Relish as a Language
#+Author: Ava Hahn
#+Title: Flesh as a Language
#+Author: Ava Affine
Note: this document is best read using a dedicated ORG mode editor
* Description
This document offers a guide on how to write beginner or intermediate scripts using the Relish language.
Readers should be able to run the Relish repl to follow along with this guide and experiment with the included examples in the REPL.
This document offers a guide on how to write beginner or intermediate scripts using the Flesh language.
Readers should be able to run the Flesh repl to follow along with this guide and experiment with the included examples in the REPL.
* Syntax
** Data types
Relish leverages the following data types:
Flesh leverages the following data types:
- Strings: delimited by one of the following: ~' " `~
- Integers: up to 128 bit signed integers
- Floats: all floats are stored as 64 bit floats
- Booleans: ~true~ or ~false~
- Symbols: an un-delimited chunk of text containing alphanumerics or one of the following: ~- _ ?~
Symbols and Functions can contain data of any type. there is no immediate restriction on what can be set/passed to what..... However, internally Relish is typed, and many builtin functions will get picky about what types are passed to them.
Symbols and Functions can contain data of any type. there is no immediate restriction on what can be set/passed to what..... However, internally Flesh is typed, and many builtin functions will get picky about what data is passed to them.
** S-Expressions
Relish, like other LISPs, is *HOMOICONIC* which means that user written code entered at the REPL is data, and that there is a direct correlation between the code as written and the program as stored in memory.
Flesh, like other LISPs, is *HOMOICONIC* which means that user written code entered at the REPL is data, and that there is a direct correlation between the code as written and the program as stored in memory.
This is achieved through *S-EXPRESSIONS*. An S-Expression (or symbolic expression) is simply a list of elements surrounded by parenthesis. Within this list are elements of any data, and potentially nested s-expressions (sometimes referred to as sexprs). Each s-expression represents one statement, or line of code to be evaluated. To evaluate an s-expression also requires that any nested s-expressions are first evaluated.
Programs in Relish (and most other lisps) are written with S-Expressions, and are then represented in memory as linked lists of heterogenous data. In memory, a linked list may contain addresses to other linked lists.
Programs in Flesh (and most other lisps) are written with S-Expressions, and are then represented in memory as linked lists of heterogenous data. In memory, a linked list may contain addresses to other linked lists.
An example:
#+BEGIN_EXAMPLE lisp
@ -31,8 +32,8 @@ An example:
As a tree:
#+BEGIN_EXAMPLE
top-level -> element1 -> "element2" -> 3 -> [] -> [] ->
\ \_> peer-nested ->
\_> nested -> 2 -> 5 -> 2 ->
\ \_> peer-nested ->
\_> nested -> 2 -> 5 -> 2 ->
#+END_EXAMPLE
As in memory:
@ -45,7 +46,7 @@ In order to evaluate the code stored at ADDR 1, first ADDR 2 and ADDR 3 must be
In evaluation, a list is digested and its simplest possible form is returned. A list may represent a function call, for which the result is the simplest possible form. The list may contain variables, for which evaluation must replace with the defined values of those variables. The top level list must wait as the deepest nested lists are evaluated and their simplest possible forms return upwards to then be evaluated as members of the top level s-expression.
In this document, and in the Relish interpreter, s-expressions may be referred to as 'forms'.
In this document, and in the Flesh interpreter, s-expressions may be referred to as 'forms'.
** Calling a function
S-Expressions can represent function calls in addition to trees of data. A function call is a list of data starting with a symbol that is defined to be a function:
@ -62,7 +63,7 @@ In this example, ~(add 5 2)~ is evaluated first, its result is then passed to ~(
** Control flow
*** If
An *if form* is the most basic form of conditional evaluation offered by Relish.
An *if form* is the most basic form of conditional evaluation offered by Flesh.
It is a function that takes lazily evaluated arguments: a condition, a then clause, and an else clause.
If the condition evaluates to true, the then clause is evaluated and the result returned. Otherwise the else clause is evaluated and the result is returned. If the condition evaluates to neither true nor false, (a non-boolean value), a type error is returned.
@ -93,7 +94,7 @@ Like the *if form*, if the conditional returns a non-boolean value the *while lo
#+END_SRC
*** Let
*Let* is one of the most powerful forms Relish offers.
*Let* is one of the most powerful forms Flesh offers.
The first body in a call to let is a list of lists. Specifically, a list of variable declarations that look like this: ~(name value)~. Each successive variable definition can build off of the last one, like this: ~((step1 "hello") (step2 (concat step1 " ")) (step3 (concat step2 "world")))~. The resulting value of step3 is "hello world".
@ -121,7 +122,7 @@ If all forms evaluate to ~true~, ~true~ is returned.
Example:
#+BEGIN_SRC lisp
(circuit
(load my-shell-command) ;; exit 0 casted to true, also: requires CFG_RELISH_POSIX
(load my-shell-command) ;; exit 0 casted to true, also: requires CFG_FLESH_POSIX
(get-state-flag global-state)
(eq? (some-big-calculation) expected-result))
#+END_SRC
@ -178,7 +179,7 @@ CURRENT VALUE AND/OR BODY:
#+END_SRC
*** Quote and Eval
As stated previously: Lisp, and consequently Relish, is homoiconic. This means that code can be passed around (and modified) as data.
As stated previously: Lisp, and consequently Flesh, is homoiconic. This means that code can be passed around (and modified) as data.
This allows us to write self programming programs, or construct entire procedures on the fly. The primary means to do so are with *quote* and *eval*.
The *quote* function allows data (code) to be passed around without evaluating it. It is used to pass unevaluated code around as data that can then be evaluated later.
To be specific, typing ~(a)~ usually results in a symbol lookup for ~a~, and then possibly even a function call. However, if we *quote* ~a~, we can pass around the symbol itself:
@ -240,7 +241,7 @@ Here is the lambda bound to a variable inside a let statement:
#+END_SRC
* Defining variables and functions
In Relish, both variables and functions are stored in a table of symbols.
In Flesh, both variables and functions are stored in a table of symbols.
All Symbols defined with ~def~ are *GLOBAL*. The only cases when symbols are local is when they are defined as part of *let* forms or as arguments to functions.
In order to define a symbol, the following inputs are required:
- A name
@ -279,7 +280,7 @@ Removing a symbol consists of a call to ~def~ with no additional arguments:
#+END_SRC
* Builtin functions
The following table is up to date as of Relish 0.3.0. For latest information try the following:
The following table is up to date as of Flesh 0.4.0. For latest information try the following:
- Call ~env~ from a fresh shell: ~(env)~
This will output all variables and functions defined
- Read the [[file:src/stl.rs][std library declaration code]]
@ -322,7 +323,7 @@ Perusing them may yield answers on all the cases a given builtin can handle.
[[file:tests][The test directory]]
** Help function
Relish is self documenting. The *help* function can be used to inspect any variable or function.
Flesh is self documenting. The *help* function can be used to inspect any variable or function.
It will show the name, current value, docstring, arguments, and definition of any builtin or user defined function or variable.
#+BEGIN_EXAMPLE
> (help my-adder)
@ -339,8 +340,8 @@ args: x y
form: ((add x y))
#+END_EXAMPLE
#+BEGIN_EXAMPLE
> (help CFG_RELISH_ENV)
NAME: CFG_RELISH_ENV
> (help CFG_FLESH_ENV)
NAME: CFG_FLESH_ENV
ARGS: (its a variable)
@ -352,18 +353,18 @@ CURRENT VALUE AND/OR BODY:
true
#+END_EXAMPLE
Every single symbol in Relish can be inspected in this way, unless some third party developer purposefully left a docstring blank.
Every single symbol in Flesh can be inspected in this way, unless some third party developer purposefully left a docstring blank.
* Snippets directory
The *snippets directory* may also yield some interesting examples.
Within it are several examples that the authors and maintainers wanted to keep around but didnt know where.
It is sort of like a lint roller.
It also contains considerably subpar implementations of Relish's internals that are kept around for historical reasons.
It also contains considerably subpar implementations of Flesh's internals that are kept around for historical reasons.
** Userlib
The *Userlib* was added as a script containing many valuable functions such as ~set~ and ~prepend~.
You can use it by calling it in your shell config
(See [[file:snippets/basic_minimal_configuration.rls][The minimal shell configuration example]] for more info).
(See [[file:snippets/basic_minimal_configuration.f][The minimal shell configuration example]] for more info).
* Common patterns
This section contains common composites of control flow that may be used to build more complex or effective applications. More ideas may be explored in the [[file:snippets][snippets]] directory of this project.