Module SILE.types.node
This module defines the standard node classes used in SILE.
Some packages or other modules may define their own node classes for specific purposes, but this does not have to be covered here.
Class box
| box:_init(spec) | Constructor |
| box:absolute() | Create an absolute version of the box. |
| box:lineContribution() | Returns either the width or the height of the box. |
| box:outputYourself(_, _) | Output routine for a box. |
| box:toText() | Returns a text description of the box for debugging purposes. |
Class hbox
| hbox:_init(spec) | Constructor |
| hbox:scaledWidth(line) | Returns the width of the hbox, scaled by the line ratio. |
| hbox:outputYourself(typesetter, line) | ôutput routine for a hbox. |
Class nnode
| nnode:_init(spec) | Constructor |
| nnode:absolute() | Create an absolute version of the box. |
| nnode:outputYourself(typesetter, line) | Output routine for a nnode. |
| nnode:toText() | Returns the text content of the nnode. |
Class unshaped
| unshaped:_init(spec) | Constructor |
| unshaped:shape() | Shapes the text of the unshaped node. |
| unshaped:outputYourself(_, _) | Output routine for an unshaped node. |
Class discretionary
| discretionary:toText() | Returns a text representation of the discretionary node. |
| discretionary:markAsPrebreak() | Mark the discretionary node as used in prebreak context. |
| discretionary:cloneAsPostbreak() | Clone the discretionary node for postbreak use. |
| discretionary:outputYourself(typesetter, line) | Output routine for a discretionary node. |
| discretionary:prebreakWidth() | Returns the width of the prebreak nodes. |
| discretionary:postbreakWidth() | Returns the width of the postbreak nodes. |
| discretionary:replacementWidth() | Returns the width of the replacement nodes. |
| discretionary:prebreakHeight() | Returns the height of the prebreak nodes. |
| discretionary:postbreakHeight() | Returns the height of the postbreak nodes. |
| discretionary:replacementHeight() | Returns the height of the replacement nodes. |
| discretionary:replacementDepth() | Returns the depth of the prebreak nodes. |
Class glue
| glue:outputYourself(typesetter, line) | Output routine for a glue node. |
Class hfillglue
| hfillglue:_init(spec) | Constructor |
Class hssglue
| hssglue:_init(spec) | Constructor |
Class vglue
| vglue:_init(spec) | Constructor |
| vglue:adjustGlue(adjustment) | Adjust the vglue by a certain amount. |
| vglue:outputYourself(typesetter, line) | Output routine for a vglue. |
Class penalty
| penalty:_init(spec) | Constructor |
| penalty:outputYourself(_, _) | Output routine for a penalty. |
| penalty:toText() | Returns a text representation of the penalty node. |
| penalty:unbox() | Unbox a penalty. |
Class vbox
| vbox:_init(spec) | Constructor |
| vbox:toText() | Returns a text representation of the vbox. |
| vbox:outputYourself(typesetter, line) | Output routine for a vbox. |
| vbox:unbox() | Unbox a vbox. |
| vbox:append(box) | Added a box or several to the current vbox. |
Class box
Base abstract box class used by the other box types.
Other node classes derive from it, adding or overriding properties and methods. It should not be used directly.
- box:_init(spec)
-
Constructor
Parameters:
- spec table A table with the properties of the box.
- box:absolute()
-
Create an absolute version of the box.
All Dimensions are based absolute (i.e. in points)
Returns:
-
box
A new box with the same properties as the original, but with absolute dimensions.
- box:lineContribution()
-
Returns either the width or the height of the box.
Regardless of the orientations, "width" is always in the writingDirection,
and "height" is always in the "pageDirection"
Returns:
-
SILE.types.length
The width or height of the box, depending on the orientation.
- box:outputYourself(_, _)
-
Output routine for a box.
This is an abstract method that must be overridden by subclasses.
Parameters:
- _
- _
- box:toText()
-
Returns a text description of the box for debugging purposes.
Returns:
-
string
A string representation of the box.
Class hbox
A hbox is a box node used in horizontal mode.
Derived from box.
Properties ishbox and isbox are true.
- hbox:_init(spec)
-
Constructor
Parameters:
- spec table A table with the properties of the hbox.
- hbox:scaledWidth(line)
-
Returns the width of the hbox, scaled by the line ratio.
This is used to determine the width of the hbox when it is output.
Parameters:
- line table The line properties (notably ratio)
Returns:
-
SILE.types.length
The scaled width of the hbox.
- hbox:outputYourself(typesetter, line)
-
ôutput routine for a hbox.
Parameters:
- typesetter SILE.typesetters.base The typesetter object (only used for the frame).
- line table Line properties (notably ratio)
Class nnode
A nnode is a node representing text content.
Derived from hbox.
Properties isnnode and isbox are true.
- nnode:_init(spec)
-
Constructor
Parameters:
- spec table A table with the properties of the nnode.
- nnode:absolute()
-
Create an absolute version of the box.
This overrides the base class method as nnode content is assumed to in points already.
Returns:
-
box
The box itself.
- nnode:outputYourself(typesetter, line)
-
Output routine for a nnode.
Parameters:
- typesetter SILE.typesetters.base The typesetter object (only used for the frame).
- line table Line properties (notably ratio)
- nnode:toText()
-
Returns the text content of the nnode.
Contrary to the parent class, this is the actual text content of the node,
not a text representation of the node.
Returns:
-
string
The text content of the nnode.
Class unshaped
An unshaped node is a text node that has not been shaped yet.
Derived from nnode.
Properties isunshaped is true. Note that isnnode is NOT true, as an unshaped node is not a representable node yet.
- unshaped:_init(spec)
-
Constructor
Parameters:
- spec table A table with the properties of the unshaped node.
- unshaped:shape()
-
Shapes the text of the unshaped node.
This is done by calling the current shaper with the text and options of the node.
The result is a list of nnodes inheriting the parent of the unshaped node.
The notion of parent is used by the hyphenation logic and discretionaries.
Returns:
-
table
A list of nnodes representing the shaped text.
- unshaped:outputYourself(_, _)
-
Output routine for an unshaped node.
Unshaped nodes are not supposed to make it to the output, so this method raises an error.
Parameters:
- _
- _
Class discretionary
A discretionary node is a node that can be broken at a certain point.
It has optional replacement, prebreak and postbreak nodes, which must be nnode nodes.
Derived from hbox.
Properties is_discretionary is true.
Usage:
SILE.types.node.discretionary({ replacement = ..., prebreak = ..., postbreak = ...})
- discretionary:toText()
-
Returns a text representation of the discretionary node.
This is used for debugging purposes, returning '-' for a used discretionary and '_' otherwise.
Returns:
-
string
A string representation of the discretionary node ('-' or '_').
- discretionary:markAsPrebreak()
- Mark the discretionary node as used in prebreak context. This is used to indicate that the discretionary node is used (i.e. the parent is hyphenated) and the prebreak nodes should be output (typically at the end of a broken line).
- discretionary:cloneAsPostbreak()
-
Clone the discretionary node for postbreak use.
This is used to create a new discretionary node that is used in postbreak context.
The discretionary must previously have been marked as used.
When breaking compound words, some languages expect the hyphen (prebreak) to be repeated in the postbreak context, typically at the beginning of the next line.
Returns:
-
SILE.types.node.discretionary
A new discretionary node with the same properties as the original, but marked for use in postbreak context.
- discretionary:outputYourself(typesetter, line)
-
Output routine for a discretionary node.
Depending on how the node was marked, it will output either the prebreak, postbreak or replacement nodes.
Parameters:
- typesetter SILE.typesetters.base The typesetter object (only used for the frame).
- line table Line properties (notably ratio)
- discretionary:prebreakWidth()
-
Returns the width of the prebreak nodes.
Returns:
-
SILE.types.length
The total width of the prebreak nodes.
- discretionary:postbreakWidth()
-
Returns the width of the postbreak nodes.
Returns:
-
SILE.types.length
The total width of the postbreak nodes.
- discretionary:replacementWidth()
-
Returns the width of the replacement nodes.
Returns:
-
SILE.types.length
The total width of the replacement nodes.
- discretionary:prebreakHeight()
-
Returns the height of the prebreak nodes.
Returns:
-
SILE.types.length
The total height of the prebreak nodes.
- discretionary:postbreakHeight()
-
Returns the height of the postbreak nodes.
Returns:
-
SILE.types.length
The total height of the postbreak nodes.
- discretionary:replacementHeight()
-
Returns the height of the replacement nodes.
Returns:
-
SILE.types.length
The total height of the replacement nodes.
- discretionary:replacementDepth()
-
Returns the depth of the prebreak nodes.
Returns:
-
SILE.types.length
The total depth of the prebreak nodes.
Class glue
A glue node is a node that can stretch or shrink to fill horizontal space.
Derived from box.
Properties is_glue is true
- glue:outputYourself(typesetter, line)
-
Output routine for a glue node.
Parameters:
- typesetter SILE.typesetters.base The typesetter object (only used for the frame).
- line table Line properties (notably ratio)
Class hfillglue
A hfillglue is just a standard glue with infinite stretch.
(Convenience subclass so callers do not have to know what infinity is.)
Derived from glue.
- hfillglue:_init(spec)
-
Constructor
Parameters:
- spec table A table with the properties of the glue.
Class hssglue
A hssglue is just a standard glue with infinite stretch and shrink.
(Convenience subclass so callers do not have to know what infinity is.)
Derived from glue.
- hssglue:_init(spec)
-
Constructor
Parameters:
- spec table A table with the properties of the glue.
Class vglue
A vglue node is a node that can stretch or shrink to fill vertical space.
Derived from box.
Property is_vglue is true.
- vglue:_init(spec)
-
Constructor
Parameters:
- spec table A table with the properties of the vglue.
- vglue:adjustGlue(adjustment)
-
Adjust the vglue by a certain amount.
Parameters:
- adjustment SILE.types.length The amount to adjust the vglue by.
- vglue:outputYourself(typesetter, line)
-
Output routine for a vglue.
Parameters:
- typesetter SILE.typesetters.base The typesetter object (only used for the frame).
- line table Line properties (notably height and depth)
Class penalty
A penalty node has a value which is used by the line breaking algorithm (in horizontal mode)
or the page breaking algorithm (in vertical mode), to determine where to break.
The value is expected to be a number between -10000 and 10000.
The higher the value, the less desirable it is to break at that point.
The extreme values (-10000 and 10000) are used to indicate that the break is forbidden or mandatory,
i.e. in certain way represent an infinite penalty.
Derived from box.
Property is_penalty is true.
- penalty:_init(spec)
-
Constructor
Parameters:
- spec table A table with the properties of the penalty.
- penalty:outputYourself(_, _)
-
Output routine for a penalty.
If found in the output, penalties have no representation, so this method does nothing.
(Overriding it on some penalties may be useful for debugging purposes.)
Parameters:
- _
- _
- penalty:toText()
-
Returns a text representation of the penalty node.
This is used for debugging purposes, returning '(!)' for a penalty.
Returns:
-
string
A string representation of the penalty node ('(!)').
- penalty:unbox()
-
Unbox a penalty.
This method exists consistency with vbox-derived classes, for a penalty used in vertical mode.
Returns:
-
table
A table with the penalty node.
Class vbox
A vbox is a box node used in vertical mode.
Derived from box.
Properties isvbox and isbox are true.
- vbox:_init(spec)
-
Constructor
Parameters:
- spec table A table with the properties of the vbox.
- vbox:toText()
-
Returns a text representation of the vbox.
This is used for debugging purposes, returning a string representation of the vbox and its content.
Returns:
-
string
A string representation of the vbox.
- vbox:outputYourself(typesetter, line)
-
Output routine for a vbox.
Parameters:
- typesetter SILE.typesetters.base The typesetter object (only used for the frame).
- line table Line properties (notably ratio)
- vbox:unbox()
-
Unbox a vbox.
Returns:
-
table
A table with the nodes inside the vbox.
- vbox:append(box)
-
Added a box or several to the current vbox.
The box height is the height is the total height of the content, minus the depth of the last box.
The depth of the vbox is the depth of the last box.
Parameters: