Merge pull request #190 from tomhea/dev

Dev - read for 1.0.0

CONTRIBUTING.md

@@ -55,12 +55,13 @@ When filing an issue, make sure to answer these five questions:
 General questions should go to the [Questions thread](https://github.com/tomhea/flip-jump/discussions/176), or the [Discussions](https://github.com/tomhea/flip-jump/discussions) in general. 
 
 # How to suggest a feature or enhancement
-The FlipJump philosophy is to be the simplest langauge of all, that can do any modern computation.
+The FlipJump philosophy is to be the simplest language of all, that can do any modern computation.
 
 FlipJump should be below the OS, as it's a cpu-architecture after all.
 
-The FlipJump stl should be minimalistic, efficient in both space and time, and to offer macros similar to x86 ops.<br>
-The generic stl macro should look like `macro_name n dst src` for an n-bit/hex variable, with dst being the destination-variable, and src being source-variable. (e.g. `hex.add n, dst, src`). 
+The FlipJump stl should be minimalistic, efficient in both space and time, and offer macros similar to x86 ops.
+
+The generic stl macro should look like `macro_name n dst src` for an n-bit/hex variable, with dst being the destination-variable, and src being the source-variable. (e.g. `hex.add n, dst, src`). 
 
 If you find yourself wishing for a feature that doesn't exist, you are probably not alone. Some features that FlipJump has today have been added because our users saw the need. Open an issue on our issues list on GitHub which describes the feature you would like to see, why you need it, and how it should work.
 

README.md

@@ -105,10 +105,10 @@ Hello, World!
 - The first line will assemble your code.
 - The second line will run your code.
 
-You can also use the faster (stable, but still in development) cpp-based interpreter (currently in a [different branch](https://github.com/tomhea/flip-jump/tree/cpp-interpreter/src/cpp_fji)):
+You can also use the faster [cpp-based interpreter](https://github.com/tomhea/fji-cpp):
 
 ```bash
->>> fji hello.fjm
+>>> fji hello.fjm -s
 Hello, World!
 ```
 
@@ -123,11 +123,7 @@ Hello, World!
   - assembler.py    - assembles the macro-less fj file.
   - [more...](src/README.md)
 
-other branches:
-  - [cpp_fji/](https://github.com/tomhea/flip-jump/tree/cpp-interpreter/src/cpp_fji)        - the cpp interpreter (much faster, about 2Mfj/s).
-  - [riscv2fj/](https://github.com/tomhea/flip-jump/tree/riscv2fj/src/riscv2fj)             - translates a riscv-executable to an equivalent fj code.
-
-**[stl](stl)** (standard library files - macros. [list of all macros](https://esolangs.org/wiki/FlipJump#The_Standard_Library)):
+**[stl](stl/README.md)** (standard library files - macros. [list of all macros](https://esolangs.org/wiki/FlipJump#The_Standard_Library)):
   - runlib.fj   - constants and initialization macros.
   - bitlib.fj   - macros for manipulating binary variables and vectors (i.e. numbers).
   - mathlib.fj  - advanced math macros (mul/div).

stl/README.md

@@ -0,0 +1,75 @@
+# FlipJump Standard Library
+
+The stl is a collection of FlipJump files, each a collection of **highly-optimized** and **[tested](../tests)** macros, that are free to use by any FlipJump program that may benefit from it.
+
+It mainly offers binary/hexadecimal data-structures, mathematical and logical operations, conditional jumps, pointers, casting, and input/output.
+
+These FlipJump files result from a lot of research, runs, and tests. 
+
+**@note**: The faster mathematical macros are under the `hex` namespace.
+
+
+# The Files
+
+### [runlib.fj](runlib.fj)
+This file contains constants and initialization macros.
+
+**@note**: It should be the first file in the compilation order.
+
+### [bitlib.fj](bitlib.fj)
+Defines the `bit` data-structure (for binary variables).
+
+Offers macros for manipulating binary variables and vectors (i.e. numbers).
+
+You can find conditional jumps, memory manipulations, and logical and arithmetical macros. 
+
+### [mathlib.fj](mathlib.fj)
+Offers multiplication and division macros for bit/hex variables.
+
+**@note**: The hex.div fails test as for now. You can use the bit version and castings.
+
+### [hexlib.fj](hexlib.fj)
+Defines the `hex` data-structure (for hexadecimal variables), which is smaller and faster than `bit`. 
+
+Offers macros for manipulating hexadecimal variables and vectors (i.e. numbers).
+
+You can find conditional jumps, memory manipulations, and logical and arithmetical macros. 
+
+### [declib.fj](declib.fj)
+Defines the `dec` data-structure (for decimal variables).
+
+It is not implemented yet, but it would offer conditional jumps, memory manipulations, and arithmetical macros for manipulating decimal variables. 
+
+### [iolib.fj](iolib.fj)
+Offers outputting chars, strings. also outputting bit and hex variables as binary, hexadecimal, ascii, or decimal.
+
+Offers input macros for the bit and hex variables, as numbers or as ascii.
+
+Offers casting between different variable types.
+
+### [ptrlib.fj](ptrlib.fj)
+Offers the concept of pointers, i.e. reading, jumping to, and flipping bits, directly from a pointer (i.e. a bit-variable that holds an address).
+
+Also offers a stack and functions based on these pointers.
+
+### [conf.json](conf.json)
+A configurable json file that maintains ordered lists of the standard library files. 
+
+
+# Contribute
+
+The FlipJump philosophy is to be the simplest language of all, that can do any modern computation.
+
+FlipJump should be below the OS, as it's a cpu-architecture after all.
+
+The FlipJump stl should be minimalistic, efficient in both space and time, and offer macros similar to x86 ops.
+
+The generic stl macro should look like `macro_name n dst src` for an n-bit/hex variable, with dst being the destination-variable, and src being the source-variable.
+- e.g. the [hexlib.fj](hexlib.fj) / `hex.add n, dst, src`. 
+
+
+# Read More
+
+You can explore the full list of all macros from the [esolang page](https://esolangs.org/wiki/FlipJump#The_Standard_Library).
+
+If you are new to the FlipJump standard-library, Start by reading the [bitlib.fj](stl/bitlib.fj) standard library file (start with `xor`, `if`). That's where the FlipJump magic begins.