inform7/inter/Manual/Inform Annotations.w

Inform Annotations.

The standard set of symbol annotations used within Inform.

@h Status.
The Inter specification allows for any number of annotations to be used;
none are required.

The Inform compiler, however, has a standard set of annotations used to
pass hints from the front end of the compiler to the back end; hints which
mainly do not change the meaning of the program, but cause the eventual
Inform 6 code to be generated in a particular order, or using particular
syntaxes, to be make it easier to read or more compatible with code not
generated by I7.

@h Miscellaneous constants.

@ |__hex|. Applies to |constant|. Marks that the value of this constant
is most legible in hexadecimal rather than decimal. Inter itself uses
this when writing a textual inter fomr of the constant's declaration,
and the Inform back end uses it when compiling Inform 6, in that it will
compile to a hexadecimal literal like |$4F02| rather than a decimal one
like |20226|. There is no effect on the final program.

@ |__signed|. Applies to |constant|. Marks that the value of this constant
is most legible if printed as a signed decimal literal than as an
unsigned one.

@ |__late|. Applies to |constant|. Suggests that this should be placed late
on the final compiled code, rather than at its current place. (This clue
helps the I6 code generator to avoid not-yet-declared errors; I6 is quite
finicky about code ordering.)

@ |__noun_filter|. Applies to |constant| which is a function. Marks that this
function is a noun filter in command parser grammar.

@ |__scope_filter|. Applies to |constant| which is a function. Marks that this
function is a scope filter in command parser grammar.

@ |__action|. Applies to |constant|. Marks it as the name of an action.
		
@ |__fake_action|. Applies to symbols already tagged |_action|, and marks
that their actions are I6 template fake actions. (It currently contains
just four of these.)

@ |__assimilated|. Applies to |constant|. Marks it as a symbol defined in
I6 template code which has been assimilated into memory inter.

@ |__holding|. Applies to |constant|. This is part of a convoluted system
for handling references to constants not yet defined, in the sense that
the inter to define them has not yet been generated in memory. A "holding"
constant is used to reserve a name for later definition.

@ |__delenda_est|. Applies to |constant|. Likewise; but marks a symbol for
later deletion rather than later definition.

@h Constant lists.

@ |__buffer_array|. Applies to |constant| which is a literal list. Asks
this to be compiled as virtual machine command parsing buffer.
	
@ |__byte_array|. Applies to |constant| which is a literal list. Asks
this to be compiled as an array of bytes.
	
@ |__string_array|. Applies to |constant| which is a literal list. Asks this
to be compiled as an array of bytes preceded by its size.
	
@ |__table_array|. Applies to |constant| which is a literal list. Asks this
to be compiled as an array of words preceded by its size.

@ |__inline_array|. Applies to |constant| which is a literal list. Asks that,
if this is compiled as a property value in Inform 6, it should use the inline
syntax (as is conventional for the I6 |name| property, for example).

@ |__verb|. Applies to |constant| which is a literal list. Asks this to be
compiled as Inform 6 command parser grammar.

@ |__meta_verb|. Applies to |constant| which is a literal list and also has
the |__verb| annotation: means that this is a "meta-verb", and should be
compiled after the regular verbs.

@h Primitive names.

@ |__bip|. Applies to |primitive|. This is used internally in the code
generator to match textual names such as |!bitwisenot| with functionality:
it's essentially a cache to avoid having to parse names over and over.
(BIP stands for "built in primitive".)

@h Local variables.

@ |__call_parameter|. Applies to |local|. Inform's front end marks
call parameters this way in case optimisation stages in the back end might
need to know; and if nothing else, it enables the code generator to print
I6 comments showing the intention.
	
@ |__implied_call_parameter|. Applies to |local|. Similarly. What
makes a call parameter "implied" is that it is not directly one of the
tokens from an Inform 7 function, but has been added for some implementation
reason. For example, a phrase option bitmap is passed as an implied call
parameter.

@h Global variables.

@ |__explicit_variable|. Applies to |variable|. Marks this as having a name
already supplied in high-level I7 source text.

@h Kinds.

@ |__weak_ID|. Applies to |kind|. The weak ID of a kind is a single small
non-negative integer which is unique to that kind's constructor; it can't
distinguish between lists of X and lists of Y, but in general it can
distinguish a list from a number, or a number from a text. This annotation
marks the name of a kind with the same weak ID value which will be used
at run-time for that kind.

@ |__source_order|. Applies (undependently) to |property| and to |kind|:
a lower value for this annotation means that one property was defined earlier
in the Inform source text that the other, and similarly for kinds.

@h Instances.

@ |__object_kind_counter|. Applies to |kind|. Towards the end of code
generation, it's convenient to count the subkinds of |K_object| in order
of their creation in the original source text. That count is recorded
here: |K1_thing| will get |__object_kind_counter=1|, and so on.

@ |__arrow_count|. Applies to |instance| of objects; it's the depth in the
spatial containment tree, where 0 is the top level (usually rooms), 1 the
level for things immediately inside level-0 objects, and so on. So called
because the Inform 6 notation for containment is this many |->| arrows in
a row. This is applied only at the final stage of code generation.
	
@ |__declaration_order|. Applies to |instance| of objects; it's the order
in which they are declared in the final Inform 6 code, with the first object
as 0, and so on. This is applied only at the final stage of code generation.

@h Properties.

@ |__either_or|. Applies to |property|. Marks it as one which is either
held or not held.
	
@ |__attribute|. Applies to |property|, and only to those also annotated
with |__either_or|. Asks to compile this at run-time as a virtual machine
attribute.
	
@ |__explicit_attribute|. Applies to |property|, and only to those also
annotated with |__either_or|. Marks this as not only an attribute, but one
with a name already supplied in high-level I7 source text.

@ |__property_name|. Applies to |property|. Where a property name came from
I7 source text, and thus has a friendly sort of name ("carrying capacity",
for example), the Inform front end applies this annotation. The back end
then uses it only to help run-time I6 code prpduce better error messages
if the program uses the property incorrectly.

@ |__rto|. Applies to |property|, and marks it as a run-time only property:
that is, not one which is explicitly present in the Inform 7 source text,
but one which has been added to provide run-time support for some feature.

@ |__source_order|. Applies (undependently) to |property| and to |kind|:
a lower value for this annotation means that one property was defined earlier
in the Inform source text that the other, and similarly for kinds.