Merge pull request #188 from tomhea/dev

Dev - reformat src, update readme, compressed version

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[[email protected]](mailto:[email protected]).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Introduction
+First off, thank you for considering contributing to FlipJump. It's people like you that make the esoteric language community such a great, active and evolving community.
+
+Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
+
+FlipJump is an open source project, and we love to receive contributions from our community — you!<br> 
+There are many ways to contribute, from writing tutorials or blog posts, writing new fj-programs, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into the FlipJump source / standard-library itself.
+
+Also, please take 2 minutes to show this project to the people you know that would **see the magic in this language.**
+
+Please, don't use the issue tracker for support-questions. Instead, use the [Questions thread](https://github.com/tomhea/flip-jump/discussions/176), or the [Discussions](https://github.com/tomhea/flip-jump/discussions) in general. 
+
+## Responsibilities
+ * Ensure cross-platform compatibility for every change that's accepted. Windows & Ubuntu Linux.
+ * Ensure that code that goes into core passes the --regular [tests](tests/README.md).
+ * Create issues (+Discussions) for any major changes and enhancements that you wish to make. Discuss things transparently and get community feedback.
+ * Don't change the stl-api, only offer new options. feel free to discuss it first.
+ * Keep each PR as small as possible, preferably one new change/feature per PR.
+ * Be welcoming to newcomers and encourage diverse new contributors from all backgrounds. See the [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
+
+## Your First Contribution
+Unsure where to begin contributing to FlipJump? You can start by creating and running your own FlipJump programs, on your own repos, and spread the rumor :)<br>
+Also, please take a look at the [Contribution thread](https://github.com/tomhea/flip-jump/discussions/148).
+
+Working on your first Pull Request? You can learn how from this free series, [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github).
+
+At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first 😸
+
+If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed, and that you need to update your branch, so it's easier to merge.
+
+# Getting started
+1. Create your own fork of the code
+2. Do the changes in your fork (keep them minimal).
+3. If you like the change and think the project could use it:
+    * Be sure you have followed the [code style](CONTRIBUTING.md#clean-code) for the project.
+    * be sure your project passes the --regular [tests](tests/README.md).
+    * Send a pull request.
+
+If you have **small or "obvious" fixes**, include SMALLFIX in the PR/issue name.
+such fixes can be:
+* Spelling / grammar fixes
+* Typo correction, white space and formatting changes
+* Comment clean up
+* Functions/Classes rearrangements in the same file
+It should still pass the --regular tests.
+
+# How to report a bug
+When filing an issue, make sure to answer these five questions:
+
+ 1. What version of FlipJump are you using (if no version, make sure you fetched the last changes, and specify the branch name)?
+ 2. What operating system are you using?
+ 3. What did you do?
+ 4. What did you expect to see?
+ 5. What did you see instead?
+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.
+
+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`). 
+
+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.
+
+## Code review process
+After feedback has been given to the Pull Request, we expect responses within two weeks. After two weeks we may close the pull request if it isn't showing any activity.
+
+# Community
+You can chat with the core team and the community on [GitHub Discussions](https://github.com/tomhea/flip-jump/discussions).
+
+# Clean Code
+Get familiar with [Clean Code](https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29) (mainly the functions/names sections).
+
+In short:
+- use **clear names** (full words, **descriptive**, not-too-long), for variables, functions/macros (verb-name), and classes (nouns).
+- **functions should do exactly one thing**. no side effects. They should be **very short** (and call other descriptive functions). IT IS POSSIBLE for a function to be 4-5 lines (and we should aim to that). 
+
+Keep in mind that the developers of this community invested much of their time in making this project as clean, simple, and documented as they can. 
+
+If you find a piece of code that isn't compliant with this standard, it probably has an open issue and is known, and if not, please open a new issue.  
+
+Follow this rule but don't try to be perfect, and use the [80/20](https://en.wikipedia.org/wiki/Pareto_principle) principle. Yet, make an effort to make the code as simple, as much as you'd expect from others in this project's community.
+

README.md

@@ -1,6 +1,8 @@
 # FlipJump
 
 FlipJump is the simplest programing language.<br>
+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`
 
@@ -10,6 +12,9 @@ The operation takes 2 memory addresses - it flips (inverts) the bit the first ad
 
 This project is a **Macro Assembler**, an **Interpreter** and a **Tested Standard Library** to the language.
 
+This calculator was built with only FlipJump ([source](programs/calc.fj)):
+![Calculations using only FlipJump](res/calc.gif)
+
 ## Hello, World!
 
 A simple fj [hello-world](programs/print_tests/hello_no-stl.fj) program, not using the standard library:
@@ -18,21 +23,21 @@ A simple fj [hello-world](programs/print_tests/hello_no-stl.fj) program, not usi
 def startup @ code_start > IO  {
     ;code_start
   IO:
-    ;0
+    ;0              // the second op is reserved for Input/Output.
   code_start:
 }
 
 
 def output_bit bit < IO {
-    IO + bit;
+    IO + bit;       // flipping IO+0 outputs 0; flipping IO+1 outputs 1.
 }
 def output_char ascii {
     rep(8, i) output_bit ((ascii>>i)&1)
 }
 
 def end_loop @ loop_label {
     loop_label:
-    ;loop_label
+    ;loop_label     // fj finishes on a self loop
 }
 
     startup
@@ -44,6 +49,7 @@ def end_loop @ loop_label {
     output_char 'o'
     output_char ','
     output_char ' '
+
     output_char 'W'
     output_char 'o'
     output_char 'r'
@@ -78,20 +84,21 @@ Cloning into 'flip-jump'...
 ```bash
 >>> python src/fj.py programs/hello_world.fj
 Hello, World!
->>> python src/fj.py programs/hello_no-stl.fj --no-stl
-Hello, World!
 ```
-  - The --no-stl flag tells the assembler not to include the standard library. The flag is needed as we implemented the macros ourselves.
+![Hello World in FlipJump](res/hello.gif)
+
+  - The --no-stl flag tells the assembler not to include the standard library. for example: `python src/fj.py programs/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 `python src/fj.py -h` 
+  - you can find all the different flags with `python src/fj.py -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
->>> fja.py hello.fj -o hello_world.fjm
->>> fji.py hello.fjm
+>>> fj.py --asm hello.fj -o hello_world.fjm
+>>> fj.py --run hello_world.fjm
 Hello, World!
 ```
 
@@ -105,22 +112,20 @@ You can also use the faster (stable, but still in development) cpp-based interpr
 Hello, World!
 ```
 
-
 # Project Structure
 
-**[src](src)** (assembler + interpreter source files):
+**[src](src/README.md)** (assembler + interpreter source files):
+  - fj.py           - the FlipJump Assembler & Interpreter script.
+  - fjm.py          - read/write .fjm (flip-jump-memory) files.
+  - fjm_run.py      - interpret / debug assembled fj files.
   - fj_parser.py    - pythonic lex/yacc parser.
   - preprocessor.py - unwind all macros and reps.
-  - assembler.py    - assembles the macroless fj file.
-  - fjm_run.py      - interpreter assembled fj files.
-  - defs.py         - classes/functions/constants used throughout the project.
-  - fjm.py          - read/write .fjm (flip-jump-memory) files.
-  - fja.py          - the FlipJump Assembler script.
-  - fji.py          - the FlipJump Interpreter script.
-  - fj.py           - the FlipJump Assembler & Interpreter script.
+  - 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.
+  - [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)):
   - runlib.fj   - constants and initialization macros.
@@ -137,12 +142,12 @@ other branches:
   - [calc.fj](programs/calc.fj)     - command line calculator for 2 hex/dec numbers: ```a [+-*/%] b```.
   - [func_tests/](programs/func_tests)     - performs function calls and operations on stack.
   - [hexlib_tests/](programs/hexlib_tests)   - tests for the macros in stl/hexlib.fj.
-  - [quine16.fj](programs/quine16.fj)  - a 16-bits quine by [lestrozi](https://github.com/lestrozi); prints itself.
+  - [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)  - simulating the concept of a Class 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)** (FlipJump programs), for example:
+**[tests](tests/README.md)** (FlipJump programs), for example:
   - compiled/   - the designated directory for the assembled tests files.
   - inout/      - .in and .out files for each test in the folder above.
   - conftest.py - pytest configuration file.
@@ -158,8 +163,11 @@ A very extensive explanation can be found on the [GitHub wiki page](https://gith
 
 More detailed explanation and the **specifications of the FlipJump assembly** can be found on the [FlipJump esolangs page](https://esolangs.org/wiki/FlipJump).
 
-Start by reading the [bitlib.fj](stl/bitlib.fj) standard library file. That's where the FlipJump magic begins.
+Read more about the [flip-jump source files](src/README.md) and [how to run the tests](tests/README.md). 
+
+If you want to contribute to this project, read the [CONTRIBUTING.md](CONTRIBUTING.md) file, and take a look at the [Discussions](https://github.com/tomhea/flip-jump/discussions/148).
+
+If you are new to FlipJump and you want to learn how modern computation can be executed using FlipJump, Start by reading the [bitlib.fj](stl/bitlib.fj) standard library file (start with `xor`, `if`). That's where the FlipJump magic begins.
 
-If you want to contribute to this project, open a pull request, and start [Discussing](https://github.com/tomhea/flip-jump/discussions/148).
+You can also write and run programs for yourself! It is just [that](README.md#how-to-run) easy :)
 
-You can also write and run programs for yourself! It is just [that](#how-to-run) easy :)