| Title: | Emulate a 'Forth' Programming Environment |
|---|---|
| Description: | Emulates a 'Forth' programming environment with added features to interface between R and 'Forth'. Implements most of the functionality described in the original "Starting Forth" textbook <https://www.forth.com/starting-forth/>. |
| Authors: | Aidan Lakshman [aut, cre] |
| Maintainer: | Aidan Lakshman <[email protected]> |
| License: | GPL-3 |
| Version: | 1.1.0 |
| Built: | 2025-03-01 06:22:27 UTC |
| Source: | https://github.com/ahl27/froth |
Functions to inspect and save installed froth words.
froth.dictionary() writeFrothDictionary(file="", ...)froth.dictionary() writeFrothDictionary(file="", ...)
file |
file to write to, or "" for the console |
... |
additional arguments passed to |
froth.dictionary will list all installed words, grouped by their type (built-in, alias, user-defined).
writeFrothDictionary allows users to export their function definitions. The default argument will print out user-defined definitions to the console. This output can be redirected to a file by changing the file argument.
None. froth.dictionary lists all installed words using message, and writeFrothDictionary either prints to the console or to a file.
Aidan Lakshman [email protected]
saveFrothSession
loadFrothSession
## Show all words froth.dictionary() ## Define a few new words froth.parse(": MAKE_THREE 1 2 + . ;") froth.parse(": MAKE_FIVE 2 3 + . ;") ## print out definition writeFrothDictionary()## Show all words froth.dictionary() ## Define a few new words froth.parse(": MAKE_THREE 1 2 + . ;") froth.parse(": MAKE_FIVE 2 3 + . ;") ## print out definition writeFrothDictionary()
Function to run froth code from R.
froth.parse(inputline) froth.source(filepath)froth.parse(inputline) froth.source(filepath)
inputline |
A string to parse with froth |
filepath |
Path to a file containing froth or FORTH code to parse with froth |
These functions run the froth interpreter on strings read in either as arguments (froth.parse) or from a file (froth.source). Both functions will run froth code without having to enter the REPL.
Invisibly returns an integer status code, with 0 corresponding to normal execution.
Aidan Lakshman [email protected]
## Add two numbers froth.parse("1 2 + .") ## source a function to print a ASCII table called 'rect' tf <- tempfile() defn <- ': RECT 256 0 DO I 16 MOD 0= IF CR THEN ." * " LOOP ;' writeLines(defn, con=tf) froth.source(tf) froth.parse('rect')## Add two numbers froth.parse("1 2 + .") ## source a function to print a ASCII table called 'rect' tf <- tempfile() defn <- ': RECT 256 0 DO I 16 MOD 0= IF CR THEN ." * " LOOP ;' writeLines(defn, con=tf) froth.source(tf) froth.parse('rect')
Resets the froth session to defaults. This deletes any user-defined functions and variables, and clears the stack.
froth.reset()froth.reset()
None; called to reset internal froth stacks.
Aidan Lakshman [email protected]
froth.RDefine("rnorm", rnorm, 3L) froth.reset() froth.parse("5 0 1 rnorm .s") # fr> rnorm ?froth.RDefine("rnorm", rnorm, 3L) froth.reset() froth.parse("5 0 1 rnorm .s") # fr> rnorm ?
Methods to communicate with the froth environment without dropping into a REPL.
froth.RPush(object) froth.RPop(nobj=1L) froth.RDefine(name, fun, nargs)froth.RPush(object) froth.RPop(nobj=1L) froth.RDefine(name, fun, nargs)
object |
An R object to push to the froth stack |
nobj |
Number of objects to pop from the froth stack |
name |
Froth name for |
fun |
An R function to define within froth |
nargs |
Number of arguments expected for |
These functions allow interaction with the froth stack from R. froth.RPush and froth.RPop allow push/pop operations on the froth stack. These operations are called from R, so pushing any R object is supported.
Some functions are easier to define using R than froth. froth.RDefine creates a froth function wrapper to call a specified R function, and then builds it into the froth environment. This makes using functions like rnorm within froth easier; see below for an illustrative example.
Functions defined with froth.RDefine expect their arguments to be popped directly off the froth stack, with the top of the stack corresponding to the last argument of the function.
froth.RPop returns a list with the top nobj elements of the stack.
froth.RPush and froth.RDefine invisibly return an integer corresponding to the status of the operation. 0 indicates normal completion.
Functions defined with froth.RDefine will not be saved using saveFrothSession.
Aidan Lakshman [email protected]
## Example of calling rnorm in froth ## rnorm expects 3 arguments: rnorm(n, mean, sd) froth.RDefine(name='R_rnorm', fun=rnorm, nargs=3L) ## Now we can call rnorm from froth using the 'R_rnorm' word. ## Note that the arguments are expected on the stack ## such that the top of the stack is `sd`, ## the second is `mean`, and the third is `n`. ## n froth.RPush(5) ## mean froth.RPush(0.0) ## sd froth.RPush(1.0) ## running the function ## note this will push the results back onto the stack froth.parse("R_rnorm") ## we can get the result with froth.RPop froth.RPop(5L) ## As a oneliner: (doesn't return the values) froth.parse("5 0 1 R_rnorm .s")## Example of calling rnorm in froth ## rnorm expects 3 arguments: rnorm(n, mean, sd) froth.RDefine(name='R_rnorm', fun=rnorm, nargs=3L) ## Now we can call rnorm from froth using the 'R_rnorm' word. ## Note that the arguments are expected on the stack ## such that the top of the stack is `sd`, ## the second is `mean`, and the third is `n`. ## n froth.RPush(5) ## mean froth.RPush(0.0) ## sd froth.RPush(1.0) ## running the function ## note this will push the results back onto the stack froth.parse("R_rnorm") ## we can get the result with froth.RPop froth.RPop(5L) ## As a oneliner: (doesn't return the values) froth.parse("5 0 1 R_rnorm .s")
Methods to preserve user-defined entries and variables.
saveFrothSession(file=NULL, ...) loadFrothSession(file=NULL)saveFrothSession(file=NULL, ...) loadFrothSession(file=NULL)
file |
Path to a file used for saving/loading |
... |
Additional arguments passed to |
saveFrothSession saves current user-defined methods and variables within the Froth dictionary to the file specified. Built-in methods are loaded when the package is attached, so these aren't saved. Note that methods defined using froth.RDefine are currently not able to be saved.
loadFrothSession will restart the froth environment, which will erase any current user-defined methods and variables. It then loads the contents of the the file specified into the current Froth session.
None. loadFrothSession will update internal froth stacks, and saveFrothSession will save to a file.
Aidan Lakshman [email protected]
tf <- tempfile() froth.RDefine('rnorm', rnorm, 3L) saveFrothSession(tf) froth.reset() froth.parse("5 0 1 rnorm .s") # fr> rnorm ? loadFrothSession(tf) froth.parse("5 0 1 rnorm .s")tf <- tempfile() froth.RDefine('rnorm', rnorm, 3L) saveFrothSession(tf) froth.reset() froth.parse("5 0 1 rnorm .s") # fr> rnorm ? loadFrothSession(tf) froth.parse("5 0 1 rnorm .s")