updated doc

Author: P4o1o

docs/_sources/basic_operations.rst.txt

@@ -1,241 +1 @@
-Basic Operations
-================
-
-Introduction
-------------
-
-In stack-based programming with Reverse Polish Notation (RPN), operations are performed by manipulating a stack data structure. RPN expressions are written in postfix notation, where operators follow their operands. This allows for efficient calculations without the need for parentheses or precedence rules.
-
-Mathematical Operations
-------------------------
-
-**Addition (+)**
-~~~~~~~~~~~~~~~~
-
-The `+` operator adds two numbers by popping them from the the stack, performing the addition operation, and pushing the result back onto the stack. Both integer and floating-point numbers are supported. If at least one of the operands is a floating-point number, the result will be a floating-point number.
-
-Example:
-
-.. code-block:: text
-
-    5 3 + => 8.0
-
-**Subtraction (-)**
-~~~~~~~~~~~~~~~~~~~
-
-The `-` operator subtracts the first value on the stack from the second value by popping them from the stack, performing the subtraction operation, and pushing the result back onto the stack. Both integer and floating-point numbers are supported. If at least one of the operands is a floating-point number, the result will be a floating-point number.
-
-Example:
-
-.. code-block:: text
-
-    5 3 - => 2.0
-
-**Multiplication (*)**
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The `*` operator multiplies two numbers by popping them from the the stack, performing the multiplication operation, and pushing the result back onto the stack. Both integer and floating-point numbers are supported. If at least one of the operands is a floating-point number, the result will be a floating-point number.
-
-Example:
-
-.. code-block:: text
-
-    5 3 * => 15.0
-
-**Division (/)**
-~~~~~~~~~~~~~~~~
-
-The `/` operator divides the second value on the stack by the first value by popping them from the stack, performing the division operation, and pushing the result back onto the stack. Both integer and floating-point numbers are supported. The result will always be a floating-point number.
-
-Example:
-
-.. code-block:: text
-
-    11 5 / => 2
-
-**Modulus (%)**
-~~~~~~~~~~~~~~~~
-
-The `%` operator calculates the remainder of dividing the second value on the stack by the first value by popping them from the stack, performing the modulus operation, and pushing the result back onto the stack. This operation is only supported for integer numbers.
-
-Example:
-
-.. code-block:: text
-
-    10 3 % => 1
-
-**Exponential (pow)**
-~~~~~~~~~~~~~~~~~~~~~
-
-The `pow` operator raises the second value on the stack to the power of the first value by popping them from the stack, performing the exponentiation operation, and pushing the result back onto the stack. Both integer and floating-point numbers are supported. The result will always be a floating-point number.
-
-Example:
-
-.. code-block:: text
-
-    2 3 pow => 8.0
-
-**Square Root (sqrt)**
-~~~~~~~~~~~~~~~~~~~~~~
-
-The `sqrt` compute the square root of the first value in the stack and pushes the result back onto the stack. Both integer and floating-point numbers are supported. The result will always be a floating-point number.
-
-Example:
-
-.. code-block:: text
-
-    9 sqrt => 3.00000
-
-Boolean Operations
--------------------
-
-**Logical AND (and)**
-~~~~~~~~~~~~~~~~~~~~~
-
-The `and` operator performs a logical AND operation between the first two boolean values on the stack. It pops the two values from the stack, performs the logical AND operation, and pushes the result back onto the stack.
-
-Example:
-
-.. code-block:: text
-
-    true true and => true
-    true false and => false
-
-**Logical OR (or)**
-~~~~~~~~~~~~~~~~~~~~
-
-The `or` operator performs a logical OR operation between the first two boolean values on the stack. It pops the two values from the stack, performs the logical OR operation, and pushes the result back onto the stack.
-
-Example:
-
-.. code-block:: text
-
-    true false or => true
-    false false or => false
-
-**Logical XOR (xor)**
-~~~~~~~~~~~~~~~~~~~~~~
-
-The `xor` operator performs a logical XOR operation between the first two boolean values on the stack. It pops the two values from the stack, performs the logical XOR operation, and pushes the result back onto the stack.
-
-Example:
-
-.. code-block:: text
-
-    true true xor => false
-    true false xor => true
-
-**Logical NOT (not)**
-~~~~~~~~~~~~~~~~~~~~~~
-
-The `not` operator performs a logical NOT operation on the first boolean value on the stack. It pops the value from the stack, performs the logical NOT operation, and pushes the result back onto the stack.
-
-Example:
-
-.. code-block:: text
-
-    true not => false
-    false not => true
-
-Comparison Operations
-----------------------
-
-**Equal (==)**
-~~~~~~~~~~~~~~~
-
-The `==` operator compares the first two values on the stack for equality. It pops two values from the stack, compares them, and pushes `true` if they are equal, otherwise pushes `false`.
-
-Example:
-
-.. code-block:: text
-
-    5 5 == => true
-    5 6 == => false
-
-**Not Equal (!=)**
-~~~~~~~~~~~~~~~~~~~
-
-The `!=` operator compares the first two values on the stack for inequality. It pops the two values from the stack, compares them, and pushes `true` if they are not equal, otherwise pushes `false`.
-
-Example:
-
-.. code-block:: text
-
-    5 5 != => false
-    5 6 != => true
-
-**Less Than (<)**
-~~~~~~~~~~~~~~~~~~
-
-The `<` operator compares the first two values on the stack. It pops the two values from the stack, compares them, and pushes `true` if the second value is greater than the first, otherwise pushes `false`.
-
-Example:
-
-.. code-block:: text
-
-    5 6 < => true
-    6 5 < => false
-    5 5 < => false
-
-**Greater Than (>)**
-~~~~~~~~~~~~~~~~~~~~~
-
-The `>` operator compares the first two values on the stack. It pops the two values from the stack, compares them, and pushes `true` if the first value is greater than the second, otherwise pushes `false`.
-
-Example:
-
-.. code-block:: text
-
-    5 6 > => false
-    6 5 > => true
-    5 5 > => false
-
-**Less Than or Equal To (<=)**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The `<=` operator compares the first two values on the stack. It pops the two values from the stack, compares them, and pushes `true` if the second value is greater than or equal to the first, otherwise pushes `false`.
-
-Example:
-
-.. code-block:: text
-
-    5 6 <= => true
-    6 5 <= => false
-    5 5 <= => true
-
-**Greater Than or Equal To (>=)**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The `>=` operator compares the first two values on the stack. It pops the two values from the stack, compares them, and pushes `true` if the first value is greater than or equal to the second, otherwise pushes `false`.
-
-Example:
-
-.. code-block:: text
-
-    5 6 >= => false
-    6 5 >= => true
-    5 5 >= => true
-
-
-Type Casting
-------------
-
-**Integer Casting (int)**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The `int` operator converts a floating-point number on the stack to an integer by truncating the decimal part. It pops a value from the stack, performs the conversion, and pushes the integer result back onto the stack.
-
-Example:
-
-.. code-block:: text
-
-    5.7 int => 5
-    3.14 int => 3
-
-Exit Operation
---------------
-
-**Exit (exit)**
-~~~~~~~~~~~~~~~~
-
-The `exit` operation terminates the execution of the program.
+.. include:: _sources/basic_operations.rst.txt

docs/_sources/examples.rst.txt

@@ -1,45 +1 @@
-Code Examples
-=============
-
-
-Example 1
----------
-
-We want to define an instruction that fill the stack with a value `value`, many times as going from the value `from` to the value `to`.
-We can do it in different ways:
-
-Here we define the instruction an give to it the desired values by defining also them as instructions
-
-.. code-block:: text
-
-    [from [value swap(size 1 -) 1 + dup to < swap swap(size 1 -) swap] loop swap(size 1 -) drop] define(fill)
-
-    [0] define(from) [10] define(to) [3.1415926535897932] define(value)
-
-    fill
-
-Alternatively we assume that the values are in the stack in this order: `from to value`
-
-.. code-block:: text
-
-    [[swap(size 1 -) 1 + dup] [< swap swap(size 1 -) swap] swap3 quote compose swap quote swap2 compose compose loop swap(size 1 -) drop] define(fill)
-
-    0 10 3.1415926535897932
-
-    fill
-
-Here are the steps to convert the first way in the second
-
-.. code-block:: text
-
-    from to value [swap(size 1 -) 1 + dup] [< swap swap(size 1 -) swap]
-
-    swap3 quote compose => from [< swap swap(size 1 -) swap] value [swap(size 1 -) 1 + dup to]
-
-    swap quote swap2 compose => from [value] [swap(size 1 -) 1 + dup to < swap swap(size 1 -) swap]
-
-    compose => from [value swap(size 1 -) 1 + dup to < swap swap(size 1 -) swap]
-
-    from to value [swap(size 1 -) 1 + dup] [< swap swap(size 1 -) swap] swap3 quote compose swap quote swap2 compose compose loop swap(size 1 -) drop => that's our fill instruction!
-
-    [[swap(size 1 -) 1 + dup] [< swap swap(size 1 -) swap] swap3 quote compose swap quote swap2 compose compose loop swap(size 1 -) drop] define(fill)
+.. include:: _sources/examples.rst.txt

docs/_sources/index.rst.txt

@@ -1,7 +1,4 @@
-.. stack_script documentation master file, created by
-   sphinx-quickstart on Fri Apr 19 04:14:57 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. stack_script documentation master file, created by sphinx-quickstart
 
 Welcome to stack_script's documentation!
 ========================================
@@ -12,12 +9,13 @@ Welcome to stack_script's documentation!
 
    basic_operations
    stack_operations
-   loop_control
    input_output
    instruction_definition
+   loop_control
+   inner_stack
+   string_operations
    examples
 
-
 Indices and tables
 ==================
 

docs/_sources/inner_stack.rst.txt

@@ -0,0 +1 @@
+.. include:: _sources/inner_stack.rst.txt

docs/_sources/input_output.rst.txt

@@ -1,55 +1 @@
-Input/Output
-------------
-
-**print**
-~~~~~~~~~
-
-The `print` operation prints the first value of the stack to be popped without removing it.
-
-Example:
-
-Suppose we have the following instructions on the stack:
-
-.. code-block:: text
-
-    42 print
-
-After executing the `print` operation, the value 42 will be printed to the output.
-
-**printall**
-~~~~~~~~~~~~
-
-The `printall` operation prints all values on the stack without removing them. It prints the values from top to bottom.
-
-Example:
-
-Suppose we have the following instructions on the stack:
-
-.. code-block:: text
-
-    1 2 3 printall
-
-After executing the `printall` operation, the values 1, 2, and 3 will be printed to the output, each separated by a new line.
-
-**save()**
-The `save` instruction saves the whole content of the stack in the specified file (in appending mode)
-
-Example:
-
-.. code-block:: text
-
-    10 32 3 2 4 3  save(examples/example0.sksp)
-
-
-**load()**
-The `save` instruction read the content of the specified file and execute its content
-
-
-Example:
-
-.. code-block:: text
-
-    load(examples/example0.sksp) => 10 32 3 2 4 3
-
-    load(examples/example1.sksp)
-    mean => 9
+.. include:: _sources/input_output.rst.txt