AlphaStack

Introduction

AlphaStack is an stack-based language that uses only letters of the alphabet as values and instructions.

Being stack based, the instructions typically pop their arguments from the stacks and push their results onto the stack.

Stacks and Procedures

AlphaStack has two stacks:

The value stack is where most operations happens, with individual letters being pushed and popped into it.

The procedure stack contains procedures, the only instruction that can add to this stack is d and some other instructions can access the data stored there.

A procedure is a sequence of letters that can be executed at a later time. Procedures only ever exist on the procedure stack.

This manual will often show a summary of an operation as follows:

This shows the instruction a and its effect on the stack. Values before it in the summary represent the top of the stack before the execution of that instruction. Values after it represent what the head of the stack has been replaced with. In this example, op1 and op2 will be popped off the stack and result will be popped onto the stack.

Literal Mode

AlphaStack has two modes: literal mode and instruction mode.

In literal mode all valid characters are pushed directly onto the stack until the mode is switched.

In instruction mode, all charcters are interpreted as instructions and executed immediately.

The instruction l is used to switch between these two modes, and it's the only instruction to have an effect in literal mode.

Program execution always starts in literal mode so you can add data before adding code.

Comments

AlphaStack doesn't directly support comments but there are a few techniques to simulate them.

All examples in this section are a print the characters a and b using alp and lblp respectively.

First of all, all characters that are not lower case ASCII characters are ignored, so you can always add spaces, upper case letter, and special character.

alp SPACES AND UPPER CASE LETTERS ARE IGNORED! lblp

Since yelling in every comment is considered ruse there's an alternative: using the l instruction you can start pushing values onto the stack, then clear it with u. Note that u needs a marker (which can be any letter) to stop clearing the stack so you can't use that character in the comment.

alp lx this is pushed then popped from the stack, so it has no effect on the program xlu lblp

One side effect of this is that you can't use the marker letter (x in this example) nor single ls in this style of comment as those they will switch back to instruction mode. Pairs of ls will work as switching modes twice has no effect.

alp lx Hello comment! xlu lblp

Numbers

In AlphaStack there are only letters, no numbers. However can consider interpret the letters as numbers based on their position in the alphabet. With this in mind, a can be thought as 0, b as 1 and so on.

Similarly, the value a is considered false, while all other values are considered true.

Registers

Each letter has a register associated with it. These registered can be freely written to or read from (using s and g). Some instructions modify their behaviour based on the value of the corresponding register.

At the start of a program all registers have a value of a (0).

Tutorial

This section will walk through the basics of AlphaStack with some practical examples. The tutorials assume you've been through the introduction fist.

Hello World

This tutorial shows the basics of printing text to standard output

abcd

Since a program starts in literal mode, this code pushes abcd onto the value stack. d being at the top of the stack and a at the bottom.

abcd l

Any characters that are not letters are ignored, so the space does nothing. l exits literal mode and enters instruction mode. This means after it letters will be executed as instructions rather than pushed onto the stack.

abcd l pppp

Here p is executed 4 times, printing 4 letters off the top of the stack. This clears the stack as each letter is popped before printing and outputs dbca.
The order of the letters is reversed because they are printed from the top of the stack.

Now, if we want to print abcd as numbers instead, we need to set the p register to c first, this is done with the s command which pops a reister and its value off the stack:

abcd pc l s pppp

Here pc on the stack is consumed by s to do just that and the code outputs 3210.

Again, spaces are not meaningful in AlphaStack in the example they are used to highlight which literals are used by which instuction.

If you want to enter values in literal mode and then print them in the same order as they were pushed onto the stack, you need to flip them around first:

abcd e l f pppp

Now f pops e off the stack, this corresponds with the number 4, and flips that many items on the stack. In this case the stack ends up as dbca, printing abcd.

Let's say we want to print the word "hello". There's an issue here, l switches between literal mode and instruction mode so it can't be directly entered as a literal. To work around this we can push a value l onto the stack by performing a simple mathematical operation:

kb l a p

a pops two values off the stack and adds them together, in this case adds b (1) to k, obtaining l. Then p prints it.

Now we can print hello like so:

o kb kb e h l p p ap ap p

The first two p print h and e respectively. Then a followed by p print an l, this is done twice. The final p prints the o.

Replacing each l individually can become tedious so we can push a single one onto the stack and then replace a different character with it.

Here a turns kb into l like before. o then pops the 3 topmost items on the stack: yxl. It then performs a replacement of the values on the stack with as follows: all occurrences of x are replaced by l until the next y is reached. In this case there are no y values on the stack after the initial one so the entire stack is processed. Finally the five p print hello.

We can combine all of this with different print modes to print Hello World!:

a pd djro pa w pb w pc ojje xjbk pa h pb l sps ao pppp spsps pppp sp

Procedures and Loops

Let's say you don't want to type a p for every single letters you want to output. We can create a procedure that prints the stack until a condition is met.

First we need to get a condition that checks the top of the stack for a given value and halts execution when found. Conditionals are handled by i, which needs a procedure to run when the condition is met. We start by defining the halting procedure:/p>

xhx l d

d here uses x as a delimiter and pushes a procedure containing h on top of the procedure stack.

Now we are ready to define the main procedure. Since we need literals in the main procedure we need to perform the usual trick to replace j with l:

xpikacjbzjx jbk ob xhx l d sao d

This code starts as before with d popping xhx from the value stack and pushing h onto the procedure stack. Then sao performs the j to l replacement: s pops ob to set the o register to keep the delimiter. a the pops bk to push a l. o pops jl to replace all occurrences of j with l using x as a delimiter. Since we set the o register register to the value b using s, the x delimiters are not removed from the stack. This allows d to use the same deimiter.

Finally, d pops xpikaclbzlx from the value stack and pushes lzblcakip onto the procedure stack. Note that d removes the delimiters from the procedure and reverses the order of its letters so when you define procedures in literal mode, you need to flip them around.

Now let's see that the code in the procedure does:

lzbl ca kip

l toggles between modes so lzbl results in a literal pushing z and b onto the stack. c then pops b from the stack, this is a value of 1 which means c copies the next item on the stack, skipping the z. After c the stack top of the contains a copy of the initial top of the stack followed by z.

a then performs an operation on these two. The operation performed by a is determined by the value of the a register. The default operation is addition but it will need to be set to equality comparison before the procedure is executed. If the a register is set to comparison, a will pop the two letters off the top of the stack and push true (b) or false (a) depending whether they are the same.

Follows k which copies the top procedure from the procedure stack, this is requires to prevent i from consuming it since we are looping. i consumes the copied procedure and the result of the comparison, executing the procedure if the result is true (b). When the procedure is executed, the program halts (this procedure is h, which was defined at the start. Finally p pops and prints the top of the stack. This only happens if the condition was false as it means the program was not halted.

Final bit of setup:

a af xpikacjbzjx jbk ob xhx l d sao d s r

Here is the same but there is more data onto the stack and two more instructions. The second s pops af to set the a to equality comparison mode. Then r will pop the remaining a which means it will loop forever (or in this case until halted.

Now all that's needed is some data on the stack to be printed, using z as a delimiter (since it's the value we're comparing against on the procedure).

z kcatsehtgnitnirp a af xpikacjbzjx jbk ob xhx l d sao d s r

printingthestack

Alphabet

AlphaStack uses the 26 (lower case) letters of the Latin alphabet. All other characters are ignores, including upper case letters.

Letter Details

a - Arithmetic Operation

Synopsis

The a pops two values from the stack, performs a mathematical operation on them and pushes the result back onto the stack. In all cases num1 is the left hand side operand and num2 is the right hand side operand.

The specific operation to be performed on the two operands depends on the value of the a register.

a - Operation Register

Examples

cdlap

f

The program starts in literal mode, so c and d are pushed onto the stack as data.
l disables literal mode, so a is executed as an instruction. It pops c (2) and d (3) from the stack calculates their sum, f (5), then pushes it onto the stack.
Finally, p prints the top of the stack to standard output.

czlap

b

This example adds c (2) and z (25). Ther output is b (1) because math operations are modulo 26.

cdaclsap

g

This example multiplies c (2) and d (3). This is achieved by setting the a register to c using s.

b - Break

Synopsis

Breaks out of the current loop. Does not affect the stack.

Example

If we take this starting example:

xpkbl a labl c lxl d lal r

it will endlessly print a.

The explanation chunk by chunk:

xpkbl a

Pushes xpkb onto the stack, then calls a to add b and k to obtain l since l can't be pushed onto the stack directly, obtaining xpl.

labl c

Pushes a and copies the l with c resulting with the stack xplal.

lxl d

Pushes x as a marker, then d rolls the stack betwen the two x markers into a procedure. Note that the procedure will be reversed compared to the other of the stack. The procedure will be pushed into the procedure stack as lalp.

lal r

Pushes a onto the stack to create an infinite loop with r, which will pop the created procedure and loop it indefinitely. The procedure just prints a every time.

xbpkbl a labl c lxl d lal r

a

c - Copy

Synopsis

Copies a value index positions into the stack.

It pops index, looks into the stack from the top that many spaces, and pushes a copy of the corresponding value on top of the stack.

Example

somedatafl c

This pushes somedataf onto the stack then executes c. It will pop f (5), then look that many spaces down the remaining stack, find m and copy it on top of the stack. This results in a stack of somedatam.

d - Define

Synopsis

Defines a procedure delimited by mark and pushes it on the procedure stack.

It pops the first stack value, mark which can be anything, then keeps popping until another value equal to mark is found (or the stack is empty).

The result is then pushed onto the procedure stack, with the values flipped compared to how they were in the initial stack. The flip happens because values are pushed onto the procedure as they are popped from the stack.

Example

zerudecorp a af xpikacjbzjx jbk xhx ob l sdaodsr

procedure

Before the l all the letter are pushed onto the stack. then the following operations are performed:

s pops ob and sets the o register is set to keep the delimiter.

d pops xhx and pushes h as a procedure. Here we are using x as a delimiter but any letter works as delimiter, just ensure it isn't used with the procedure itself.

a pops bk, adds them, and pushes l (this is because l cannot be used as a literal).

o pops jl and preforms a replacement from j to l. using x as delimiter. Results in changing the top of the stack from xpikacjbzjx to xpikaclbzlx. The x delimiters are preserved due to the value of o register that was set previously.

d pops xpikaclbzlx and pushes lzblcakip as a procedure.

s pops af and sets the a register to perform equality comparison.

r pops a and performs the last procedure indefinitely.

lzbl c akip

lzbl pushes zb onto the stack.

c pops b and copies the item below the head of the stack back on top. This copies the value set at the start of the main code

a pops the copied value and b from the stack pushing b (true) or a (false) based on their comparison (because a register is set to comparison.

k duplicates the top procedure. Note that r pops the procedure before looping so the top procedure is now h.

i pops the value left by a and the procedure duplicated by k. If the result of the comparison is true, (the letter copied by c is z), it will call the procedure which in turns halts the program using h. If the condition is not true nothing else happens.

p pops the top of the stack and prints it. This causes the stack size to decrease by one.

After this r keeps repeating the procedure, which has the effect of printing the stack until the character z is reached.

e - Execute Specific

Synopsis

Executes a specific procedure based on e register, not affecting any of the stacks.

This is handy to repeatedly calling a procedure without having to modify stack values.

e - Execute Index Register

Procedure index for e. A value of a (0), which is the default means the first procedure.

This index is counted from the bottom of the procedure stack.

Example

tset xqx xax xpx xhx eb l s dddd eeee

test

Values are pushed onto the stack until l.

s pops eb and sets the e register is set to b (1).

d is called 4 times and it defines procedures based on the x delimiter. After this the procedure stack has these procedures: h, p, a, q.

e is called 4 times as well, each time executing the procedure at index 1, which just prints the top of the stack. Note that any procedure defined after the one with the given index doesn't matter as e register refers to indices starting from the bottom of the procedure stack.

f - Flip

Synopsis

Reverses the order of count items on the top of the stack.

Pops count, then pops that many other items off the top of the stack and pushes them back onto the stack but in reverse order.

Example

foobar d l f

Values are pushed onto the stack until l, resulting in the stack containing foobard.

f pops d (3), then flips the next 3 items on the stack, resulting with a stack of foorab.

g - Get

Synopsis

Pops reg from the stack, then pushes the value of the corresponding register onto the stack.

Example

m mf l s g

Values are pushed onto the stack until l, resulting in the stack containing mmf.

s pops mf and sets the m register to f.

g pops m and pushes its value (f) onto the stack, resulting in a stack with f.

h - Halt

Synopsis

Halts execution, without affecting the stack.

Example

abcd l p p h p p

dc

Values are pushed onto the stack until l, resulting in the stack containing abcd.

p is called twice popping d and c off the stack and printing them.

h halts execution so the remaining p calls are not executed.

i - If

Synopsis

Pops the top value from the stack and the top procedure off the top of the procedure stack. If the value is true (anything but a), the procedure is then executed.

The value of the i register defines if-else chain, i will pop enough values and procedure to satisfy that many conditions.

i - If Else Count Register

Determines how many if-else chains are present (if any).

The default value of a (0), indicates there is no else to execute. i will pop a single value and procedure.

A value of b, indicates an else procedure. i will pop one value and two procedures, the second procedure being executed if the condition is not true.

For higher values of the i register, i will pop additional values off the stack and procedures, executing the procedure of the first matching condition (or the last procedure if no conditions match).

Examples

z xjajx yjkb l ao d t i p

Output: a or z based on user input.

Values are pushed onto the stack until l, resulting in the stack containing zxjajxyjkb.

a pops bk, adds them, and pushes l (this is because l cannot be used as a literal).

o pops yjl and preforms a replacement from j to l until the end of the stack since there are no other y values on the stack. All this results with a stack of zxlalx.

d pops xlalx and pushes lal as a procedure. This procedure just pushes a onto the stack.

t reads a character from the user, converts it into a letter, and pushes it onto the stack.

i pops this user-generated value, the procedure, and if the value is true, the procedure is executed. Now the stack is either z or za.

p pops the top of the stack and prints it, printing a if the user input evaluated as true, and z otherwise.

xjajx xjzjx yjkb ib l s ao dd t i p

This example has the same output as the previous one but it works slightly differently.

The first operation after exiting literal mode is s to set i register to b (1). This indicates that i register should use an else procedure.

Now the next difference is that there are two procedures in the procedure stack: lzl and lal, wich just push z or a onto the value stack. Note that lal is the procedure on top of the stack because it has been pushed last.

i now pops both procedures off the procedure stack, executing the first on true and the second on false.

xjajx xjbjx xjcjx yjkb ic l s ao ddd tt lclf i p

This example takes 2 inputs from the user and selects one of 3 procedures to execute.

tt will read 2 inputs from the user and push them onto the stack. since this will cause the inputs to be in reverse order (the last input is on top of the stack) lclf uses f to flip them back around. Now the first input is on top of the stack and the second input below it.

The i register is set to c (2), indicating an else-if chain.

i now pops 2 values off the value stack and 3 procedures. It uses the first value from the stack as the first condition, if that is true the first procedure is executed. Otherwise, if the next value is true, the second procedure is executed. Finally, if both values are false, the third procedure is executed.

k - Keep

Synopsis

Duplicates the procedure on top of the procedure stack.

This is useful if you want to run i or x while keeping the procedure on the stack for later use.

Example

xpppjfoojx yjkb l ao d kxx

foofoo

Values are pushed onto the stack until l, resulting in the stack containing xpppjfoojxyjkb.

a and o ensure j values on the stack are replaced by l as l cannot be used as a literal. The stack after them is xppplfoolx

d defines the procedure looflppp, which prints the string "foo" to output.

Finally k duplicates this procedure, and x is called twice, popping and executing the two copies of the procedure.

l - Literal

Synopsis

Switches between literal and instruction modes.

Specifically it toggles the l register between a (0), which indicated literal mode, and b (1), instruction mode.

While in instruction mode all letters are executed as an instruction.

In literal mode (which is the mode at the start of execution) letters are pushed onto the value stack.

l will keep its behaviour in both modes so the letter l cannot appear directly as a literal.

l - Mode Register

Determines whether the program is in literal mode or instruction mode.

A value of a indicates literal mode, any other value is instruction mode.

Generally it's toggled with l but setting a value explicitly using s will also switch between modes.

Example

oof l ppp lrabl ppp

foobar

oof are pushed onto the stack because the program starts in literal mode.

l enables instruction mode and p is called 3 times to print foo from the stack to the output.

In lrabl literal mode is entered again to push rab onto the stack, the last l goes back into instruction mode.

Finally p is called again to print bar.

Adding l onto the stack

Since l ends literal mode, values of l cannot be directly added onto the stack, but some easy work-arounds are available.

The most basic is to use addition to get an l from other values:

kb l a

Here a pops k and b from the stack, adds them together, and pushes l (the result of this addition) back onto the stack.

Sometimes you might want multiple l on the stack, this is especially useful when defining procedures that need to output literal values on the stack. You can achieve this by combining the previous approach with the overwrite instruction (l):

jjj x jjj x j bk l ao

Here a does the same as it did before, replacing bk with l.

o pops xjl. It preforms a replacement from j to l using x as delimiter. Both instances of the delimiter are removed from the stack.

At the end the stack will be jjjlll, the first the j not being replaced because found after the delimiter when searching from the top of the stack.

m - Memory

Synopsis

Pushes the value of the m register onto the stack.

This can be useful if there is a value that needs to be pushed onto the stack multiple time.

m - Memory Cell Register

Doesn't have any special meaning, pushed onto the stack by m.

Examples

lmmmppp

aaa

l enables instruction mode.

m is called 3 times and pushes the default value (a) onto the stack each time.

p is called 3 times, popping the 3 values and printing them.

mz l s mmmppp

zzz

Same as before but s uses the z and m values from the stack to set the m register to z.

o - Overwrite

Synopsis

Replaces values on the stack until a delimiter is reached.

Pops replace and search from the stack. Then replaces all instanced of search between the two mark with replace.

If the second mark is not found, all occurrences of search will be replaced.

The two mark are removed from the stack by default but they can be preserved depending on the value of the o register.

o - Keep Mark Register

By default o deleted the markers from the stack, if this register has a value other than a, they are kept.

Example

test x test x t b l o

All the values until l are pushed onto the stack.

o pops xtb from the stack, and replaces all t into b until the next x is found.

This results in the stack ending with testbesb.

Note that the value x is arbitrary, any letter can work as a marker.

test x test x t b ob l s o

Similar as before, now s pops ob and sets the o register to b.

The rest works the same except the markers are kept, resulting in testxbesbx.

p - Print

Synopsis

Pops a letter from the stack and prints it to output.

By default prints them as lower case letters but this can changed based on the value of the p register.

p - Print Mode Register

Specifies the print mode, depending on the mode letters are printed differently.

Using the right combination of printed letter and mode, any ASCII character can be printed.

The special mode z will cause p register to not print anything turning it into a pop operation.

Examples

tnirp l ppppp

print

All the values until l are pushed onto the stack then p register is called multiple times, each time it pops a value off the stack and prints it.

Note that since p register prints off the top of the stack, the stack values need to be in reverse order to be printed.

tnirp pb l s ppppp

PRINT

Similar as before, now s pops pb and sets the p register to b, switching to uppercase print mode.

hddb pc l s pppp

1337

Print mode c can be used to print numbers.

tnirp pz l s ppppp

Print mode z can be used to pop values off the stack without printing them.

a pd djro pa w pb w pc ojje xjbk pa h pb l sps ao pppp spsps pppp sp

Hello World!

Does the usual trick to replace l (see l examples). Then keeps switching print modes and printing values from the stack.

r - Repeat

Synopsis

Pops count and the top procedure from the procedure stack and executes said procedure count times. A count of a (0) means infinite loop.

Example

tset e xpx l dr

test

After l the stack contains tsetexpx.

d pops xpx from the value stack and pushes p on the procedure stack.

r pops e (4) from the value stack, the procedure from the procedure stack and repeats it 4 times, printing the 4 remaining letters on the stack.

s - Set

Synopsis

Pops reg and val from the stack, then sets the corresponding register to val.

Example

m mf l s g

Values are pushed onto the stack until l, resulting in the stack containing mmf.

s pops mf and sets the m register to f.

g pops m and pushes its value (f) onto the stack, resulting in a stack with f.

t - Text Input

Synopsis

Pushes a letter onto the stack based on user input.

Reads one character from the input stream, converts into a letter using the reverse operation of p and sets the t register to the print mode that would yield that character.

On failure (end of file or invalid character) it sets the t register to z and doesn't push anything onto the stack.

t - Read Result Register

Holds the status of the last t operation. Basically if you want to print back the same character you need to set the p register to the value of the t register. The special value of z indicates an error. Refer to the documentation of the p register for a description of values.

Example

lt

l exits literal mode, then t reads one character from input. Follow a few examples of the end state based on the input.

If the user typed h, the t register holds the value a and the stack the value h.

If the user typed H, the stack still holds the value h but now the t register has the value b which corresponds to the upper case print mode.

If the user typed 3, the stack still holds the value d but now the t register has the value c which corresponds to the number print mode.

If the input reached end of file, the t register will have the value z and the stack will be empty.

u - Undo

Synopsis

Pops everything on the stack until mark is found.

Starts by popping mark, that can be any letter. Then it keeps popping until it finds another value of mark or the stack is empty.

Example

foobartest l u

Before u register is executed, the stack contains foobartest.

u register pops a t then keeps popping until the following t is popped, then stops. At the end the stack holds foobar

w - Wrap

Synopsis

Wraps the top count items of the stack by steps steps.

Starts by popping count and steps from the value stack. Then it pops count more items, which will be the operands of the wrap operation.

A wrap step consists on moving the first operand to the back of the list of operands. This is applied steps times.

After all the steps, the operands are pushed back onto the stack in their new order.

Examples

foobar db l w

Here w performs b (1) step on the top d items, which are bar. This turns bar into rba as the r is moved to the back.

At the end the stack contains foorba.

foobar dc l w

The only change is the number of steps, resulting in a stack with fooarb.

x - Execute

Synopsis

Pops and executes the top procedure.

Example

abc qppq l d x p

cba

After l the stack contains abcqppq.

d pops qppq and pushes pp onto the procedure stack.

x pops this procedure and executes it. the procedure calls p twice printing cb.

Finally execution continues after x, where an additional call to p prints a.

y - Yield

Synopsis

Stops execution of the current procedure, leaving the stack unchanged

Example

abc qpypq l d x p

cb

This is the same as the example for x with the exception of the presence of y in the middle of the procedure, which causes the second p to not be executed.