Mbv142

-MacroBeep Documentation v 1.4.2-

Thank you for using MacroBeep! A language by @PixelatedStarfish on
esolangs.org (Andrew Vella). This documentation provides a reference
for use, and fully defines an interpreter for the language.

File Extension .mcbe

Comments and and Questions can be left on this page:
https://esolangs.org/wiki/Talk:MacroBeep


*Contents*

MacroBeep at a Glance
Acknowledgements
Design Philosophy
Language Paradigm
Limitations and Considerations
Instruction Set
The Preprocessor and Include Statements
Libraries
Program Examples
Error Codes
The Debugger
Turing Machines and the MacroBeep Tape
Proof of Turing Completeness
Grammar in EBNF
Test Cases
ASCII Table Reference
Change Log
Sources


*MacroBeep at a Glance*

Syntax

All programs start execution at the statement "macro main".
Source is designed for tracing. Statements end with a newline. An
instruction consists of a command and an optional argument.
Commands and arguments are separated by a space. An argument can be
a string or an integer. All leading whitespace is ignored. #Inline
comments start with hashtags, or octothorpes, and end at a newline.
##Multi-line comments are enclosed in doubles##

Memory

Memory is stored in cells on a tape. Each cell stores a byte.
The tape pointer can access cells, modify cells, and output cell values.
The tape pointer always starts at cell 0, or the head. All computation
in MacroBeep happens on the tape.

To improve memory management, MacroBeep features
a mark stack and a strip. The mark stack is a stack of marks.
Marks mark a specific cell so the tape pointer can return to it later.
The strip stores data temporarily for use. So combined,
these let a programmer move data from one part of the tape
to another, modify the data and move it back to the last marked
location. A debugger provides Information about the state of the
program memory for each instruction.


Macros

Macros are defined in source as a series of instructions. When a macro
is called, the instructions that define the macro are executed.
A program will implicitly run the main macro. Macros can recurse,
call other macros, and terminate with a return statement.
Macros modify cells directly; apart from an identifier, they do not
take arguments.

Files

MacroBeep programs can be composed of several files; ".mcbe" is the
extension for a MacroBeep file. Files can be run from the run directory,
or any sub-directory of the run directory. Include statements link files
together into one larger program.


*Acknowledgements*

I certainly would like to thank family, friends, and of course,
mademoiselle for their support and care.

Thank you to the Skidmore College faculty, O'Connell, Dufour, Eckmann,
Read, Reiley, and Prasad. I am glad to have my degree in computer science!
I would also like to thank Bringas, Kravsky, and Lee for their tutelage,
patience, and inspiration. MacroBeep would not exist without the esolangs wiki
and the work of youtuber Truttle1.


*Design Philosophy*

Macrobeep is designed in response to common problems people face when
learning to code in more conventional programming languages. The syntax is
designed to communicate what the computer is doing in a clear and
concise manner. For every MacroBeep program, there is an equivalent
MacroBeep program that can described as a sequence of native instructions
in a specific order.

A MacroBeep programmer does not have to search for the missing punctuation.
They do not need to find the unmatched parenthesis, or count their braces.
They do not need to deal with the particularities of data types or the
difference between objects, classes, structs, and interfaces.
High-level abstraction is sacrificed for clarity and traceability.

This language is not without cons. A programmer needs to manage program
memory themselves. Data cannot be protected. It is up to the programmer
to make sure that something is not overwritten before it should be.
A MacroBeep programmer should also be familiar with Turing machines
and the ASCII table. This document covers everything you need to program
in MacroBeep.


*Limitations and Considerations*

One can only go so far to ease the challenges of memory management
on a global tape. In theory the tape is infinite,
but cells toward the head are easier to work with, so in
practice, each macro competes for space. Planning is a must.
The tape is unforgiving, and this makes writing complex programs
a bit tedious...

Further versions require the replacement of the global tape with
isolated strips of tape for each macro. Ideally, macros would also
take arguments to promote readability.

Dealing with tape pointers for each macro would prove a
challenge all its own. So each cell would have an index
such that an argument can refer to a cell value.

Such a version would allow for much more forgiving memory management;
memory can be allocated and freed for each macro.
Tape pointers are eliminated, so each macro does not need a pointer
of its own.

*Language Paradigm*

MacroBeep is an assembly style language with an instruction set, such
that the programmer can define macros in order to describe and implement
more complex operations. There is no part of a MacroBeep program that can be
considered stateless, and there are no functions in MacroBeep. Instead,
a program modifies bytes on a tape using a pointer in a manner similar to bf,
such that each cell on the tape can store a value between 0 and 255 inclusive.
A program in MacroBeep will always run the main macro before any other
macro.


*Instruction Set*

Each operation can take an identifier or an integer value as an argument.
A macro cannot be a reserved word or operation name. Operations are
separated by a newline, and arguments by a space.

Before reading the table, a quick clarification should be made.
A branching instruction does either of these:

- shifts execution forward by some (positive or negative) number
 of instructions

- starts execution at the label given

Instruction Table

macro    (define macro; takes an identifier)

do       (do macro identified in arg, call macro)

rt       (return to macro call an execute next instruction)

null     (set cell to 0)

str      (store value of current cell in next cell, or offset from
         the current cell as specified such that -1 indicates storage
         in the left cell.)

stat     (short for 'store at', this stores the value of the current
         cell at the cell given in an argument. 'stat 2' stores the
         value of the current cell 2 cells right of the head.

rand     (set cell a random from 0 to arg or 0 to 255)

add      (add to cell; 1 if no arg)

sub      (take from cell; 1 if no arg)

right    (move pointer to the right; by 1 if no arg is given)

left     (move pointer to the left; by 1 if no arg is given)

head     (go to head of tape, or to specified offset from head)

pos      (get position of cell pointer on tape and print it)

inp      (get input; char, int, or string by args 0, 1, 2)

out      (print cell or arg)

cout     (print char on cell or arg as char)

pr       (print any value given as a string with a newline, newline
         if nothing. Use '[]' to print a space and '{}' to print a tab)

beep     (it goes beep, use an argument to specify frequency in hertz.
         Default is 1000)

label    (for an example of how to use a a label, see the false machine)

send     (copy one or more cells to the head of the tape; mark the
         location of the first cell copied. Pushes a mark)

reply    (copy one or more cells from the head of the tape to the cell
         location marked; this erases the strip of copied data and
         pops a mark of the stack.)

solar    (branch if cell is greater than 0)

lunar    (branch if cell is 0)

venusian (branch if cell is equal to next cell)

martian  (branch if cell is not equal to next cell)

jovian   (branch if cell is greater than next cell)

plutonic (branch if cell is less than next cell)

vestian  (branch if cell is greater than or equal to next cell)

sednian  (branch if cell is less than or equal to to next cell)

halt     (end program)

wait     (adds a delay of 100ms, or as specified by an argument)

include  (include files at path identified)

#        (inline comment)

##       (start or end a multi-line comment)


*The Preprocessor and Include Statements*

The Preprocessor formats source code so that it can run appropriately.
All leading whitespace before an instruction is removed. All blank lines
are removed. If needed, all null lines are replaced with empty comments.
(Comments are ignored at runtime and do not need to be removed.)
Additionally, all include statements are processed. The contents of each
included files are concatenated into a single set of source.

The include statement includes all the macros in a file so a program
can use them. As stated above, include statements include files at the path
identified. So...

include run\foo\hw.mcbe

... includes the hw.mcbe file in a subdirectory foo, in run. Note
that the run directory (or folder) is included in the file path.
This ensures that the interpreter will look for files in the run directory.

The entire contents of a directory can be included using an asterisk
( * ) like so...

include run\foo\*

Now suppose that hw.mcbe also has include statements. A programmer
could write paths back to run but it can be tedious if the path back
to the run directory is long.

The closing angle bracket ( > ) is useful for this case.
It gets replaced with the path from run to hw.mcbe. So...

include run\foo\bar\tm.mcbe

is equivalent to

include >\bar\tm.mcbe


*Libraries*

Libraries are quite simple in MacroBeep. They are ordinary .mcbe files
stored in a directory called "lib" instead of in run. You can write
your own, just as you would any other MacroBeep program.

As of this version, a library called "SumDif" is included.
It can calculate a sum and a difference using "SumDif.sum" and
"SumDif.dif"

The convention for naming macros in libraries is to start with
the name of the library, then a dot, then the rest of the macro name.
For example "SumDif.sum" is the name of the sum macro in the SumDif library.

In java the dot would indicate that sum is a static method in SumDif.
In MacroBeep the use of a dot is only a convention. The linker is
minimal in MacroBeep; it does not enforce the use of a dot operator.


*Program Examples*

It is good practice to indicate the scope of an instruction with tabs
or spaces. This can be useful to indicate which instructions are part of a
macro. Leading white space is not required. New lines are the only
significant white space characters.

The end of a program is indicated by #$

Hello World
macro main
pr Hello[]World
# Note that the [] is printed as a space

Truth Machine
macro main
pr Type[]a[]0[]or[]1[]into[]the[]truth[]machine.
inp 1
solar 3
pr 0
halt
pr 1
wait
solar -3
#$

False Machine

macro main
pr Type[]a[]0[]or[]1[]into[]the[]false[]machine.
inp 1
lunar magic
pr 1
halt
label magic
pr 0
wait
lunar magic
#$

Cat

macro main
pr Give[]me[]a[]word[]and[]I[]will[]say[]it[]back!
inp 2
head
cout
right
solar -3
#$

C scale
macro main
beep 262
beep 294
beep 330
beep 349
beep 392
beep 440
beep 494
beep 523
#$

Sum of Numbers

macro sum
 send 2

right
 label WhileCellTwoIsNotZero
   add -1
   head
   add 1
right
   solar WhileCellTwoIsNotZero
 reply
 rt

macro init #initialize
 right 2
 add
 right
 add 2
 right
 add 3
 right
 add 5
 right
 add 8
 right
 add 13
 right
 add 21
 rt

macro main
 do init
 head 2

 #Loop through numbers and add them together
 label Loop
  right
  lunar ifTheCellIsZeroGoHere
  left
  do sum
  str
  right
  solar Loop

 #Output
 label ifTheCellIsZeroGoHere
 left
 out
 rt
 #$

Note that some main macros do not include a return statement 'rt'.
This is because the program ends when the macro does. A 'rt'
can be added to the main macro but it is not required. A macro
without an 'rt' will continue to execute until it reaches an 'rt'
somewhere or gets to an End Of File. So...

macro main
beep
macro sub
beep 555
rt

... will execute. 'do sub' will execute the macro 'sub'. 'do main'
will execute from the top to the 'rt'. However, any statements
after the 'rt' would not execute, since macro 'main' has finished.


*Error Codes*

Error (0)
The Generic Error Message, for errors not described below.

Undefined Instruction (1)
Thrown when the interpreter encounters an instruction that is not
defined in the instruction set.

File Not Found (2)
Either the file does not exist, or it is in the wrong directory.

Undefined Macro or Label (3)
The macro called by "do" has no matching definition; alternatively,
the label branched to does not exist.

Missing Main Macro (4)
"macro main" is missing, the program cannot start.

Stack Overflow (5)
This error is most commonly caused by an infinite recursion. Too many
macro calls on the call stack.

Not a Cell Error (6)
Occurs when a program tries to modify a cell that does not exist,
such as cell -1 or cell infinity.

Include Statement in Macro (7)
An include statement cannot be written into a macro definition.

Preprocessor Error (8)
A preprocessor error that is not caught by any other error code. Check
include statements carefully.

Duplicate Macro or Label (9)
A macro or label is defined more than once in the program. Calls to
it are ambiguous.

Argument Error. Integer Expected (10)
An instruction that only takes an integer argument was not given an
integer argument.

Bad Argument (11)
This is the error thrown when the interpreter reads statements that
are syntactically correct, but incomputable in this language, such as
"wait -100". Esoteric models of time notwithstanding, instructions that
require negative time to compute would throw this error.

Astrological Error (12)
This error occurs when the next instruction to execute is located
outside source entirely. It is as if you gave the interpreter a To-Do list
of 10 or so items in an order, and then said "Hey, no need to do that fifth
thing, go do item 24, or -5 instead. " Confusion would be understandable,
and nothing would get done!


*The Debugger*

This displays the following information for each instruction:
-The current instruction.
-The current macro.
-Position of a marked cell.
-Data on the strip (used by the send and reply operations)
-A section of five cells on the tape, centered on the pointer.

Every 25 steps, the debugger will stop and wait for a key press.
This keeps from overloading the shell with text.



*Turing Machines and the MacroBeep Tape*

What is a Turing Machine?

The Turing Machine is a theoretical machine first described by Alan
Turing. It consists of a tape divided into cells and a pointer that
can modify cells on the tape. The tape extends without bound, so the
machine never runs out of cells. (In practice, this is not possible,
but such a limitation is usually ignored).

A Turing machine can do the following:

Shift the pointer left or right
Read the value on the cell
Write a value to a cell

The pointer can point to one cell at any given time, and it can only
act on the cell at which it points. To act on another cell the pointer
has to move to that cell. The pointer of a Turing Machine is programmable.
It can be given instructions like: "Set the current cell to 0", or
"If the current cell is one, go one cell to the right". These instructions
describe something called a Finite State Machine, which is a machine
that knows its current state, and decides what to do next according
to its instructions.

In the case of "If the current cell is one, go one cell to the right",
the pointer can read the current cell, and decide whether or not it
should go to the next cell on the right. If the current cell is one, the
pointer goes right (which changes its state), and if not, it stays
put.

The typical Turing machine has cells that can be set to 0 or 1 (sometimes
'blank' or 'null' is included, meaning no data is on this cell).
Here is a crude, plain text visual, with the pointer pointing to
the second cell on the tape:


1 | 1 | 0 | 1 | 0 | 0 | 1
    ^

The first cell of the tape is called the head of the tape, all other
cells are positioned right of the head.

The Turing Machine can compute anything that is computable, and anything
that can simulate a Turing Machine can compute anything that is computable.
To put it another way, such a machine can decide any decidable
problem, or solve any solvable math problem if it is programmed to
do so. Something that can simulate a Turing Machine is Turing Complete,
and any Turing Complete system can simulate any other Turing Complete
system.

The MacroBeep Tape

MacroBeep makes use of a Turing Machine for computation, but cells
on this machine can store any integer value from 0 to 255 inclusive.
In other words, each cell stores a byte of information, equivalent to
8 cells in the tape above. Many esoteric programming languages use
a tape like this one. The most notable example is none other than one of
the most famous, a language by Urban Muller [sic] (with a swear word in the
name), which will be referred to as bf. Here is a visual of the byte tape
used in bf and MacroBeep:

000 | 255 | 023 | 150 | 045 | 213 | 010
^

Note that, as with a Turing machine, the tape extends to the right
without bound. Also note that the pointer can do all of the things
a pointer on a Turing machine can. Furthermore this pointer can modify
bytes, adding or subtracting from them such that they can be at any
integer value from 0 to 255. The initial state of the tape is such that
every cell is set to 0.

In MacroBeep, 'pos' gives the pointer position, 'out' gives the current
cell value; 'left' and 'right' move the pointer, 'add' and 'sub' modify
cell values. Note that 'pos' and 'out' are excellent debugging
operations. See the Instruction Set for more information.


*Proof of Turing Completeness*

bf is Turing complete, and consists of only eight instructions.
Given the above, by translating each bf command to MacroBeep, it can
be shown that MacroBeep is also
Turing complete.

This table provides a means to translate between MacroBeep and bf.

MacroBeep                                       bf Description

right                                           >  increment

left                                            <  decrement

add                                             +  add 1 to cell

sub                                             -  take 1 from
                                                   cell

cout                                            . Output ASCII
                                                  value at cell

inp                                             ,  Take input at
                                                   cell

lunar (by some positive number of instructions) [  jump past ]
                                                   if cell is 0

solar (by some negative number of instructions) ]  goto [ if cell is
                                                   greater than 0


*Grammar in EBNF*

Extended Backus-Naur Form is a metasyntax that can describe the syntax
of a programming language. It is useful for understanding how the language
is parsed for interpretation.

Key:
::= assignment, equivalence
| or
(group)
{repeated at least one time}
[optional]
'string literal'
symbol
, symbol concatenation
; symbol terminator
(*comment*)

Program ::= {statement}

statement ::= macro | instruct

macro ::= 'macro', s, alnum, n, {instruct}, ['rt'];
(*be careful when leaving out 'rt'*)

instruct ::= word, s, [arg], n;

arg ::= alnum | inte

alnum ::= {(lett | digit)};

word ::= {lett};

inte ::= {digit};

s ::= ' ';

n ::= '\n';

digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';

lett ::= 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k'
| 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' |'w' |
'x' | 'y' | 'z';


*Test Cases*

This includes various tests that a MacroBeep interpreter needs to
pass to be correct. Do not assume this is an exhaustive list. Rather,
use this list as a guide to understand the language.

As a general rule, each instruction needs to pass:
-A test with no argument
-A test with an expected argument
-A test with an unexpected argument

Be sure that errors thrown are correct.
An incorrect error at the right time is an easy mistake to leave in!


Input and Output Test
Test:
Hello World

Desc:
Tests print statements and comments

Output:
Hello Worlds!
Hello  World

Code:
macro main
pr Hello[]Worlds!
# include SUDDENLY A COMMENT WOAH!!
pr
pr Hello{}Wor##OH WOW A
MULTILINER
WHAT##ld

Result:
PASSED


Test:
Truth Machine

Output:
0
OR
111111111111111111111111111...

For the code, see program examples.
Result:
PASSED


Test:
False Machine

Output:
0000000000000000000...
OR
1

For the code, see program examples.
Result:
PASSED

Test:
Cat

Output:
Output the given input

For the code, see program examples.
Result:
PASSED

Test:
Beep

Output:
beeps at a frequency of the argument given mod 2501

Code:
macro main
beep
beep 3300
beep 500

Result:
PASSED

Test:
Generalized IO test
Output:
The ascii value of the first character given.
(Note this also applies if an inp arg that is greater than 2 is given)

Code:
macro main
inp
out

Result:
PASSED

Test:
Arithmetic Operations Test
Output:
The sum of several numbers, 53.

For the code, see program examples
Result:
PASSED

Error Tests

Undefined Instruction (1) [PASSED]
macro main
foo

File [or in this case, directory] Not Found (2) [PASSED]
include foo\*
macro main

Undefined Macro or Label. (3) [PASSED]
macro main
do foo
cosmic foo
#comment out one statement to test the other

Missing Main Macro (4) [PASSED]
This is not code in MacroBeep.

Stack Overflow (5) [INCONCLUSIVE]
macro store
do store

macro main
do store
#This will eventually throw the error

Not a Cell Error (6) [PASSED]
macro main
left
add 50
#no cell -1

Include Statement in Macro (7) [PASSED]
macro main
include foo

Preprocessor Error [Check Includes] (8) [PASSED]
include
macro main

Duplicate Definitions [test for macros and labels] (9) [PASSED]
macro main
macro foo
macro foo

Argument Error: Integer Expected (10) [PASSED]
macro main
wait foo

Bad Argument (11) [PASSED]
macro main
wait -100


Astrological Error (12) [PASSED]
macro main
lunar -10

Include Tests

There are six such tests, each test uses 3 files: MAIN, A, and
B respectively. Each test should produce the same output, a beep at
1000 hertz and a beep at 500 hertz; excluding the first test, which should
only output one beep at 1000 hertz.

Test 1
MAIN

include a.mcbe
macro main
do b

A

macro b
beep
rt

Test 2
MAIN

include a.mcbe
include b.mcbe
macro main
do b
do c

A

macro b
beep
rt

B

macro c
beep 500
rt

Test 3
MAIN

include dir/a.mcbe
include dir/b.mcbe
macro main
do b
do c

A

macro b
beep
rt

B

macro c
beep 500
rt

Test 4
MAIN

include a.mcbe
macro main
do b
do c

A

include b.mcbe
macro b
beep
rt

B

macro c
beep 500
rt

Test 5
MAIN

include run\foo\*

macro main
do that
do this


A (in run/foo)

macro that
beep
rt

B (in run/foo/bar)

macro this
beep 500
rt

Test 6
MAIN

include run\foo\a.mcbe

macro main
do that
do this


A (in run/foo)

include >\bar\bar.mcbe

macro that
beep
rt

B (in run/foo/bar)

macro this
beep 500
rt

*ASCII Table Reference*


Characters on the ASCII table correspond to integer values. For example,
"H" is equal to 72. In MacroBeep "cout 72" prints an H.

Null        0

Beep        7

Tab         9

New Line   10

Space      32

!          33

"          34

#          35

$          36

%          37

&          38

'          39

(          40

)          41

*          42

+          43

,          44

-          45

.          46

/          47

0          48

1          49

2          50

3          51

4          52

5          53

6          54

7          55

8          56

9          57

:          58

;          59

<          60

=          61

>          62

?          63

@          64

A          65

B          66

C          67

D          68

E          69

F          70

G          71

H          72

I          73

J          74

K          75

L          76

M          77

N          78

O          79

P          80

Q          81

R          82

S          83

T          84

U          85

V          86

W          87

X          88

Y          89

Z          90

[          91

\          92

]          93

^          94

_          95

`          96

a          97

b          98

c          99

d         100

e         101

f         102

g         103

h         104

i         105

j         106

k         107

l         108

m         109

n         110

o         111

p         112

q         113

r         114

s         115

t         116

u         117

v         118

w         119

x         120

y         121

z         122

{         123

|         124

}         125

~         126



*Change Log (changes from v1.3.0)*

-Added send and reply instructions
-Added tom and mark instructions
-Implemented mark stack for memory management
-Implemented a debugger
-Implemented a library called SumDif
-Implemented a Help menu to print docs by section
-Bug fixes
-Updated and expanded docs
-Removed typos

*Sources*

ASCII table. ASCII Table - ASCII Character Codes, HTML, Octal, Hex,
Decimal. (n.d.). Retrieved January 16, 2022,
from https://www.asciitable.com/

Bf. Esolang. (n.d.). Retrieved January 16, 2022,
from https://esolangs.org/wiki/Bf
(Swear word removed.)

Truth-machine. Esolang. (n.d.). Retrieved February 2, 2022,
from https://esolangs. org/wiki/Truth-machine

Macrobeep. Esolang. (n.d.). Retrieved January 16, 2022,
from https://esolangs.org/wiki/MacroBeep

Wikimedia Foundation. (2021, December 25). Extended backus-naur form.
Wikipedia. Retrieved January 17, 2022,
from https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form#Table_of_Symbols

Wikimedia Foundation. (2022, January 4). Turing completeness. Wikipedia.
Retrieved January 16, 2022,
from https://en.wikipedia. org/wiki/Turing_completeness

Wikimedia Foundation. (2022, January 14). Turing machine. Wikipedia.
Retrieved January 16, 2022,
from https://en.wikipedia.org/wiki/Turing_machine


-End of Documentation (Scroll Up)-