flipjump 1.2.0__tar.gz

flipjump-1.2.0/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2023, Tom Herman
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

flipjump-1.2.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.1
+Name: flipjump
+Version: 1.2.0
+Summary: The single instruction language - Flip a bit, then Jump
+Home-page: https://esolangs.org/wiki/FlipJump
+License: BSD-2-Clause-Simplified
+Keywords: esolang,oisc,assembly
+Author: Tom Herman
+Author-email: flipjumpproject@gmail.com
+Requires-Python: >=3.7,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Other
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Assemblers
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: Software Development :: Libraries
+Provides-Extra: stats
+Provides-Extra: tests
+Requires-Dist: easygui (>=0.98.3,<0.99.0)
+Requires-Dist: plotly (>=5.16.1,<6.0.0) ; extra == "stats"
+Requires-Dist: pytest (>=7.4.0,<8.0.0) ; extra == "tests"
+Requires-Dist: pytest-ordering (>=0.6,<0.7) ; extra == "tests"
+Requires-Dist: pytest-xdist (>=3.3.1,<4.0.0) ; extra == "tests"
+Requires-Dist: sly (>=0.4,<0.5)
+Project-URL: Documentation, https://github.com/tomhea/flip-jump/wiki
+Project-URL: Repository, https://github.com/tomhea/flip-jump
+Description-Content-Type: text/markdown
+
+# FlipJump
+
+[![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/tomhea/flip-jump)](https://github.com/tomhea/flip-jump#project-structure)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/tomhea/flip-jump)](https://github.com/tomhea/flip-jump/releases/latest)
+[![GitHub Discussions](https://img.shields.io/github/discussions/tomhea/flip-jump)](https://github.com/tomhea/flip-jump/discussions)
+[![GitHub](https://img.shields.io/github/license/tomhea/flip-jump)](LICENSE)
+[![Website](https://img.shields.io/website?down_color=red&down_message=down&up_message=up&url=https%3A%2F%2Fesolangs.org%2Fwiki%2FFlipJump)](https://esolangs.org/wiki/FlipJump)
+[![PyPI - Version](https://img.shields.io/pypi/v/flipjump)](https://pypi.org/project/flipjump/)
+
+FlipJump is the simplest programing language.  
+Yet, it can do **any modern computation**.
+
+It's an Esoteric language ([FlipJump esolangs page](https://esolangs.org/wiki/FlipJump)), with just 1 operation `a;b`:  
+- `not *a; jump b`
+
+Which means - **Flip** a bit, then **Jump**.
+
+The operation takes 2 memory addresses - it flips (inverts) the bit the first address points to, and jumps to (continue execution from) the second address. The next opcode is the two memory-addresses found right where you jumped to. You flip and jump again, and so on...  
+
+
+This project includes a **Macro Assembler**, an **Interpreter**, and a **Thoroughly Tested Standard Library** for the FlipJump language.  
+Additionally, it provides a **Python Library** that makes it easy to work with those components.
+
+This calculator was built with only FlipJump ([source](programs/calc.fj)):
+![Calculations using only FlipJump](res/calc.gif)
+
+## Hello, World!
+
+<details>
+  <summary>A simple hello-world flipjump program, not using the standard library:</summary>
+(jump to the source code)
+
+```c
+// define macros that will be used later
+
+// this macro exports the "IO" label to be a global label
+def startup @ code_start > IO  {
+    ;code_start
+  IO:
+    ;0              // the second op is reserved for Input/Output.
+  code_start:
+}
+
+// this macro gets one parameter "bit", and uses the global label "IO".
+def output_bit bit < IO {
+    IO + bit;       // flipping IO+0 outputs 0; flipping IO+1 outputs 1.
+}
+def output_char ascii {
+    // the next line will be unwinded into 8 output_bit macro-uses, each with a different parameter
+    rep(8, i) output_bit ((ascii>>i)&1)
+}
+
+def end_loop @ loop_label {
+    loop_label:
+    ;loop_label     // a flipjump program finishes on a self loop
+}
+
+
+// The first lines of actual code:
+
+    startup
+    
+    output_char 'H'
+    output_char 'e'
+    output_char 'l'
+    output_char 'l'
+    output_char 'o'
+    output_char ','
+    output_char ' '
+    
+    output_char 'W'
+    output_char 'o'
+    output_char 'r'
+    output_char 'l'
+    output_char 'd'
+    output_char '!'
+    
+    end_loop
+
+```
+
+The source code can be found here: [hello_no-stl.fj](programs/print_tests/hello_no-stl.fj).
+
+The FlipJump assembly supports a ```"Hello, World!"``` syntax for initializing a variable with a string value.
+Look at the [hello_world.fj](programs/print_tests/hello_world.fj) program for more info.
+
+Note that all of these macros are already implemented in the standard library (all in [runlib.fj](flipjump/stl/runlib.fj)):
+- startup
+- end_loop     (loop)
+- output_char
+- output       (for printing string consts, e.g. output "Hello, World!")
+</details>
+
+
+# How to install?
+
+```shell
+pip install flipjump
+```
+
+You can also install it with its extras:
+- flipjump[**stats**]: support for viewing macro usage in an interactive graph.
+- flipjump[**tests**]: all the testing libraries needed.
+```shell
+pip install flipjump[stats,tests]
+```
+
+
+Pycharm Extensions:
+- Add <span style="color:orange">syntax highlighting</span> support for *.fj files - just import the [PycharmHighlighting.zip](ide-extensions/pycharm/PycharmHighlighting.zip) settings.
+- Add a ctrl+shift+click (find fj-macro definition) functionality by using the [AutoHotKey script](ide-extensions/pycharm/fj-pycharm-def-finder.ahk).
+
+# How to run?
+
+Use the `fj` utility:
+```shell
+fj hello_world.fj
+```
+
+![Hello World in FlipJump](res/hello.gif)
+
+  - The --no-stl flag tells the assembler not to include the standard library. for example: `fj programs/print_tests/hello_no-stl.fj --no-stl`.
+  - the -w [WIDTH] flag allows compiling the .fj files to a WIDTH-bits memory width. WIDTH is 64 by default.
+  - You can use the -o flag to save the assembled file for later use too.
+  - you can find all the different flags with `fj -h`.
+
+You can also **[Test the project](tests/README.md)** with the project's tests, and with your tests.
+
+You can also assemble and run separately:
+
+```bash
+fj --asm hello.fj -o hello_world.fjm
+fj --run hello_world.fjm
+```
+
+- The first line will assemble your code.
+- The second line will run your code.
+
+You can also use the faster [cpp-based interpreter](https://github.com/tomhea/fji-cpp):
+
+```bash
+>>> fji hello.fjm -s
+Hello, World!
+```
+
+### How to Debug?
+Programs won't work on their first run. They just can't. That's why we support the next debugging flags.
+
+- No debugging flags at all: Shows the last 10 executed addresses of tests that failed their run (i.e. finished not by looping). 
+- `-d [PATH]`: Save debug information: Adds [very extensive label names](tests/README.md#example-label-name-youll-get-with-using---debuginfo-len), Which are like a "**macro-stack**" for each of the last executed address. (can be used with `--debug-ops-list LEN`)
+- `--debug-ops-list LEN`: Shows the last _LEN_ executed addresses (instead of 10). (can be used with `-d`)
+- `-b NAME [NAME ...]`: Places breakpoints at every specified label NAMEs (note that label names are long: [more information about labels](flipjump/README.md#generated-label-names)). (requires `-b`)
+- `-B NAME [NAME ...]`: Places breakpoints at every label that contains one of the given NAMEs. (requires `-b`)
+
+
+# Get Started with FlipJump
+- Install flipjump: `pip install flipjump`
+- Write your flipjump program (use the [stl - standard library](flipjump/stl/README.md) macros).
+  - For example: [print_dec.fj](programs/print_tests/print_dec.fj).
+- assemble+run your program: `fj print_dec.fj`
+
+### Example usage of the flipjump python library
+```python
+from pathlib import Path
+from flipjump import assemble_and_run  # assemble, run_test_output, ...
+
+fj_file_paths = [Path('path/to/main.fj'), Path('path/to/consts.fj')]
+termination_statistics = assemble_and_run(fj_file_paths)
+```
+
+_You can also use the `flipjump.assemble_run_according_to_cmd_line_args(cmd_line_args=[...])`._
+
+
+# Project Structure
+
+**[flipjump](flipjump/README.md)** (assembler + interpreter source files):
+  - [flipjump_cli.py](flipjump/flipjump_cli.py) - Main CLI script fot the FlipJump Assembler & Interpreter.
+  - [fjm/](flipjump/fjm) - Tools for reading/writing .fjm (flip-jump-memory) files.
+  - [interpreter/fjm_run.py](flipjump/interpretter/fjm_run.py) - Interpreter + debugger for assembled fj files.
+  - [assembler/](flipjump/assembler) - Components for assembling FlipJump code.
+    - [fj_parser.py](flipjump/assembler/fj_parser.py) - Pythonic lex/yacc parser.
+    - [preprocessor.py](flipjump/assembler/preprocessor.py) - Unwinds all macros and reps (repetitions).
+    - [assembler.py](flipjump/assembler/assembler.py) - Assembles macro-less fj files.
+  - [more...](flipjump/README.md) - Additional project files and documentation.
+
+**[flipjump/stl](flipjump/stl/README.md)** (standard library files - macros. The [stl readme](flipjump/stl/README.md#the-files) contains the list of all macros):
+  - runlib.fj - Constants and initialization macros. Output constant strings.
+  - [bit/](flipjump/stl/README.md#bit) - Directory of stl files. Macros for io/manipulating binary variables and vectors (i.e. numbers): math, logic, conditional jumps, pointers, casting, IO, ...
+  - [hex/](flipjump/stl/README.md#hex) - Directory of stl files. Macros for io/manipulating hexadecimal variables and vectors (i.e. numbers): math, logic, conditional jumps, pointers, casting, IO, ...
+  - mathlib.fj - Advanced math macros (mul/div).
+  - casting.fj - Macros for casting between bit/hex.
+  - ptrlib.fj - Macros for working with pointers, stacks, and functions.
+  - conf.json - The list of the standard library files.
+
+**[programs](programs)** (flipjump programs, used by the tests), for example:
+  - [hello_world.fj](programs/print_tests/hello_world.fj) - Prints "hello world :)"
+  - [calc.fj](programs/calc.fj) - A command-line calculator for 2 hex/dec numbers: ```a [+-*/%] b```.
+  - [func_tests/](programs/func_tests) - Programs for testing function calls and stack operations.
+  - [hexlib_tests/](programs/hexlib_tests) - Tests for all the hex macros, except the hex.pointers.
+  - [quine16.fj](programs/quine16.fj) - A 16-bits quine by [lestrozi](https://github.com/lestrozi); when assembled with `-w16 -v0` - prints itself.
+  - [pair_ns.fj](programs/concept_checks/pair_ns.fj) - Simulates the concept of a Class, by using a namespace.
+  - [print_dec.fj](programs/print_tests/print_dec.fj) - Prints binary variables as decimals.
+  - [multi_comp/](programs/multi_comp) - Simulates a big project (compilation of multiple files).
+
+**[tests](tests/README.md)** (tests compiling+running the programs with the stl), for example:
+  - compiled/ - The designated directory for the assembled tests files.
+  - inout/ - Contains the .in and .out files for each test.
+  - conftest.py - The pytest configuration file. The tests are being generated here.
+  - test_fj.py - The base test functions for compilation and running ([how to run](tests/README.md#run-the-tests)).
+  - test_compile_*.csv - Arguments for the compile tests ([compile test arguments format](tests/README.md#compile-csvs-format)).
+  - test_run_*.csv - Arguments for the run tests ([run test arguments format](tests/README.md#run-csvs-format)).
+  - conf.json - The tests groups+order lists.
+  - xfail_*.csv - [xfail](https://docs.pytest.org/en/7.1.x/how-to/skipping.html#xfail-mark-test-functions-as-expected-to-fail) these tests.
+
+
+# Read More - Extra Documentation
+
+Take a look at the other READMEs:
+* Read more about the [assembler/interpreter source files](flipjump/README.md).    
+* Read more about [how to run the tests](tests/README.md).
+* Read more about the [standard library](flipjump/stl/README.md).
+
+A very extensive explanation can be found on the [GitHub wiki page](https://github.com/tomhea/flip-jump/wiki/Learn-FlipJump).
+
+More detailed explanation and the **specifications of the FlipJump assembly** can be found on the [FlipJump esolangs page](https://esolangs.org/wiki/FlipJump).
+
+If you are new to FlipJump and you want to learn how modern computation can be executed using FlipJump, and you want to jump onto your first flipjump code - Start by reading the [bit.xor](flipjump/stl/bit/logics.fj) and [bit.if](flipjump/stl/bit/cond_jumps.fj) macros. That's where the FlipJump magic begins.  
+If you want to understand how the deep optimized hex macros work, understand how the next macros are implemented: [hex.exact_xor](flipjump/stl/hex/logics.fj), [hex.output](flipjump/stl/hex/output.fj), [hex.inc1](flipjump/stl/hex/math_basic.fj), and [hex.add](flipjump/stl/hex/math.fj) (understand the concept of the [lookup tables](https://esolangs.org/wiki/FlipJump#Lookup_Tables).
+
+You can also write and run programs for yourself! It is just [that](README.md#how-to-run) easy :)
+
+
+# Contribute
+
+If you want to contribute to this project, read the [CONTRIBUTING.md](CONTRIBUTING.md) file, and take a look at the [I-Want-To-Contribute Thread](https://github.com/tomhea/flip-jump/discussions/148).
+
+Actually, just writing your own flipjump programs and sharing them with the world is a great contribution to the community :)  
+Take a look at what the [standard library](flipjump/stl/README.md) offers, and see some [example programs](programs) to get you inspired!
+

flipjump-1.2.0/README.md

@@ -0,0 +1,238 @@
+# FlipJump
+
+[![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/tomhea/flip-jump)](https://github.com/tomhea/flip-jump#project-structure)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/tomhea/flip-jump)](https://github.com/tomhea/flip-jump/releases/latest)
+[![GitHub Discussions](https://img.shields.io/github/discussions/tomhea/flip-jump)](https://github.com/tomhea/flip-jump/discussions)
+[![GitHub](https://img.shields.io/github/license/tomhea/flip-jump)](LICENSE)
+[![Website](https://img.shields.io/website?down_color=red&down_message=down&up_message=up&url=https%3A%2F%2Fesolangs.org%2Fwiki%2FFlipJump)](https://esolangs.org/wiki/FlipJump)
+[![PyPI - Version](https://img.shields.io/pypi/v/flipjump)](https://pypi.org/project/flipjump/)
+
+FlipJump is the simplest programing language.  
+Yet, it can do **any modern computation**.
+
+It's an Esoteric language ([FlipJump esolangs page](https://esolangs.org/wiki/FlipJump)), with just 1 operation `a;b`:  
+- `not *a; jump b`
+
+Which means - **Flip** a bit, then **Jump**.
+
+The operation takes 2 memory addresses - it flips (inverts) the bit the first address points to, and jumps to (continue execution from) the second address. The next opcode is the two memory-addresses found right where you jumped to. You flip and jump again, and so on...  
+
+
+This project includes a **Macro Assembler**, an **Interpreter**, and a **Thoroughly Tested Standard Library** for the FlipJump language.  
+Additionally, it provides a **Python Library** that makes it easy to work with those components.
+
+This calculator was built with only FlipJump ([source](programs/calc.fj)):
+![Calculations using only FlipJump](res/calc.gif)
+
+## Hello, World!
+
+<details>
+  <summary>A simple hello-world flipjump program, not using the standard library:</summary>
+(jump to the source code)
+
+```c
+// define macros that will be used later
+
+// this macro exports the "IO" label to be a global label
+def startup @ code_start > IO  {
+    ;code_start
+  IO:
+    ;0              // the second op is reserved for Input/Output.
+  code_start:
+}
+
+// this macro gets one parameter "bit", and uses the global label "IO".
+def output_bit bit < IO {
+    IO + bit;       // flipping IO+0 outputs 0; flipping IO+1 outputs 1.
+}
+def output_char ascii {
+    // the next line will be unwinded into 8 output_bit macro-uses, each with a different parameter
+    rep(8, i) output_bit ((ascii>>i)&1)
+}
+
+def end_loop @ loop_label {
+    loop_label:
+    ;loop_label     // a flipjump program finishes on a self loop
+}
+
+
+// The first lines of actual code:
+
+    startup
+    
+    output_char 'H'
+    output_char 'e'
+    output_char 'l'
+    output_char 'l'
+    output_char 'o'
+    output_char ','
+    output_char ' '
+    
+    output_char 'W'
+    output_char 'o'
+    output_char 'r'
+    output_char 'l'
+    output_char 'd'
+    output_char '!'
+    
+    end_loop
+
+```
+
+The source code can be found here: [hello_no-stl.fj](programs/print_tests/hello_no-stl.fj).
+
+The FlipJump assembly supports a ```"Hello, World!"``` syntax for initializing a variable with a string value.
+Look at the [hello_world.fj](programs/print_tests/hello_world.fj) program for more info.
+
+Note that all of these macros are already implemented in the standard library (all in [runlib.fj](flipjump/stl/runlib.fj)):
+- startup
+- end_loop     (loop)
+- output_char
+- output       (for printing string consts, e.g. output "Hello, World!")
+</details>
+
+
+# How to install?
+
+```shell
+pip install flipjump
+```
+
+You can also install it with its extras:
+- flipjump[**stats**]: support for viewing macro usage in an interactive graph.
+- flipjump[**tests**]: all the testing libraries needed.
+```shell
+pip install flipjump[stats,tests]
+```
+
+
+Pycharm Extensions:
+- Add <span style="color:orange">syntax highlighting</span> support for *.fj files - just import the [PycharmHighlighting.zip](ide-extensions/pycharm/PycharmHighlighting.zip) settings.
+- Add a ctrl+shift+click (find fj-macro definition) functionality by using the [AutoHotKey script](ide-extensions/pycharm/fj-pycharm-def-finder.ahk).
+
+# How to run?
+
+Use the `fj` utility:
+```shell
+fj hello_world.fj
+```
+
+![Hello World in FlipJump](res/hello.gif)
+
+  - The --no-stl flag tells the assembler not to include the standard library. for example: `fj programs/print_tests/hello_no-stl.fj --no-stl`.
+  - the -w [WIDTH] flag allows compiling the .fj files to a WIDTH-bits memory width. WIDTH is 64 by default.
+  - You can use the -o flag to save the assembled file for later use too.
+  - you can find all the different flags with `fj -h`.
+
+You can also **[Test the project](tests/README.md)** with the project's tests, and with your tests.
+
+You can also assemble and run separately:
+
+```bash
+fj --asm hello.fj -o hello_world.fjm
+fj --run hello_world.fjm
+```
+
+- The first line will assemble your code.
+- The second line will run your code.
+
+You can also use the faster [cpp-based interpreter](https://github.com/tomhea/fji-cpp):
+
+```bash
+>>> fji hello.fjm -s
+Hello, World!
+```
+
+### How to Debug?
+Programs won't work on their first run. They just can't. That's why we support the next debugging flags.
+
+- No debugging flags at all: Shows the last 10 executed addresses of tests that failed their run (i.e. finished not by looping). 
+- `-d [PATH]`: Save debug information: Adds [very extensive label names](tests/README.md#example-label-name-youll-get-with-using---debuginfo-len), Which are like a "**macro-stack**" for each of the last executed address. (can be used with `--debug-ops-list LEN`)
+- `--debug-ops-list LEN`: Shows the last _LEN_ executed addresses (instead of 10). (can be used with `-d`)
+- `-b NAME [NAME ...]`: Places breakpoints at every specified label NAMEs (note that label names are long: [more information about labels](flipjump/README.md#generated-label-names)). (requires `-b`)
+- `-B NAME [NAME ...]`: Places breakpoints at every label that contains one of the given NAMEs. (requires `-b`)
+
+
+# Get Started with FlipJump
+- Install flipjump: `pip install flipjump`
+- Write your flipjump program (use the [stl - standard library](flipjump/stl/README.md) macros).
+  - For example: [print_dec.fj](programs/print_tests/print_dec.fj).
+- assemble+run your program: `fj print_dec.fj`
+
+### Example usage of the flipjump python library
+```python
+from pathlib import Path
+from flipjump import assemble_and_run  # assemble, run_test_output, ...
+
+fj_file_paths = [Path('path/to/main.fj'), Path('path/to/consts.fj')]
+termination_statistics = assemble_and_run(fj_file_paths)
+```
+
+_You can also use the `flipjump.assemble_run_according_to_cmd_line_args(cmd_line_args=[...])`._
+
+
+# Project Structure
+
+**[flipjump](flipjump/README.md)** (assembler + interpreter source files):
+  - [flipjump_cli.py](flipjump/flipjump_cli.py) - Main CLI script fot the FlipJump Assembler & Interpreter.
+  - [fjm/](flipjump/fjm) - Tools for reading/writing .fjm (flip-jump-memory) files.
+  - [interpreter/fjm_run.py](flipjump/interpretter/fjm_run.py) - Interpreter + debugger for assembled fj files.
+  - [assembler/](flipjump/assembler) - Components for assembling FlipJump code.
+    - [fj_parser.py](flipjump/assembler/fj_parser.py) - Pythonic lex/yacc parser.
+    - [preprocessor.py](flipjump/assembler/preprocessor.py) - Unwinds all macros and reps (repetitions).
+    - [assembler.py](flipjump/assembler/assembler.py) - Assembles macro-less fj files.
+  - [more...](flipjump/README.md) - Additional project files and documentation.
+
+**[flipjump/stl](flipjump/stl/README.md)** (standard library files - macros. The [stl readme](flipjump/stl/README.md#the-files) contains the list of all macros):
+  - runlib.fj - Constants and initialization macros. Output constant strings.
+  - [bit/](flipjump/stl/README.md#bit) - Directory of stl files. Macros for io/manipulating binary variables and vectors (i.e. numbers): math, logic, conditional jumps, pointers, casting, IO, ...
+  - [hex/](flipjump/stl/README.md#hex) - Directory of stl files. Macros for io/manipulating hexadecimal variables and vectors (i.e. numbers): math, logic, conditional jumps, pointers, casting, IO, ...
+  - mathlib.fj - Advanced math macros (mul/div).
+  - casting.fj - Macros for casting between bit/hex.
+  - ptrlib.fj - Macros for working with pointers, stacks, and functions.
+  - conf.json - The list of the standard library files.
+
+**[programs](programs)** (flipjump programs, used by the tests), for example:
+  - [hello_world.fj](programs/print_tests/hello_world.fj) - Prints "hello world :)"
+  - [calc.fj](programs/calc.fj) - A command-line calculator for 2 hex/dec numbers: ```a [+-*/%] b```.
+  - [func_tests/](programs/func_tests) - Programs for testing function calls and stack operations.
+  - [hexlib_tests/](programs/hexlib_tests) - Tests for all the hex macros, except the hex.pointers.
+  - [quine16.fj](programs/quine16.fj) - A 16-bits quine by [lestrozi](https://github.com/lestrozi); when assembled with `-w16 -v0` - prints itself.
+  - [pair_ns.fj](programs/concept_checks/pair_ns.fj) - Simulates the concept of a Class, by using a namespace.
+  - [print_dec.fj](programs/print_tests/print_dec.fj) - Prints binary variables as decimals.
+  - [multi_comp/](programs/multi_comp) - Simulates a big project (compilation of multiple files).
+
+**[tests](tests/README.md)** (tests compiling+running the programs with the stl), for example:
+  - compiled/ - The designated directory for the assembled tests files.
+  - inout/ - Contains the .in and .out files for each test.
+  - conftest.py - The pytest configuration file. The tests are being generated here.
+  - test_fj.py - The base test functions for compilation and running ([how to run](tests/README.md#run-the-tests)).
+  - test_compile_*.csv - Arguments for the compile tests ([compile test arguments format](tests/README.md#compile-csvs-format)).
+  - test_run_*.csv - Arguments for the run tests ([run test arguments format](tests/README.md#run-csvs-format)).
+  - conf.json - The tests groups+order lists.
+  - xfail_*.csv - [xfail](https://docs.pytest.org/en/7.1.x/how-to/skipping.html#xfail-mark-test-functions-as-expected-to-fail) these tests.
+
+
+# Read More - Extra Documentation
+
+Take a look at the other READMEs:
+* Read more about the [assembler/interpreter source files](flipjump/README.md).    
+* Read more about [how to run the tests](tests/README.md).
+* Read more about the [standard library](flipjump/stl/README.md).
+
+A very extensive explanation can be found on the [GitHub wiki page](https://github.com/tomhea/flip-jump/wiki/Learn-FlipJump).
+
+More detailed explanation and the **specifications of the FlipJump assembly** can be found on the [FlipJump esolangs page](https://esolangs.org/wiki/FlipJump).
+
+If you are new to FlipJump and you want to learn how modern computation can be executed using FlipJump, and you want to jump onto your first flipjump code - Start by reading the [bit.xor](flipjump/stl/bit/logics.fj) and [bit.if](flipjump/stl/bit/cond_jumps.fj) macros. That's where the FlipJump magic begins.  
+If you want to understand how the deep optimized hex macros work, understand how the next macros are implemented: [hex.exact_xor](flipjump/stl/hex/logics.fj), [hex.output](flipjump/stl/hex/output.fj), [hex.inc1](flipjump/stl/hex/math_basic.fj), and [hex.add](flipjump/stl/hex/math.fj) (understand the concept of the [lookup tables](https://esolangs.org/wiki/FlipJump#Lookup_Tables).
+
+You can also write and run programs for yourself! It is just [that](README.md#how-to-run) easy :)
+
+
+# Contribute
+
+If you want to contribute to this project, read the [CONTRIBUTING.md](CONTRIBUTING.md) file, and take a look at the [I-Want-To-Contribute Thread](https://github.com/tomhea/flip-jump/discussions/148).
+
+Actually, just writing your own flipjump programs and sharing them with the world is a great contribution to the community :)  
+Take a look at what the [standard library](flipjump/stl/README.md) offers, and see some [example programs](programs) to get you inspired!

flipjump-1.2.0/flipjump/README.md

@@ -0,0 +1,95 @@
+# FlipJump Source Code
+
+In this documentation file you could find information about every python source file in the flipjump module.
+
+## The FlipJump Macro-Assembler
+
+The assembler has 4 steps:
+- parsing the .fj text files into a dictionary of macros and their ops ([fj_parser.py](assembler/fj_parser.py)).
+- resolving (unwinding) the macros (and reps) to get a straight stream of ops ([preprocessor.py](assembler/preprocessor.py)).
+- resolving the label values and getting the ops binary data ([assembler.py](assembler/assembler.py)). 
+- writing the binary data into the executable ([fjm_writer.py](fjm/fjm_writer.py)).
+
+The whole process is executed within the [assemble()](assembler/assembler.py) function.
+![Assembly of calc.fj](../res/calc__asm.jpg)
+
+- The [ops.py](assembler/inner_classes/ops.py) file contains the classes of the different assembly ops.
+- The [expr.py](assembler/inner_classes/expr.py) file contains the expression class (Expr), which is the code's representation of the assembly mathematical expressions. The expressions are based on numbers and labels.
+
+## The FlipJump Interpreter
+
+The Interpreter ([fjm_run.py](interpretter/fjm_run.py)) stores the entire memory in a dictionary {address: value}, and supports unaligned-word access. 
+
+The whole interpretation is done within the [run()](interpretter/fjm_run.py) function (also uses the [fjm_reader.py](fjm/fjm_reader.py) to read the fjm file - i.e. to get the flipjump program memory from the compiled fjm file).  
+More about [how to run](../README.md#how-to-run).
+![Running the compiled calculator](../res/calc__run.jpg)
+
+The Interpreter has a built-in debugger, and it's activated by specifying breakpoints when called (via the [breakpoints.py](interpretter/debugging/breakpoints.py)'s `BreakpointHandler`).
+The debugger can stop on the next breakpoint, or on a fixed number of executed ops after the current breakpoint.
+In order to call the debugger with the right labels, get familiar with the [generating label names](README.md#Generated-Label-Names) (and see the debugger-image there), and use the `-d`/`-b`/`-B` cli options.  
+More about [how to debug](../README.md#how-to-debug).
+
+The [macro_usage_graph.py](interpretter/debugging/macro_usage_graph.py) file exports a feature to present the macro-usage (which are the most used macros, and what % do they take from the overall flipjump ops) in a graph.  
+In order to view it, run the assembler with `--stats` (requires plotly to be installed (installed automatically with `pip install flipjump[stats]`)).  
+For example:
+![The macro-usage statistics of calc.fj](../res/calc_stats.png)
+
+## The Using-FlipJump Files
+
+- The [flipjump_cli.py](flipjump_cli.py) file is the main FlipJump cli-script. run with --help to see its capabilities. The `fj` utility runs the main() of this file.
+- The [flipjump_quickstart.py](flipjump_quickstart.py) file contains the fundamental assemble/run functions that are exposed to the users. They are wrappers to the inner api. These are the functions that will be exported when you `import flipjump`.
+
+### FJM versions
+
+The .fjm file currently has 4 versions:
+
+- Version 0: The basic version
+- Version 1: The normal version (more configurable than the basic version)
+- Version 2: The relative-jumps version (good for further compression)
+- Version 3: The compressed version
+
+You can specify the version you want with the `-v VERSION` flag.  
+The assembler chooses **by default** version **3** if the `--outfile` is specified, and version **1** if it isn't. 
+
+### Generated Label Names
+
+The generated label string is a concatenation of the macro call tree, each separated by '---', and finish with the label local-name.
+
+Each macro call string is as follows:\
+short_file_name **:** line **:** macro_called
+
+So if a->bit.b->hex.c->my_label: (a, bit.b called from file f2 lines 3,5; hex.c from file s1, line 72), the label's name will be:\
+f2:3:a---f2:5:bit.b---s1:72:hex.c---my_label
+
+On a rep-call (on index==i), the macro call string is:\
+short_file_name : line : rep{i} : macro_called\
+for example: f1:32:rep6:hex.print---f2:17:print_bit---print_label
+
+the short_file_name is (by default) s1,s2,s3,... for the standard library files (in the order of [stl/conf.json - all](stl/conf.json)),
+and f1,f2,f3,... for the compiled .fj files, in the order they are mentioned to the compiler (or appear in the test-line).
+
+You can place breakpoints to stop on specific labels using the `-d`, followed by a  `-b` and a label name (or `-B` and a part of a label name). For example:
+![Debugging Demo](../res/breakpoint.jpg)
+
+## More Files
+
+- The [fjm_consts.py](fjm/fjm_consts.py) contains the constants needed for interacting with the fjm format (used by the [fjm_reader.py](fjm/fjm_reader.py) + [fjm_writer.py](fjm/fjm_writer.py)).
+- The [utils/](utils) folder contains common utilities used and shared by the entire project:
+  - [utils/classes.py](utils/classes.py) - contains the common classes used in the entire project
+  - [utils/functions.py](utils/functions.py) - contains the common utility functions used in the entire project
+  - [utils/constants.py](utils/constants.py) - contains the project's constants and definitions.
+  - [utils/exceptions.py](utils/exceptions.py) - contains all the project's exceptions.
+- The [interpreter/io_devices/](interpretter/io_devices) folder contains modules for different Input/Output-handling classes (can be passed as a parameter to the interpreter). 
+  - The standard one is [StandardIO.py](interpretter/io_devices/StandardIO.py), which takes its input from the standard input, and write its output to the standard output.
+  - The tests use the [FixedIO.py](interpretter/io_devices/FixedIO.py), which takes a defined input and remembers its output.
+  - If you want to assert that your program takes no input and generates no output, use the [BrokenIO.py](interpretter/io_devices/BrokenIO.py), which raises exception on every input/output.
+  - Finally, the pure abstract IO handler class - [IODevice.py](interpretter/io_devices/IODevice.py).
+
+# Read More
+
+The FlipJump source is built in a way that allows simple addition of new features.
+
+Every addition should be supported from the parsing level, up to the phase that is disappears (and probably is replaced with some flipjump ops). See the `assemble()` function in [assembler](assembler/assembler.py) to better understand the assembler 'pipeline'.
+
+For example, if you want to add a new operation `a@b` that calculates _a^2+b^2_ or `a!` for _factorial(a)_, it is simple as adding a parsing rule in [fj_parser.py](assembler/fj_parser.py), and then adding the function to the op_string_to_function() in [expr.py](assembler/inner_classes/expr.py). That's it.
+

flipjump-1.2.0/flipjump/__init__.py

@@ -0,0 +1,23 @@
+from flipjump.flipjump_cli import assemble_run_according_to_cmd_line_args
+from flipjump.flipjump_quickstart import (assemble, run, debug, run_test_output,
+                                          assemble_and_run, assemble_and_debug, assemble_and_run_test_output,
+                                          FJMVersion, TerminationCause, TerminationStatistics,
+                                          FixedIO, IODevice, StandardIO)
+from flipjump.utils.exceptions import IODeviceException, FlipJumpException
+from flipjump.interpretter.io_devices.BrokenIO import BrokenIO
+
+
+__all__ = [
+    'assemble_run_according_to_cmd_line_args',
+    'assemble',
+    'run',
+    'debug',
+    'run_test_output',
+    'assemble_and_run',
+    'assemble_and_debug',
+    'assemble_and_run_test_output',
+    'FJMVersion',
+    'TerminationCause',
+    'TerminationStatistics',
+    'FlipJumpException',
+]