View source for Oración

{{stub}}{{infobox swproj
|name=Oración
|image=Oracion.jpg
|by=Alexander Nicholi
|langs={{wp|ANSI C}}
|systems=[[Sirius DOS]], [[A*]]
|archs={{wp|Intel 80286|i286}}
|lic=[[Artisan Software Licence#ASL 1.1|ASL 1.1]]
}}
'''Oración''' is an assembler program that originally targets the i286 and ARMv4T instruction sets. It leverages [[Gordian]] to perform symbol resolution and its language is the target for higher level language compilers, including both [[Feeble C compiler|FCC]] and [[Sirius C*]].

==Language overview==
Unlike most assembler dialects, Oración is not line-oriented at all (in fact, <code>\r</code> and <code>\n</code> are semantically equivalent to all other whitespace characters). It uses semicolons as statement terminators, and bracing in place of colon-delimited labels. This was decided upon out of kindness to 80-character terminals (which, believe it or not, are a huge cornerstone of accessibility even into the modern day). Directives begin with either a dot <code>.</code> or exclamation mark <code>!</code> depending on whether they are emitting, and opcodes are normal identifiers which have their arguments follow them like in other assembler dialects (no parentheses, only whitespace between the opcode and the first argument, and further arguments comma-separated). Only ANSI C style block comments <code>/*</code> <code>*/</code> are permitted. Finally, it is a strictly ASCII-only grammar, albeit with a [[doc comment exception]].

==Directives==
Oración provides many directives supplicating the main task of machine code assembly. There are two categories of directives: logical directives, prefixed with a dot <tt>.</tt>, and emitting directives, prefixed with an exclamation mark <tt>!</tt> They include: <code>.abort</code>, <code>!align</code>, <code>.define</code>, <code>.elif</code>, <code>.elifdef</code>, <code>.elifndef</code>, <code>.else</code>, <code>!globl</code>, <code>.if</code>, <code>.ifdef</code>, <code>.ifndef</code>, <code>.include</code>, <code>!isa</code>, <code>.log</code>, <code>!raw</code>, <code>!rawr</code>, and <code>.undef</code>. Logical directives are evaluated and resolved before any emitting directives, and are evaluated sequentially to provide temporality to such directives as <code>.define</code>, <code>.undef</code> and the various messaging directives. Once those are resolved out, the emitting directives are resolved together with actual opcodes to create the final machine code.

===<tt>.abort</tt>===
{{oras directive start|.abort}}
{{oras directive end}}

Aborts the assembly process. The <code>.log</code> directive can be used immediately preceding this to give an error message.

===<tt>!align</tt>===
{{oras directive start|!align}}
{{oras directive reqparam1st|name=number of octets|type=uintn}}
{{oras directive optparam|name=fill octet|type=uint8}}
{{oras directive end}}

Aligns the assembler output to a given number of octets. If <tt>fill octet</tt> is omitted, it defaults to zeroes. This is behaviourally equivalent to GNU <tt>as</tt>'s <code>.balign</code> directive.

===<tt>.define</tt>===
{{oras directive start|.define}}
{{oras directive reqparam1st|name=name|type=ident}}
{{oras directive reqparam|name=value|type=constexpr}}
{{oras directive end}}

Creates a definition by name to a given value that is a [[#constant expressions|constant expression]].

===<tt>.elif</tt>===
{{oras directive start|.elif}}
{{oras directive reqparam1st|name=expression|type=constexpr}}
{{oras directive endblock}}

Conditional testing a [[#constant expressions|constant expression]]. If truthy, the contents of the block that follows are [[#emission evaluation|evaluated for emission]]. This directive '''must''' follow the block of another <code>.elif</code>, <code>.elifdef</code>, <code>.elifndef</code>, <code>.if</code>, <code>.ifdef</code> or <code>.ifndef</code> directive.

===<tt>.elifdef</tt>===
{{oras directive start|.elifdef}}
{{oras directive reqparam1st|name=symbol|type=ident}}
{{oras directive endblock}}

Conditional testing for whether a symbol is <code>.define</code>d. If truthy, the contents of the block that follows are [[#emission evaluation|evaluated for emission]]. This directive '''must''' follow the block of another <code>.elif</code>, <code>.elifdef</code>, <code>.elifndef</code>, <code>.if</code>, <code>.ifdef</code> or <code>.ifndef</code> directive.

===<tt>.elifndef</tt>===
{{oras directive start|.elifndef}}
{{oras directive reqparam1st|name=symbol|type=ident}}
{{oras directive endblock}}

Conditional testing for whether a symbol is ''not'' <code>.define</code>d. This is the inverse of the <code>.elifdef</code> directive. This directive '''must''' follow the block of another <code>.elif</code>, <code>.elifdef</code>, <code>.elifndef</code>, <code>.if</code>, <code>.ifdef</code> or <code>.ifndef</code> directive.

===<tt>.else</tt>===
{{oras directive start|@else}}
{{oras directive endblock}}

Provides a block for [[#emission evaluation|emission evaluation]] for the inverse value of a previous conditional directive. This directive '''must''' follow the block of another <code>.elif</code>, <code>.elifdef</code>, <code>.elifndef</code>, <code>.if</code>, <code>.ifdef</code> or <code>.ifndef</code> directive.

===<tt>!globl</tt>===
{{oras directive start|!globl}}
{{oras directive reqparam1st|name=symbol|type=ident}}
{{oras directive varparam|name=symbol|type=ident}}
{{oras directive end}}

Marks one or more ''symbols'' as globals for emission, meaning that they are externally visible to other assembly units if defined here, and are externally visible and defined in another assembly unit if not defined here.

===<tt>.if</tt>===
{{oras directive start|.if}}
{{oras directive reqparam1st|name=expression|type=constexpr}}
{{oras directive endblock}}

Conditional testing a [[#constant expressions|constant expression]]. If truthy, the contents of the block that follows are [[#emission evaluation|evaluated for emission]].

===<tt>.ifdef</tt>===
{{oras directive start|.ifdef}}
{{oras directive reqparam1st|name=symbol|type=ident}}
{{oras directive endblock}}

Conditional testing for whether a symbol is <code>.define</code>d. If truthy, the contents of the block that follows are [[#emission evaluation|evaluated for emission]].

===<tt>.ifndef</tt>===
{{oras directive start|.ifndef}}
{{oras directive reqparam1st|name=symbol|type=ident}}
{{oras directive endblock}}

Conditional testing for whether a symbol is ''not'' <code>.define</code>d. This is the inverse of the <code>.elifdef</code> directive.

===<tt>.include</tt>===
{{oras directive start|.include}}
{{oras directive reqparam1st|name=filepath|type=stringlit}}
{{oras directive end}}

Physically <code>.include</code> another assembly unit by file path, as if its contents were transcluded in-place at the position of the directive.

===<tt>!isa</tt>===
{{oras directive start|!isa}}
{{oras directive reqparam1st|name=isa|type=stringlit}}
{{oras directive varparam|name=isa|type=stringlit}}
{{oras directive end}}

Oración uses an <code>!isa</code> directive to specify what opcodes are permitted in a given file. At the base level, the names given refer to lists of opcode names. It is an error to have any overlap in the names provided by each opcode group. This approach is done to promote composability of ISA specification in assembly code, such that a base ISA can be given along with a list of additions (such as later revisions or extensions) that it may use.

===<tt>.log</tt>===
{{oras directive start|.info}}
{{oras directive reqparam1st|name=message|type=stringlit}}
{{oras directive varparam|name=message|type=stringlit}}
{{oras directive end}}

Print out a diagnostic string as given in a list of string literals.

===<tt>!raw</tt>===
{{oras directive start|!raw}}
{{oras directive reqparam1st|name=bitsize|type=uintn}}
{{oras directive reqparam|name=data|type=intn}}
{{oras directive varparam|name=data|type=intn}}
{{oras directive end}}

Emit raw data in the assembly process. The first argument specifies the size of each data item, denominated in '''bits'''. One or more data items may be given, and they are emitted sequentially in the order specified.

===<tt>!rawr</tt>===
{{oras directive start|!rawr}}
{{oras directive reqparam1st|name=bitsize|type=uintn}}
{{oras directive reqparam|name=repeatcount|type=uintn}}
{{oras directive reqparam|name=data|type=intn}}
{{oras directive varparam|name=data|type=intn}}
{{oras directive end}}

Emit raw data in the assembly process, with a specified repeating of the data given. The first argument specifies the size of each data item, denominated in '''bits'''. The second argument specifies how many times the sequence emission shall be repeated. One or more data items may be given, and they are emitted sequentially in the order specified. In the repeating process, this ordered sequence is ''then'' repeated the number of times given.

===<tt>.undef</tt>===
{{oras directive start|.undef}}
{{oras directive reqparam1st|name=name|type=ident}}
{{oras directive end}}

Undefine a previously <code>.define</code>d definition by name. If the name given was not defined, this directive is ignored.

==Constant expressions==
A '''constant expression''', or '''constexpr''', is an arbitrary expression comprised of primitives that are either arbitrary-length integers or other symbols defined non-circularly by a <code>.define</code> directive, joined together with any of the following operators: addition <tt>+</tt>, subtraction <tt>-</tt>, multiplication <tt>*</tt>, division <tt>/</tt>, modulus <tt>%</tt>, exponent <tt>**</tt>, logical left shift <tt>&lt;&lt;</tt>, logical right shift <tt>&gt;&gt;</tt>, bitwise (long-circuit) AND <tt>&amp;</tt>, bitwise (long-circuit) OR <tt>|</tt>, bitwise (long-circuit) XOR <tt>^</tt>, bitwise (long-circuit) NOT <tt>~</tt>, logical (short-circuit) AND <tt>&amp;&amp;</tt>, logical (short-circuit) OR <tt>||</tt>, logical (short-circuit) XOR ergo inequality <tt>!=</tt>, logical (short-circuit) NOT <tt>!</tt>, logical equality <tt>==</tt>, and the ternary conditional <tt>?</tt> <tt>:</tt>.

==Opcode structure==
Oración defines a general structure for defining the structure of an opcode:

<pre>struct instr[sz]
{
   struct instr_param * params[sz];
   ptri param_sz;
}

enum instr_param_type
{
   INSTR_PARAM_TYPE_LIT,
   INSTR_PARAM_TYPE_REG,
   INSTR_PARAM_TYPE_IMM
};

struct instr_param[sz]
{
   bit occupy[sz];
   enum instr_param_type type;
   u8 index;
};</pre>

[[Category:Byblos components]]