| Name | pystacker JSON |
| Version |
1.8.0
JSON |
| download |
| home_page | https://github.com/remokasu/stacker |
| Summary | Stacker: RPN Calculator in Python |
| upload_time | 2024-10-19 01:08:12 |
| maintainer | None |
| docs_url | None |
| author | remokasu |
| requires_python | None |
| license | MIT License Copyright (c) 2023 @remokasu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
reverse-polish-calculator
rpn
terminal-app
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
prompt-toolkit
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Stacker: An RPN Calculator and Extensible Programming Language
[](https://www.python.org/downloads/)
Stacker is a powerful Reverse Polish Notation (RPN) calculator built with Python, featuring basic mathematical operations and extensibility through plugins.
## Installation
```bash
git clone git@github.com:remokasu/stacker.git
cd stacker
pip install .
```
## Dependencies
Python Prompt Toolkit is required for Stacker. Install it using the following command:
```bash
pip install prompt_toolkit
```
## Feedback and Contributions
Feedback and contributions are welcome. Please submit issues or suggestions on the [Issues page](https://github.com/remokasu/stacker/issues).
## Usage
Run Stacker:
```bash
stacker
```
Or:
```bash
python -m stacker
```
Stacker supports standard arithmetic operations (+, -, *, /) and advanced functions (sin, cos, tan, etc.). Users can input commands in RPN format and extend functionality using custom plugins.
### Input Examples
Stacker allows for straightforward RPN input. For example:
- Single-line input:
```bash
stacker:0> 3 4 +
[7]
```
- Multi-line input:
```bash
stacker:0> 3
[3]
stacker:1> 4
[3, 4]
stacker:2> +
[7]
```
- ### Numbers:
The Stacker command allows you to directly push integers, floating-point numbers, and complex numbers onto the stack. This facilitates easy management of various types of numerical data.
- Integers:
```bash
stacker:0> 3
[3]
```
In this example, the integer 3 is added to the stack.
- Floating-Point Numbers:
```bash
stacker:1> 3.14
[3.14]
```
Here, the floating-point number 3.14 is added to the stack.
- Complex Numbers:
```bash
stacker:2> 1+2j
[(1+2j)]
```
In this case, the complex number 1+2j (with a real part of 1 and an imaginary part of 2) is added to the stack. Complex numbers are denoted by combining the real and imaginary parts with a +, and the imaginary part is indicated using j.
- ### Strings:
- syntax:
```bash
"Hello, World!"
```
- example:
```bash
stacker:0> "Hello, World!"
["Hello, World!"]
```
In this example, the string "Hello, World!" is added to the stack.
- ### Variables:
- syntax:
``` bash
value $name set
```
- example:
```bash
stacker:0> 3 $x set
```
In this example, we assign `3` to `x`.
If you input an undefined symbol, you need to prefix the symbol name with a dollar sign ($). <br>
Hereafter, when x is used, 3 will be pushed onto the stack. Additionally, when using predefined symbols, the dollar sign is not required.
``` bash
stacker:0> 3 $x set
stacker:1> x
[3]
```
- Arrays:
- Single-line array:
```bash
stacker:0> [1 2 3; 4 5 6]
[[1, 2, 3], [4, 5, 6]]
```
- Multi-line array:
```bash
stacker:0> [1 2 3;
... > 4 5 6]
[[1, 2, 3], [4, 5, 6]]
```
- ### Code blocks:
Code blocks are enclosed in curly braces ({}). These blocks are pushed onto the stack in their raw form and can be executed later. For example: {1 2 +}. These blocks are particularly useful for deferred (lazy) evaluation. Specific use-cases include conditional statements and loop controls.
- syntax:
```bash
{1 2 +}
```
- example:
```bash
stacker:0> {1 2 +}
[{1 2 +}]
```
In this command, the block `{1 2 +}` is pushed (added) to the stack.
- ### Code Blocks
Code blocks in Stacker are enclosed in curly braces ({}). These blocks are fundamental structures that enable deferred evaluation and control flow management.
Syntax:
```bash
{code_elements}
```
Key Characteristics:
1. Structure: Code blocks contain one or more code elements separated by spaces.
2. Deferred Evaluation: The contents of a code block are not immediately executed.
3. Stack Interaction: When encountered, code blocks are pushed onto the stack in their raw form.
4. Execution: Code blocks can be executed at a later time when needed.
Common Use Cases:
- Conditional statements
- Loop controls
- Function definitions
Example:
```bash
stacker:0> {1 2 +}
[{1 2 +}]
```
In this example, the block `{1 2 +}` is pushed onto the stack as a single entity. The output shows the stack's contents after the operation, indicating that the block has been stored but not executed.
Note: The execution of a code block's contents occurs only when explicitly triggered, allowing for flexible program control and lazy evaluation strategies.
- ### Control Structures in Stacker
Stacker provides two main types of control structures: conditionals and loops. These allow for dynamic program flow based on conditions and repetitive execution of code blocks.
- #### Conditionals
Conditionals in Stacker enable execution of code based on specified conditions.
- ##### if Statement
The `if` statement executes a code block if a condition is true.
Syntax:
```bash
condition <true-expr> if
```
Example:
```bash
stacker:0> 0 $x set
stacker:1> x 0 == {3 4 +} if
[7]
```
Result: Pushes `7` onto the stack as `x` equals `0`.
- ##### ifelse Statement
The `ifelse` statement provides branching based on a condition, executing one of two code blocks.
Syntax:
```bash
condition <true-expr> <false-expr> ifelse
```
Example:
```bash
stacker:0> 0 $x set
stacker:1> x 0 == {3 4 +} {3 4 -} ifelse
[7]
```
Result: Pushes `7` onto the stack as `x` equals `0`.
- #### Loops
Loops in Stacker allow for repeated execution of code blocks.
- ##### do Loop
The `do` loop iterates over a range of values.
Syntax:
```bash
start_value end_value $symbol {body} do
```
Example:
```bash
stacker:0> 1 10 $i {i echo} do
1
2
3
4
5
6
7
8
9
10
```
Result: Prints numbers from 0 to 10.
- ##### dolist
The `dolist` loop iterates over a list of values.
Syntax:
```bash
[value1 value2 ... valueN] $symbol {body} dolist
```
Example:
```bash
stacker:0> [1 2 3 4 5] $i {i echo} dolist
1
2
3
4
5
```
Result: Prints numbers 1 through 5.
Note:
When expressing a list of consecutive values, the concise notation value1 valueN `seq` can be used instead of `[value1 value2 ... valueN]` to efficiently describe a sequence with a constant step size.
- ##### times
The `times` loop repeats a code block a specified number of times.
Syntax:
```bash
{body} n times
```
Example:
```bash
stacker:0> 1 {dup ++} 10 times
[1 2 3 4 5 6 7 8 9 10 11]
```
Result: Pushes numbers 1 through 11 onto the stack by repeatedly duplicating and incrementing.
- #### break
- syntax:
```bash
{break}
```
- example:
```bash
stacker:0> 0 $i set
stacker:1> 0 9 $i {{break} i 5 == if i echo} do
0
1
2
3
4
5
```
This example prints the numbers from 0 to 5. When `i` is equal to `5`, the loop is terminated by `break`.
- ### Define a function:
- syntax:
```bash
{arg1 arg2 ... argN} {body} $name defun
```
- example:
```bash
stacker:0> {x y} {x y *} $multiply defun
stacker:1> 10 20 multiply
[200]
```
This defines a function named `multiply` that takes two arguments `x` and `y` and multiplies them together.
- ### Define a macro:
- syntax:
```bash
{body} $name defmacro
```
- example:
```bash
stacker:0> {2 ^ 3 * 5 +} $calculatePowerAndAdd defmacro
stacker:1> 5 calculatePowerAndAdd
[80]
```
This defines a macro with the body `{2 ^ 3 * 5 +}` and assigns it the name `calculatePowerAndAdd`. This macro squares the number on the stack, multiplies it by 3, and then adds 5.
- ### Lambda Functions
Lambda functions are anonymous functions that can be defined and executed on the fly. They are useful for creating temporary functions without the need for a formal definition.
- syntax:
```bash
{arg1 arg2 ... argN} {body} lambda
```
- example:
```bash
stacker:0> {x y} {x y *} lambda
[λxλy.{x y *}]
```
- example:
```bash
stacker:0> {x y} {x y *} lambda $multiply set
stacker:1> 3 4 multiply
[12]
```
This example defines a lambda function that multiplies two numbers and assigns it to the variable `multiply`. The function is then called with the arguments `3` and `4`.
- ### Include Scripts
Stacker scripts can be included in other scripts using the `include` command. For example:
``` bash
stacker:0> "my_script.stk" include
```
All functions, macros and variables defined in "my_script.stk" are added to the current stack.
- ### File Writing and Reading
- Writing to a file:
```bash
stacker:0> "output.txt" "hoge" write
```
This writes the string "hoge" to the file "output.txt".
- Reading from a file:
```bash
stacker:0> "output.txt" read
[hoge]
```
This reads the contents of "output.txt" and executes it.
```
stacker:0> "output.txt" read $text set
```
You can also set the contents of the file to a variable using the `set` command.
## Running Scripts
Stacker scripts can be created in `.stk` files. To run a script, simply execute it with Stacker. For example:
- my_script.stk:
```bash
0 $p set
0 100000 $k {
-1 k ^ 2 k * 1 + / p + p set
} do
4 p * p set
p echo
```
Running the script:
```bash
stacker my_script.stk
```
## Command Line Execution
You can directly execute a specified RPN expression from the command line.
```bash
stacker -e "3 4 + echo"
```
## Settings
- disable_plugin
Disable a specified plugin:
```bash
stacker:0> "hoge" disable_plugin
```
This command deactivates the `hoge` operator added as a plugin.
Note that it cannot be used on non-plugin operators.
- disable_all_plugins
Disable all plugins at once.
```bash
stacker:0> disable_all_plugins
```
- enable_disp_ans
Enables the display of the last result (ans) at the end of the stack.
```bash
stacker:0> enable_disp_ans
stacker:1> 3 4 +
7
[7]
```
- disable_disp_ans
Disables the display of the last result (ans) at the end of the stack.
```bash
stacker:0> disable_disp_ans
stacker:1> 3 4 +
[7]
```
- enable_disp_stack
Enables the setting to display the stack contents each time. By default, this setting is already active.
```bash
stacker:0> enable_disp_stack
```
- disable_disp_stack
Sets the display of stack contents to be disabled. When this setting is enabled, only the latest element of the stack is displayed.
```bash
stacker:0> disable_disp_stack
```
- disable_disp_logo
Disables the display of the logo at startup.
```bash
stacker:0> disable_disp_logo
```
## Configuration File
You can automatically load settings at startup. The configuration file should be placed in ~/.stackerrc. For example, if you write the following contents in ~/.stackerrc, the disable_disp_logo and disable_disp_stack will be automatically activated at startup.
```bash
disable_disp_logo
disable_disp_stack
enabble_disp_ans
```
## Creating Plugins
Create custom plugins for Stacker using Python:
1. **Creating the Plugin**:
In the `plugins` directory, create a new Python file for your plugin (e.g., `my_plugin.py`).
```
stacker/
│
├── stacker/
│ ├── plugins/
│ │ ├── my_plugin.py
│ │ └── ...
│ │
│ ├── data/
│ ├── stacker.py
│ ├── test.py
│ └── ...
│
└── ...
```
Adding your plugin here and reinstalling Stacker will apply the plugin permanently.
2. **Defining Functions and Classes**:
Define the necessary functions and classes in `my_plugin.py`.
3. **Defining the `setup` Function**:
In `my_plugin.py`, define a `setup` function that takes `stacker` as its only argument.
4. **Registering Custom Commands and Parameters**:
Within the `setup` function, use the `register_plugin` method of `stacker` to register custom commands. Additionally, you can also register custom parameters using the `register_parameter` method. This allows for greater flexibility and customization in your plugin's behavior.
Here's an example where custom commands for matrix operations and a custom parameter are registered:
Example:
```python
from stacker.stacker import Stacker
def function(a, b):
# Do something
def setup(stacker: Stacker):
stacker.register_plugin("command", function)
```
You can specify the command description for the help command using desc. This field is optional.
This example demonstrates how to register functions for matrix operations and how to set a custom parameter within a plugin. The register_parameter method is used to add a custom parameter to the Stacker environment, allowing for additional customization and control within your plugin.
5. **Reinstalling Stacker**:
Run the following command to reinstall Stacker:
```
> python setup.py install
```
**Note**: If you want to apply the plugin only temporarily, create a `plugins` directory in the directory where Stacker is executed and add your plugin there. The method for creating it is the same as described above. This method does not require reinstalling Stacker.
6. **Using the Plugin**:
When Stacker is launched, the plugin will automatically be loaded, and the custom commands will be available for use.
7. **Disabling Plugins**:
Use operatorName disable_plugin to disable a specific plugin.<br>
Use disable_all_plugins to disable all plugins.<br>
## Running on Python
You can also run Stacker as a Python module. For example:
```python
from stacker import Stacker
stacker = Stacker()
print(stacker.eval("3 4 +"))
```
## Supported Operations
### Basic Operators
| Operator | Description | Example |
|----------|-------------------------------------------------------|----------------------------|
| + | Add | `3 5 +` |
| - | Subtract | `10 3 -` |
| * | Multiply | `4 6 *` |
| / | Divide | `12 4 /` |
| // | Integer divide | `7 2 //` |
| % | Modulus | `9 2 %` |
| ^ | Power | `3 2 ^` |
| == | Equal | `1 1 ==` |
| != | Not equal | `1 0 !=` |
| < | Less than | `1 2 <` |
| <= | Less than or equal to | `3 3 <=` |
| > | Greater than | `2 1 >` |
| >= | Greater than or equal to | `3 3 >=` |
| neg | Negate | `5 neg` |
| and | Logical and | `true false and` |
| or | Logical or | `true false or` |
| not | Logical not | `true not` |
| band | Bitwise and | `3 2 band` |
| bor | Bitwise or | `3 2 bor` |
| bxor | Bitwise xor | `3 2 bxor` |
| >> | Right bit shit | `8 2 >>` |
| << | Left bit shit | `2 2 <<` |
| ~ | Bitwise not | `5 ~` |
| bin | Binary representation (result is a string) | `5 bin` |
| oct | Octal representation (result is a string) | `10 oct` |
| dec | Decimal representation (result is an integer) | `0b101010 dec` |
| hex | Hexadecimal representation (result is a string) | `255 hex` |
### Math Operator
| Operator | Description | Example |
|----------|-------------------------------------------------------|----------------------------|
| abs | Absolute value | `-3 abs` |
| exp | Exponential | `3 exp` |
| log | Natural logarithm | `2 log` |
| log10 | Common logarithm (base 10) | `4 log10` |
| log2 | Logarithm base 2 | `4 log2` |
| sin | Sine | `30 sin` |
| cos | Cosine | `45 cos` |
| tan | Tangent | `60 tan` |
| asin | Arcsine | `0.5 asin` |
| acos | Arccosine | `0.5 acos` |
| atan | Arctangent | `1 atan` |
| sinh | Hyperbolic sine | `1 sinh` |
| cosh | Hyperbolic cosine | `1 cosh` |
| tanh | Hyperbolic tangent | `1 tanh` |
| asinh | Inverse hyperbolic sine | `1 asinh` |
| acosh | Inverse hyperbolic cosine | `2 acosh` |
| atanh | Inverse hyperbolic tangent | `0.5 atanh` |
| sqrt | Square root | `9 sqrt` |
| ceil | Ceiling | `3.2 ceil` |
| floor | Floor | `3.8 floor` |
| round | Round | `3.5 round` |
| roundn | Round to specified decimal places | `3.51 1 roundn` |
| float | Convert to floating-point number | `5 float` |
| int | Convert to integer | `3.14 int` |
| gcd | Greatest common divisor | `4 2 gcd` |
| ! | Factorial | `4 !` |
| radians | Convert degrees to radians | `180 radians` |
| random | Generate a random floating-point number between 0 and 1| `random` |
| randint | Generate a random integer within a specified range | `1 6 randint` |
| uniform | Generate a random floating-point number within a specified range | `1 2 uniform` |
| dice | Roll dice (e.g., 3d6) | `3 6 dice` |
### Stack Operators
| Operator | Description | Example |
|----------|-----------------------------------------------------------|------------------------|
| drop | Drops the top element of the stack. | `drop` |
| drop2 | Drops the top two elements of the stack. | `drop2` |
| dropn | Drops the nth element from the top of the stack. | `n drop` |
| dup | Duplicate the top element of the stack. | `dup` |
| dup2 | Duplicate the top two elements of the stack. | `dup2` |
| dupn | Duplicate the nth element from the top of the stack. | `n dup` |
| swap | Swap the top two elements of the stack. | `swap` |
| rev | Reverse the stack. | `rev` |
| rot | Move the third element to the top of the stack. | `rot` |
| unrot | Move the top element to the third position of the stack. | `unrot` |
| roll | Moves the nth element to the top of the stack. | `roll` |
| over | Copy the second element from the top of the stack. | `over` |
| pick | Copies the nth element to the top of the stack. | `n pick` |
| nip | Remove the second element from the top of the stack. | `nip` |
| depth | Returns the depth of the stack. | `depth` |
| ins | Insert the specified value at the specified position. | `3 1 ins` |
| count | Counts the number of occurrences of a value in the stack. | `count` |
| clear | Clear the stack. | `clear` |
| disp | Display the stack. | `disp` |
### Control Operators
| Operator | Description | Example |
|----------|-------------------------------------------------------|----------------------------|
| if | Conditional statement | `{...} true if` |
| ifelse | Conditional statement with an else block | `{true block} {false block} true ifelse` |
| iferror | Conditional statement for error handling | `{try block} {catch block} iferror` |
| do | Loop | `0 10 $i {i echo} do` |
| times | Loop a specified number of times | `{dup ++} 10 times` |
| break | Break out of a loop | `break` |
### Function, Macro, Lambda, and Variable Operators
| Operator | Description | Example |
|----------|-------------------------------------------------------|----------------------------|
| defun | Define a function | `{x y} {x y *} $multiply defun` |
| defmacro | Define a macro | `{2 ^ 3 * 5 +} $calculatePowerAndAdd defmacro` |
| lambda | Create a lambda function | `{x y} {x y *} lambda` |
| set | Assign a value to a variable | `3 $x set` |
### Array Operators
| Operator | Description | Example |
|----------|-------------------------------------------------------|----------------------------|
| map | Apply a function to each element of an array | `[1 2 3] {dup} map` |
| zip | Combine two arrays into a single array | `[1 2 3] [4 5 6] zip` |
| filter | Filter an array based on a condition | `[1 2 3 4 5] {2 % 0 ==} filter` |
| all | Check if all elements of an array satisfy a condition | `[1 2 3 4 5] {2 % 0 ==} all` |
| any | Check if any element of an array satisfies a condition | `[1 2 3 4 5] {2 % 0 ==} any` |
### Other Operators
| Operator | Description | Example |
|----------|-------------------------------------------------------|----------------------------|
| sub | Substack the top element of the stack | `sub` |
| subn | Cluster elements between the top and the nth (make substacks) | `3 subn` |
| include | Include the specified file | `"file.stk" include` |
| eval | Evaluate the specified RPN expression | `'3 5 +' eval` |
| evalpy | Evaluate the specified Python expression | `'3+5' evalpy` |
| echo | Print the specified value to stdout without adding it to the stack | `3 4 + echo` |
| input | Get input from the user | `input` |
| read | Read the contents of the specified file | `"file.txt" read` |
| write | Write the specified value to the specified file | `"hoge" "file.txt" write` |
## Constants
| Constants | Description |
|-----------|------------------|
| e | Euler's number |
| pi | Pi |
| tau | Tau |
| nan | Not a number |
| inf | Infinity |
| true | Boolean true |
| false | Boolean false |
Raw data
{
"_id": null,
"home_page": "https://github.com/remokasu/stacker",
"name": "pystacker",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "reverse-polish-calculator rpn terminal-app",
"author": "remokasu",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/97/bd/15d3d3f38f58df5bd21921327defd922d7afb315120d534d3ca868f74739/pystacker-1.8.0.tar.gz",
"platform": null,
"description": "# Stacker: An RPN Calculator and Extensible Programming Language\n\n[](https://www.python.org/downloads/)\n\n\nStacker is a powerful Reverse Polish Notation (RPN) calculator built with Python, featuring basic mathematical operations and extensibility through plugins.\n\n## Installation\n\n```bash\ngit clone git@github.com:remokasu/stacker.git\ncd stacker\npip install .\n```\n\n\n## Dependencies\n\nPython Prompt Toolkit is required for Stacker. Install it using the following command:\n```bash\npip install prompt_toolkit\n```\n\n## Feedback and Contributions\n\nFeedback and contributions are welcome. Please submit issues or suggestions on the [Issues page](https://github.com/remokasu/stacker/issues).\n\n\n## Usage\n\nRun Stacker:\n```bash\nstacker\n```\nOr:\n```bash\npython -m stacker\n```\n\nStacker supports standard arithmetic operations (+, -, *, /) and advanced functions (sin, cos, tan, etc.). Users can input commands in RPN format and extend functionality using custom plugins.\n\n### Input Examples\n\nStacker allows for straightforward RPN input. For example:\n\n- Single-line input:\n ```bash\n stacker:0> 3 4 +\n [7]\n ```\n\n- Multi-line input:\n ```bash\n stacker:0> 3\n [3]\n stacker:1> 4\n [3, 4]\n stacker:2> +\n [7]\n ```\n\n- ### Numbers:\n The Stacker command allows you to directly push integers, floating-point numbers, and complex numbers onto the stack. This facilitates easy management of various types of numerical data.\n\n - Integers:\n ```bash\n stacker:0> 3\n [3]\n ```\n In this example, the integer 3 is added to the stack.\n\n - Floating-Point Numbers:\n ```bash\n stacker:1> 3.14\n [3.14]\n ```\n Here, the floating-point number 3.14 is added to the stack.\n\n - Complex Numbers:\n ```bash\n stacker:2> 1+2j\n [(1+2j)]\n ```\n In this case, the complex number 1+2j (with a real part of 1 and an imaginary part of 2) is added to the stack. Complex numbers are denoted by combining the real and imaginary parts with a +, and the imaginary part is indicated using j.\n\n- ### Strings:\n - syntax:\n ```bash\n \"Hello, World!\"\n ```\n - example:\n ```bash\n stacker:0> \"Hello, World!\"\n [\"Hello, World!\"]\n ```\n In this example, the string \"Hello, World!\" is added to the stack.\n\n\n- ### Variables:\n - syntax:\n ``` bash\n value $name set\n ```\n - example:\n ```bash\n stacker:0> 3 $x set\n ```\n In this example, we assign `3` to `x`.\n If you input an undefined symbol, you need to prefix the symbol name with a dollar sign ($). <br>\n Hereafter, when x is used, 3 will be pushed onto the stack. Additionally, when using predefined symbols, the dollar sign is not required.\n ``` bash\n stacker:0> 3 $x set\n stacker:1> x\n [3]\n ```\n\n- Arrays:\n - Single-line array:\n ```bash\n stacker:0> [1 2 3; 4 5 6]\n [[1, 2, 3], [4, 5, 6]]\n ```\n\n - Multi-line array:\n ```bash\n stacker:0> [1 2 3;\n ... > 4 5 6]\n [[1, 2, 3], [4, 5, 6]]\n ```\n\n\n- ### Code blocks:\n\n Code blocks are enclosed in curly braces ({}). These blocks are pushed onto the stack in their raw form and can be executed later. For example: {1 2 +}. These blocks are particularly useful for deferred (lazy) evaluation. Specific use-cases include conditional statements and loop controls.\n\n - syntax:\n ```bash\n {1 2 +}\n ```\n - example:\n ```bash\n stacker:0> {1 2 +}\n [{1 2 +}]\n ```\n In this command, the block `{1 2 +}` is pushed (added) to the stack.\n\n- ### Code Blocks\n\n Code blocks in Stacker are enclosed in curly braces ({}). These blocks are fundamental structures that enable deferred evaluation and control flow management.\n\n Syntax:\n ```bash\n {code_elements}\n ```\n\n Key Characteristics:\n 1. Structure: Code blocks contain one or more code elements separated by spaces.\n 2. Deferred Evaluation: The contents of a code block are not immediately executed.\n 3. Stack Interaction: When encountered, code blocks are pushed onto the stack in their raw form.\n 4. Execution: Code blocks can be executed at a later time when needed.\n\n Common Use Cases:\n - Conditional statements\n - Loop controls\n - Function definitions\n\n Example:\n ```bash\n stacker:0> {1 2 +}\n [{1 2 +}]\n ```\n\n In this example, the block `{1 2 +}` is pushed onto the stack as a single entity. The output shows the stack's contents after the operation, indicating that the block has been stored but not executed.\n\n Note: The execution of a code block's contents occurs only when explicitly triggered, allowing for flexible program control and lazy evaluation strategies.\n\n- ### Control Structures in Stacker\n\n Stacker provides two main types of control structures: conditionals and loops. These allow for dynamic program flow based on conditions and repetitive execution of code blocks.\n\n - #### Conditionals\n\n Conditionals in Stacker enable execution of code based on specified conditions.\n\n - ##### if Statement\n\n The `if` statement executes a code block if a condition is true.\n\n Syntax:\n ```bash\n condition <true-expr> if\n ```\n\n Example:\n ```bash\n stacker:0> 0 $x set\n stacker:1> x 0 == {3 4 +} if\n [7]\n ```\n\n Result: Pushes `7` onto the stack as `x` equals `0`.\n\n - ##### ifelse Statement\n\n The `ifelse` statement provides branching based on a condition, executing one of two code blocks.\n\n Syntax:\n ```bash\n condition <true-expr> <false-expr> ifelse\n ```\n\n Example:\n ```bash\n stacker:0> 0 $x set\n stacker:1> x 0 == {3 4 +} {3 4 -} ifelse\n [7]\n ```\n\n Result: Pushes `7` onto the stack as `x` equals `0`.\n\n - #### Loops\n\n Loops in Stacker allow for repeated execution of code blocks.\n\n - ##### do Loop\n\n The `do` loop iterates over a range of values.\n\n Syntax:\n ```bash\n start_value end_value $symbol {body} do\n ```\n\n Example:\n ```bash\n stacker:0> 1 10 $i {i echo} do\n 1\n 2\n 3\n 4\n 5\n 6\n 7\n 8\n 9\n 10\n ```\n\n Result: Prints numbers from 0 to 10.\n\n - ##### dolist\n\n The `dolist` loop iterates over a list of values.\n\n Syntax:\n ```bash\n [value1 value2 ... valueN] $symbol {body} dolist\n ```\n\n Example:\n ```bash\n stacker:0> [1 2 3 4 5] $i {i echo} dolist\n 1\n 2\n 3\n 4\n 5\n ```\n\n Result: Prints numbers 1 through 5.\n\n Note:\n When expressing a list of consecutive values, the concise notation value1 valueN `seq` can be used instead of `[value1 value2 ... valueN]` to efficiently describe a sequence with a constant step size.\n\n - ##### times\n\n The `times` loop repeats a code block a specified number of times.\n\n Syntax:\n ```bash\n {body} n times\n ```\n\n Example:\n ```bash\n stacker:0> 1 {dup ++} 10 times\n [1 2 3 4 5 6 7 8 9 10 11]\n ```\n\n Result: Pushes numbers 1 through 11 onto the stack by repeatedly duplicating and incrementing.\n\n - #### break\n - syntax:\n ```bash\n {break}\n ```\n - example:\n ```bash\n stacker:0> 0 $i set\n stacker:1> 0 9 $i {{break} i 5 == if i echo} do\n 0\n 1\n 2\n 3\n 4\n 5\n ```\n This example prints the numbers from 0 to 5. When `i` is equal to `5`, the loop is terminated by `break`.\n\n- ### Define a function:\n - syntax:\n ```bash\n {arg1 arg2 ... argN} {body} $name defun\n ```\n - example:\n ```bash\n stacker:0> {x y} {x y *} $multiply defun\n stacker:1> 10 20 multiply\n [200]\n ```\n This defines a function named `multiply` that takes two arguments `x` and `y` and multiplies them together.\n\n- ### Define a macro:\n - syntax:\n ```bash\n {body} $name defmacro\n ```\n - example:\n ```bash\n stacker:0> {2 ^ 3 * 5 +} $calculatePowerAndAdd defmacro\n stacker:1> 5 calculatePowerAndAdd\n [80]\n ```\n This defines a macro with the body `{2 ^ 3 * 5 +}` and assigns it the name `calculatePowerAndAdd`. This macro squares the number on the stack, multiplies it by 3, and then adds 5.\n\n- ### Lambda Functions\n Lambda functions are anonymous functions that can be defined and executed on the fly. They are useful for creating temporary functions without the need for a formal definition.\n\n - syntax:\n ```bash\n {arg1 arg2 ... argN} {body} lambda\n ```\n - example:\n ```bash\n stacker:0> {x y} {x y *} lambda\n [\u03bbx\u03bby.{x y *}]\n ```\n\n - example:\n ```bash\n stacker:0> {x y} {x y *} lambda $multiply set\n stacker:1> 3 4 multiply\n [12]\n ```\n This example defines a lambda function that multiplies two numbers and assigns it to the variable `multiply`. The function is then called with the arguments `3` and `4`.\n\n\n- ### Include Scripts\n Stacker scripts can be included in other scripts using the `include` command. For example:\n\n ``` bash\n stacker:0> \"my_script.stk\" include\n ```\n All functions, macros and variables defined in \"my_script.stk\" are added to the current stack.\n\n- ### File Writing and Reading\n - Writing to a file:\n ```bash\n stacker:0> \"output.txt\" \"hoge\" write\n ```\n This writes the string \"hoge\" to the file \"output.txt\".\n\n - Reading from a file:\n ```bash\n stacker:0> \"output.txt\" read\n [hoge]\n ```\n This reads the contents of \"output.txt\" and executes it.\n\n ```\n stacker:0> \"output.txt\" read $text set\n ```\n You can also set the contents of the file to a variable using the `set` command.\n\n## Running Scripts\nStacker scripts can be created in `.stk` files. To run a script, simply execute it with Stacker. For example:\n\n- my_script.stk:\n ```bash\n 0 $p set\n 0 100000 $k {\n -1 k ^ 2 k * 1 + / p + p set\n } do\n 4 p * p set\n p echo\n ```\n\n Running the script:\n ```bash\n stacker my_script.stk\n ```\n\n\n## Command Line Execution\nYou can directly execute a specified RPN expression from the command line.\n\n```bash\nstacker -e \"3 4 + echo\"\n```\n\n\n## Settings\n- disable_plugin\n Disable a specified plugin:\n ```bash\n stacker:0> \"hoge\" disable_plugin\n ```\n This command deactivates the `hoge` operator added as a plugin.\n Note that it cannot be used on non-plugin operators.\n\n- disable_all_plugins\n Disable all plugins at once.\n ```bash\n stacker:0> disable_all_plugins\n ```\n\n- enable_disp_ans\n Enables the display of the last result (ans) at the end of the stack.\n ```bash\n stacker:0> enable_disp_ans\n stacker:1> 3 4 +\n 7\n [7]\n ```\n\n- disable_disp_ans\n Disables the display of the last result (ans) at the end of the stack.\n ```bash\n stacker:0> disable_disp_ans\n stacker:1> 3 4 +\n [7]\n ```\n\n- enable_disp_stack\n Enables the setting to display the stack contents each time. By default, this setting is already active.\n ```bash\n stacker:0> enable_disp_stack\n ```\n\n- disable_disp_stack\n Sets the display of stack contents to be disabled. When this setting is enabled, only the latest element of the stack is displayed.\n ```bash\n stacker:0> disable_disp_stack\n ```\n\n- disable_disp_logo\n Disables the display of the logo at startup.\n ```bash\n stacker:0> disable_disp_logo\n ```\n\n\n\n## Configuration File\nYou can automatically load settings at startup. The configuration file should be placed in ~/.stackerrc. For example, if you write the following contents in ~/.stackerrc, the disable_disp_logo and disable_disp_stack will be automatically activated at startup.\n```bash\ndisable_disp_logo\ndisable_disp_stack\nenabble_disp_ans\n```\n\n## Creating Plugins\n\nCreate custom plugins for Stacker using Python:\n\n1. **Creating the Plugin**:\n In the `plugins` directory, create a new Python file for your plugin (e.g., `my_plugin.py`). \n\n ``` \n stacker/\n \u2502\n \u251c\u2500\u2500 stacker/\n \u2502 \u251c\u2500\u2500 plugins/\n \u2502 \u2502 \u251c\u2500\u2500 my_plugin.py\n \u2502 \u2502 \u2514\u2500\u2500 ...\n \u2502 \u2502\n \u2502 \u251c\u2500\u2500 data/\n \u2502 \u251c\u2500\u2500 stacker.py\n \u2502 \u251c\u2500\u2500 test.py\n \u2502 \u2514\u2500\u2500 ...\n \u2502\n \u2514\u2500\u2500 ...\n ```\n\n Adding your plugin here and reinstalling Stacker will apply the plugin permanently.\n\n2. **Defining Functions and Classes**:\n Define the necessary functions and classes in `my_plugin.py`.\n\n3. **Defining the `setup` Function**:\n In `my_plugin.py`, define a `setup` function that takes `stacker` as its only argument.\n\n4. **Registering Custom Commands and Parameters**:\n\n Within the `setup` function, use the `register_plugin` method of `stacker` to register custom commands. Additionally, you can also register custom parameters using the `register_parameter` method. This allows for greater flexibility and customization in your plugin's behavior.\n\n Here's an example where custom commands for matrix operations and a custom parameter are registered:\n\n Example:\n ```python\n from stacker.stacker import Stacker\n\n def function(a, b):\n # Do something\n\n def setup(stacker: Stacker):\n stacker.register_plugin(\"command\", function)\n ```\n\n You can specify the command description for the help command using desc. This field is optional.\n\n This example demonstrates how to register functions for matrix operations and how to set a custom parameter within a plugin. The register_parameter method is used to add a custom parameter to the Stacker environment, allowing for additional customization and control within your plugin.\n\n5. **Reinstalling Stacker**:\n Run the following command to reinstall Stacker:\n ```\n > python setup.py install\n ```\n\n **Note**: If you want to apply the plugin only temporarily, create a `plugins` directory in the directory where Stacker is executed and add your plugin there. The method for creating it is the same as described above. This method does not require reinstalling Stacker.\n\n\n6. **Using the Plugin**:\n When Stacker is launched, the plugin will automatically be loaded, and the custom commands will be available for use.\n\n7. **Disabling Plugins**:\nUse operatorName disable_plugin to disable a specific plugin.<br>\nUse disable_all_plugins to disable all plugins.<br>\n\n\n## Running on Python\nYou can also run Stacker as a Python module. For example:\n```python\nfrom stacker import Stacker\nstacker = Stacker()\nprint(stacker.eval(\"3 4 +\"))\n```\n\n## Supported Operations\n\n### Basic Operators\n\n| Operator | Description | Example |\n|----------|-------------------------------------------------------|----------------------------|\n| + | Add | `3 5 +` |\n| - | Subtract | `10 3 -` |\n| * | Multiply | `4 6 *` |\n| / | Divide | `12 4 /` |\n| // | Integer divide | `7 2 //` |\n| % | Modulus | `9 2 %` |\n| ^ | Power | `3 2 ^` |\n| == | Equal | `1 1 ==` |\n| != | Not equal | `1 0 !=` |\n| < | Less than | `1 2 <` |\n| <= | Less than or equal to | `3 3 <=` |\n| > | Greater than | `2 1 >` |\n| >= | Greater than or equal to | `3 3 >=` |\n| neg | Negate | `5 neg` |\n| and | Logical and | `true false and` |\n| or | Logical or | `true false or` |\n| not | Logical not | `true not` |\n| band | Bitwise and | `3 2 band` |\n| bor | Bitwise or | `3 2 bor` |\n| bxor | Bitwise xor | `3 2 bxor` |\n| >> | Right bit shit | `8 2 >>` |\n| << | Left bit shit | `2 2 <<` |\n| ~ | Bitwise not | `5 ~` |\n| bin | Binary representation (result is a string) | `5 bin` |\n| oct | Octal representation (result is a string) | `10 oct` |\n| dec | Decimal representation (result is an integer) | `0b101010 dec` |\n| hex | Hexadecimal representation (result is a string) | `255 hex` |\n\n\n### Math Operator\n\n| Operator | Description | Example |\n|----------|-------------------------------------------------------|----------------------------|\n| abs | Absolute value | `-3 abs` |\n| exp | Exponential | `3 exp` |\n| log | Natural logarithm | `2 log` |\n| log10 | Common logarithm (base 10) | `4 log10` |\n| log2 | Logarithm base 2 | `4 log2` |\n| sin | Sine | `30 sin` |\n| cos | Cosine | `45 cos` |\n| tan | Tangent | `60 tan` |\n| asin | Arcsine | `0.5 asin` |\n| acos | Arccosine | `0.5 acos` |\n| atan | Arctangent | `1 atan` |\n| sinh | Hyperbolic sine | `1 sinh` |\n| cosh | Hyperbolic cosine | `1 cosh` |\n| tanh | Hyperbolic tangent | `1 tanh` |\n| asinh | Inverse hyperbolic sine | `1 asinh` |\n| acosh | Inverse hyperbolic cosine | `2 acosh` |\n| atanh | Inverse hyperbolic tangent | `0.5 atanh` |\n| sqrt | Square root | `9 sqrt` |\n| ceil | Ceiling | `3.2 ceil` |\n| floor | Floor | `3.8 floor` |\n| round | Round | `3.5 round` |\n| roundn | Round to specified decimal places | `3.51 1 roundn` |\n| float | Convert to floating-point number | `5 float` |\n| int | Convert to integer | `3.14 int` |\n| gcd | Greatest common divisor | `4 2 gcd` |\n| ! | Factorial | `4 !` |\n| radians | Convert degrees to radians | `180 radians` |\n| random | Generate a random floating-point number between 0 and 1| `random` |\n| randint | Generate a random integer within a specified range | `1 6 randint` |\n| uniform | Generate a random floating-point number within a specified range | `1 2 uniform` |\n| dice | Roll dice (e.g., 3d6) | `3 6 dice` |\n\n\n### Stack Operators\n| Operator | Description | Example |\n|----------|-----------------------------------------------------------|------------------------|\n| drop | Drops the top element of the stack. | `drop` |\n| drop2 | Drops the top two elements of the stack. | `drop2` |\n| dropn | Drops the nth element from the top of the stack. | `n drop` |\n| dup | Duplicate the top element of the stack. | `dup` |\n| dup2 | Duplicate the top two elements of the stack. | `dup2` |\n| dupn | Duplicate the nth element from the top of the stack. | `n dup` |\n| swap | Swap the top two elements of the stack. | `swap` |\n| rev | Reverse the stack. | `rev` |\n| rot | Move the third element to the top of the stack. | `rot` |\n| unrot | Move the top element to the third position of the stack. | `unrot` |\n| roll | Moves the nth element to the top of the stack. | `roll` |\n| over | Copy the second element from the top of the stack. | `over` |\n| pick | Copies the nth element to the top of the stack. | `n pick` |\n| nip | Remove the second element from the top of the stack. | `nip` |\n| depth | Returns the depth of the stack. | `depth` |\n| ins | Insert the specified value at the specified position. | `3 1 ins` |\n| count | Counts the number of occurrences of a value in the stack. | `count` |\n| clear | Clear the stack. | `clear` |\n| disp | Display the stack. | `disp` |\n\n\n### Control Operators\n| Operator | Description | Example |\n|----------|-------------------------------------------------------|----------------------------|\n| if | Conditional statement | `{...} true if` |\n| ifelse | Conditional statement with an else block | `{true block} {false block} true ifelse` |\n| iferror | Conditional statement for error handling | `{try block} {catch block} iferror` |\n| do | Loop | `0 10 $i {i echo} do` |\n| times | Loop a specified number of times | `{dup ++} 10 times` |\n| break | Break out of a loop | `break` |\n\n\n### Function, Macro, Lambda, and Variable Operators\n| Operator | Description | Example |\n|----------|-------------------------------------------------------|----------------------------|\n| defun | Define a function | `{x y} {x y *} $multiply defun` |\n| defmacro | Define a macro | `{2 ^ 3 * 5 +} $calculatePowerAndAdd defmacro` |\n| lambda | Create a lambda function | `{x y} {x y *} lambda` |\n| set | Assign a value to a variable | `3 $x set` |\n\n\n### Array Operators\n| Operator | Description | Example |\n|----------|-------------------------------------------------------|----------------------------|\n| map | Apply a function to each element of an array | `[1 2 3] {dup} map` |\n| zip | Combine two arrays into a single array | `[1 2 3] [4 5 6] zip` |\n| filter | Filter an array based on a condition | `[1 2 3 4 5] {2 % 0 ==} filter` |\n| all | Check if all elements of an array satisfy a condition | `[1 2 3 4 5] {2 % 0 ==} all` |\n| any | Check if any element of an array satisfies a condition | `[1 2 3 4 5] {2 % 0 ==} any` |\n\n\n### Other Operators\n| Operator | Description | Example |\n|----------|-------------------------------------------------------|----------------------------|\n| sub | Substack the top element of the stack | `sub` |\n| subn | Cluster elements between the top and the nth (make substacks) | `3 subn` |\n| include | Include the specified file | `\"file.stk\" include` |\n| eval | Evaluate the specified RPN expression | `'3 5 +' eval` |\n| evalpy | Evaluate the specified Python expression | `'3+5' evalpy` |\n| echo | Print the specified value to stdout without adding it to the stack | `3 4 + echo` |\n| input | Get input from the user | `input` |\n| read | Read the contents of the specified file | `\"file.txt\" read` |\n| write | Write the specified value to the specified file | `\"hoge\" \"file.txt\" write` |\n\n\n## Constants\n| Constants | Description |\n|-----------|------------------|\n| e | Euler's number |\n| pi | Pi |\n| tau | Tau |\n| nan | Not a number |\n| inf | Infinity |\n| true | Boolean true |\n| false | Boolean false |\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 @remokasu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Stacker: RPN Calculator in Python",
"version": "1.8.0",
"project_urls": {
"Homepage": "https://github.com/remokasu/stacker"
},
"split_keywords": [
"reverse-polish-calculator",
"rpn",
"terminal-app"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "53d5a2cd5b630169aca966252ed027d34fdce9172df2d380ace1b80599a7ba21",
"md5": "6143a28cf09c42706a260f3c0ebd71a2",
"sha256": "ee78c5115797ddeffd58e5a164833391a2c9c9c97c21a6ea0e77cf24edb515b7"
},
"downloads": -1,
"filename": "pystacker-1.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6143a28cf09c42706a260f3c0ebd71a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 77677,
"upload_time": "2024-10-19T01:08:11",
"upload_time_iso_8601": "2024-10-19T01:08:11.135094Z",
"url": "https://files.pythonhosted.org/packages/53/d5/a2cd5b630169aca966252ed027d34fdce9172df2d380ace1b80599a7ba21/pystacker-1.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "97bd15d3d3f38f58df5bd21921327defd922d7afb315120d534d3ca868f74739",
"md5": "760f5c1c12981629a65e114ad6ae5c9b",
"sha256": "f8371487e2f93ba33a04b0cbca6cbfe49b8d0219a4fc0f310a3622c40643120c"
},
"downloads": -1,
"filename": "pystacker-1.8.0.tar.gz",
"has_sig": false,
"md5_digest": "760f5c1c12981629a65e114ad6ae5c9b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 55318,
"upload_time": "2024-10-19T01:08:12",
"upload_time_iso_8601": "2024-10-19T01:08:12.848437Z",
"url": "https://files.pythonhosted.org/packages/97/bd/15d3d3f38f58df5bd21921327defd922d7afb315120d534d3ca868f74739/pystacker-1.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-19 01:08:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "remokasu",
"github_project": "stacker",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "prompt-toolkit",
"specs": []
}
],
"lcname": "pystacker"
}
