blang/README.md

```
/*  _     _                       _
   | |   / |                     / /
   | |__| ||__ _ _ __   __ _    / /
   | '_ | |/  ' | '_ \ / _' |  / /
   | \_|| | ||  | | | | /_| | /_/
    \___/_____/___| |__,_  / _
                     |____/  */
```
# blang!
the bang language

Public domain. 2022 DTB.

Bang language is an unpleasant toy designed to be used in the murderu.us IRC
server, but easily adapted anywhere due to its simplicity both in terms of
model and implementation.

## Glossary

### chart

The listing of the program currently running.
This can be modified during runtime.

### command

A character that indicates what the bang language executor should do next.

### comment

Ornamental characters, i.e. in-code notes.

Comments can start with `';'` (in which case they're discarded from the chart)
or `'#'` (in which case they're kept on the chart).

Comments end with `'!'` or `'\n'`.

### hand

The general-purpose register.

### catch

To set the hand to a value.

### throw

To set a value to the contents of the hand.

## Reference

All operations are one character long.
When an unknown operation is executed the resulting behavior is undefined
(and maliciously so; for example, execution can stop or garbage can be written
to the chart).

Operation mappings are based on ergonomics and history.
`'&'` and `'*'` are taken from C.
`'+'` and `'-'` are taken from Brainfuck.
`'<'` and `'>'` are more or less taken from the Bourne shell.
The general ergonomics of bang language are informed by the story of Mel,
part of hacker folklore.

### `'!'`

No-op. Does nothing.
`' '`, `'\n'`, `'\r'`, `'\t'`, and `'\v'` are all also no-ops
\- keep this in mind when styling code that contains `'?'`!

### `'#'`

Denotes a comment.
The contents of the comment are kept in the chart but not executed.

### `';'`

Denotes a comment.
The contents of the comment are discarded from the chart before runtime.

### `'^'` and `'%'`

`'^'` palms the content of the location of the program to which chart points.
`'%'` throws at that location.

The following program prints "Hello, world!",
by iterating over the program listing itself and terminating after printing a
line feed (10 decimal in ASCII):
```
!Hello, world!
{
&+*
^>
----------?};	subtract 10, if the value is non-zero return
vv*
```

### `'&'` and `'*'`

`'&'` (et) palms the chart. `'*'` (splat) throws the chart.

The following program rewrites itself during runtime, navigating the chart
using et and splat. Keep in mind `'!'` must be followed by `';'` in comments
to maintain chartlessness:

```
!vv;	zero out hand
{?>;	set return point; if hand is non-zero, print hand
!&;	palm the chart
++++*;	add 4 to palm; splat the new chart
<!%;	write '!;' to the new chart position
&++*;	palm the chart; add 2 to palm; splat the new chart
<<%;	write '<' to the new chart position
&+*;	advance the chart one space
<
%;	write '\n' to the new chart position
&+*;	advance the chart one space
<>%;	write '>' to the new chart position
&+*;	advance the chart one space
<v%;	write 'v' to the new chart position
&+*;	advance the chart one space
<v%;	write 'v' to the new chart position
<!;	palm '!;'
};	return
```

Right before the final `'}'`, the chart is the following:

```
!vv;	zero out hand
{!>;	print hand
<
>;	palm `'\n'`; print hand
vv*;	splat zero to chart

The rest of the program isn't executed.
```

### `'<'` and `'>'`

`'<'` palms the next character literal.

`'>'` prints the literal contents of hand to standard output.

The following program prints "Hello, world!" the easy way:

```
!<H><e><l><l><o><,>< ><w><o><r><l><d><!>v++++++++++>v*
```

This is a quine; a program that prints itself.

```
{&+*!^>v?}v*
```

The following program prints the printable ASCII space:

```
!^*{;	palm bang (the first printable ASCII char), splat
&>+*;	et, throw onto screen, increment, splat
------
------
------
------
------
------
------
------
------
------
------
------
------
------
------
------
------
------
------
------
------;	subtract 126
v?};	if hand == 0, return
<
>;	print newline
vv*;	exit
```