<commit_before># Footnote

Name
-----

The project is called Footnote for two reasons:
1. Just like a footnote, the set of instructions supported by the Footnote VM is extremely small.
2. This project began as a footnote to a different project I was working on at the time but took on a life of it's own, very much like the footnotes of [<NAME>](https://en.wikipedia.org/wiki/David_Foster_Wallace).

Setup
---------

<b>Requirements.</b>
This project requires java (version 1.5+) to run.  
<b>Installation Steps.</b>
Compile the java source files.  

Running
----------

To run the program on the command line, change into the directory where the compiled code is kept and execute the line:
<pre>java Footnote [options] infile [outfile]</pre>
For infile and outfile, no extension should be specified.

<b>Running with No Options and No outfile.</b> If no options or outfile is specified, then one of the following three things will occur:
1. A program will be assembled.  This happens if infile unambiguously refers to infile.ftnt.
In this case, the assembled program will be in infile.i.
2. A program will be run.  This happens if infile unambiguously refers to infile.i.
3. A program will be assembled and run.  This happens if infile is present with both .ftnt and .i extensions.
In this case, infile.i  will be replaced with a reassembled version (from infile.ftnt file) and the new infile.i file will be run.

<b>Outfile.</b>
The outfile is only valid if infile.ftnt is present.
If infile.ftnt is absent, an error will be printed.
In this case, infile.ftnt will be assembled and saved to outfile.i.

<b>Options.</b>
1. <b>-version</b>  displays the current version.  
If this flag is set, all other arguments are ignored and the version is printed.
2. <b>-sym</b> valid only for assembly.  
Saves the symbol table to symbols.txt
3. <b>-lines</b> valid only for assembly.
Saves the mapping from instruction counter in the assembled program to line of unassembled code.
The map is saved to a file called linemap.txt
4. <b>-memory amount</b> valid only for running.
Sets the memory of the virtual machine to <b>amount</b> 32-bit integers.
The default <b>amount</b> is 256.




Virtual Machine Architecture
-----------------

The Footnote Virtual Machine is simple (There are only sixteen instructions - see below) but powerful (This limited set of instructions is powerful enough to write any program).
Footnote VM operates on 32-bit integers and allows the user to set the memory with a command line argument.

<b>Virtual Machine Basics.</b>
1. stack.  
The virtual machine does not have usable registers; instead, a stack is provided.
The stack always starts at the highest memory location (i.e. the bottom of the stack is always at the highest memory address).
As elements are pushed onto the stack, the stack grows toward memory address 0. 
The location of the top of the stack is stored in a register called 'stack'.
2. maximum stack height.  
FootnoteVM's stack has a capacity that is determined when the program is loaded into main memory.
The maximum stack height is always equal to the maximum memory address minus the number of integers in the specified program.
In other words, the maximum stack height is equal to the maximum memory address minus the number of integers used to define the Executable and Data Sections of a program (see <b>Program Basics</b> below).
3. sequential execution.  
Machine instructions from a program are executed in a sequential order, except in the case of jmp and beq (see <b>Instructions</b> below).
These two instructions allow the user to set the next instruction address to be any arbitrary value (as long as the value is a valid address).
The program counter keeps of the next instruction's address using a special register, called pc.

<b>Program Basics.</b>
Each program written to be executed on the contains three sections:
1. Called the Executable Section, this first section contains all the executable code of the program.
This part of the program begins with the first integer of the program and continues until the first initialization of the data section.
It is best practice to explicitly terminate this section with a hlt instruction (so that it is clear where the next section starts), but it is not an error to terminate in some other way.
2. The Data Section contains the initializations of memory locations which will be used as variables during program execution.
The final integers of the program make up this section beginning after the last instruction.
3. The final section of each program is the Stack Section.
Unlike the Data section which must be explicitly initialized by the user, the stack section is always taken to be the rest of available memory not used by the previous two sections.
For example, if the first two sections together use 130 integers of memory, then the stack section will comprise the remaining 126 integers of memory, assuming there are 256 integers of memory in total.

<b>Instructions.</b>
Each instruction will be defined and discussed using the format described below:
- [name (opcode)] [args] | [(before -> after) description]

Each list item begins by giving the name and the opcode (in hexadecimal) for the instruction.
Then, the arguments taken by the instruction are given.
There are no instructions with optional arguments.
If an instruction takes arguments, they must be given.
After the vertical bar "<b>|</b>", the effect of the instruction on the stack (if there is one) is specified.  
The effect is described by providing a before and after picture of the stack relative to the instruction being discussed.
On the left, the before image of the stack is given by the first or first few items on the stack followed by an ellipsis (...) representing the rest of the items on the stack.
On the right, the after image of the stack is given by redrawing the first few items of the stack after the instruction is performed, again followed by an ellipsis.
For example, if the stack effect is pictured as (x y... -> y x...), then this means that the top two values on the stack are reversed in order.
Finally, there is a short description of what the instruction does.

<table>
    <colgroup>
       <col span="1" style="width: 12.5%;">
       <col span="1" style="width: 12.5%;">
       <col span="1" style="width: 25%;">
       <col span="1" style="width: 50%;">
    </colgroup>
    <!-- Put <thead>, <tbody>, and <tr>'s here! -->
    <thead>
    <th>Name [args]</th>
    <th>Opcode</th>
    <th>Effect on Stack</th>
    <th>Description</th>
    </thead>
    <tbody>
    <tr>
    <td>dup</td>
    <td>0xA</td>
    <td>x... -> x x...</td>
    <td>This instruction pushes a duplicate of the value on top of the stack.</td>
    </tr>
    <tr>
    <td>down val</td>
    <td>0xB</td>
    <td>val = 1: <nobr>x y... -> y x...</nobr> val = 2: <nobr>x y z... -> y z x...</nobr></td>
    <td>This instruction moves the top element on the stack val levels deep into the stack.</td>
    </tr>
    </tbody>
</table>

|name [args]|opcode|     effect on stack       |          description             |
|---|---|---------------------------|----------------------------------|
|   dup     |  0xA |     x... -> x x...        |this instruction pushes a duplicate of the value on top of the stack.|
|  down val |  0xB |<nobr>val = 1: x y... -> y x...</nobr><nobr> val = 2: x y z... -> y z x...</nobr>| this instruction moves the top element on the stack val levels deep into the stack.|
|iarith code|0x4|<nobr>x y... -> f(x, y)...</nobr>|this instruction applies a mathematical function to the top two stack elements. The function this instruction executes depends on the argument code which must be supplied. See <b>Integer Arithmetic Extended Instructions</b> below for details.|
|undefine|0xC|no stack effects|This instruction does nothing.|  
|farith code|0x5|x y... -> f(x, y)...|This instruction pops the top two values from the stack, performs some floating point operation (designated by the code argument) on them and pushes the result to the stack. Currently, no floating point operations are defined.|
|undefined|0x6|no stack effects|This instruction does nothing.| 
|undefined|0x7|no stack effects|This instruction does nothing.|
|jmp|0x0|x... -> ...|This instruction pops the top value off the stack and goes to that position.|
|beq|0x1|x y z... -> ...|This instruction branches pops the top three values off the stack. If the second two popped values are equal, it branches to the first popped value.|
|zero|0x8|... -> 0...|This instruction pushes a zero on the top of the stack.|
|one|0x9|... -> 1...|This instruction pushes a one on the top of the stack.|
|ld location|0x2|... -> (val at location)...|This instruction pushes a value from a specified location in memory (location) onto the top of the stack. This instruction has two modes, determined by the value of location. (Absolute Mode) If location is greater than or equal to 0, it is treated like memory address, the value stored at that location is put on top of the stack. (Relative Mode) If location is less than zero, it is treated like a relative address, and the value stored at the memory address equal to the maximum stack height plus location is pushed onto the stack.|
|sys code|0x3|no before and after shown|This instruction handles system calls. The code determines which action is taken by the system. Additional arguments (if any) must be on the stack and will be popped off the stack after execution. For more information on system calls, see <b>System Calls</b> below.|
|st location|0xE|x... -> ...|This instruction pops a value of the top of the stack and stores in in a specified address in memory (location). Like ld, this instruction operates in two modes, see ld for details.|
|hlt|0x15|no stack effects|This instruction signals the end of a program.|
|ldi val|0xD|... -> val...|This instruction pushes the next value onto the stack.|

<b>Integer Arithmetic Extended Instructions</b>
An integer arithmetic extended instruction always obtains its arguments by popping the top two values from the stack.
It then executes a mathematical operation on them (e.g., add) and pushes the result to the stack.
When describing various integer arithmetic calls, the following format is used:
* code (name) - description
* 0x1 (add) - adds the top two values on the stack together.
* 0x2 (sub) - subtracts the second to top value on the stack from the top value on the stack.<commit_msg>test 5 same<commit_after># Footnote

Name
-----

The project is called Footnote for two reasons:
1. Just like a footnote, the set of instructions supported by the Footnote VM is extremely small.
2. This project began as a footnote to a different project I was working on at the time but took on a life of it's own, very much like the footnotes of [<NAME>](https://en.wikipedia.org/wiki/David_Foster_Wallace).

Setup
---------

<b>Requirements.</b>
This project requires java (version 1.5+) to run.  
<b>Installation Steps.</b>
Compile the java source files.  

Running
----------

To run the program on the command line, change into the directory where the compiled code is kept and execute the line:
<pre>java Footnote [options] infile [outfile]</pre>
For infile and outfile, no extension should be specified.

<b>Running with No Options and No outfile.</b> If no options or outfile is specified, then one of the following three things will occur:
1. A program will be assembled.  This happens if infile unambiguously refers to infile.ftnt.
In this case, the assembled program will be in infile.i.
2. A program will be run.  This happens if infile unambiguously refers to infile.i.
3. A program will be assembled and run.  This happens if infile is present with both .ftnt and .i extensions.
In this case, infile.i  will be replaced with a reassembled version (from infile.ftnt file) and the new infile.i file will be run.

<b>Outfile.</b>
The outfile is only valid if infile.ftnt is present.
If infile.ftnt is absent, an error will be printed.
In this case, infile.ftnt will be assembled and saved to outfile.i.

<b>Options.</b>
1. <b>-version</b>  displays the current version.  
If this flag is set, all other arguments are ignored and the version is printed.
2. <b>-sym</b> valid only for assembly.  
Saves the symbol table to symbols.txt
3. <b>-lines</b> valid only for assembly.
Saves the mapping from instruction counter in the assembled program to line of unassembled code.
The map is saved to a file called linemap.txt
4. <b>-memory amount</b> valid only for running.
Sets the memory of the virtual machine to <b>amount</b> 32-bit integers.
The default <b>amount</b> is 256.




Virtual Machine Architecture
-----------------

The Footnote Virtual Machine is simple (There are only sixteen instructions - see below) but powerful (This limited set of instructions is powerful enough to write any program).
Footnote VM operates on 32-bit integers and allows the user to set the memory with a command line argument.

<b>Virtual Machine Basics.</b>
1. stack.  
The virtual machine does not have usable registers; instead, a stack is provided.
The stack always starts at the highest memory location (i.e. the bottom of the stack is always at the highest memory address).
As elements are pushed onto the stack, the stack grows toward memory address 0. 
The location of the top of the stack is stored in a register called 'stack'.
2. maximum stack height.  
FootnoteVM's stack has a capacity that is determined when the program is loaded into main memory.
The maximum stack height is always equal to the maximum memory address minus the number of integers in the specified program.
In other words, the maximum stack height is equal to the maximum memory address minus the number of integers used to define the Executable and Data Sections of a program (see <b>Program Basics</b> below).
3. sequential execution.  
Machine instructions from a program are executed in a sequential order, except in the case of jmp and beq (see <b>Instructions</b> below).
These two instructions allow the user to set the next instruction address to be any arbitrary value (as long as the value is a valid address).
The program counter keeps of the next instruction's address using a special register, called pc.

<b>Program Basics.</b>
Each program written to be executed on the contains three sections:
1. Called the Executable Section, this first section contains all the executable code of the program.
This part of the program begins with the first integer of the program and continues until the first initialization of the data section.
It is best practice to explicitly terminate this section with a hlt instruction (so that it is clear where the next section starts), but it is not an error to terminate in some other way.
2. The Data Section contains the initializations of memory locations which will be used as variables during program execution.
The final integers of the program make up this section beginning after the last instruction.
3. The final section of each program is the Stack Section.
Unlike the Data section which must be explicitly initialized by the user, the stack section is always taken to be the rest of available memory not used by the previous two sections.
For example, if the first two sections together use 130 integers of memory, then the stack section will comprise the remaining 126 integers of memory, assuming there are 256 integers of memory in total.

<b>Instructions.</b>
Each instruction will be defined and discussed using the format described below:
- [name (opcode)] [args] | [(before -> after) description]

Each list item begins by giving the name and the opcode (in hexadecimal) for the instruction.
Then, the arguments taken by the instruction are given.
There are no instructions with optional arguments.
If an instruction takes arguments, they must be given.
After the vertical bar "<b>|</b>", the effect of the instruction on the stack (if there is one) is specified.  
The effect is described by providing a before and after picture of the stack relative to the instruction being discussed.
On the left, the before image of the stack is given by the first or first few items on the stack followed by an ellipsis (...) representing the rest of the items on the stack.
On the right, the after image of the stack is given by redrawing the first few items of the stack after the instruction is performed, again followed by an ellipsis.
For example, if the stack effect is pictured as (x y... -> y x...), then this means that the top two values on the stack are reversed in order.
Finally, there is a short description of what the instruction does.

<table>
    <colgroup>
       <col span="1" style="width: 12.5%;">
       <col span="1" style="width: 12.5%;">
       <col span="1" style="width: 25%;">
       <col span="1" style="width: 50%;">
    </colgroup>
    <!-- Put <thead>, <tbody>, and <tr>'s here! -->
    <thead>
    <th>Name [args]</th>
    <th>Opcode</th>
    <th>Effect on Stack</th>
    <th>Description</th>
    </thead>
    <tbody>
    <tr>
    <td>dup</td>
    <td>0xA</td>
    <td>x... -> x x...</td>
    <td>This instruction pushes a duplicate of the value on top of the stack.</td>
    </tr>
    <tr>
    <td>down val</td>
    <td>0xB</td>
    <td>val = 1: <nobr>x y... -> y x...</nobr><br> val = 2: <nobr>x y z... -> y z x...</nobr></td>
    <td>This instruction moves the top element on the stack val levels deep into the stack.</td>
    </tr>
    </tbody>
</table>

|name [args]|opcode|     effect on stack       |          description             |
|---|---|---------------------------|----------------------------------|
|   dup     |  0xA |     x... -> x x...        |this instruction pushes a duplicate of the value on top of the stack.|
|  down val |  0xB |<nobr>val = 1: x y... -> y x...</nobr><nobr> val = 2: x y z... -> y z x...</nobr>| this instruction moves the top element on the stack val levels deep into the stack.|
|iarith code|0x4|<nobr>x y... -> f(x, y)...</nobr>|this instruction applies a mathematical function to the top two stack elements. The function this instruction executes depends on the argument code which must be supplied. See <b>Integer Arithmetic Extended Instructions</b> below for details.|
|undefine|0xC|no stack effects|This instruction does nothing.|  
|farith code|0x5|x y... -> f(x, y)...|This instruction pops the top two values from the stack, performs some floating point operation (designated by the code argument) on them and pushes the result to the stack. Currently, no floating point operations are defined.|
|undefined|0x6|no stack effects|This instruction does nothing.| 
|undefined|0x7|no stack effects|This instruction does nothing.|
|jmp|0x0|x... -> ...|This instruction pops the top value off the stack and goes to that position.|
|beq|0x1|x y z... -> ...|This instruction branches pops the top three values off the stack. If the second two popped values are equal, it branches to the first popped value.|
|zero|0x8|... -> 0...|This instruction pushes a zero on the top of the stack.|
|one|0x9|... -> 1...|This instruction pushes a one on the top of the stack.|
|ld location|0x2|... -> (val at location)...|This instruction pushes a value from a specified location in memory (location) onto the top of the stack. This instruction has two modes, determined by the value of location. (Absolute Mode) If location is greater than or equal to 0, it is treated like memory address, the value stored at that location is put on top of the stack. (Relative Mode) If location is less than zero, it is treated like a relative address, and the value stored at the memory address equal to the maximum stack height plus location is pushed onto the stack.|
|sys code|0x3|no before and after shown|This instruction handles system calls. The code determines which action is taken by the system. Additional arguments (if any) must be on the stack and will be popped off the stack after execution. For more information on system calls, see <b>System Calls</b> below.|
|st location|0xE|x... -> ...|This instruction pops a value of the top of the stack and stores in in a specified address in memory (location). Like ld, this instruction operates in two modes, see ld for details.|
|hlt|0x15|no stack effects|This instruction signals the end of a program.|
|ldi val|0xD|... -> val...|This instruction pushes the next value onto the stack.|

<b>Integer Arithmetic Extended Instructions</b>
An integer arithmetic extended instruction always obtains its arguments by popping the top two values from the stack.
It then executes a mathematical operation on them (e.g., add) and pushes the result to the stack.
When describing various integer arithmetic calls, the following format is used:
* code (name) - description
* 0x1 (add) - adds the top two values on the stack together.
* 0x2 (sub) - subtracts the second to top value on the stack from the top value on the stack.
{'fraction_non_alphanumeric': 0.087788084536674, 'fraction_numerical': 0.008558860093717128, 'mean_word_length': 3.5956932542298397, 'pattern_counts': {'":': 0, '<': 198, '<?xml version=': 0, '>': 232, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '436976', 'n_tokens_mistral': 5621, 'n_tokens_neox': 5369, 'n_words': 3181}