1LaTeXML::Core::DocumentU(s3e)r Contributed Perl DocumentaLtaiToenXML::Core::Document(3)
2
6 "LaTeXML::Core::Document" - represents an XML document under
7 construction.
8
10 A "LaTeXML::Core::Document" represents an XML document being
11 constructed by LaTeXML, and also provides the methods for constructing
12 it. It extends LaTeXML::Common::Object.
13 LaTeXML will have digested the source material resulting in a
15 LaTeXML::Core::List (from a LaTeXML::Core::Stomach) of
16 LaTeXML::Core::Boxs, LaTeXML::Core::Whatsits and sublists. At this
17 stage, a document is created and it is responsible for `absorbing' the
18 digested material. Generally, the LaTeXML::Core::Boxs and
19 LaTeXML::Core::Lists create text nodes, whereas the
20 LaTeXML::Core::Whatsits create "XML" document fragments, elements and
21 attributes according to the defining
22 LaTeXML::Core::Definition::Constructor.
23 Most document construction occurs at a current insertion point where
25 material will be added, and which moves along with the inserted
26 material. The LaTeXML::Common::Model, derived from various
27 declarations and document type, is consulted to determine whether an
28 insertion is allowed and when elements may need to be automatically
29 opened or closed in order to carry out a given insertion. For example,
30 a "subsection" element will typically be closed automatically when it
31 is attempted to open a "section" element.
32 In the methods described here, the term $qname is used for XML
34 qualified names. These are tag names with a namespace prefix. The
35 prefix should be one registered with the current Model, for use within
36 the code. This prefix is not necessarily the same as the one used in
37 any DTD, but should be mapped to the a Namespace URI that was
38 registered for the DTD.
39 The arguments named $node are an XML::LibXML node.
41 The methods here are grouped into three sections covering basic access
43 to the document, insertion methods at the current insertion point, and
44 less commonly used, lower-level, document manipulation methods.
45 Accessors
47 "$doc = $document->getDocument;"
48 Returns the "XML::LibXML::Document" currently being constructed.
49 "$doc = $document->getModel;"
51 Returns the "LaTeXML::Common::Model" that represents the document
52 model used for this document.
53 "$node = $document->getNode;"
55 Returns the node at the current insertion point during
56 construction. This node is considered still to be `open'; any
57 insertions will go into it (if possible). The node will be an
58 "XML::LibXML::Element", "XML::LibXML::Text" or, initially,
59 "XML::LibXML::Document".
60 "$node = $document->getElement;"
62 Returns the closest ancestor to the current insertion point that is
63 an Element.
64 "$node = $document->getChildElement($node);"
66 Returns a list of the child elements, if any, of the $node.
67 "@nodes = $document->getLastChildElement($node);"
69 Returns the last child element of the $node, if it has one, else
70 undef.
71 "$node = $document->getFirstChildElement($node);"
73 Returns the first child element of the $node, if it has one, else
74 undef.
75 "@nodes = $document->findnodes($xpath,$node);"
77 Returns a list of nodes matching the given $xpath expression. The
78 context node for $xpath is $node, if given, otherwise it is the
79 document element.
80 "$node = $document->findnode($xpath,$node);"
82 Returns the first node matching the given $xpath expression. The
83 context node for $xpath is $node, if given, otherwise it is the
84 document element.
85 "$node = $document->getNodeQName($node);"
87 Returns the qualified name (localname with namespace prefix) of the
88 given $node. The namespace prefix mapping is the code mapping of
89 the current document model.
90 "$boolean = $document->canContain($tag,$child);"
92 Returns whether an element $tag can contain a child $child. $tag
93 and $child can be nodes, qualified names of nodes
94 (prefix:localname), or one of a set of special symbols "#PCDATA",
95 "#Comment", "#Document" or "#ProcessingInstruction".
96 "$boolean = $document->canContainIndirect($tag,$child);"
98 Returns whether an element $tag can contain a child $child either
99 directly, or after automatically opening one or more autoOpen-able
100 elements.
101 "$boolean = $document->canContainSomehow($tag,$child);"
103 Returns whether an element $tag can contain a child $child either
104 directly, or after automatically opening one or more autoOpen-able
105 elements.
106 "$boolean = $document->canHaveAttribute($tag,$attrib);"
108 Returns whether an element $tag can have an attribute named
109 $attrib.
110 "$boolean = $document->canAutoOpen($tag);"
112 Returns whether an element $tag is able to be automatically opened.
113 "$boolean = $document->canAutoClose($node);"
115 Returns whether the node $node can be automatically closed.
116 Construction Methods
118 These methods are the most common ones used for construction of
119 documents. They generally operate by creating new material at the
120 current insertion point. That point initially is just the document
121 itself, but it moves along to follow any new insertions. These methods
122 also adapt to the document model so as to automatically open or close
123 elements, when it is required for the pending insertion and allowed by
124 the document model (See Tag).
125 "$xmldoc = $document->finalize;"
127 This method finalizes the document by cleaning up various temporary
128 attributes, and returns the XML::LibXML::Document that was
129 constructed.
130 "@nodes = $document->absorb($digested);"
132 Absorb the $digested object into the document at the current
133 insertion point according to its type. Various of the the other
134 methods are invoked as needed, and document nodes may be
135 automatically opened or closed according to the document model.
136 This method returns the nodes that were constructed. Note that the
138 nodes may include children of other nodes, and nodes that may
139 already have been removed from the document (See filterChildren and
140 filterDeleted). Also, text insertions are often merged with
141 existing text nodes; in such cases, the whole text node is included
142 in the result.
143 "$document->insertElement($qname,$content,%attributes);"
145 This is a shorthand for creating an element $qname (with given
146 attributes), absorbing $content from within that new node, and then
147 closing it. The $content must be digested material, either a
148 single box, or an array of boxes, which will be absorbed into the
149 element. This method returns the newly created node, although it
150 will no longer be the current insertion point.
151 "$document->insertMathToken($string,%attributes);"
153 Insert a math token (XMTok) containing the string $string with the
154 given attributes. Useful attributes would be name, role, font.
155 Returns the newly inserted node.
156 "$document->insertComment($text);"
158 Insert, and return, a comment with the given $text into the current
159 node.
160 "$document->insertPI($op,%attributes);"
162 Insert, and return, a ProcessingInstruction into the current node.
163 "$document->openText($text,$font);"
165 Open a text node in font $font, performing any required automatic
166 opening and closing of intermedate nodes (including those needed
167 for font changes) and inserting the string $text into it.
168 "$document->openElement($qname,%attributes);"
170 Open an element, named $qname and with the given attributes. This
171 will be inserted into the current node while performing any
172 required automatic opening and closing of intermedate nodes. The
173 new element is returned, and also becomes the current insertion
174 point. An error (fatal if in "Strict" mode) is signalled if there
175 is no allowed way to insert such an element into the current node.
176 "$document->closeElement($qname);"
178 Close the closest open element named $qname including any
179 intermedate nodes that may be automatically closed. If that is not
180 possible, signal an error. The closed node's parent becomes the
181 current node. This method returns the closed node.
182 "$node = $document->isOpenable($qname);"
184 Check whether it is possible to open a $qname element at the
185 current insertion point.
186 "$node = $document->isCloseable($qname);"
188 Check whether it is possible to close a $qname element, returning
189 the node that would be closed if possible, otherwise undef.
190 "$document->maybeCloseElement($qname);"
192 Close a $qname element, if it is possible to do so, returns the
193 closed node if it was found, else undef.
194 "$document->addAttribute($key=>$value);"
196 Add the given attribute to the node nearest to the current
197 insertion point that is allowed to have it. This does not change
198 the current insertion point.
199 "$document->closeToNode($node);"
201 This method closes all children of $node until $node becomes the
202 insertion point. Note that it closes any open nodes, not only
203 autoCloseable ones.
204 Internal Insertion Methods
206 These are described as an aide to understanding the code; they rarely,
208 if ever, should be used outside this module.
209 "$document->setNode($node);"
211 Sets the current insertion point to be $node. This should be
212 rarely used, if at all; The construction methods of document
213 generally maintain the notion of insertion point automatically.
214 This may be useful to allow insertion into a different part of the
215 document, but you probably want to set the insertion point back to
216 the previous node, afterwards.
217 "$string = $document->getInsertionContext($levels);"
219 For debugging, return a string showing the context of the current
220 insertion point; that is, the string of the nodes leading up to it.
221 if $levels is defined, show only that many nodes.
222 "$node = $document->find_insertion_point($qname);"
224 This internal method is used to find the appropriate point,
225 relative to the current insertion point, that an element with the
226 specified $qname can be inserted. That position may require
227 automatic opening or closing of elements, according to what is
228 allowed by the document model.
229 "@nodes = getInsertionCandidates($node);"
231 Returns a list of elements where an arbitrary insertion might take
232 place. Roughly this is a list starting with $node, followed by its
233 parent and the parents siblings (in reverse order), followed by the
234 grandparent and siblings (in reverse order).
235 "$node = $document->floatToElement($qname);"
237 Finds the nearest element at or preceding the current insertion
238 point (see "getInsertionCandidates"), that can accept an element
239 $qname; it moves the insertion point to that point, and returns the
240 previous insertion point. Generally, after doing whatever you need
241 at the new insertion point, you should call
242 "$document->setNode($node);" to restore the insertion point. If no
243 such point is found, the insertion point is left unchanged, and
244 undef is returned.
245 "$node = $document->floatToAttribute($key);"
247 This method works the same as "floatToElement", but find the
248 nearest element that can accept the attribute $key.
249 "$node = $document->openText_internal($text);"
251 This is an internal method, used by "openText", that assumes the
252 insertion point has been appropriately adjusted.)
253 "$node = $document->openMathText_internal($text);"
255 This internal method appends $text to the current insertion point,
256 which is assumed to be a math node. It checks for math ligatures
257 and carries out any combinations called for.
258 "$node = $document->closeText_internal();"
260 This internal method closes the current node, which should be a
261 text node. It carries out any text ligatures on the content.
262 "$node = $document->closeNode_internal($node);"
264 This internal method closes any open text or element nodes starting
265 at the current insertion point, up to and including $node.
266 Afterwards, the parent of $node will be the current insertion
267 point. It condenses the tree to avoid redundant font switching
268 elements.
269 "$document->afterOpen($node);"
271 Carries out any afterOpen operations that have been recorded (using
272 "Tag") for the element name of $node.
273 "$document->afterClose($node);"
275 Carries out any afterClose operations that have been recorded
276 (using "Tag") for the element name of $node.
277 Document Modification
279 The following methods are used to perform various sorts of modification
280 and rearrangements of the document, after the normal flow of insertion
281 has taken place. These may be needed after an environment (or perhaps
282 the whole document) has been completed and one needs to analyze what it
283 contains to decide on the appropriate representation.
284 "$document->setAttribute($node,$key,$value);"
286 Sets the attribute $key to $value on $node. This method is
287 preferred over the direct LibXML one, since it takes care of
288 decoding namespaces (if $key is a qname), and also manages
289 recording of xml:id's.
290 "$document->recordID($id,$node);"
292 Records the association of the given $node with the $id, which
293 should be the "xml:id" attribute of the $node. Usually this
294 association will be maintained by the methods that create nodes or
295 set attributes.
296 "$document->unRecordID($id);"
298 Removes the node associated with the given $id, if any. This might
299 be needed if a node is deleted.
300 "$document->modifyID($id);"
302 Adjusts $id, if needed, so that it is unique. It does this by
303 appending a letter and incrementing until it finds an id that is
304 not yet associated with a node.
305 "$node = $document->lookupID($id);"
307 Returns the node, if any, that is associated with the given $id.
308 "$document->setNodeBox($node,$box);"
310 Records the $box (being a Box, Whatsit or List), that was
311 (presumably) responsible for the creation of the element $node.
312 This information is useful for determining source locations,
313 original TeX strings, and so forth.
314 "$box = $document->getNodeBox($node);"
316 Returns the $box that was responsible for creating the element
317 $node.
318 "$document->setNodeFont($node,$font);"
320 Records the font object that encodes the font that should be used
321 to display any text within the element $node.
322 "$font = $document->getNodeFont($node);"
324 Returns the font object associated with the element $node.
325 "$node = $document->openElementAt($point,$qname,%attributes);"
327 Opens a new child element in $point with the qualified name $qname
328 and with the given attributes. This method is not affected by, nor
329 does it affect, the current insertion point. It does manage
330 namespaces, xml:id's and associating a box, font and locator with
331 the new element, as well as running any "afterOpen" operations.
332 "$node = $document->closeElementAt($node);"
334 Closes $node. This method is not affected by, nor does it affect,
335 the current insertion point. However, it does run any "afterClose"
336 operations, so any element that was created using the lower-level
337 "openElementAt" should be closed using this method.
338 "$node = $document->appendClone($node,@newchildren);"
340 Appends clones of @newchildren to $node. This method modifies any
341 ids found within @newchildren (using "modifyID"), and fixes up any
342 references to those ids within the clones so that they refer to the
343 modified id.
344 "$node = $document->wrapNodes($qname,@nodes);"
346 This method wraps the @nodes by a new element with qualified name
347 $qname, that new node replaces the first of @node. The remaining
348 nodes in @nodes must be following siblings of the first one.
349 NOTE: Does this need multiple nodes? If so, perhaps some kind of
351 movenodes helper? Otherwise, what about attributes?
352 "$node = $document->unwrapNodes($node);"
354 Unwrap the children of $node, by replacing $node by its children.
355 "$node = $document->replaceNode($node,@nodes);"
357 Replace $node by @nodes; presumably they are some sort of
358 descendant nodes.
359 "$node = $document->renameNode($node,$newname);"
361 Rename $node to the tagname $newname; equivalently replace $node by
362 a new node with name $newname and copy the attributes and contents.
363 It is assumed that $newname can contain those attributes and
364 contents.
365 "@nodes = $document->filterDeletions(@nodes);"
367 This function is useful with "$doc-"absorb($box)>, when you want to
368 filter out any nodes that have been deleted and no longer appear in
369 the document.
370 "@nodes = $document->filterChildren(@nodes);"
372 This function is useful with "$doc-"absorb($box)>, when you want to
373 filter out any nodes that are children of other nodes in @nodes.
374
376 Bruce Miller <bruce.miller@nist.gov>
377
379 Public domain software, produced as part of work done by the United
380 States Government & not subject to copyright in the US.
381perl v5.38.0 2023-07-19 LaTeXML::Core::Document(3)