.==============================================================================.
|  __  _ ___ _  __  __                                                         |
| || | |  |  | ||  || |                                                        |
| |--' '  '  ' '-- '--'                                                        |
| '                                                                            |
| PITICO                                                                       |
| v0.1 (preview build)                                                         |
| Copyright (c) 2024-2025 Andre Kishimoto.                                     |
'=============================================================================='

PITICO (pronunciation: "pee-tee-coo", acronym for "Pequeno Intérprete Trabalha
Interpretando Códigos", which means "Tiny Interpreter Works Interpreting Codes")
is a REPL written in C that interprets and runs a small language inspired by
TinyBASIC, which was designed by Dennis Allison and the People's Computer
Company (PCC), and its specification appeared in volume 1 of Dr. Dobb's Journal
of Computer Calisthenics & Orthodontia (a '70s PCC publication that would later
become Dr. Dobb's Journal).

.==============================================================================.
| TABLE OF CONTENTS                                                            |
+------------------------------------------------------------------------------+
| 1. FEATURES                                                                  |
| 2. AVAILABLE COMMANDS                                                        |
| 3. SUMMARY OF COMMANDS AND OPERATORS                                         |
| 4. CODE SAMPLES                                                              |
| 5. HISTORY                                                                   |
| 6. BUGS, COMMENTS, QUESTIONS, ETC.                                           |
| 7. ABOUT                                                                     |
'=============================================================================='

.==============================================================================.
| 1. FEATURES                                                                  |
'=============================================================================='
- Supports a subset of a TinyBASIC dialect and additional commands which were
not part of the original TinyBASIC specification - see the "AVAILABLE COMMANDS"
section below.
- Supports 26 float number variables (from A to Z).
- Supports 5 arithmetic operations:
  + addition
  - subtract
  * multiplication
  / division
  ^ exponentiation
- Statements can be interpreted in two modes:
  - DIRECT MODE: A statement is immediately interpreted.
  - INDIRECT MODE: A program stored in memory is interpreted starting from its
  first line of code.

.==============================================================================.
| 2. AVAILABLE COMMANDS                                                        |
'=============================================================================='
Important:
- PITICO is case-insensitive.
- Any statement that starts with a number is processed in one of two ways:
  - There are contents after the number: The whole statement, including the
  number, is added to the stored program code (in-memory code), which can be
  executed in INDIRECT MODE via a RUN call.
  - The statement consists of a number only: If there is a line in the stored
  program code that starts with the specified number, the entire line is removed
  from the stored program code.
- Any statement that does not start with a number is immediately processed by
the interpreter (DIRECT MODE).

.------.
| HELP |
|      `-----------------------------------------------------------------------.
| Prints a list of available commands.                                         |
|                                                                              |
| Syntax:                                                                      |
| HELP                                                                         |
|                                                                              |
| Note:                                                                        |
| HELP can only be called in DIRECT MODE.                                      |
'------------------------------------------------------------------------------'
.-------.
| ABOUT |
|       `----------------------------------------------------------------------.
| Prints the copyright information.                                            |
|                                                                              |
| Syntax:                                                                      |
| ABOUT                                                                        |
'------------------------------------------------------------------------------'
.------.
| VARS |
|      `-----------------------------------------------------------------------.
| Prints all variables that are set.                                           |
|                                                                              |
| Syntax:                                                                      |
| VARS                                                                         |
'------------------------------------------------------------------------------'
.------.
| LIST |
|      `-----------------------------------------------------------------------.
| Prints the stored program code.                                              |
|                                                                              |
| Syntax:                                                                      |
| LIST                                                                         |
'------------------------------------------------------------------------------'
.-----.
| RUN |
|     `------------------------------------------------------------------------.
| Runs the stored program code, starting from its first line of code.          |
|                                                                              |
| Syntax:                                                                      |
| RUN                                                                          |
|                                                                              |
| Note:                                                                        |
| RUN can only be called in DIRECT MODE.                                       |
'------------------------------------------------------------------------------'
.-------.
| CLEAR |
|       `----------------------------------------------------------------------.
| Clears the interpreter's memory (stored program code and variables).         |
|                                                                              |
| Syntax:                                                                      |
| CLEAR                                                                        |
|                                                                              |
| Note:                                                                        |
| CLEAR can only be called in DIRECT MODE.                                     |
'------------------------------------------------------------------------------'
.-------.
| PRINT |
|       `----------------------------------------------------------------------.
| Prints contents in the terminal. How the contents appear in the terminal is  |
| defined by the syntax below.                                                 |
|                                                                              |
| Syntax:                                                                      |
| PRINT (<string> | <expr>) [("," | ";") <string> | <expr>] [("," | ";")]      |
|                                                                              |
| Where:                                                                       |
| - <string>: Anything between double quotes ("HELLO", "123", "...").          |
| - <expr>: An expression that results in a number, such as 1+2 or X^2. Every  |
| variable used in an expression must be valid (i.e., it must hold a value).   |
| - (<string> | <expr>): What comes right after PRINT can be a <string> OR a   |
| <expr>.                                                                      |
| - [("," | ";") <string> | <expr>]: Optional. You can print more than one     |
| <string> and more than one <expr> and even make a combination of <string>    |
| and <expr>.                                                                  |
|   - Each <string> | <expr> must be separated by a comma or semicolon.        |
|   - If they are separated by a comma, no blank space is added between them.  |
|   - If they are separated by a semicolon, then a blank space is added        |
|   between them.                                                              |
| - [("," | ";")]: Optional. If the PRINT statement ends with a comma or       |
| a semicolon, a line break is added at the end of the statement.              |
+------------------------------------------------------------------------------+
| Some PRINT examples:                                                         |
| (Consider that "> _" is the REPL's cursor waiting for the user input)        |
|                                                                              |
| > PRINT "HELLO", "WORLD"                                                     |
| HELLOWORLD> _                                                                |
|                                                                              |
| > PRINT "HELLO"; "WORLD"                                                     |
| HELLO WORLD> _                                                               |
|                                                                              |
| > PRINT "HELLO"; "WORLD";                                                    |
| HELLO WORLD                                                                  |
| > _                                                                          |
|                                                                              |
| > PRINT "1 + 2 = ", 1 + 2,                                                   |
| 1 + 2 = 3                                                                    |
| > _                                                                          |
|                                                                              |
| > PRINT ,                                                                    |
| *** ERROR: Invalid expression.                                               |
| (Note that right after PRINT the interpreter expects a <string> or <expr>)   |
|                                                                              |
| > PRINT                                                                      |
| > _                                                                          |
| (If the user only inputs PRINT, the interpreter will have nothing to output  |
| in the terminal - not an error in this case)                                 |
'------------------------------------------------------------------------------'
.---------.
| PRINTLN |
|         `--------------------------------------------------------------------.
| Same as PRINT, but the interpreter adds a line break at the end.             |
'------------------------------------------------------------------------------'
.-------.
| INPUT |
|       `----------------------------------------------------------------------.
| Reads a value from the keyboard and puts it into a variable.                 |
|                                                                              |
| Syntax:                                                                      |
| INPUT [<msg> ","] <var>                                                      |
|                                                                              |
| Where:                                                                       |
| - <msg>: A string to the shown in the terminal.                              |
| - [<msg> ","]: Optional. If <msg> (followed by a comma) is defined, the      |
| interpreter will show the <msg> before reading the value from the keyboard.  |
| If <msg> is not set, then the interpreter will show "<var>: " before reading |
| the value from the keyboard.                                                 |
| - <var>: Which variable should receive the value inserted by the user. There |
| are 26 variables available in the interpreter, from A to Z.                  |
|                                                                              |
| Note:                                                                        |
| PITICO differs from the original TinyBASIC, as it does not accept multiple   |
| variables at once in the INPUT statement.                                    |
+------------------------------------------------------------------------------+
| Some INPUT examples:                                                         |
| (Consider that "> _" or "_" is the REPL's cursor waiting for the user input) |
|                                                                              |
| > INPUT X                                                                    |
| X: _                                                                         |
|                                                                              |
| > INPUT "What is the value of X? ", X                                        |
| What is the value of X? _                                                    |
|                                                                              |
| > INPUT "Bla bla bla" Y                                                      |
| *** ERROR: Missing comma between <msg> and <var>.                            |
'------------------------------------------------------------------------------'
.-----.
| LET |
|     `------------------------------------------------------------------------.
| Assigns a value to a variable.                                               |
|                                                                              |
| Syntax:                                                                      |
| [LET] <var> = <expr>                                                         |
|                                                                              |
| Where:                                                                       |
| - <var>: The variable to be set.                                             |
| - <expr>: An expression that results in a number, such as 1+2 or X^2. Every  |
| variable used in an expression must be valid (i.e., it must hold a value).   |
|                                                                              |
| Note:                                                                        |
| The keyword LET is optional and can be ommited.                              |
+------------------------------------------------------------------------------+
| Some LET examples:                                                           |
|                                                                              |
| > LET A = 1                                                                  |
| > LET B = 2                                                                  |
| > C = (A * 5) + B                                                            |
|                                                                              |
| > LET Y = X                                                                  |
| *** ERROR: Variable 'X' not set.                                             |
'------------------------------------------------------------------------------'
.----.
| IF |
|    `-------------------------------------------------------------------------.
| Runs a statement if a condition is true. If the condition is false, it is    |
| possible to run another statement (ELSE).                                    |
|                                                                              |
| Syntax:                                                                      |
| IF <expr> <relop> <expr> [THEN] <if_stmt> [ELSE <else_stmt>]                 |
|                                                                              |
| Where:                                                                       |
| - <expr>: An expression that results in a number, such as 1+2 or X^2. Every  |
| variable used in an expression must be valid (i.e., it must hold a value).   |
| - <relop>: One of the following relational operators:                        |
|   =  equal to (PITICO also accepts == as equality)                           |
|   >  greater than                                                            |
|   >= greater than or equal to                                                |
|   <  less than                                                               |
|   <= less than or equal to                                                   |
|   <> not equal to (PITICO also accepts >< and != as inequality)              |
| - <if_stmt>: Statement to be executed when <expr> <relop> <expr> is true.    |
| - [ELSE <else_stmt>]: Optional. If defined, when <expr> <relop> <expr> is    |
| false, the <else_stmt> is executed instead of <if_stmt>.                     |
|                                                                              |
| Note:                                                                        |
| The keyword THEN is optional and can be ommited.                             |
+------------------------------------------------------------------------------+
| Some IF examples:                                                            |
|                                                                              |
| > LET X = 99                                                                 |
| > IF X=99 THEN PRINTLN "x equals 99"                                         |
| x equals 99                                                                  |
|                                                                              |
| > IF X<99 THEN PRINTLN "x less than 99"                                      |
| (Since the condition X<99 is false and there is no ELSE, nothing happens)    |
|                                                                              |
| > IF X <= 99 PRINTLN "x less than or equal to 99"                            |
| x less than or equal to 99                                                   |
|                                                                              |
| > IF X > 99 THEN PRINTLN "x greater than 99" ELSE INC X                      |
| (The condition is false and there is an ELSE, so INC X is executed)          |
|                                                                              |
| > PRINT "x=", X,                                                             |
| x=100                                                                        |
|                                                                              |
| > IF X > 99 THEN PRINTLN "x greater than 99" ELSE INC X                      |
| x greater than 99                                                            |
|                                                                              |
| > IF X <> 99 PRINT "x is not 99"                                             |
| x is not 99                                                                  |
|                                                                              |
| > LET Y = X - 10                                                             |
| > IF X==Y PRINTLN "x=y" ELSE IF X==Y+10 PRINTLN "x=y+10" ELSE PRINTLN "???"  |
| x=y+10                                                                       |
'------------------------------------------------------------------------------'
.------.
| GOTO |
|      `-----------------------------------------------------------------------.
| Runs the code found in the specified line number in the stored program.      |
| If the line is invalid (does not exist, is zero or negative), an error       |
| message is printed.                                                          |
|                                                                              |
| Syntax:                                                                      |
| GOTO <line>                                                                  |
|                                                                              |
| Where:                                                                       |
| - <line>: A valid line number (greater than zero).                           |
'------------------------------------------------------------------------------'
.-------.
| GOSUB |
|       `----------------------------------------------------------------------.
| Runs the code found in the specified line number=<expr> in the stored        |
| program.                                                                     |
| If the line is invalid (does not exist, is zero or negative), an error       |
| message is printed.                                                          |
|                                                                              |
| Syntax:                                                                      |
| GOSUB <expr>                                                                 |
|                                                                              |
| Where:                                                                       |
| - <expr>: An expression that results in a number, such as 1+2 or X^2. Every  |
| variable used in an expression must be valid (i.e., it must hold a value).   |
'------------------------------------------------------------------------------'
.--------.
| RETURN |
|        `---------------------------------------------------------------------.
| Ends a GOSUB call.                                                           |
| Not useful in DIRECT MODE, since it only affects the execution of the stored |
| program.                                                                     |
|                                                                              |
| Syntax:                                                                      |
| RETURN                                                                       |
'------------------------------------------------------------------------------'
.-----.
| END |
|     `------------------------------------------------------------------------.
| Ends a RUN call/the execution of the stored program.                         |
| Not useful in DIRECT MODE, since it only affects the execution of the stored |
| program.                                                                     |
|                                                                              |
| Syntax:                                                                      |
| END                                                                          |
'------------------------------------------------------------------------------'
.-------.
| SLEEP |
|       `----------------------------------------------------------------------.
| Pauses the program's execution for the specified duration in milliseconds.   |
|                                                                              |
| Syntax:                                                                      |
| SLEEP <ms>                                                                   |
|                                                                              |
| Where:                                                                       |
| - <ms>: How many milliseconds the interpreter should wait until resuming     |
| program execution. Must be a positive number.                                |
'------------------------------------------------------------------------------'
.-----.
| REM |
|     `------------------------------------------------------------------------.
| Comments a line of code in the stored program, if the specified line number  |
| exists.                                                                      |
|                                                                              |
| Syntax:                                                                      |
| REM <line>                                                                   |
|                                                                              |
| Where:                                                                       |
| - <line>: The line number of the stored program code to comment.             |
'------------------------------------------------------------------------------'
.------.
| TREM |
|      `-----------------------------------------------------------------------.
| Comments/uncomments (toggle) a line of code in the stored program, if the    |
| specified line number exists.                                                |
|                                                                              |
| Syntax:                                                                      |
| TREM <line>                                                                  |
|                                                                              |
| Where:                                                                       |
| - <line>: The line number of the stored program code to comment/uncomment.   |
'------------------------------------------------------------------------------'
.-----.
| INC |
|     `------------------------------------------------------------------------.
| Increases a variable value by one.                                           |
|                                                                              |
| Syntax:                                                                      |
| INC <var>                                                                    |
|                                                                              |
| Where:                                                                       |
| - <var>: Which variable should have its value increased by one. There are 26 |
| variables available in the interpreter, from A to Z.                         |
'------------------------------------------------------------------------------'
.-----.
| DEC |
|     `------------------------------------------------------------------------.
| Decreases a variable value by one.                                           |
|                                                                              |
| Syntax:                                                                      |
| DEC <var>                                                                    |
|                                                                              |
| Where:                                                                       |
| - <var>: Which variable should have its value decreased by one. There are 26 |
| variables available in the interpreter, from A to Z.                         |
'------------------------------------------------------------------------------'
.------.
| RAND |
|      `-----------------------------------------------------------------------.
| Generates a random number in the range [0.0, 1.0], inclusive. RAND must be   |
| used in an expression.                                                       |
|                                                                              |
| Syntax:                                                                      |
| RAND                                                                         |
'------------------------------------------------------------------------------'
.------.
| PREC |
|      `-----------------------------------------------------------------------.
| Sets the precision of output float numbers if a parameter is provided.       |
| The parameter must be in the range [0, 15], inclusive.                       |
| If PREC is called without parameters, it prints the current precision of     |
| output float numbers.                                                        |
|                                                                              |
| Syntax:                                                                      |
| PREC [<expr>]                                                                |
|                                                                              |
| Where:                                                                       |
| - <expr>: Optional. An expression that results in a number, such as 1+2 or   |
| X^2. Every variable used in an expression must be valid (i.e., it must hold  |
| a value).                                                                    |
'------------------------------------------------------------------------------'
.------.
| LANG |
|      `-----------------------------------------------------------------------.
| Sets the program's output language if a parameter is provided. The parameter |
| must be either EN for English or PT for Portuguese.                          |
| If LANG is called without parameters, it prints the program's current output |
| language.                                                                    |
|                                                                              |
| Syntax:                                                                      |
| LANG [EN | PT]                                                               |
|                                                                              |
| Where:                                                                       |
| - [EN | PT]: Optional. EN sets the language to English and PT to Portuguese. |
|                                                                              |
| Note:                                                                        |
| It is also possible to set the language by simply using EN or PT statements. |
| LANG, EN, and PT can only be called in DIRECT MODE.                          |
'------------------------------------------------------------------------------'
.-----.
| CLS |
|     `------------------------------------------------------------------------.
| Clears the terminal screen.                                                  |
|                                                                              |
| Syntax:                                                                      |
| CLS                                                                          |
'------------------------------------------------------------------------------'
.-------.
| STACK |
|       `----------------------------------------------------------------------.
| Prints the contents of the token stack and the gosub stack.                  |
|                                                                              |
| Syntax:                                                                      |
| STACK                                                                        |
|                                                                              |
| Note:                                                                        |
| STACK was initially a debug mode used during PITICO's development, but it    |
| was included in the release, as it might be useful for debugging errors in   |
| user code.                                                                   |
'------------------------------------------------------------------------------'
.------.
| EXIT |
|      `-----------------------------------------------------------------------.
| Exits the interpreter.                                                       |
|                                                                              |
| Syntax:                                                                      |
| EXIT                                                                         |
|                                                                              |
| Note:                                                                        |
| EXIT can only be called in DIRECT MODE.                                      |
'------------------------------------------------------------------------------'

.==============================================================================.
| 3. SUMMARY OF COMMANDS AND OPERATORS                                         |
'=============================================================================='
Commands/keywords in alphabetical order:
  ABOUT       CLEAR       CLS       DEC       ELSE        EN        END
  EXIT        GOSUB       GOTO      HELP      IF          INC       INPUT
  LANG        LET         LIST      PREC      PRINT       PRINTLN   PT
  RAND        REM         RETURN    RUN       SLEEP       STACK     THEN
  TREM        VARS

Assignment operator:
  =

Arithmetic operators:
  +     -     *     /     ^

Relational operators:
  =     ==    >     >=    <     <=    <>    ><    !=

.==============================================================================.
| 4. CODE SAMPLES                                                              |
'=============================================================================='
The subdirectory "samples" contains a few code samples that you can run inside
PITICO.

At the moment, PITICO does not support loading code from files, but you can copy
the code from the samples and paste it inside PITICO (the terminal of current
operating systems should handle the pasted code without any issues).

.==============================================================================.
| 5. HISTORY                                                                   |
'=============================================================================='
- 2025/01/26 (v0.1.1):
  - Fixed typo in HELP text.
- 2025/01/25 (v0.1.0):
  - First [public] preview build (Windows 64-bit).

.==============================================================================.
| 6. BUGS, COMMENTS, QUESTIONS, ETC.                                           |
'=============================================================================='
Please send an e-mail to: andre@kishimoto.com.br
Preferably written in either English or Portuguese.

.==============================================================================.
| 7. ABOUT                                                                     |
'=============================================================================='
PITICO is developed and (c) 2024-2025 Andre Kishimoto.
https://www.kishimoto.com.br
