The last time Hackerfall tried to access this page, it returned a not found error. A cached version of the page is below, or click here to continue anyway

Backtick Macro Processor User's Guide

Backtick Macro Processor

User's Guide

Very preliminary draft

© 2017 Mark W. Humphries.

Backtick is a minimalist macro processor1. Its principal application areas thus far are preprocessing2 assembly language for custom FPGA-based cores, and as a lightweight tool for experimentation with bitwise and fixed-point integer algorithms.

Backtick behaves for the most part as a character stream filter3, it accepts 8-bit ASCII4 input and produces 8-bit ASCII output, expanding any embedded directives (i.e., macros, literals, and built-ins) it encounters along the way.

Backtick is small, simple, and flexible. Most of Backtick is loaded at startup from macro source, the runtime only implements a very rudimentary set of built-in primitives. This approach makes Backtick inherently very slow. Nonetheless, the author is quite content with it for his own idiosyncratic needs. Caveat utilitor.

The following conventions are used in the examples to distinguish between Backtick's stdin, stdout, and stderr streams.

stdin is shown in a blue fixed width font.

stdout is shown in a green fixed width font.

stderr is shown in a red fixed width font.

Whenever it is necessary for clarity to represent a normally invisible character, a description appears surrounded by bullets, e.g., •end-of-file•, with the exception of a newlines which are displayed as ↵

When experimenting with Backtick, you may find it useful to redirect stderr to a separate terminal, so as to get a clearer idea of which output is destined for stderr as opposed to stdout (e.g., on a Unix-like system this can usually be accomplished by invoking Backtick with a command line such as ./backtick 2>/dev/ttys001 ) or using a terminal multiplexer such as tmux13.

Supplied macros and built-ins are documented in the Macro Glossary.

The first step is to compile a Backtick runtime for your specific platform. Follow the instructions in Appendix A. Compiling the Runtime.

Go to directory where the runtime files are located. Invoke Backtick at your OS shell's command line. Backtick does not take any command line parameters. Since you invoked the Backtick runtime at a terminal console without piping or redirecting to its stdin, the runtime just awaits input lines from your terminal. Although Backtick is not meant for interactive use (any error will cause an immediate error exit back to the operating system), like any filter program it is still possible to experiment with it interactively from a console.

When Backtick starts up it loads autoload.mac, then awaits input on stdin. Backtick starts up with echo mode set to noecho, this mode prevents Backtick from automatically echoing input to stdout (although in the present case your OS shell will likely be echoing your keystrokes as you type at the console). noecho is useful when entering macro definitions and long block comments.

When echo mode is set to stdout on the other hand, non-escaped input is echoed to stdout.

If you type the following:

`stdout`↵ Hello World!↵

You'll should see this output:

Hello World!

The ` immediately before the ↵ in `stdout`↵ 'escapes' that carriage return, to prevent it from printing. From now on we will omit showing the ↵ at the end of line unless it is particularly relevant to the example.

The current echo mode and other useful debugging information are displayed by the info built-in (or its shortcut ?).

To invoke a macro or built-in, we precede its name with a backtick.

`? stack (depth: 0) frame 0 (slots: 0) no echo allocated: 22688

We are displaying the info utility's output in red to show that it goes to stderr rather than stdout.

Lets switch back to noecho and define our first macro. Normally we wouldn't be switching echo mode back and forth repeatedly, we'd define most macros at the beginning of a file (or import them from a macro file using the include) then switch to stdout mode for the remainder of the file.

`noecho `'country `"The Duchy of Grand Fenwick" `new

We have just defined a new macro whose name is country and whose content is The Duchy of Grand Fenwick 14. In more detail, `'country caused the token country to be pushed onto the stack, `"The Duchy of Grand Fenwick" caused the string The Duchy of Grand Fenwick to be pushed above it on the stack, then `new invoked the new built-in to pop both strings from the stack and use them to add a new macro named country to the dictionary with The Duchy of Grand Fenwick as its content.

We can verify this by invoking the list built-in (or it's synonym ??), to list all currently defined macros.

`??

You should be seing a long list of macro definitions scroll by, the last one of which should look like this (the number in parentheses is the character length of the content string).

country (26) {The Duchy of Grand Fenwick}

We can change the content of an existing macro using the store macro:

`'Spain `'country `store

Expanding the country macro while echo mode is set to stdout causes its content to be streamed to stdout.

`stdout` The rain in `country stays mainly on the plain The rain in Spain stays mainly on the plain

If we wish to output something other then whitespace immediately after country, an exclamation point for example, we can place an escaped space (` ) between the name and the exclamation point so that Backtick doesn't try to expand a non-existent macro named country! instead of the desired country.

I love `country` ! I love Spain!

You can exit Backtick with bye.

We're now done with our brief interactive trial of Backtick's most basic functioning. We can exit back to the OS normally using the bye macro.

`bye

Macros and built-ins serve a similar purpose to functions or procedures in most languages.

We will use directive as an umbrella term for both macros and built-ins.

Each time the Backtick runtime starts up, it attempts to load autoload.mac, a user-customizable macro file. Autoload.mac can in turn load other macro files, such as the provided backtick.mac, a small basic library of macros.

Backtick is a stack-based8 languages, as such it provides direct programmer access to the explicit stack from which directives fetch their arguments and onto which they deposit their return values. This is commonly referred to as the the data stack, or where there is no possibility of confusion, simply as the stack.

All entries on the stack are character strings (as are all parameters and return values). Nevertheless not all directives will accept arbitrary character strings, many impose further constraints on their parameters. From a data typing perspective it is the directives that are typed rather than the operands on the stack.

A case in point are basic arithmetic and bitwise directives, they expect strings representing decimal integers as their operands. For example the built-in add pops two strings from the stack, and it expects that both strings represent valid decimal integers, it adds those integers together, and pushes a signed decimal string representation of the sum.

As is typical for stack-based languages, Backtick code is expressed in Reverse Polish Notation (RPN)9, a.k.a. Postfix Notation.

In general directives consume their stack arguments, although there are specialized stack permutation macros that just rearrange items on the stack.

You can use the info built-in (or its shortcut ?) to display the contents of the stack at any point.

You can also pop the top string from the stack and output it to stdout with print (or its shortcut .), or to stderr with msg.

`1`2`3`print`print`print 321 `1`print`2`print`3`print 123 `1`print `2`print `3`print 123 `stdout` `1`print `2`print `3`print 1 2 3

Stack Comments

A special form of comment in stack-based languages summarizes the items a directive expects on the stack (i.e., its parameters), and the items it leaves on the stack after its expansion (i.e., its return values). It is known variously as a stack comment, stack effect diagram, stack notation, or stack picture.

The general format is ( before&nbsp— after ). The before section describes the expected state of the stack immediately prior to the directive's expansion, the after section describes the state of the stack immediately following the directive's expansion. The stack diagram describes only as many of the items at the top of the stack as are relevant to the particular directive. In both sections, the rightmost item denotes the topmost item on the stack. A stack diagram with empty before and after sections denotes an directive that has neither parameters nor return values: ( — ).

The following table shows some common examples of notations used in stack diagrams.

Notation Description Example +n A positive decimal integer in the range 0 ‥ 9,223,372,036,854,775,807 (i.e., 63 significant bits). mpn  ( — +n ) a [b c…] Generic positional abbreviations for the topmost stack entries. rot  ( a b c — b c a ) arr An array identifier. array  ( — arr ) bin A string of up to 64 significant 1s and 0s. binary  ( i — bin ) flag A canonical flag, 0 for false or -1 for true. geu  ( i1 i2 — flag ) filename A legal file name for the host OS (possibly including the file's path). text  ( filename — ) hex A string of hexadecimal digits (0-9,a-f). a>h  ( s — hex ) i A decimal string in the range -9,223,372,036,854,775,808 ‥ 18,446,744,073,709,551,615. add  ( i1 i2 — n ) n A decimal integer in the range -9,223,372,036,854,775,808 ‥ 9,223,372,036,854,775,807 (i.e., one who's two's complement representation would fit within 64 bits). dec  ( i — n ) name The name of a macro. new  ( name s — ) s A generic characters string (possibly even an empty one). leading  ( s imin-len — s' ) u A unsigned decimal integer in the range 0 ‥ 18,446,744,073,709,551,615 (i.e., 64 significant bits). divu  ( i1 i2 — u )

Integer Parameters

Built-ins that expect integer parameters first convert decimal parameters to their 64-bit canonical binary form (2's-complement in the case of negative decimals) and then interpret and process those 64-bit values according to the built-in's function.

The following table illustrates the correspondence between decimal parameters and their 64-bit canonical binary form (shown here in hex for brevity). Note the overlap of the negative integers with the unsigned integers that lie above the most positive signed integer.

Decimal 64-bit Canonical 18446744073709551615 ffffffffffffffff : : 9223372036854775808 8000000000000000 9223372036854775807 7fffffffffffffff : : 0 0000000000000000 -1  ffffffffffffffff : : -9223372036854775808 8000000000000000

Expansion is the process of performing the actions (i.e., semantics) denoted by a string.

The expansion semantics of plain text (i.e., containing no `) are simply to be echoed as per the current echo mode.

Hello world! Hello world!

The ` prefix is the means to invoke special behaviors and control expansion.

Pushing Literals onto the Stack

Literal Pattern Examples `decimal integer `-0000123`print -123 `$hex integer `$ff`print 255 `%binary integer `%10101`print 21 `'token `'xyz`print xyz `"string" `"Hello world!"`print Hello world! `{string} `{Simon says "jump!"}`print Simon says "jump!" `[[string]] `[{string}] `[(string)] `[<string>] `[other-charstringother-char] `[[Testing 1, 2, 3]]`print `[{Testing 1, 2, 3}]`print `[(Testing 1, 2, 3)]`print `[<Testing 1, 2, 3>]`print `[:Testing 1, 2, 3:]`print `[~Testing 1, 2, 3~]`print `[ Testing 1, 2, 3 ]`print `[xTesting 1, 2, 3x]`print Testing 1, 2, 3

Note that integer literals may contain underscores for legibility:

`$ffff_ffff_ffff_ffff`print -1

Escaping a backtick

To forestall the normal expansion behavior of a backtick, precede it with another backtick.

This `` is a backtick This ` is a backtick

Escaping white-space

To forestall the expansion of a run of white-space (possibly up to, and including, the next of end of line), precede the run with a backtick.

abc`␣␣␣xyz`␣␣ abcxyz

Comments

To comment out a block of text, enclose it as follows, `(start-char … end-char). If the start-char is an 'opening' character, i.e. from the set ([{<, end-char is the corresponding closing character from the set >}]) otherwise start-char and end-char are the same.

`(␣…this is a comment…␣) `({…this is a comment…}) `(:…this is a comment…:) `((…this is a comment…)) `((   …this is a multi-line comment…   …this is a multi-line comment…  ))

An alternate way to comment out a large block of text, as long as it doesn't contain any `, is to simply set echo mode to noecho.

`noecho …None of this text will be echoed… …None of this text will be echoed… …None of this text will be echoed…

Expanding Macros and Built-ins

A token prefixed with a ` that does not correspond to any of the special cases above, is looked up in the dictionary in the hopes of finding either a macro or a built-in that bears that token as its name (for details of how this search proceeds see Dictionary Order vs Search Order).

The expansion semantics of a built-in are to execute the predefined runtime behavior.

`1`2`add`print 3

The expansion semantics of a macro are to recursively expand its definition's content string.

`noecho `'hi ( -- ) `"Hello world!" `new `stdout` `hi Hello world!

Expanding from the Stack

To expand the string at the top of the stack, use the expand built-in.

`"Hello World!"`expand Hello world!

Conditional expansion (i.e., control flow)

…This section of the User's Guide will be expanded at a future date…

See the glossary section on control flow.

Breaking out of a nested expansion

…This section of the User's Guide will be expanded at a future date…

zbreak

Loops

`"Oh no!↵ "`loop

Oh no! Oh no! Oh no!

You're now stuck in an infinite loop, use Ctrl-C to terminate the runtime.

Breaking out of a loop

The normal way of of breaking out of a loop (from anywhere within the loop, beginning, middle, or end) is with the aforementioned built-in zbreak.

…This section of the User's Guide will be expanded at a future date…

Counted loops

The most basic forms of counted loops use either the times macro or the itimes macros.

`noecho `'shout ( -- s ) `{`"Shooby-doo-wop-do-wop-wop-wop-wop!↵ "} `new `stdout` `shout`3`times Shooby-doo-wop-do-wop-wop-wop-wop! Shooby-doo-wop-do-wop-wop-wop-wop! Shooby-doo-wop-do-wop-wop-wop-wop!

`{:`print}`10`itimes

:9:8:7:6:5:4:3:2:1:0

…This section of the User's Guide will be expanded at a future date…

Bypassing expansion altogether

If you wish to bypass expansion processing altogether you can use the text built-in to stream a text file directly to stdout.

The dictionary is the symbol table of directives. A macro's definition is its entry in the Backtick dictionary, comprising a name string and a content string. The dictionary entry of a built-in runtime primitive comprises it's name and it's 'baked-in' runtime behavior.

You can add new definitions to the dictionary with the new built-in, or with any macro which invokes new during its expansion. constant is an example of such a macro. The expansion behavior of a macro defined using constant will be to push an integer onto the stack.

`'dozen `12 `constant `dozen`msg 12

When Backtick searches the dictionary for a name coming directly from input, it searches in reverse chronological order, from the newest dictionary entry to the oldest entries (comprising the built-in runtime primitives). The search stops as soon as it encounters a matching name. Dictionary search is case-sensitive.

When expansion nests however, the definition of the currently expanding macro (at each succeeding level of expansion) acts as the reference point of three steps of dictionary search:

Step 1 — Search older entries, looking for the youngest matching predecessor.

Step 2 — Search younger entries, looking for the oldest matching successor (i.e. we're attempting to resolve a forward reference).

Step 3 — Lastly, check self (i.e. direct recursion).

The default input source is stdin, the include and text built-ins can cause input to nest to another source.

`{my_macros.mac}`include

`{some_plain_text.txt}`text

…This section of the User's Guide will be expanded at a future date…

Backtick has a primitive facility for allocating arrays of strings: Array directives.

…This section of the User's Guide will be expanded at a future date…

A slot frame (or simply a frame) is similar in concept to a locals frame in most languages, or a closure in some languages.

A frame is convenient when the same parameters are reused multiple times in a single macro definition.

Frames are created and populated (or repopulated) by invoking the # (populate frame) built-in, which pops the specified number of strings from the data stack into the frame.

Frames are maintained in a frame stack. Only the top frame in the frame stack is accessible at any point in time, not only in the expansion context where it originated, but in any of its nested expansion contexts (until a new frame is pushed onto the frame stack above it).

When expansion un-nests back past the frame's originating expansion context, the frame is automatically discarded.

The slot built-in pushes a copy of any individual slot from the current frame onto the data stack. For convenience there are also 6 predefined shortcut macros for accessing the first 6 slots in the current frame: a b c d e f.

`'stash ( a b c -- c a b c ) `{`3`#`c`a`b`c} `new

See Frame directives.

Macro Stack Effect Category Sub-Category Source Description # s1 ‥ si i — framesbuilt-in

Populate (or repopulate) a slot frame. Cf. this guide's section on Frames

- Stack Effect Category Sub-Category Source Description -rot a b c — c a b stack permutation backtick.mac

Rotate top three stack entries counter-clockwise.

-2rot a b c d e f — e f a b c d stack permutation backtick.mac

Rotate top three pairs of stack entries counter-clockwise.

. Stack Effect Category Sub-Category Source Description . s — output stdout backtick.mac

Shortcut synomym for print.

? Stack Effect Category Sub-Category Source Description ? — utilities system information backtick.mac

Shortcut synomym for info.

?? — utilities system information backtick.mac

Shortcut synomym for list.

?dup 0|i — 0|{i i} stack duplication backtick.mac

Conditionally duplicate, i.e., duplicate the top of stack if it is a non-zero decimal.

E.g.,  123 — 123 123  0 — 0

2 Stack Effect Category Sub-Category Source Description 2dup a b — a b a b stack duplication backtick.mac

Duplicate the top two stack entries.

2over a b c d — a b c d a b stack duplication backtick.mac

Push a copy the second pair of stack entries.

2swap a b c d — c d a b stack permutation backtick.mac

Exchange the top two pairs of stack entries.

a Stack Effect Category Sub-Category Source Description a — s frames – backtick.mac

Push a copy of slot a (i.e., slot #0) of the top frame.

a94 i — a94 ASCII – backtick.mac

Converts a decimal to a base 94 representation composed from the 94 contiguous ASCII graphic non-whitespace characters at code points 33 to 126 (! to ~).

An example use case is in the generation of Value Change Dump (VCD) files.

http://en.wikipedia.org/wiki/Value_change_dump

a94>d a94 — n ASCII – backtick.mac

Base 94 to signed decimal.

a>h s — hex ASCIIbuilt-in

Convert a ASCII character string to a hex string of corresponding codepoints.

E.g., hello — 68656c6c6f

abort s — n/a utilities shutdown backtick.mac

Flush stdout, output string s to stderr, then error exit to OS.

abs i — +n|mnn integer arithmetic backtick.mac

Absolute value.

N.B. A quirk of two's complement is that the absolute value of the most negative number (mnn) is itself and therefore still negative. See nabs for an alternative.

http://en.wikipedia.org/wiki/Two's_complement#Most_negative_number

add i1 i2 — n integer arithmetic built-in

Addition, n ← i1 + i2.

and i1 i2 — n integer bitwise backtick.mac

Bitwise and.

Bitwise truth table:

http://en.wikipedia.org/wiki/AND_gate http://en.wikipedia.org/wiki/Logical_conjunction

andc i1 i2 — n integer bitwise backtick.mac

Bitwise and-with-complement. a.k.a. bitwise: nimp, andn, inhibition, a > b, b < a, a &~ b.

Bitwise truth table:

http://en.wikipedia.org/wiki/Material_nonimplication

array — arr arraysbuilt-in

Create an array.

assert i|0 s — |n/a utilities shutdown backtick.mac b Stack Effect Category Sub-Category Source Description b — s frames – backtick.mac

Push a copy of slot b (i.e., slot #1) of the top frame.

b>d binary — n integer conversion backtick.mac

Binary string to decimal string.

E.g., 1111011 — 123

binary i — bin integer conversion backtick.mac

Decimal string to binary string.

E.g., 123 — 1111011

bsub i1 i2 — n integer arithmetic backtick.mac

Biased subtraction, n ← i1 + i2,  i.e. n ← (i1 − i2) − 1.

bye — n/a utilities shutdown backtick.mac

Normal exit to OS.

c Stack Effect Category Sub-Category Source Description c — s frames – backtick.mac

Push a copy of slot c (i.e., slot #2) of the top frame.

cand i1 i2 — n integer bitwise backtick.mac

Bitwise complement-then-and. a.k.a. bitwise: nif, ~a & b, inhibition, bic (bit clear), a < b, b > a.

Bitwise truth table:

http://en.wikipedia.org/wiki/Converse_nonimplication

cat s1 s2 — s1s2 string generation built-in

Concatenate two strings.

E.g., abc def — abcdef

chr i — c ASCII – backtick.mac

ASCII characters from significant bytes of an integer.

clip s — char|nil s' string sub-strings backtick.mac

Cut after first char.

E.g., abcdefg — a bcdefg

clog2 i — +n integer arithmetic backtick.mac

Binary logarithm (ceiling). See also log2.

N.B. clog2 of 0 defined here as 0.

clr‑low‑1 i — n integer bitwise backtick.mac

Clear least significant 1 bit (produces 0 if none).

`clr‑low‑1`ze to determine whether an unsigned integer is either a power of 2 or 0.

clr‑low‑1s i — n integer bitwise backtick.mac

Clear least significant string of 1 bits.

`clr‑low‑1s`ze to determine whether a +n is of the form (2^j)-(2^k) for some j>=k>=0.

clr‑trail‑1s i — n integer bitwise backtick.mac

Clear trailing 1 bits.

`clr‑trail‑1s`ze to determine whether an unsigned integer is of the form (2^n)-1, 0, or -1.

clr‑xlow‑0 i — n integer bitwise backtick.mac

Clear all bits except set least significant 0 bit.

clr‑xlow‑0+ i — n integer bitwise backtick.mac

Clear all bits except set from least significant 0 onwards.

clr‑xlow‑1 i — n integer bitwise backtick.mac

Clear all bits except least significant 1 bit.

clr‑xlow‑1+ i — n integer bitwise backtick.mac

Clear all bits except set from least significant 1 onwards.

clr‑xtrail‑0s i — n integer bitwise backtick.mac

Clear all bits except set trailing 0 bits.

clr‑xtrail‑1s i — n integer bitwise backtick.mac

Clear all bits except trailing 1 bits.

constant name i — dictionary definers backtick.mac

Definer for integer constants. Defined constant's stack effect will be ( — n ).

cor i1 i2 — n integer bitwise backtick.mac

Bitwise complement-then-or. a.k.a. bitwise: imp, ~a | b, implication, a implies b, if a then b, a ≥ b, b ≤ a.

Bitwise truth table:

http://en.wikipedia.org/wiki/Material_conditional

craw s — s' string special backtick.mac

Converts an ASCII string into a string of \xhh C-style hex literals, one per character.

C11 doesn't support raw string literals, this can be used to provide an equivalent effect.

E.g., ab%scd — \x61\x62\x25\x73\x63\x64

cut s i — s1 s2 string sub-strings built-in

Cut a string into two sub-strings.

E.g., abcdefg 3 — abc defg

d Stack Effect Category Sub-Category Source Description d — s frames – backtick.mac

Push a copy of slot d (i.e., slot #3) of the top frame.

ddec i — n-1 n special factors – backtick.mac

Duplicate and post-decrement. A common factor of many bithacks.

dec i — n integer arithmetic backtick.mac

Decrement, n ← i - 1.

delete name — dictionary modification built-in

Delete a macro from the dictionary.

die — n/a utilities shutdown backtick.mac

Error exit to OS.

dinc i — n+1 n special factors – backtick.mac

Duplicate and post-increment. A common factor of many bithacks.

div i1 i2 — n integer arithmetic backtick.mac

Euclidean division (a.k.a. modulus division), n ← i1 ÷e  i2.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation http://en.wikipedia.org/wiki/Euclidean_division

divf i1 i2 — n integer arithmetic backtick.mac

Floored division, n ← i1 ÷f  i2.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation

divmod i1 i2 — nquot nrem integer arithmetic backtick.mac

Euclidean division and remainder, nquot ← i1 ÷e  i2, nrem ← i1 mode  i2.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation http://en.wikipedia.org/wiki/Euclidean_division

divmodf i1 i2 — nquot nrem integer arithmetic backtick.mac

Floored division and remainder, nquot ← i1 ÷f  i2, nrem ← i1 modf  i2.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation

divmodt i1 i2 — nquot nrem integer arithmetic backtick.mac

Truncated division and remainder, nquot ← i1 ÷t  i2, nrem ← i1 modt  i2.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation

divmodu u1 u2 — uquot urem integer arithmetic backtick.mac

Unsigned division and remainder, uquot ← i1 ÷u  i2, urem ← i1 modu  i2.

Checks for division by 0.

divt i1 i2 — n integer arithmetic backtick.mac

Truncated division, n ← i1 ÷t  i2.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation

divu i1 i2 — u integer arithmetic backtick.mac

Unsigned division, u ← i1 ÷u  i2.

Checks for division by 0.

doz i1 i2 — +n integer arithmetic backtick.mac

Signed difference or zero, a.k.a. monus, saturated subtraction.

drop a — stack reduction backtick.mac

Discard top of stack.

drops … i — stack reduction backtick.mac

Discard top i stack entries.

dup a — a a stack duplication backtick.mac

Duplicate top of stack.

dyadic i1 i2 i — n integer bitwise backtick.mac

Dyadic bitwise boolean function.

Performs the two-variable boolean function identified by the function number i on all 64 bits of i1 and i2. Only the low order nibble of i is examined, yielding a boolean function number from 0 to 15.

The boolean function's number corresponds to its truth table. For example the boolean function number of the two-variable and is 1 (i.e., 0001), that of or is 7 (i.e., 0111), that of xor is 6 (i.e., 0110), that of nand is 14 (i.e., 1110), etc…

i1 i2 0 and andc x cand y xor or nor eqv y orc x cor nand -1 00 0000 0000 1111 1111 01 0000 1111 0000 1111 10 0011 0011 0011 0011 11 0101 0101 0101 0101 0123 4567 89ab cdef e Stack Effect Category Sub-Category Source Description e — s frames – backtick.mac

Push a copy of slot e (i.e., slot #4) of the top frame.

echord — n output echo built-in

Read the current echo mode setting.

echowr 0|1|2 — output echo built-in

Sets the echo mode (the current destination to which expanded plain text is echoed). noecho corresponds to 0, stdout to 1, stderr to 2.

eq i1 i2 — flag integer comparison backtick.mac

Equal, flag ← i1 = i2.

eqv i1 i2 — n integer bitwise backtick.mac

Bitwise equivalence. a.k.a. bitwise: xnor, a  b, a ~^ b.

Bitwise truth table:

http://en.wikipedia.org/wiki/XNOR_gate http://en.wikipedia.org/wiki/Logical_biconditional

exists? name — flag dictionary search built-in

Check if a macro with a particular name exists in the dictionary.

exit i — n/a utilities shutdown built-in

Exit to OS.

If i is zero exit with OS success exit code (usually 0), otherwise exit with OS's failure exit code.

expand s — ??? control flowbuilt-in

Expand a string.

f Stack Effect Category Sub-Category Source Description f — s frames – backtick.mac

Push a copy of slot f (i.e., slot #5) of the top frame.

first s — char|nil string sub-strings backtick.mac

First character of string.

g Stack Effect Category Sub-Category Source Description ge i1 i2 — flag integer comparison backtick.mac

Signed greater-than-or-equal, flag ← i1 ≥ i2.

http://en.wikipedia.org/wiki/Two's_complement

geu i1 i2 — flag integer comparison backtick.mac

Unsigned greater-than-or-equal, flag ← i1 ≥u  i2.

gt i1 i2 — flag integer comparison backtick.mac

Signed greater-than, flag ← i1 > i2.

http://en.wikipedia.org/wiki/Two's_complement

gtu i1 i2 — flag integer comparison backtick.mac

Unsigned greater-than, flag ← i1 >u  i2.

h Stack Effect Category Sub-Category Source Description h>a hex — s ASCIIbuilt-in

Hex-to-ASCII.

E.g., 68656c6c6f — hello

h>d hex — n integer conversion backtick.mac

Hex to decimal.

E.g., 68656c6c6f — 448378203247

head s — s' string sub-strings backtick.mac

Leading characters of string.

E.g., hello — hell

hex i — hex integer conversion built-in

Convert a decimal to a hex string.

E.g., 448378203247 — 68656c6c6f

hw i — 0-64 integer bitwise backtick.mac

Hamming weight (a.k.a population count, bit summation).

http://en.wikipedia.org/wiki/Hamming_weight

i Stack Effect Category Sub-Category Source Description if i s — ??? control flow – backtick.mac

if i: expand s.

ifa i s1 s2 s3 — ? control flow – backtick.mac

If-arithmetic. if i is if i is =0: expand s2, if i is >0: expand s3.

ifelse i s1 s2 — ? control flow – backtick.mac

If i: expand s1 else: expand s2.

ilit i—s' integer constants backtick.mac

Literalize an integer.

inc i — n integer arithmetic backtick.mac

Increment, n ← i + 1.

include filename — ??? inputbuilt-in

Include a macro file.

N.B. Prior to including the file, sets the current echo mode to noecho. Restores the previous echo mode upon completion.

info — utilities system information built-in

Print data stack and other debugging information on stderr.

insert ssrc sdest i — s' string generation backtick.mac

Insert sub-string.

itimes body i – ??? control flow - backtick.mac

body ( … i – ??? )

…This section of the User's Guide will be expanded at a future date…

l Stack Effect Category Sub-Category Source Description last s — char|nil string sub-strings backtick.mac

Last character of string.

le i1 i2 — flag integer comparison backtick.mac

Signed less-than-or-equal, flag ← i1 ≤ i2.

http://en.wikipedia.org/wiki/Two's_complement

leading s imin-len — s' string generation backtick.mac

Pad string with leading zeros.

E.g., 123 6 — 000123

left s i — s' string sub-strings backtick.mac

Left sub-string from cut point.

E.g., abcdefg 3 — abc

length s — u string information built-in

Length of a string.

E.g., hello — 5

leu i1 i2 — flag integer comparison backtick.mac

Unsigned less-than-or-equal, flag ← i1 ≤u  i2.

lift a b — a a b stack duplication backtick.mac

Duplicate the second item on the stack.

list — utilities system information built-in

List macros to stderr.

lit token—s' string special backtick.mac

Literalize a token by prepending it with a ` character.

load name — s dictionary modification built-in

Load the content of a macro to the stack.

log2 i — n integer arithmetic backtick.mac

Binary logarithm (floor).clog2.

N.B. log2 of 0 defined here as -1

loop s — ??? control flowbuilt-in

Expands s repeatedly until zbreak causes a loop exit.

lpad s imin-len — s' string generation backtick.mac

Left pad string with spaces.

E.g., hello 8 — ␣␣␣hello

lt i1 i2 — flag integer comparison backtick.mac

Signed less-than, flag ← i1 < i2.

http://en.wikipedia.org/wiki/Two's_complement

ltu i1 i2 — flag integer comparison backtick.mac

Unsigned less-than, flag ← i1 <u  i2.

m Stack Effect Category Sub-Category Source Description mac backtick.mac

Signed multiply-accumulate.

…This section of the User's Guide will be expanded at a future date…

max i1 i2 — n integer comparison backtick.mac

Signed maximum, n ← i1 max i2.

maxu i1 i2 — u integer comparison backtick.mac

Unsigned maximum, u ← i1 maxu  i2.

mid s istart ilen — s' string sub-strings backtick.mac

Extract a sub-string.

E.g., abcdefg 3 2 — de

min i1 i2 — n integer comparison backtick.mac

Signed minimum, n ← i1 min i2.

minu i1 i2 — u integer comparison backtick.mac

Unsigned minimum, u ← i1 minu  i2.

mirror i — n integer bitwise backtick.mac

Mirror bits.

mnn — -n integer constants backtick.mac

Most negative number (64-bit two's complement).

Useful as a mask to isolate the most-significant bit (i.e., the sign bit).

Note that the two's complement's negation of the most negative number (and therefore its two's complement's absolute value) is itself.

http://en.wikipedia.org/wiki/Two's_complement#Most_negative_number

mod i1 i2 — n integer arithmetic backtick.mac

Remainder of Euclidean division, n ← i1 mode  i2.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation http://en.wikipedia.org/wiki/Euclidean_division

modf i1 i2 — n integer arithmetic backtick.mac

Remainder of floored division, n ← i1 modf  i2.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation

modt i1 i2 — n integer arithmetic backtick.mac

Remainder of truncated division, n ← i1 modt  i2.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation

modu i1 i2 — u integer arithmetic backtick.mac

Remainder of unsigned division, u ← i1 modu  i2.

Checks for division by 0.

mpn — +n integer constants backtick.mac

Most positive number (64-bit two's complement).

http://en.wikipedia.org/wiki/Two's_complement

msg s — output stderr built-in

Flush stdout then output string s to stderr.

Any error writing to stderr causes an immediate failure exit.

mul i1 i2 — n integer arithmetic backtick.mac

Low order 64-bits of a product, n ← lsb63‥0 ( i1 × i2 ).

muldiv i1 i2 i3 — n integer arithmetic backtick.mac

Signed multiplication followed by Euclidean division (uses a 128-bit intermediary product), n ← ( i1 × i2 )&nbsp÷e  i3.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF)

muldivf i1 i2 i3 — n integer arithmetic backtick.mac

Signed multiplication followed by floored division (uses a 128-bit intermediary product), n ← ( i1 × i2 )&nbsp÷f  i3.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF)

muldivt i1 i2 i3 — n integer arithmetic backtick.mac

Signed multiplication followed by truncated division (uses a 128-bit intermediary product), n ← ( i1 × i2 )&nbsp÷t  i3.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF)

muldivu i1 i2 i3 — u integer arithmetic backtick.mac

Unsigned multiplication followed by division (uses a 128-bit intermediary product), u ← ( i1 ×u  i2 )&nbsp÷u  i3.

Checks for division by 0.

mux i1 i2 imask — n integer bitwise backtick.mac

64x 2-1 Multiplexer.

Bitwise truth table:

http://en.wikipedia.org/wiki/Multiplexer

n Stack Effect Category Sub-Category Source Description nabs i — -n integer arithmetic backtick.mac

Negative absolute value.

Unlike absolute value, nabs handles the most negative two's complement number correctly.

http://en.wikipedia.org/wiki/Two's_complement#Most_negative_number

nand i1 i2 — n integer bitwise backtick.mac

Bitwise nand.

Bitwise truth table:

http://en.wikipedia.org/wiki/NAND_gate http://en.wikipedia.org/wiki/Sheffer_stroke

ne i1 i2 — flag integer comparison backtick.mac

Integer not-equal, flag ← i1 ≠ i2.

neg i — n integer arithmetic backtick.mac

Negate, i ← n.

N.B. A quirk of two's complement is that the negation of the most negative number is itself.

http://en.wikipedia.org/wiki/Two's_complement http://en.wikipedia.org/wiki/Two's_complement#Most_negative_number

new name s — dictionary definers built-in

Define a macro.

nil? s — flag string test backtick.mac

Test for zero-length string.

nip a b — b stack reduction backtick.mac

Discard second stack entry.

nips … s i — s stack reduction backtick.mac

Discard the i entries from below the top of stack.

nlz i — +n integer bitwise backtick.mac

Number of leading zero bits.

noecho — output echo backtick.mac

Turn echo off.

N.B. The text built-in ignores the echo mode setting.

nor i1 i2 — n integer bitwise backtick.mac

Bitwise nor.

Bitwise truth table:

http://en.wikipedia.org/wiki/NOR_gate http://en.wikipedia.org/wiki/Logical_NOR

not i — n integer bitwise backtick.mac

Bitwise not.

Bitwise truth table: not‑xlow‑0 i — n integer bitwise backtick.mac

Complement all bits except least significant 0 bit.

not‑xlow‑1 i — n integer bitwise backtick.mac

Complement all bits except least significant 1 bit.

not‑xtrail‑0s i — n integer bitwise backtick.mac

Complement all bits except trailing 0 bits.

not‑xtrail‑1s i — n integer bitwise backtick.mac

Complement all bits except trailing 1 bits.

o Stack Effect Category Sub-Category Source Description opt i s1 s2 — s stack conditionals backtick.mac

Opt from 2 alternatives, s ← if i: s1 else: s2.

opta i s1 s2 s3 — s stack conditionals backtick.mac

Opt-artithmetic.

or i1 i2 — n integer bitwise backtick.mac

Bitwise or.

Bitwise truth table:

http://en.wikipedia.org/wiki/OR_gate http://en.wikipedia.org/wiki/Logical_disjunction

orc i1 i2 — n integer bitwise backtick.mac

Bitwise or-with-complement. a.k.a. bitwise: iif, orn, a |~ b, b implies a, if b then a, a ≤ b, b ≥ a.

Bitwise truth table:

http://en.wikipedia.org/wiki/Converse_implication

over a b — a b a stack duplication backtick.mac

Push a copy the second stack entry.

p Stack Effect Category Sub-Category Source Description perform name — ??? control flow – backtick.mac

Expand directive indirectly from its name.

pi — numer denom integer rational approximations backtick.mac

62-bit over 60-bit rational approximation of pi.

E.g., `1_000_000_000_000_000_000`pi`muldivu`print 3141592653589793238

print s — output stdout built-in

Print a string to stdout.

r Stack Effect Category Sub-Category Source Description read indx arr — s arraysbuilt-in

Read string from an array entry, s ← arr[indx].

release arr — arraysbuilt-in

Release an array. No-op if the array doesn't exit.

replicate s i — s' string generation backtick.mac

Replicate a string.

E.g., xyz 3 — xyzxyzxyz

reverse s — s' string generation backtick.mac

Reverse string.

E.g., hello — olleh

right s i — s' string sub-strings backtick.mac

Right sub-string from cut point.

E.g., abcdefg 3 — defg

rol i — n integer bitwise backtick.mac

Rotate left 1 bit.

ror i — n integer bitwise backtick.mac

Rotate right 1 bit.

rot a b c — b c a stack permutation backtick.mac

Rotate top three stack entries clockwise.

rpad s imin-len — s' string generation backtick.mac

Right pad string with spaces.

E.g., hello 8 — hello␣␣␣

rsplice s1 s2 — s2␣s1 string generation backtick.mac Reverse splice, concatenate two strings in reverse order, inserting a single space between them. rsub i1 i2 — n integer arithmetic backtick.mac

Reverse subtraction, n ← i2 − i1.

s Stack Effect Category Sub-Category Source Description sar i — n integer bitwise backtick.mac

Shift arithmetic right 1 bit.

http://en.wikipedia.org/wiki/Arithmetic_shift

scale i1 i2 i3 — n nrem integer arithmetic built-in

Signed integer scaling using Euclidean division (uses a 128-bit intermediary product), n ← ( i1 × i2 )&nbsp÷e  i3, nrem ← ( i1 × i2 ) mode  i3.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation http://en.wikipedia.org/wiki/Euclidean_division

scalef i1 i2 i3 — n nrem integer arithmetic built-in

Signed integer scaling using floored division (uses a 128-bit intermediary product), n ← i1 × i2&nbsp÷f  i3, nrem ← ( i1 × i2 ) modf  i3.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation

scalet i1 i2 i3 — n nrem integer arithmetic built-in

Signed integer scaling using truncated division (uses a 128-bit intermediary product), n ← i1 × i2&nbsp÷t  i3, nrem ← ( i1 × i2 ) modt  i3.

Checks for division by 0 and division overflow.

Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF) The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF) http://en.wikipedia.org/wiki/Modulo_operation

scaleu i1 i2 i3 — u urem integer arithmetic built-in

Unsigned integer scaling (uses a 128-bit intermediary product), u ← i1 ×u  i2&nbsp÷u  i3, urem ← ( i1 ×u  i2 ) modu  i3.

Checks for division by 0.

set‑low‑0 i — n integer bitwise backtick.mac

Set least significant 0 bit (produces -1 if none).

set‑low‑0s i — n integer bitwise backtick.mac

Set least significant string of 0 bits.

set‑trail‑0s i — n integer bitwise backtick.mac

Set trailing 0 bits.

set‑xlow‑0 i — n integer bitwise backtick.mac

Set all bits except least significant 0 bit.

set‑xlow‑0+ i — n integer bitwise backtick.mac

Set all bits except clear from least significant 0 bit onwards.

set‑xlow‑1 i — n integer bitwise backtick.mac

Set all bits except clear least significant 1 bit.

set‑xlow‑1+ i — n integer bitwise backtick.mac

Set all bits except clear from least significant 1 bit onwards.

set‑xtrail‑0s i — n integer bitwise backtick.mac

Set all bits except trailing 0 bits.

set‑xtrail‑1s i — n integer bitwise backtick.mac

Set all bits except clear trailing 1 bits.

shift i ishift — n integer bitwise built-in

Shift bits. A positive ishift shifts i to the left. A negative ishift shifts i to the right.

http://en.wikipedia.org/wiki/Logical_shift

shifta i ishift — n integer bitwise backtick.mac

Shift-arithmetic.

A negative ishift shifts i to the right, while a positive ishift shifts i to the left.

shl i — n integer bitwise backtick.mac

Shift left 1 bit.

http://en.wikipedia.org/wiki/Logical_shift

shr i — n integer bitwise backtick.mac

Shift right 1 bit.

http://en.wikipedia.org/wiki/Logical_shift

sign i — -1|0|1 integer arithmetic backtick.mac

Sign function a.k.a signum function.

https://en.wikipedia.org/wiki/Sign_function

signed i — n integer conversion backtick.mac

Decimal to signed decimal.

slot i — s framesbuilt-in

Fetch the content of a slot from the current slot frame.

snip s — s' char|nil string sub-strings backtick.mac

Cut string before last character.

space  — ␣ string generation backtick.mac

Push a single space character string.

spaces i — s string generation backtick.mac

Generate a string of spaces.

E.g., 5 — ␣␣␣␣␣

spin a b c — c b a stack permutation backtick.mac

Exchange the top and third stack entries.

splice s1 s2 — s1␣s2 string generation backtick.mac Concatenate two strings, inserting a single space between them. stash a b c — c a b c stack duplication backtick.mac

Insert a copy of the top stack entry below the third stack entry.

stderr — output echo backtick.mac

Set echo mode to stderr.

N.B. The text built-in ignores the echo mode setting.

stdout — output echo backtick.mac

Set echo mode to stdout.

store s name — dictionary modification built-in

Store a string to a macro.

sub i1 i2 — n integer arithmetic backtick.mac

Subtraction, n ← i1 − i2.

swap a b — b a stack permutation backtick.mac

Exchange the top two stack entries.

swish a b c — b a c stack permutation backtick.mac

Exchange the second and third stack entries.

t Stack Effect Category Sub-Category Source Description tac s1 s2 — s2s1 string generation backtick.mac

Concatenate two strings in reverse order (i.e., prepend).

E.g., def abc — abcdef

tail s — s' string sub-strings backtick.mac

Trailing characters of string.

E.g., hello — ello

text filename — inputbuilt-in

Stream a text file directly to stdout without attempting to expand its content and regardless of the current echo mode.

times body i – ??? control flow - backtick.mac

…This section of the User's Guide will be expanded at a future date…

triadic i1 i2 i3 i — n integer bitwise built-in

Triadic bitwise boolean function.

Performs the three-variable boolean function identified by the function number i on all 64 bits of i1, i2, and i3. Only the low order byte of i is examined, yielding a boolean function number from 0 to 255.

The boolean function's number corresponds to its truth table. For example the boolean function number of the three-variable boolean function (a and b ) or c is 87 (57 in hex), that of (a xor (b and c)) or not(b or c) is 158 (i.e., 9e in hex), etc…

i1 0000 1111 i2 0011 0011 i3 0101 0101 Example 1: (a and b) or c 0101 0111 i.e. 87 ($57) Example 2: (a xor (b and c)) or not(b or c) 1001 1110 i.e. 158 ($9e) tuck a b — b a b stack duplication backtick.mac

Insert copy of top of stack below second stack entry.

u Stack Effect Category Sub-Category Source Description unsigned i — u integer conversion backtick.mac

Decimal to unsigned decimal.

w Stack Effect Category Sub-Category Source Description write s indx arr — arraysbuilt-in

Write a string to an array entry, arr[indx] ← s.

x Stack Effect Category Sub-Category Source Description xor i1 i2 — n integer bitwise backtick.mac

Bitwise exclusive-or.

Bitwise truth table:

http://en.wikipedia.org/wiki/XOR_gate http://en.wikipedia.org/wiki/Exclusive_or

z Stack Effect Category Sub-Category Source Description zbreak i — control flowbuilt-in

Zero-break.

If i is equal to zero break out of the innermost expansion or loop.

ze i — flag integer comparison backtick.mac

Zero-equal, flag ← i = 0.

zeros i — s string generation backtick.mac

Generate a string of zeros.

E.g., 7 — 0000000

zge i — flag integer comparison backtick.mac

Zero-greater-than-or-equal, flag ← i ≥ 0.

http://en.wikipedia.org/wiki/Two's_complement

zgt i — flag integer comparison backtick.mac

Zero-greater-than, flag ← i > 0.

http://en.wikipedia.org/wiki/Two's_complement

zle i — flag integer comparison backtick.mac

Zero-less-than-or-equal, flag ← i ≤ 0.

http://en.wikipedia.org/wiki/Two's_complement

zlt i — flag integer comparison backtick.mac

Zero-less-than, flag ← i < 0.

http://en.wikipedia.org/wiki/Two's_complement

zne i — flag integer comparison backtick.mac

Zero-not-equal, flag ← i ≠ 0.

Useful for converting an integer to a canonical flag (i.e., either 0 or -1).

…This section of the User's Guide will be expanded at a future date…

…This section of the User's Guide will be expanded at a future date…

readme.md A brief summary of the project in Github's markdown format. backtick.c C-language source code of Backtick runtime. common.h An C-language header file shared by Backtick and some other of the author's projects. backtick_build.sh A bash shell script to build the Backtick runtime. backtick.mac The default macro library file containing the macros described in this document. autoload.mac A user-customizable macro file automatically loaded by the Backtick runtime at startup. Autoload.mac can in turn load other macro files. docs/index.html The file you are currently reading. LICENSE.txt Backtick is published under an MIT license, this file contains the text of the license. examples/99bottles.mac Prints the lyrics to the song 99 Bottles of Beer.
  1. http://en.wikipedia.org/wiki/General-purpose_macro_processor
  2. http://en.wikipedia.org/wiki/Preprocessor
  3. http://en.wikipedia.org/wiki/Filter_(software)
  4. http://en.wikipedia.org/wiki/Extended_ASCII
  5. http://en.wikipedia.org/wiki/C11_(C_standard_revision)
  6. http://en.wikipedia.org/wiki/Undefined_behavior
  7. http://en.wikipedia.org/wiki/Forth_(programming_language)
  8. http://en.wikipedia.org/wiki/Stack-oriented_programming_language
  9. http://en.wikipedia.org/wiki/Reverse_Polish_notation
  10. Fixed-Point Arithmetic: An Introduction, Randy Yates, 2009 (PDF)
  11. Division and Modulus for Computer Scientists, Daan Leijen, 2001 (PDF)
  12. The Euclidean Definition of the Functions div and mod, Raymond T. Boute, 1992 (PDF)
  13. http://en.wikipedia.org/wiki/Tmux
  14. http://en.wikipedia.org/wiki/Grand_Fenwick
Backtick Macro Processor User's Guide. — Copyright (c) 2017 Mark W. Humphries.

Continue reading on rdrop-exit.github.io