<commit_before># fjorton

The `fjorton` library is a proof-of-concept to bring some
Forth features to the Python world.

The idea is quite simple. Python silently drops every
reference, left on the stack without use. E.g. this code:
```python

def f():
    (2, 3, 4)
    do_something

```

normally will be translated by Python2 into that bytecode:
```
    ...
    (LOAD_CONST, (2, 3, 4)),  # put the symbol on the stack
    (POP_TOP, None),          # dismiss it
    (LOAD_GLOBAL, "do_something"),  # again...
    (POP_TOP, None),                # ... and dismiss
    ...
```

Basicall, the `fjorton` library changes the bytecode, so the
referenced symbols aren't dropped, but either saved to the
implicit stack, or called as a function.

More precise, tha `@fjorton` decorator does following steps:

1. Tries to load `stack` variable from arguments; if there is
   no `stack` argument, creates an empty `___stack___`.
2. Pushes every object, that is being dropped by `POP_TOP` and
   has no `__call__` attribute, to the `___stack___`.
3. Every object, that is being dropped by `POP_TOP` and has
   `__call__` attribute, instead is being called with
   `___stack___` as the only positional argument.
4. Every `return` or `return None` is being replaced with
   `return locals()['___stack___']`.

E.g.:
```python

from fjorton import fjorton


def add(stack):
    # pushes to the stack the sum of two
    # last stack cells
    stack.append(stack.pop() + stack.pop())


@fjorton
def f():
    #     # here the stack is being created
    56,   # 56 is pushed to the stack
    67,   # 67 is pushed to the stack
    add   # `add()` is being called as `add(locals()['___stack___'])`
    #     # here the function returns the stack

f() == [123]
```

Short Q'n'A:

* *Why `56,` not `56`?* -- 'Cause Python optimizes out all simple literals
  to be dropped by `POP_TOP`, so they simply disappear from the bytecode.
  The `56,` statement creates a tuple, and it will remain in the bytecode,
  so we have a chance to work with it. The library translates one-cell tuples
  into simple references.
* *Why `[123]`, not `123`?* -- 'Cause it's a stack, it's a list. In that case
  it contains only one cell. But that's not the rule.
* *May the function body contain normal Python code?* -- Sure. The library
  just extends the code a bit in a compatible (I hope so) way.
* *Why should I use the library?* -- You should **not**. It's made just for
  fun, it is against all the Python rules, so please avoid to use it in the
  production.
* *Will Python3 be supported?* -- Maybe.<commit_msg>readme update<commit_after>fjorton
=======

The `fjorton` library is a proof-of-concept to bring some
Forth features to the Python world.

The idea is quite simple. Python silently drops every
reference, left on the stack without use. E.g. this code::

    def f():
        (2, 3, 4)
        do_something


normally will be translated by Python2 into that bytecode::
    ...
    (LOAD_CONST, (2, 3, 4)),        # put the symbol on the stack
    (POP_TOP, None),                # dismiss it
    (LOAD_GLOBAL, "do_something"),  # again...
    (POP_TOP, None),                # ... and dismiss
    ...

The `fjorton` library changes the bytecode, so the referenced
symbols aren't dropped, but either saved to the implicit stack,
or called as a function.

If the object is callable Python object -- a function, an object
with `.__call__()` method -- `fjorton` will call it, otherwise the
reference will be pushed onto the stack.

There known limitations:

* The library doesn't recognise object methods/attributes as callable
  (yet; that will be fixed later)
* The library doesn't handle built-in or C methods, since it's
  impossible to get their signature and properly map the stack to
  the arguments.

The code sample::

    import fjorton

    @fjorton.func
    def add(a, b):
        a + b


    @fjorton.func
    def test():
        56,
        67,
        add

    assert test() == [123]


Short Q'n'A:

* *Why `56,` not `56`?* -- 'Cause Python optimizes out all simple literals
  to be dropped by `POP_TOP`, so they simply disappear from the bytecode.
  The `56,` statement creates a tuple, and it will remain in the bytecode,
  so we have a chance to work with it. The library translates one-cell tuples
  into simple references.
* *Why `[123]`, not `123`?* -- 'Cause it's a stack, it's a list.
* *May the function body contain normal Python code?* -- Sure. The library
  just extends the code a bit in a compatible (I hope so) way.
* *Why should I use the library?* -- You should **not**. It's made just for
  fun, it is against all the Python rules, so please avoid to use it in the
  production.
* *Will Python3 be supported?* -- Maybe.
{'fraction_non_alphanumeric': 0.099343359457742, 'fraction_numerical': 0.013132810845159923, 'mean_word_length': 3.02901023890785, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3535707', 'n_tokens_mistral': 1504, 'n_tokens_neox': 1411, 'n_words': 682}