plan.txt

Carrot
the simplistic string-based esolang made for code-golfing
by Kritixi Lithos

Carrot is an esolang that is made for string-manipulation. The program starts of in a 2-dimensional tape, a sheet, and each cell on this tape contains three global variables that I call the stack: the stack-string, the stack-float and the stack-array. The program starts with the stack being the stack-string, ie string-mode. All the operators the program encounters will affect the string-mode directly, and some will change the stack-mode. Furthermore, the program is able to move across the tape via movement commands. As stated earlier, each cell on the tape will have its own stack.


Note: "TODO"s do not mean that they have yet to be implemented, they just mean that I still need to think about that partcular feature

Thoughts
--------

> "Will you be adding the ability to access an array by index? (I haven't read through the entire doc yet) If so I'd say appending and prepending, if not on the last element." - TheLethalCoder

Add an operator that will explode the array onto the sheet (tape of tapes) either horizontally or vertically.

(
> What about nested arrays?
)

> [resolved] Slash operator vs regex arg

//Use spaces to identify operator vs arg
//Use a different delimiter for regex

CONSENSUS: "In fact I can't think of another way of using a regex at the moment so just '/pattern/flags' could be fine on its own." - TheLethalCoder


Caret-mode
----------

The program starts in caret-mode. The data between the carets is called the caret-data.

^ : (caret) toggles caret-mode
    string-mode: appends the caret-data to the string
    float-mode : TODO
    array-mode : TODO
v : (down-caret) toggles caret-mode
    string-mode: prepends the caret-data to the string
    float-mode : TODO
    array-mode : TODO

Stack
-----

stack-string: a string
stack-float : a float, the only numeric stack-type
stack-array : an array than can contain mixed types

The programs starts in string-mode where the user can manipulate the stack-string. The stack-mode can be changed later in the program at will.

Data Types
----------

string: a string; /"(.*\\"?)+"/
float : a float, the only numeric data type; /\d+|\d*\.\d+/
array : an array that can contain mixed types; the format fo the array is not decided yet; TODO
        possibly something like this: {data1 data2 .. dataN} => {1 2 -5"asd"} =JS=> [1,2,-5,"asd"]
regex : ---a regular expression; /regex/flags; yeahhhhhh I'm not going to provide a regex to match a regex---
        change: '/pattern/flags'

/*sub.  : a regular expression followed by a string
        /regex/flags"replacement"
        ~TODO~ done: change this into two datatypes so that it would be two args instead of one
*/

Input
-----

Input is taken as a file. (this can be changed to optional command-line argument later on)
Input is consisted of Carrot literals. (this can be changed to interpret all of input as a string later on)

/*
#  : return all of the input as a string
$  : pop one line of input and return that as a string
$_ : (where _ is any digit) return the _th line of the input as a string
*/

#  : return all of input as an array
$  : pop one piece of data from the input
$_ : (where _ is any integer) return the _th data from the input,
      if _ is negative, return the _th data from the end of the input

Commands
--------

The commands that affect the stack and take in any number of arguments are called as operators as they operate on the stack. The others are called non-operators.

Non-operators
-------------

These are functions that do not affect the content of the stack.

TODO for other arguments and lowercase counterparts

Lowercase variants switches stack to the respective stack-mode without writing anything to the stack.

S: switch stack to string-mode
string-mode: switch stack to string-mode; TODO because redundant
float-mode : switch stack to string-mode
             none  : set stack-string to stack+""
array-mode : switch stack to string-mode
             none  : join elements of stack with "" set that value to stack-string
             string: join elements of stack with arg set that value to stack-string
             float : join elements of stack with arg set that value to stack-string

s: switch to string-mode without changing the stack
string-mode: switch to string-mode; TODO because redundant
float-mode : switch to string-mode
             none  : switch to string-mode
array-mode : switch to string-mode
             none  : switch to string-mode

F: switch stack to float-mode
string-mode: switch stack to float-mode
             none  : set stack-float to parseFloat(stack)
float-mode : switch stack to float-mode; TODO because redundant
array-mode : switch stack to float-mode; TODO
             none  : set stack-float to parseFloat(stack.join(""))

f: switch to float-mode without changing the stack
string-mode: switch to float-mode
             none  : switch to float-mode
float-mode : switch to float-mode; TODO because redundant
array-mode : switch to float-mode
             none  : switch to float-mode

A: switch stack to array-mode
string-mode: switch stack to array-mode
             none  : set stack-array to [stack] or push(stack); TODO
             string: split stack by arg and set the result to stack-array
float-mode : switch stack to array-mode
             none  : set stack-array to [stack] or push(stack); TODO
array-mode : switch stack to array-mode; TODO because redundant

a: switch to array-mode without changing the stack
string-mode: switch to array-mode
             none  : switch to array-mode
float-mode : switch to array-mode
             none  : switch to float-mode
array-mode : switch to array-mode; TODO because redundant

Operators
---------

These are functions that take in zero or more arguments and affect the content of the stack.

arg  = argument
argN = the Nth argument
none = no arguments
r    = regex
s    = string
f    = float
a    = array

```
Explanation of layout

operator description
mode1: description
       none     : description
       arg-type1: description
       arg-typeN: description
       {arg1-type + ... + argN-type}: description
modeN: ...
```

+ plus
string-mode: concatenate
             none  : TODO
             string: concatenate arg to stack
             float : concatenate arg (as a string) to stack
             array : TODO
             regex : TODO
float-mode : add
             none  : TODO
             string: add arg to stack
             float : add parseFloat(arg) to stack
             array : TODO
             regex : TODO
array-mode : ~push arg/~perform + on last element of array; TODO
             none  : sum of floats; TODO if non-floats exist

- minus
string-mode: remove
             none  : TODO
             string: remove all instances of arg from stack
             float : remove the first (or last if arg is negative) arg characters from stack
             array : TODO
             regex : TODO
float-mode : subtract
             none  : negate stack
             string: TODO
             float : subtract arg from stack
             regex : TODO
array-mode : ~pop/~perform - on last element of array; TODO

* asterisk
string-mode: duplicate
             none  : TODO
             string: interleave stack with arg; TODO
             float : string duplicate; "asd"*n="asd".repeat(n+1) /*or just .repeat(n) for either 1) all values of n 2) fractional values of n*/; fractional floats also supported
             array : TODO
             regex : TODO
float-mode:  multiply
             none  : return the sign on the stack; 1, 0, -1 for positive, zero, negative
             string: TODO
             float : multiply arg with stack
             array : TODO
             regex : TODO
array-mode:  perform * on last element of array?; TODO
             none  : product of floats; TODO if non-floats exist

/ forward slash
string-mode: remove/regex magic
             none  : TODO
             string: TODO
             float : remove character at argth index from stack
             array : TODO
             regex : set the stack-array to be equal to the matches of arg on stack
             r+s   : substitution; replace matches of arg1 on stack with arg2
float-mode : divide
             none  : return the fractional part of the stack
             string: TODO
             float : divide stack by arg
             array : TODO
             regex : TODO
array-mode : perform / on last element of array?; TODO

% forward slash
string-mode: remove
             none  : TODO
             string: TODO
             float : remove all but the first (or last if arg is negative) arg characters from the string (opposite of -)
             array : TODO
             regex : TODO
float-mode : divide
             none  : TODO
             string: TODO
             float : return stack % arg
             array : TODO
             regex : TODO
array-mode : perform / on last element of array?; TODO

Sub-processes
-------------

() are sub-processes. Whatever is inside the parentheses is evaluated as another Carrot program, but with the same garden and stackmodes and position in the garden (yet the current cell in the garden will be emptied) and the result of this program can act as an argument to a command.

Loops
-----

[] are loops. They start from the current stack-mode. Then everything inside is executed as Carrot commands. After running all the commands, the program goes back to the start if the stack in the start stack-mode has changed. So effectively, these loops will only terminate if the stack in the start stack-mode does not change in an iteration.

The sheet, a 2D tape
--------------------

The sheet is a 2D tape where every cell contains three global stack variables.

Here are some commands to move across the tape.

h: move one cell left
j: move one cell down
k: move one cell up
l: move one cell right