Editing Attributes

= Introduction =

Attributes are a new concept introduced in LuaTeX. In a way, they are a mix between count registers (they are numbers) and fonts (they are attached to the [[nodes]] created under their scope). They allow information to be carried between different stages of processing.

= Syntax =

Syntactically, attributes are no different from (and can be used as) count registers. Accordingly, primitive commands to handle attribute registers mimick those for count registers: like <tt>\count</tt>, <tt>\attribute</tt> is used to refer to a register, and like <tt>\countdef</tt>, <tt>\attributedef</tt> defines a control sequence to be a synonym for a register. The syntax is:

<pre>
\attribute <16-bit number> <optional equals> <32-bit number>
\attributedef <csname> <optional equals> <16-bit number>
</pre>

It is wise to have a \newattribute command, like \newcount (from plain TeX, used also in LaTeX and ConTeXt), for the allocation of registers. The command exists in LuaTeX, and is available in the [http://tug.ctan.org/pkg/luatexbase luatexbase] package for plain TeX and LaTeX under the name \newluatexattribute.

Whenever a count register is allowed, an attribute register too; that is, primitives like \advance, \multiply, \divide, can be used. More generally, anywhere a number is needed, attributes will do. Of course, assignments to attribute registers obey grouping.

Attributes differ from count registers in two respects:

* They have a special value, -"7FFFFFFF in hexadecimal or -2147483647 in decimal; an attribute with that value (which is default) is said to be <em>unset</em>. With any larger value, the attribute is <em>set</em>.
* When [[nodes]] are created, they carry with them the values of all the attributes in force at creation time (except for some asynchronous attribute settings). In other words, when inspecting a [[nodes|node]] at whatever stage of its processing, one can retrieve (and also modify) the values of the attributes when the node was created. In that respect, attributes behave like fonts (glyph [[nodes]] always carry information about their fonts).

== Box attributes ==

When creating boxes, there exists a new keyword <tt>attr</tt> besides <tt>to</tt> and <tt>spread</tt>. The node representing the box will then have the associate attribute, but not its contents. For instance, after:

<pre>
\attribute0=1
\setbox0=\hbox attr 1 = 1 {contents}
</pre>

The box (as a node) and each node of its contents have value 1 for attribute 0, but only the box node has value 1 for attribute 1; its contents has whatever value is currently assigned to that attribute (very probably the attribute is unset).

The syntax for the <tt>attr</tt> keyword is the following (all spaces are optional):

<pre>
attr <number> = <number>
</pre>

The <tt>attr</tt> declaration should precede the <tt>to</tt> or <tt>spread</tt> declaration if any.

== Asynchronous attribute settings ==

Sometimes [[nodes]] are assigned attribute values depending not on the real values at creation time but on the values of the surrounding nodes. The following simplistic code illustrates that:

<pre>
{\attribute0=1 Ve}\par
</pre>

LuaTeX will insert a font kern between the two letters (if the font says so, of course). That node will have attribute 0 set to 1, even though that is no longer the real value. Indeed, the kern node is created when building the paragraph, i.e. when the <tt>\par</tt> command is encountered; at that time, attribute 0 no longer has value 1, since that value was assigned in a group and the group is closed. So the kern should normally have whatever value is in force outside the group; instead it is given the value of the nodes that prompted its creation (more precisely, the value of the first node, which can differ from the second one). Similarly, a ligature node takes the values of those nodes it is created from, as does a discretionary node.

The <tt>\leftskip</tt> and <tt>\rightskip</tt> glues, inserted when non-zero at the beginning and end of each line of a paragraph, take the value of the neighboring nodes (i.e. the first and last nodes of a line, respectively).

Those asynchronous settings are supposed to make more sense than assignments that would follow the real values. Counter-measures can easily be implemented if necessary: for instance, one can inspect all lines in a paragraph and reassign to the <tt>\leftskip</tt> and <tt>\rightskip</tt> glues the current values for the attributes.


= On the Lua side =

== Registers ==

Like all registers, attributes are stored in a Lua table in the <tt>tex</tt> library. Hence besides <tt>tex.count</tt>, <tt>tex.box</tt>, etc., there exists <tt>tex.attribute</tt>. The indices to entries are either a register number or the name of a control sequence defined with <tt>\attributedef</tt>. For instance, after

<pre>
\attributedef\myattribute=100
\myattribute=1
</pre>

both <tt>tex.attribute.myattribute</tt> and <tt>tex.attribute[100]</tt> return 1. The entry can also be assigned to, but then the assignment is necessarily local.

There are also two functions to set or retrieve attribute values, with the following syntax:

<pre>
tex.getattribute(<register>)
tex.setattribute(["global",] <register>, <number>)
</pre>

In both case <tt><register></tt> is the same as an entry in <tt>tex.attribute</tt>: either a number or a string representing a control sequence defined with <tt>\attributedef</tt>. The first function returns the current value of the attribute, while the second sets it, either locally or globally if the first optional argument is given.

== Attributes in nodes ==

The <tt>node</tt> library offers the following function to deal with the values of attributes for a given node:

<pre>
node.has_attribute(<node>, <attribute>[, <value>])
</pre>

Without the third argument, if <tt><node></tt> has <tt>attribute</tt> <em>set</em>, i.e. with a value different from -"7FFFFFFF, then the value is returned; otherwise <tt>nil</tt> is returned. If the third argument is given, the value of the attribute is returned if and only if it is equal to <value>, and <tt>nil</tt> otherwise.

<pre>
node.set_attribute(<node>, <attribute>, <value>)
</pre>

Sets <attribute> to <value> for <node>.

<pre>
node.unset_attribute(<node>, <attribute>[, <value>])
</pre>

Unsets <attribute> for <node> and returns the old value; if <value> is present, the attribute is unset only if it matches <value>.

== Attribute lists ==

In [[nodes]], attributes actually are implemented as nodes in a list. That is why the <tt>attr</tt> field of all nodes (except attribute nodes themselves) points to a node of type <tt>attribute_list</tt>. That node has only one field <tt>next</tt> pointing to the first attribute node in the list, if any. There might not be any such node because only <em>set</em> attributes are present in the list. Attribute nodes have three fields:

* <tt>number</tt>: the attribute's number;
* <tt>value</tt>: the attribute's value;
* <tt>next</tt>: the next attribute in the list, i.e. an attribute node that is <em>set</em>.

As an example, the following code prints <tt>0 = 5</tt> and <tt>10 = 45</tt>.

<pre>
\setbox0=\hbox attr0 = 5 attr10 = 45 {contents}

\directlua{
  local attr = tex.box[0].attr.next
  while attr do
    texio.write_nl(attr.number .. " = " .. attr.value)
    attr = attr.next
  end
}
</pre>


= Examples =

The idea behind attributes is to mark material at a given time so as to spot it at a later stage of processing. The example in the page on the [[Post linebreak filter#Margin notes|<tt>post_linebreak_filter</tt>]] [[Callbacks|callback]] shows how attributes can be put to use for margin notes: the text to which a note is added is marked with an attribute, and later, when the paragraph has been built, the note is appended to the line containing that text, identified by its having a given value for the attribute.