Skip to content
somebody1234 edited this page Mar 9, 2017 · 9 revisions

We'll start with examples in the Charcoal REPL. To use the REPL, simply run the command ./charcoal.py, python charcoal.py or python3 charcoal.py. Note that ./charcoal.py will not work on Windows. Alternatively, you can run charcoal.py from Idle.

Printing

The central concept in Charcoal is printing strings to a canvas using a cursor. Any expression not preceded by a command is implicitly printed left-to-right. An expression preceded by one of the arrows ←↑→↓↖↗↘↙ is printed in that direction. Each print begins from the location where the previous one left off.

Charcoal> foo
foo
Charcoal> ↘bar
foob  
    a 
     r

Note that the second and third lines are left-padded with spaces, and the first and second lines are right-padded. You can change the background character to something other than space; more on that later.

After a few REPL commands, the canvas can get crowded. To clear it, hit Ctrl+C or use the Clear command.

Charcoal> ^C
Cleared canvas

Any run of printable ASCII--including space (0x20)--is a string literal. Strings can also include , which represents a newline.

Charcoal> Hello, World!¶123
Hello, World!
123

Since the ASCII digits are used in string literals, integer literals consist of the superscript digits ⁰¹²³⁴⁵⁶⁷⁸⁹. Printing an integer results in a line, using a character selected from /\|- based on the direction of printing.

Charcoal> ⁷
-------
Charcoal> ↙³
-------/
      / 
     /  

Basic math

To output a number instead of a line, we need the Cast operator . This converts strings to numbers and vice versa.

Charcoal> I⁴
4

Arithmetic behaves mostly as expected, though the symbols are different: ⁺⁻×÷ and for exponentiation. Division rounds down to the nearest integer.

All operators are prefix. This sometimes creates the need to use the separator ¦ between operands to prevent them from being parsed as a single literal.

Charcoal> I⁺⁴¦⁴
8
Charcoal> ,I⁻⁴¦⁴
8,0
Charcoal> ,I×⁴¦⁴
8,0,16
Charcoal> ^C
Cleared canvas
Charcoal> I÷⁶¦⁴
1
Charcoal> ,IX³¦³
1,27

Variables

A variable in Charcoal is any Greek lowercase letter from αβγδεζηθικλμνξπρσςτυφχψω. (Omicron was omitted because it looks too much like o.) You can assign values to them using the command:

Charcoal> A⁵β

Charcoal> ×$β
$$$$$

Input

There are two ways to take input -- to store it as a variable, and to use it directly.

If there is no variable after the command, it is treated as an operator with no arguments, returning the next input:

Charcoal> N
Input number: 5
-----

If there is a variable, input is instead stored in the variable, and nothing is returned.

Charcoal> Nβ
Input number: 3
Charcoal> β
---

Control flow

¿ is the if command. It is followed by an expression (we shall call this x), and two bodies y and z, which are either an expression or multiple expressions surrounded by the double angle brackets «». y gets executed if x evaluates to a truthy value, else y gets executed.

Charcoal> ¿⁰foo¦bar
foo
Charcoal> ¿a«←ab»cd
foba

is the for command. It is followed by an expression x and a body y. If x is a number, it is converted to a range from 0 to x, excluding x itself. Then, x is iterated over, y being run once for each element in x, the element being stored in the first free variable in ικλμνξπρςστυφχψωαβγδεζηθ.

Charcoal> F²⁴na¦batman
nanananananananananananananananananananananananabatman
Charcoal> ^C
Cleared canvas
Charcoal> FHello, World!ײι
HHeelllloo,,  WWoorrlldd!!

is the while command. It is followed by an expression x and a body y. While x evaluates to truthy, y is run, the value of x being stored in ικλμνξπρςστυφχψωαβγδεζηθ.

Charcoal>A¹⁰βWβ«⁺ι A⁻β¹β»
10 9 8 7 6 5 4 3 2 1 

HF is RefreshFor - the same as for but with a numeric delay in milliseconds before x.

Similarly, HW is RefreshFor - the same as while but with a numeric delay in milliseconds before x.

Finally we have , the ternary operator. This accepts three expressions x, y and z, returning y if x evaluates to true else z.

Charcoal> ײ⎇¹b²
bb

More output commands

Multiprint () acts the same as print except that it accepts a multidirection instead of a directions, which is either a list of directions multidirections (+X*|-\/<>^KLTVY7¬).

Below is a list of directions and the directions they expand to:

Symbol Directions
+ Right, Down, Left, Up
X Up Right, Down Right, Down Left, Up Left
* Right, Down Right, Down, Down Left, Left, Up Left, Up, Up Right
` `
- Left, Right
\ Up Left, Down Right
/ Up Right, Down Left
< Up Right, Down Right
> Down Left, Up Left
^ Down Right, Down Left
K Up, Up Right, Down Right, Down
L Up, Right
T Right, Down, Left
V Up Left, Up Right
Y Up Left, Up Right, Down
7 Down Left, Left
¬ Down, Left

The general rule is the directions start from Right, and continue clockwise. The exceptions to this are V and Y.

Charcoal> P*abc
c c c
 bbb 
cbabc
 bbb 
c c c

Rectangle (UR) creates a rectangle with the specified width and height, using | and - as edges and + as corners.

Charcoal> UR⁵¦⁵
+---+
|   |
|   |
|   |
+---+

Box () creates a rectangle with the specified width and height, and using the specified characters as the edge, starting from the top edge.

Charcoal> B⁵¦⁵¦abc
abcab
a   c
c   a
b   b
acbac

Polygon () accepts a list of sides, which are alternating numbers and directions

Other operators

Other data types

Cursor movement

Canvas operations

Output control and animation

Clone this wiki locally