From 0ad9f11e68932298b08f28b68a448535fced2984 Mon Sep 17 00:00:00 2001 From: Alex Smith Date: Tue, 24 Jun 2008 15:16:04 -0400 Subject: [PATCH] Documentation for CREATEd operators --- doc/ick.txi | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/ick.txi b/doc/ick.txi index 0fee8bd..f857cda 100644 --- a/doc/ick.txi +++ b/doc/ick.txi @@ -4603,6 +4603,36 @@ statements at compile time without knowing what they are). The actual expressions used in the @code{CREATE} statement don't matter; they're just examples for the runtime to match against. +@cindex CREATE, operators +It is also possible (from @cic{} version 0.29 onwards) to create new +operators. Such operators are always binary operators (that is, they +take two arguments and parse like mingle or select), and always return +32-bit results. There are three types of legal names for such +operators, all of which are treated equivalently: lowercase letters, +punctuation marks otherwise unused in @ical{}, and overstrikes +consisting of a character, a backspace, and another character (apart +from overstrikes already used for built-in @ical{} operators). The +syntax for creating an operator looks like one of these: + +@example +DO CREATE (5) x +DO CREATE .5 = +@end example + +The arguments to the operator will be overloaded onto :1601 and :1602 +(which are, like with @code{CREATE}d statements, stashed before the +overloading happens), and the return value is read from :1603 (which +is stashed, then overloaded to itself). All these three variables are +retrieved again after the operator finishes evaluating. + +Note that it is a very unwise idea to use a @code{CREATE}d operator in +the expression for a computed @code{COME FROM} or @code{NEXT FROM}, +because this always leads to an infinite regress; whenever any line +label is reached (including the line label that the @code{CREATE} +statement pointed at), the expression needs to be evaluated in order +to determine whether to @code{COME FROM} that point, which in turn +involves evaluating lines which have labels. + Some other points: a newer @code{CREATE} statement supercedes an older @code{CREATE} statement if they give equivalent templates, multiple @code{CREATE} statements may aim at the same line (this is the @@ -5084,6 +5114,14 @@ to submit multiple signatures using multiple calls to @code{ick_create}; maybe you could write a library to do that automatically. +@code{CREATE}d operators also have signatures, but of quite a +different form. The signature for a single-character operator is a +lowercase u, followed by its character code in hexadecimal (no leading +zeros, and in lowercase); the signature for an overstrike is a +lowercase o, followed by the lower relevant character code in +hexadecimal, followed by a lowercase x, followed by the higher +relevant character code in hexadecimal. + The routine that is @code{NEXT}ed to will presumably want to be able to see what in the @ical{} program was matched by the signature, so a range of function-like macros is provided to access that. They must -- 2.43.0