% Created 2023-03-01 Wed 11:19
% Intended LaTeX compiler: pdflatex
\documentclass[11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\author{Ava Hahn}
\date{\today}
\title{Relish: Rusty Expressive LIsp SHell}
\hypersetup{
 pdfauthor={Ava Hahn},
 pdftitle={Relish: Rusty Expressive LIsp SHell},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 28.2 (Org mode 9.5.5)}, 
 pdflang={English}}
\begin{document}

\maketitle
\tableofcontents

Note: this document is best read within a dedicated ORG mode interpreter

\section{Purpose statement}
\label{sec:orgc3ceb30}
The purpose of Relish is to create a highly expressive POSIX shell using a lisp interpreter.

\section{Goals}
\label{sec:orge9bdae6}
\begin{itemize}
\item Iterate on the ideas and designs that were tested with SHS
\end{itemize}
\url{https://gitlab.com/whom/shs}
\begin{itemize}
\item Act as both a high level scripting language and as a system shell
\item To be as portable as possible
\item To provide code and framework that can be embedded in other applications needing a user facing interpreter
\item To be well tested code
\item No unsafe code without extreme consideration and rigorous containment
\end{itemize}

\section{Contact}
\label{sec:org3fd450f}
\begin{itemize}
\item Matrix chat: \#vomitorium:matrix.sunnypup.io
\end{itemize}
\url{https://matrix.to/\#/\#vomitorium:matrix.sunnypup.io}

\section{How to use}
\label{sec:orge516721}
\subsection{Configuration}
\label{sec:orgfa5496e}
By default Relish will read from \textasciitilde{}/.relishrc for configuration, but the default shell will also accept a filename from the RELISH\textsubscript{CFG}\textsubscript{FILE} environment variable.

\subsubsection{The configuration file}
\label{sec:org4656ec9}
The configuration file is a script containing arbitrary Relish code.
On start, any shell which leverages the configuration code in the config module (\url{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.

\begin{enumerate}
\item Important points to note
\label{sec:orgbff9880}
\begin{itemize}
\item When the configuration file is run, it will be run with default configuration values.
\item The user/script interpreter will be run with a \textbf{re-instantiation} of the standard library, using the previously defined configuration variables.
\item 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.
\end{itemize}
\end{enumerate}

\subsubsection{Configuration Values}
\label{sec:orgf8edfc5}
\begin{itemize}
\item CFG\textsubscript{RELISH}\textsubscript{POSIX} (default 0): when on, enables POSIX style job control.
\item CFG\textsubscript{RELISH}\textsubscript{ENV} (default 1): when on, interpreter's variable table and environment variable table are kept in sync.
\item CFG\textsubscript{RELISH}\textsubscript{PROMPT} (default (echo "λ ")): A \textbf{function} definition which is called in order to output the prompt for each loop of the REPL.
\end{itemize}
Note: CFG\textsubscript{RELISH}\textsubscript{PROMPT} is only loaded once and will be ignored after initial configuration.

\subsection{Compilation}
\label{sec:org39d838c}
\begin{verbatim}
cargo build
\end{verbatim}

\subsection{Testing}
\label{sec:org6e03460}
\begin{verbatim}
cargo test
\end{verbatim}

\subsection{Running (the main shell)}
\label{sec:orgd463ecf}
\begin{verbatim}
cargo run src/bin/main.rs
\end{verbatim}

\section{Guide to codebase}
\label{sec:orgd69534c}
\subsection{\url{tests} directory}
\label{sec:orgb50a02a}
Start here if you are new.
Most of these files have unimplemented tests commented out in them.
Contributions that help fill out all of these tests
\subsubsection{Eval tests: \url{tests/test\_eval.rs}}
\label{sec:orga1b1d34}
These are particularly easy to read and write tests.

\subsubsection{Func tests: \url{tests/test\_func.rs}}
\label{sec:orge9d0267}
You can consider these to extend the eval tests to cover the co-recursive nature between eval and func calls.

\subsubsection{Lex tests: \url{tests/test\_lex.rs}}
\label{sec:org594467d}
These tests verify the handling of syntax.

\subsubsection{Lib tests: (tests/test\textsubscript{lib}*)}
\label{sec:org9bec093}
These tests are unique per stdlib module.

\subsection{\url{src} directory}
\label{sec:org76b8e4f}
This directory contains all of the user facing code in relish.
Just a few entries of note:
\subsubsection{segment: \url{src/segment.rs}}
\label{sec:orge669586}
This file lays out the \sout{spiritual} \sout{theological} \sout{ideological} \sout{theoretical} mechanical underpinnings of the entire interpreter.
The entire LISP machine centers around a singlet or pairing of datum.
The \texttt{Ctr} datatype provides an abstraction for which any type of data, including a \texttt{Seg} can be a datum.
The \texttt{Seg} datatype provides a mechanism to hold a single datum or a pair of datum. It is implemented as two \texttt{Ctr\textasciitilde{}s: \textasciitilde{}car} and \texttt{cdr}.
A primitive type system is provided through the Rust Enum datatype. A number of utility functions follow.

\subsubsection{lib: \url{src/lib.rs}}
\label{sec:org411af26}
This defines a library that can be included to provide an interpreter interface within any Rust project.
It includes the core interpreter mechanisms, full stdlib, and the configuration system.
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.

\subsubsection{stl: \url{src/stl.rs}}
\label{sec:org35c6136}
This defines the \texttt{get\_stdlib} function.
This function takes in a Variable Table (likely containing custom configuration) and returns a Function Table for use in an interpreter.
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 \texttt{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.

\subsubsection{bin: \url{src/bin/}}
\label{sec:org02ca0c3}
This contains any executable target of this project. Notably the main shell \url{src/bin/main.rs}.


\section{Current Status / TODO list}
\label{sec:org258203d}
Note: this section will not show the status of each item unless you are viewing it with a proper orgmode viewer
\subsubsection{{\bfseries\sffamily TODO} Rudimentary Control Flow}
\label{sec:orgf3270ab}
\begin{enumerate}
\item {\bfseries\sffamily DONE} if clause
\label{sec:org217bde3}
\item {\bfseries\sffamily TODO} loop clause
\label{sec:org98f181c}
\item {\bfseries\sffamily TODO} while clause
\label{sec:org17661df}
\item {\bfseries\sffamily TODO} circuit clause
\label{sec:orgc0e4e38}
\end{enumerate}
\subsubsection{{\bfseries\sffamily TODO} Configuration}
\label{sec:org6a6ce49}
\begin{enumerate}
\item {\bfseries\sffamily DONE} get\textsubscript{stdlibphase1} -> configuration -> get\textsubscript{stdlibphase2}
\label{sec:orga8173cf}
\item {\bfseries\sffamily DONE} Function to load configuration into Variable and Function tables
\label{sec:org10a79b6}
\item {\bfseries\sffamily DONE} Configure in main shell
\label{sec:org931e04b}
\item {\bfseries\sffamily DONE} manual verification of config settings
\label{sec:org2bdcfe5}
\item {\bfseries\sffamily DONE} manual verification of config defaults
\label{sec:orge04cfbf}
\end{enumerate}
\subsubsection{{\bfseries\sffamily TODO} Help function}
\label{sec:org3e23e99}
\subsubsection{{\bfseries\sffamily TODO} Env function}
\label{sec:org531ea9a}
\subsubsection{{\bfseries\sffamily TODO} User variable declaration tests}
\label{sec:org96a294c}
\subsubsection{{\bfseries\sffamily TODO} User function declaration tests}
\label{sec:orgbfd6736}
\subsubsection{{\bfseries\sffamily TODO} Load (load a script) function}
\label{sec:org407bcaa}
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
\subsubsection{{\bfseries\sffamily TODO} Main shell calls Load function on arg and exits}
\label{sec:orgfe00c72}
\subsubsection{{\bfseries\sffamily TODO} Custom error printing}
\label{sec:org5edadcd}
\subsubsection{{\bfseries\sffamily TODO} Custom ast pretty print}
\label{sec:org6eed0c6}
\subsubsection{{\bfseries\sffamily TODO} Shell module}
\label{sec:org5ffd68d}
\begin{enumerate}
\item {\bfseries\sffamily TODO} Process launching with environment variables
\label{sec:org344e4c4}
\item {\bfseries\sffamily TODO} Foreground process TTY
\label{sec:org655c227}
\item {\bfseries\sffamily TODO} Background processes
\label{sec:org6e43465}
\item {\bfseries\sffamily DONE} append
\label{sec:orgf5f4877}
\end{enumerate}
\subsubsection{{\bfseries\sffamily TODO} string operations}
\label{sec:org32cb3d8}
\begin{enumerate}
\item {\bfseries\sffamily TODO} concatenate
\label{sec:org50e3c74}
\item {\bfseries\sffamily TODO} substr by index
\label{sec:org885f9a8}
\item {\bfseries\sffamily TODO} tokenize by delimiter
\label{sec:org5d7f725}
\item {\bfseries\sffamily TODO} sprintf / string build
\label{sec:orgf0081df}
\end{enumerate}
\subsubsection{{\bfseries\sffamily TODO} arithmetic operations}
\label{sec:org49d973e}
\begin{enumerate}
\item {\bfseries\sffamily TODO} add
\label{sec:orgdf7ac0a}
\item {\bfseries\sffamily TODO} sub
\label{sec:org0bf6f03}
\item {\bfseries\sffamily TODO} div
\label{sec:orgfcbfb3e}
\item {\bfseries\sffamily TODO} mul
\label{sec:org538e579}
\item {\bfseries\sffamily TODO} exp
\label{sec:orgf78ab65}
\item {\bfseries\sffamily TODO} mod
\label{sec:org7feefea}
\end{enumerate}
\subsubsection{{\bfseries\sffamily TODO} file operations}
\label{sec:org8de4c82}
\begin{enumerate}
\item {\bfseries\sffamily TODO} read-to-string
\label{sec:orgdc39ea8}
\item {\bfseries\sffamily TODO} write-to-file
\label{sec:orga5d95bb}
\end{enumerate}
\subsubsection{{\bfseries\sffamily TODO} Network library}
\label{sec:org7326fd0}
\begin{enumerate}
\item {\bfseries\sffamily TODO} HTTP Client
\label{sec:orgc6b9da5}
\item {\bfseries\sffamily TODO} TCP Stream client
\label{sec:orgf052c59}
\item {\bfseries\sffamily TODO} UDP Client
\label{sec:org854bde3}
\item {\bfseries\sffamily TODO} TCP Listener
\label{sec:org1026057}
\item {\bfseries\sffamily TODO} HTTP Listener
\label{sec:org5d02df8}
\item {\bfseries\sffamily TODO} UDP Listener
\label{sec:orgee9978b}
\end{enumerate}
\end{document}