Nomenclature - 7ombie/phantasm GitHub Wiki

PHANTASM has its own nomenclature, including new terms and mnemonics.

Note: There is currently no commitment to any kind of backwards compatibility, so early adopters have the opportunity to improve the design of the language before anything is finalized. While nomenclature is a bikeshed issue, bikeshedding on our own time does no harm, and is a nice way to get to know each other. And we end up with a prettier bikeshed. For the foreseeable future, please treat the issue tracker as an open forum.

PHANTASM uses the term identity (especially internally) to refer to an index within an indexspace (expressed as a number literal), or an identifier (bound to an index).

PHANTASM has no signed or unsigned mnemonics. Instead the integer types (i32 and i64) are used with i when the instruction is sign-agnostic, s when signed, and u when it is unsigned. For example:

div s32    ; instead of `div_s i32`

This applies to pseudo-types like u8 and s16 too. For example:

load i64 as u16
expand i64 as s8

The WAT terms funcref and externref are replaced with pointer and proxy. For example:

define pointer table with 256

define proxy table with #100 to #200

The WAT term anyref is spelled mixed in PHANTASM. For example:

define mixed table with #1000 max

Note: PHANTASM does not use func or extern, instead employing a different grammar (reusing pointer and proxy), making func and extern redundant.

PHANTASM and WAT instructions normally have an obvious one-to-one correspondence. The push mnemonic is exceptional, as it combines otherwise unrelated instructions into a more general mnemonic for pushing stuff to the stack.

PHANTASM replaces the const, ref.func, and ref.null instructions with a push mnemonic that has various forms. For example:

push i32 1
push pointer $func
push null pointer

When the type is i32, it can be left implicit. For example:

push 1

The get and set mnemonics replace the WAT instructions local.get, local.set, global.get, global.set, table.get and table.set. Both take an optional scope qualifier, one of local, global or table. For example:

get table $opcodes
get global 1
set local $x

When the qualifier is omitted, the scope defaults to the lexical scope of the instruction (local inside functions, and global otherwise), making the qualifier unnecessary in constant expressions, and in local get and set operations within functions. For example:

define variable i32 $x thus get $global
define $sum of type $binop thus get 0, get 1, add i32

Note: The keyword thus is used to inline simple (one-line) blocks, and commas are used to group multiple instructions on the same line, and these two features can be combined.

Note: The of keyword is used to define functions, normally using <identifier> of <type> (as in the example above), or using function of <type> for unidentified functions (as in the example below). In any case, the type can use a type reference (as above) or a type expression (as below). For example:

define function of i32 $x, i32 $y -> i32 thus get $x, get $y, add i32

The ref.is_null and the positive comparisons (eq, eqz, gt and lt) use the is mnemonic. For example:

is null
is equal f64
is zero i32
is more s32
is less u64

The negative comparisons (ne, le and ge) use the not mnemonic. For example:

not equal i32
not more f64
not less s32

The copy mnemonic can reference a memory, table, memory bank or table bank, so is used for the WAT memory.copy, table.copy, memory.init and table.init instructions. For example:

copy memory
copy memory $main to $audio
copy table 1 to $opcodes
copy table bank $pointers

The to part defines the destination, and is optional when it refers to a memory or table with a zero index.

Note: The destination cannot be a bank (as they are read-only), so the destination type (either memory or table) can be inferred from the operand type.

PHANTASM spells the if block instruction branch (branch can still have an else block below it).

The WAT branch instructions br, br_if and br_table are renamed to jump, fork and exit. For example:

branch $b of i32 -> i32

    fork $b, jump

else

    exit 1 2 $b

The shr and shl instruction use the shift mnemonic, and rotr and rotl use the rotate mnemonic.

Both shift and rotate use a left or right qualifier: For example:

rotate i64 left
shift s32 right

The WAT extend instructions are divided into two types in PHANTASM, using the extend and expand mnemonics.

Those instructions that zero-extend or sign-extend an i32 to an i64 still use the extend mnemonic. For example:

extend u32 to i64

Those instructions that expand internal values (the least significant bytes), overwriting the higher bytes (where the result is the same length as the operand) use the expand mnemonic. For example:

expand i32 as s16

This renaming also allowed the affected instructions to be simplified.

The call_indirect instruction is spelled invoke. For example:

invoke type $binop
invoke i32, i32 -> i32
invoke pointer -> void via $table

The popcnt instruction is spelled nsa. For example:

nsa i32

PHANTASM spells truncate and saturate as lop and sop. For example:

lop f64 to s64
lop f32 sop s32

The ceil instruction is spelled ceiling. For example:

ceiling f64

Except for primitive type names (like i8, f64 et cetera), PHANTASM uses English words, either spelt in full or using three-letter abbreviations or acronyms. Keeping ceil would have been the only exception.

The sqrt instruction is spelled root. For example:

root f32

A WebAssembly cube-root instruction is unlikely to be added (and we could call it cube anyway), so there is no need to disambiguate.

The copysign instruction is spelled sign. For example:

sign f32

The reinterpret is spelled cast. For example:

cast f64 to i64
cast i32 to f32

This mnemonic may need to be extended to accommodate current proposals.

The xchg and cmpxchg atomic instructions are spelled swap and broker. For example:

atomic swap i32
atomic swap i64 as u8
atomic broker i64