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.
-h	--help	boolean	Show command-line usage help and exit.
None	--cg, --ppcg	boolean	Output a PPCG post version of the code. Requires -v, if it is verbose.
-c	--code	str	Code to interpret.
-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.
None	--rif, --rawinputfile	str	Path to a file with raw input, treated as a singular input.
None	--if, --inputfile	str	Path to a file with input, parsed the same way as input, but treated as multiple inputs.
None	--of, --outputfile	str	Path to a file with output, parsed the same way as input.
None	--qt, --quiettesting	boolean	If this is enabled, testcase output will not be shown.
None	--cs, --canvasstep	int	Changes canvas step interval in milliseconds (default 500).
None	--de, --decode	boolean	Turn encoded (pseudo-single-byte-code-page) code into unicode code.
-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.
None	--oa, --onlyastify	boolean	If this is enabled, the AST of the code is printed. The code is not executed.
-p	--prompt	boolean	Prompt for input.
-r	--repl	boolean	Open a REPL instead of interpreting code.
None	--rs, --restricted	boolean	Disable prompt input, REPL mode, non-raw file input and file output.
-w	--whitespace	boolean	Ignore all whitespace unless prefixed by a ´.
-Wam	--Wambiguities	boolean	Warn of any code that is ambiguous to parse.
-s	--stepcanvas	boolean	Pause canvas every time it is changed.
None	--nt, --nothrottle	boolean	Don't throttle Dump.
None	--dv, --deverbosify	boolean	Turn verbose code into normal code.
-v	--verbose	boolean	Run code, assuming it is written in verbose mode.
None	--sl, --showlength	boolean	Show the length of the code.
-t	--test	boolean	Run unit tests and exit.
None	--dc, --disablecompression	boolean	Disable compression when deverbosifying code.
None	--hd, --hexdump	boolean	Show the xxd hexdump of the code.

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
Direction	dir	One of ←↑→↓↖↗↘↙, or ✳ followed by an expression of any type.	One of :Left, :Right, :Up, :Down, :UpLeft, :UpRight, :DownLeft and :DownRight, or Direction followed by an expression of any type.
Multidirection	mdr	A run of +X*|-\/<>^KLTVY7¬←↑→↓↖↗↘↙, or ✳✳ followed by an expression of any type.	A run of :+, :X, :All, :Vertical, :Horizontal, :\ , :/, :<, :>, :^, :K, :L, :T, :V, :Y, :7, :¬, :Left, :Right, :Up, :Down, :UpLeft, :UpRight, :DownLeft and :DownRight, or Directions followed by an expression of any type.
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
Wolfram expression	wex	An exp or any of various Wolfram objects
Body	bdy	A command, or multiple commands surrounded by «»	A command, or multiple commands surrounded by {}
List	lst	A list of exp, delimited by ⟦⟧
Wolfram list	wls	A list of wex, delimited by ⟦⟧
Arrow list	dls	A list of dir, 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 ”” with the character code of the first character under 120 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.

Other strings delimited by ”” are various types of compressed strings. Below is a list of compression methods

Charcode	Character	Method
120	y	Raw (All characters in the codepage are escaped)
121	z	Dictionary (Unimplemented)
122	{	Charset (The character set is stored and indexed into)
123	|	Run-length encoding
124	}	Brotli compression
125	~	LZMA compression

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 (five if you count variants with refresh separately):

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>

Input

Charcoal tries three things to try to get a list of input

ast.literal_eval

Charcoal first tries parsing the array as a Python array. This succeeds if the result is an array.

Split by newlines

Charcoal then checks how many lines the input has. If it's more than one, then this succeeds.

Split by spaces

If all else fails, Charcoal returns the input split by spaces.