From effbdf4a2ad8d5824d41d78939aa0a16ecf9b548 Mon Sep 17 00:00:00 2001 From: Joshua Weinstein Date: Wed, 20 Jun 2018 22:58:19 -0700 Subject: [PATCH] lots of readme changes, small path display change --- README.md | 154 +++++++++++++++++++++++++++++++++++++++++++- include/IOUtil.h | 3 + src/flow/WindExec.c | 4 +- src/util/IOUtil.c | 5 ++ 4 files changed, 163 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 66c953c..16f63a6 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ The Flow-based Programming Language -![Main Md Gif](images/intro_wind.gif) +![Main Md Gif](images/intro_wind.gif)` # Table of Contents @@ -14,11 +14,22 @@ The Flow-based Programming Language - [wind mem buf](#wind_mem_buf) - [wind mem load](#wind_mem_load) - [wind mem comp](#wind_mem_comp) +- [Usage](#usage) - [Guide](#guide) - [Syntax](#syntax) - [Syntax Errors](#syntax-errors) + - [Types](#types) + - [None](#none) - [Commands](#commands) - [out](#out) + - [push](#push) + - [clr](#clr) + - [map](#map) + - [filter](#filter) + - [reduce](#reduce) + - [save](#save) + - [load](#load) +- [Stage](#stage) ## Intro @@ -182,6 +193,23 @@ Error: Expected argument or value, found 'l' ``` `l` does not correspond to any recognizable value. +### Types + +The `Wind` language uses several types, all of which are immutable. `Wind` formats data in a marked, binary format. The language does not use heap-allocated types or objects. All types are kept on various `static` arrays. This enables very simple copying and flowing of data. + +#### None + +The `None` type in Wind signifies a singular state value of being nothing. It is similar to `nil` or `null` in other languages. There isn't a whole lot to do with None, but None corresponds to a false boolean value. + +In certain boolean operations, like the not operator, `!`, it will evaluate to `False`. + +``` +wind> push None None None -> out +[ None None None ] +wind> map ! -> out +[ False False False ] +``` + ### Commands The `Wind` language uses an effecient set of commands to manipualte and process a flow of data. Commands are named words that appear before an arbitrary sequence of arguments. @@ -199,6 +227,130 @@ wind> clr -> out [ ] ``` +#### push + +The `push` command appends new data to the end of the active data. It can take an arbitrary number of arguments. + +*Example* + +``` +wind> push None True False 0 1 2 3 +wind> out +[ None True False 0 1 2 3 ] +``` + +#### clr + +The `clr` command clears all the data from the active buffer. This doesn't incur the cost of erasing data, it simply sets the end of the active buffer back to the beginning, and allows overwriting of the old data. It takes no arguments. + +*Example* + +``` +wind> push 3 3 3 3 -> out +[ 3 3 3 3 ] +wind> clr -> out +[ ] +``` + +#### map + +The `map` command transforms data over a flow of operations. Mapping can take place with a variety of operations, such as adding, subtracting, assigning, and much more. Besides for the `Del` op, mapping never erases data. + +``` +wind> push 6 7 8 9 10 12 14 +wind> out -> map + 1 | * 3 -> out +[ 6 7 8 9 10 12 14 ] +[ 21 24 27 30 33 39 45 ] +wind> map / 55 | ** 3 -> out +[ 0.056 0.083 0.118 0.162 0.216 0.357 0.548 ] +``` +Within the arguments read after a `map` command, each oper symbol can have only specific values that are valid after it. The pipe `|` is used to transition to the mapping of another symbol and it's sub-arguments. Attempting to map unmappable types results in an error: + +``` +wind> push 5 5 5 +wind> map + 5 3 2 +wind> out +[ 15 15 15 ] +wind> map + 4 - 3 +Error: Attempted to use + operator on arg with type: 'Minus' +``` +Some types in `Wind` can be treated as having number values. In this case, they can be used in mapping operations that involve typically number operations such as `+`: + +``` +wind> push 7 -> out +[ 7 ] +wind> push 5 -> map + True False 1 -> out +[ 9 7 ] +``` + +#### filter + +The `filter` command allows the limitation and restriction of a data flow. It permits the passing or failing of flowing from the one buffer to another based on a boolean condition. The `filter` command can be used with operators like `>` and `<`. + +``` +wind> push 6 7 8 9 15.04 -> out +[ 6 7 8 9 15.040 ] +wind> filter > 8 -> out +[ 9 15.040 ] +wind> filter > 15.02 -> out +[ 15.040 ] +``` + +#### reduce + +The `reduce` command fuses and squashes data together into smaller data, or in many cases a single value. For now, `reduce` only works with one operator, `+`, but many more will be added in the future. + +``` +wind> push 666 777 888 -> out +[ 666 777 888 ] +wind> map ** 3 -> out -> reduce + +[ 295408296 469097433 700227072 ] +wind> out +[ 1464732801 ] +``` + +#### save + +The `save` command allows the current, active data inside Wind to be saved to an file on disk with the `.bwind` file extension. More info on the binary specification can be found in the wiki. The idea behind this command, and the `load` command is it allows `Wind` to process and emit data in an instantly available format. Internally, `save` is just a write of the active buffer bytes to a file. + +``` +wind> push True False 3 2 -> out +[ True False 3 2 ] +wind> save "samplefile" +Saved at: samplefile.bwind +``` + +The argument to save is always a string that indicates a path, without the extension. The newly created file will have a sequence of bytes formatted like this: + +``` +[bool mark][bool body = 1] +[bool mark][bool body = 0] +[number mark][number body = 3 ] +[number mark][number body = 2 ] +``` +Where the bool body is a single byte, and the number body is a 64-bit floating point number. The pattern of the `Wind` binary format is using typed sequences of bytes. A large advantage of this is internally, it makes data easily copyable and immutable. + +#### load + +The `load` command is used to load `.bwind` files into the active buffer. This command permits direct, instant access to `Wind` typed data stored on disk. As explained previously, the loading and saving components of `Wind` allows the processing of data across a broader, vaster set of data than what can be stored inside the active buffer. + +``` +wind> push None 5 5 -> out +[ None 5 5 ] +wind> save "test" +Saved at: test.bwind +wind> clr -> out +[ ] +wind> load "test" -> out +Loaded data from: test.bwind +[ None 5 5 ] +``` +If the file path attempting to be loaded from cannot be read or does not exist, you will get an error like this: + +``` +wind> load "test1" +Error: File path 'test1' cannot be read from. +``` ## Stage diff --git a/include/IOUtil.h b/include/IOUtil.h index f6561d0..0a537ea 100644 --- a/include/IOUtil.h +++ b/include/IOUtil.h @@ -30,6 +30,9 @@ void IOUtil_debug(void); // Starts a read eval print loop. void IOUtil_repl(void); +// Gets current contents of path buffer. +const char* IOUtil_path_buf(void); + // Saves the current active buffer as a binary file with extension .windb int IOUtil_save(const char* path); diff --git a/src/flow/WindExec.c b/src/flow/WindExec.c index bd60728..9342fb9 100644 --- a/src/flow/WindExec.c +++ b/src/flow/WindExec.c @@ -88,7 +88,7 @@ int WindExec_save(void) WindState_write_err("File path '%s' cannot be written to.", savePath); return 0; } - printf("Saved at: %s\n", savePath); + printf("Saved at: %s\n", IOUtil_path_buf()); return 1; } @@ -106,6 +106,6 @@ int WindExec_load(void) WindState_write_err("File path '%s' cannot be read from.", loadPath); return 0; } - printf("Loaded data from: %s\n", loadPath); + printf("Loaded data from: %s\n", IOUtil_path_buf()); return 1; } diff --git a/src/util/IOUtil.c b/src/util/IOUtil.c index 61534df..95b47d3 100644 --- a/src/util/IOUtil.c +++ b/src/util/IOUtil.c @@ -144,6 +144,11 @@ void IOUtil_repl(void) } } +const char* IOUtil_path_buf(void) +{ + return IOUtil_PATH_BUF; +} + // Saves active buffer binary representation. int IOUtil_save(const char* path) {