Mbv130

=MacroBeep Documentation v 1. 3. 0=

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.

For info at a glance, scroll to the bottom. (It makes life easier
in a shell window. )

File Extension . mcbe

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


==Contents==

Acknowledgements
Introduction to MacroBeep
Language Paradigm and Memory
Instruction Set
The Preprocessor and Include Statements
Program Examples
Error Codes
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


==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.


==Introduction to MacroBeep==

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.

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.


==Language Paradigm and Memory==

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. MacroBeep is not a language in the functional
language paradigm. There is no part of a MacroBeep programthat 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. This language has a call stack, and the main macro is the first item
on that call stack.


==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)

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)

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 file are concatinated 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 statments 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

==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.

===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

Note that the main macros do not include a return statement 'rt'.
This is becuase 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.

Preproccesor Error (8)
A preproccesor 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!


==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 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 postion, '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 concatination
; 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. . .

Code:
macro main
pr Type[]a[]0[]or[]1[]into[]the[]truth[]machine.
inp 1
solar 3
pr 0
halt
pr 1
wait
solar -3
Result:
PASSED


Test:
False Machine

Output:
0000000000000000000. . .
OR
1

Code:
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

Result:
PASSED

Test:
Cat

Output:
Output the given input

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

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

===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 Statment 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 hrtz and a beep at 500 hrtz; excluding the first test, which should
only output one beep at 1000 hrtz.

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. 2. 1)==

-Added "At a Glance" to Docs
-Defined tests in MacroBeep, not Java
-Added stat inst to improve data management
-Extended head inst to allow for offsets
-Fixed a bug in error codes
-Implemented multiple line comments
-Updated Tests
-Updated Documentation
-Formatted Docs for bash (by hand!)

==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


==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 seperated 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 newlne.
##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.

===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 identifer, 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 statments link files
together into one larger program.

=End of Documentation (Scroll Up)=


End of Program

Press CTRL+C to quit ...