Reference sheet

Getting started with Charcoal

Using Charcoal

There are many flags you can use to specify how you want to use Charcoal.

Flag	Long	Type	Details
None	None	`str`	Path to the file of code. If the file extension is `.cl`, the file extension can be excluded.
`-c`	`--code`	`str`	Code.
`-i`	`--input`	`str`	Input(s). If more than one is specified, the program is run with each one as a separate testcase. The interpreter tries to parse each input as a Python list. If this fails, the input is split by newlines if the input has more than one line, else it is split by spaces.
`-o`	`--output`	`str`	Outputs. If this is used, the interpreter will how many testcases produce expected output.
`-rif`	`--rawinputfile`	`str`	Path to a file with raw input, treated as a singular input.
`-if`	`--inputfile`	`str`	Path to a file with input, parsed the same way as input, but treated as multiple inputs.
`-of`	`--outputfile`	`str`	Path to a file with output, parsed the same way as input.
`-qt`	`--quiettesting`	`boolean`	If this is enabled, testcase output will not be shown.
`-cs`	`--canvasstep`	`int`	Changes canvas step interval in milliseconds (default 500).
`-e`	`--normalencoding`	`boolean`	Parse input using Charcoal's custom codepage.
`-a`	`--astify`	`boolean`	If this is enabled, the AST of the code is printed before it is executed.

Types

Name	Short form	Succinct mode	Verbose mode
Integer	`int`	A run of `⁰¹²³⁴⁵⁶⁷⁸⁹`	A run of `0123456789`
String	`str`	A run of ASCII printables ( to `~`), or a compressed string (more about this later)	A string delimited with `"` or `'`, processed with Unicode unescaping
Variable	`var`	One of `αβγδεζηθικλμνξπρσςτυφχψω`	One of `abgdezhciklmnxprstufko`
Literal	`lit`	An `int`, `str`, or `var`	An `int`, `str`, or `var`
Direcion	`dir`	One of `←↑→↓↖↗↘↙`	One of `:Left`, `:Right`, `:Up`, `:Down`, `:UpLeft`, `:UpRight`, `:DownLeft` and `:DownRight`.
Multidirection	`mdr`	A run of `+X*	-/<>^KLTVY7¬←↑→↓↖↗↘↙`
Command	`cmd`	See Commands.	See Commands.
Operator	`op`	See Operators.	See Operators.
Dyad	`dy`	A dyadic operator.	A dyadic operator.
Monad	`mn`	A monadic operator.	A monadic operator.
Nilad	`nl`	A niladic operator.	A niladic operator.
Expression	`exp`	A `lit`, `lst`, `dy exp exp`, `mn exp`, or `nl`
Body	`bdy`	A command, or multiple commands surrounded by `«»`	A command, or multiple commands surrounded by `{}`
List	`lst`	A list of `lit`, delimited by `⟦⟧`
Arrow list	`als`	A list of `arw`, delimited by `⟦⟧`
Separator	`sep`	`¦`	One of `,;`

Separators can be placed after any literal, i.e. an int, str, or var.

Compressed strings

Strings delimited by “” are compressed strings. This means they are ASCII strings converted from base 96 or under (the 95 printables and newline) to base 255 (the full 8-bit codepage minus ”). The first character in the string is the encoded character for the base.

Strings delimited by ”” are permuted compressed strings. This means they are ASCII strings converted from base 96 or under to base 255. The first character in the string is the encoded index of the permutation number, the second is the encoded character for the base.

Permutation number

The default order of the ASCII character set is whitespace, symbols, lowercase letters, numbers, and uppercase letters. An index is generated based on the number of uses of each type of character using this order as the base.

Commands

Pretty simple. In succinct mode it's just <command><arguments : var>, in verbose mode it's just <command>(<arguments : var>). See more [here|Commands].

Control Flow

There are three kinds of control flow statements:

Succinct

¿<condition : exp><if_true : bdy><if_false : bdy>
Ｆ<iterable : exp><body : bdy>
Ｗ<condition : exp><body : bdy>
ＨＦ<delay : exp><iterable : exp><body : bdy>
ＨＷ<delay : exp><condition : exp><body : bdy>

Verbose

if (<condition : exp>) <if_true : bdy><if_false : bdy>
for (<iterable : exp>) <body : bdy>
while (<condition : exp>) <body : bdy> RefreshFor(<delay : exp><iterable : exp>_<body : bdy>
RefreshWhile(<delay : exp><condition : exp>)<body : bdy>