hello_world.0sh

This is a 0-shanten program that outputs the message "Hello, World!"
followed by an LF character:

   🀎🀏🀂🀅🀉🀎🀀🀏🀂🀈🀀🀅🀉 He
   🀏🀏🀀🀌🀂🀐🀙🀅🀙🀅🀀🀌🀂 ll
   🀙🀉🀀🀅🀉🀎🀀🀊🀂🀅🀙🀎🀊 o,
   🀊🀎🀂🀅🀏🀏🀂🀌🀀🀅🀊🀎🀌 %20W
   🀙🀉🀀🀅🀙🀉🀀🀉🀀🀅🀙🀅🀇 orl
   🀙🀎🀁🀅🀉🀎🀀🀉🀂🀅🀙🀁🀀 d!
   🀇🀈🀀🀉🀀🀊🀀🀅🀋🀌🀍🀎🀏 %0A

0-shanten is a stack-based esoteric programming language that is
inspired by riichi mahjong and uses only the following 35 characters
from the Mahjong Tiles Unicode block:

   🀫🀇🀈🀉🀊🀋🀌🀍🀎🀏🀙🀚🀛🀜🀝🀞🀟🀠🀡🀐🀑🀒🀓🀔🀕🀖🀗🀘🀀🀁🀂🀃🀆🀅🀄︎

The 🀫 tile is special and begins a line comment.  The other 34 tiles
each specify an instruction to execute (unless commented out).  All
characters outside the Mahjong Tiles block are ignored.

To execute a program, a program counter, an evaluation stack, nine
variables, an optional input stream and an optional output stream are
used.  The instruction set is as follows:

🀫 🀇🀈🀉🀊🀋🀌🀍🀎🀏
   Push the tile's numeric value to the stack.

🀫 🀙🀚🀛🀜🀝🀞🀟🀠🀡
   Push the value of the variable that corresponds to the tile's number
   to the stack.

🀫 🀐🀑🀒🀓🀔🀕🀖🀗🀘
   Pop the top value from the stack and assign it to the variable that
   corresponds to the tile's number.

🀫 🀀
   Pop the top two values from the stack, add the second value to the
   first and push the sum.

🀫 🀁
   Pop the top two values from the stack, subtract the second value from
   the first and push the difference.

🀫 🀂
   Pop the top two values from the stack, multply the first value by the
   second and push the product.

🀫 🀃
   Pop the top two values from the stack, divide the first value by the
   second and push the quotient and remainder.

🀫 🀆
   Read the next value from the input stream and push it to the stack.

🀫 🀅
   Pop the top value from the stack and write it to the output stream.

🀫 🀄︎
   Pop the top two values from the stack and if the first value is
   greater than 0 then jump to an instruction determined by the second.

Instructions that pop values from the stack do nothing if the stack
contains fewer than the required number of values.

As cute as this instruction set is it does not make for an interesting
enough language on its own, so to spice things we also place a few
additional constraints on programs:

o  The total instruction count must be a multiple of 13.

o  The evaluation stack is cleared every time the program counter
   becomes a multiple of 13.

o  Each consecutive group of 13 tiles must form a valid mahjong hand
   that is in tenpai.

"Wtf is tenpai?", you probably ask.  To answer this, it helps to first
understand what a mahjong hand is and how it is composed.

A game of riichi mahjong revolves around players taking turns drawing
and discarding tiles until one of them forms a complete hand.  A
standard complete hand consists of four groups of three tiles each and a
pair, making for a total of 14 tiles.  A tile group is either a same-
suit sequence of consequtive numbers or a same-suit triplet.

   🀫 Standard hand: 🀇🀈🀉 🀞🀞🀞 🀕🀖🀗 🀀🀀🀀 🀠🀠

(The actual order of the tiles within the hand does not matter, but most
players keep their hands organized to assist readability.)

There are also two exceptions to the standard 4 * 3 + 2 hand
composition: Seven Pairs and Thirteen Orphans.  Seven Pairs consists of
seven different pairs.  Thirteen Orphans consists of one of each of
every one, nine and honor tile, plus any one additional duplicate tile
from that set:

   🀫 Seven Pairs: 🀈🀈 🀎🀎 🀚🀚 🀛🀛 🀕🀕 🀃🀃 🀅🀅

   🀫 Thirteen Orphans: 🀇🀏🀙🀡🀐🀘🀀🀁🀂🀃🀆🀅🀄︎ 🀏

(In an actual game of riichi mahjong there are special circumstances
where a complete hand may include groups of four tiles and thus contain
more than 14 tiles in total, but for the purposes of this language we
only consider 14-tile hands.  In riichi mahjong terms, we can say that
these hands must not have called kan.)

While a complete hand contains 14 tiles, unless a player has just drawn
and has yet to discard a tile their hand will only contain 13 tiles.  A
hand that can be completed just by drawing the correct 14th tile is said
to be in tenpai:

   🀫 Tenpai hand: 🀊🀊🀊 🀚🀛🀜 🀜🀝🀞 🀂🀂 🀓🀔 (waiting on 🀒 or 🀕)

   🀫 Tenpai hand: 🀙🀙🀙 🀛🀛🀛 🀑🀒🀓 🀘🀘 🀞🀠 (waiting on 🀟)

   🀫 Tenpai hand: 🀍🀍 🀎🀎 🀞🀞 🀒🀒 🀀🀀 🀄︎🀄︎ 🀃 (waiting on 🀃)

An important thing to note is that there are only four copies of each
tile available, so a hand can never contain more than four copies of the
same tile.  Therefore, a hand such as the following is not in tenpai
because it can only be completed by a nonexistent fifth copy of a tile
it already has four copies of:

   🀫 Not in tenpai: 🀊🀊🀊 🀚🀛🀜 🀜🀝🀞 🀂🀂🀂 🀊

(As a side note, the minimum number of tile exchanges required for a
hand to reach tenpai is known as the hand's shanten count.  A tenpai
hand has a shanten count of 0, which is what the name of this language,
0-shanten, comes from.)

Now that we know the instruction set and understand tenpai, let's review
the very first line of code in the program near the top of this file:

   🀫 🀎🀏🀂🀅🀉🀎🀀🀏🀂🀈🀀🀅🀉 He

The first two instructions push the values 8 and 9 to the stack.  The
third instruction pops these two values, multiplies them and pushes the
result (72, which is the code point of the character H) to the stack.
The fourth instruction pops this result and writes it to the output
stream.

Similarly, the following eight instructions calculate (3 + 8) * 9 + 2
for the character e and write the result to the output stream.  The
final 13th instruction does nothing meaningful (it pushes the value 3 to
the stack) and is only present to meet the tenpai requirement.  We can
more easily visually verify that the 13 tiles make a tenpai hand by
reorganizing them:

   🀫 Tenpai hand: 🀉🀉 🀎🀎 🀏🀏 🀀🀀 🀂🀂 🀅🀅 🀈 (waiting on 🀈)

After these 13 instructions have been processed, whatever values are
still in the evaluation stack are dropped and we move on to the next 13
instructions.  See if you can figure out how the remainder of the
program works on your own!

As you may have (hopefully) realized by now, the difficulty (and fun!)
of using 0-shanten comes from needing to figure out how to express each
step of a program in fewer than 13 instructions at a time, all while
juggling only nine variables and "wasting" instructions for parity to
form tenpai hands.  In a sense, 0-shanten bears more similarities with
puzzle games than ordinary programming languages.

Interested in learning more about 0-shanten? For more information about
the language as well as example programs and reference implementations,
visit: <https://github.com/castholm/0-shanten>