lib/LaTeXML/Package.pm

filter: Statementstmt 96.8% 61 / 63 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 21 / 21 Podpod n/a totaltotal 97.6% 82 / 84 CC 1 SCAR 0.1
CC
1
Cov
97%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« lib/LaTeXML/Core/Stomach.pm ↑ Summary lib/LaTeXML/Common/Font/StandardMetrics.pm »
1 # /=====================================================================\ #
2 # | LaTeXML::Package | #
3 # | Exports of Defining forms for Package writers | #
4 # |=====================================================================| #
5 # | Part of LaTeXML: | #
6 # | Public domain software, produced as part of work done by the | #
7 # | United States Government & not subject to copyright in the US. | #
8 # |---------------------------------------------------------------------| #
9 # | Bruce Miller <bruce.miller@nist.gov> #_# | #
10 # | http://dlmf.nist.gov/LaTeXML/ (o o) | #
11 # \=========================================================ooo==U==ooo=/ #
12  
13 package LaTeXML::Package;
14 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 5 ▶use Exporter;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 5 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
18 5 ▶use LaTeXML::Global;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 5 ▶use LaTeXML::Common::Object;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 5 ▶use LaTeXML::Common::Error;
Subroutine BEGIN: called CC=1 SCAR=0.0
21 5 ▶use LaTeXML::Core::Token;
Subroutine BEGIN: called CC=1 SCAR=0.0
22 5 ▶use LaTeXML::Core::Tokens;
Subroutine BEGIN: called CC=1 SCAR=0.0
23 5 ▶use LaTeXML::Core::Box;
Subroutine BEGIN: called CC=1 SCAR=0.0
24 5 ▶use LaTeXML::Core::List;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 5 ▶use LaTeXML::Core::Mouth::Binding;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 5 ▶use LaTeXML::Core::Definition;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 5 ▶use LaTeXML::Core::Parameters;
Subroutine BEGIN: called CC=1 SCAR=0.0
28 5 ▶use LaTeXML::Common::Number;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 5 ▶use LaTeXML::Common::Float;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 5 ▶use LaTeXML::Common::Dimension;
Subroutine BEGIN: called CC=1 SCAR=0.0
31 5 ▶use LaTeXML::Common::Glue;
Subroutine BEGIN: called CC=1 SCAR=0.0
32 5 ▶use LaTeXML::Core::MuDimension;
Subroutine BEGIN: called CC=1 SCAR=0.0
33 5 ▶use LaTeXML::Core::MuGlue;
Subroutine BEGIN: called CC=1 SCAR=0.0
34 # Extra objects typically used in Bindings
35 0 ▶use LaTeXML::Core::Alignment;
Subroutine BEGIN: called CC=1 SCAR=2.6
36 use LaTeXML::Core::Array;
37 use LaTeXML::Core::KeyVal;
38 use LaTeXML::Core::KeyVals;
39 use LaTeXML::Core::Pair;
40 use LaTeXML::Core::PairList;
41 use LaTeXML::Common::Color;
42 use LaTeXML::Common::Color::rgb;
43 # Utitlities
44 use LaTeXML::Util::Pathname;
45 use LaTeXML::Util::WWW;
46 use LaTeXML::Common::XML;
47 use LaTeXML::Core::Rewrite;
48 use LaTeXML::Util::Radix;
49 use File::Which;
50 use Unicode::Normalize;
51 use Text::Balanced;
52 use Text::Unidecode;
53 use base qw(Exporter);
54 our @EXPORT = (qw(&DefAutoload &DefExpandable
55 &DefMacro &DefMacroI
56 &DefConditional &DefConditionalI &IfCondition &SetCondition
57 &DefPrimitive &DefPrimitiveI
58 &DefRegister &DefRegisterI &LookupRegister &AssignRegister &LookupDimension
59 &DefConstructor &DefConstructorI
60 &dualize_arglist &createXMRefs
61 &DefMath &DefMathI &DefEnvironment &DefEnvironmentI
62 &convertLaTeXArgs),
63  
64 # Class, Package and File loading.
65 qw(&Input &InputContent &InputDefinitions &RequirePackage &LoadClass &LoadPool &FindFile
66 &DeclareOption &PassOptions &ProcessOptions &ExecuteOptions
67 &AddToMacro &AtBeginDocument &AtEndDocument),
68  
69 # Counter support
70 qw(&NewCounter &CounterValue &SetCounter &AddToCounter &StepCounter &RefStepCounter &RefStepID &ResetCounter
71 &GenerateID &AfterAssignment
72 &MaybePeekLabel &MaybeNoteLabel),
73  
74 # Document Model
75 qw(&Tag &DocType &RelaxNGSchema &RegisterNamespace &RegisterDocumentNamespace),
76  
77 # Document Rewriting
78 qw(&DefRewrite &DefMathRewrite
79 &DefLigature &DefMathLigature),
80  
81 # Mid-level support for writing definitions.
82 qw(&Expand &Invocation &Digest &DigestText &DigestIf &DigestLiteral
83 &RawTeX &Let &StartSemiverbatim &EndSemiverbatim
84 &Tokenize &TokenizeInternal
85 &IsEmpty),
86  
87 # Font encoding
88 qw(&DeclareFontMap &FontDecode &FontDecodeString &LoadFontMap),
89  
90 # Color
91 qw(&DefColor &DefColorModel &LookupColor),
92  
93 # Support for structured/argument readers
94 qw(&ReadParameters &DefParameterType &DefColumnType),
95  
96 # Access to State
97 qw(&LookupValue &AssignValue
98 &PushValue &PopValue &UnshiftValue &ShiftValue
99 &LookupMapping &AssignMapping &LookupMappingKeys
100 &LookupCatcode &AssignCatcode
101 &LookupMeaning &LookupDefinition &InstallDefinition &XEquals &IsDefined
102 &LookupMathcode &AssignMathcode
103 &LookupSFcode &AssignSFcode
104 &LookupLCcode &AssignLCcode
105 &LookupUCcode &AssignUCcode
106 &LookupDelcode &AssignDelcode
107 ),
108  
109 # Random low-level token or string operations.
110 qw(&CleanID &CleanLabel &CleanIndexKey &CleanClassName &CleanBibKey &NormalizeBibKey &CleanURL
111 &ComposeURL
112 &UTF
113 &roman &Roman),
114 # Math & font state.
115 qw(&MergeFont),
116  
117 qw(&CheckOptions),
118 # Resources
119 qw(&RequireResource &ProcessPendingResources),
120  
121 @LaTeXML::Global::EXPORT,
122 # And export those things exported by these Core & Common packages.
123 @LaTeXML::Common::Object::EXPORT,
124 @LaTeXML::Common::Error::EXPORT,
125 @LaTeXML::Core::Token::EXPORT,
126 @LaTeXML::Core::Tokens::EXPORT,
127 @LaTeXML::Core::Box::EXPORT,
128 @LaTeXML::Core::List::EXPORT,
129 @LaTeXML::Common::Number::EXPORT,
130 @LaTeXML::Common::Float::EXPORT,
131 @LaTeXML::Common::Dimension::EXPORT,
132 @LaTeXML::Common::Glue::EXPORT,
133 @LaTeXML::Core::KeyVal::EXPORT,
134 @LaTeXML::Core::KeyVals::EXPORT,
135 @LaTeXML::Core::MuDimension::EXPORT,
136 @LaTeXML::Core::MuGlue::EXPORT,
137 @LaTeXML::Core::Pair::EXPORT,
138 @LaTeXML::Core::PairList::EXPORT,
139 @LaTeXML::Common::Color::EXPORT,
140 @LaTeXML::Core::Alignment::EXPORT,
141 @LaTeXML::Common::XML::EXPORT,
142 @LaTeXML::Util::Radix::EXPORT,
143 );
144  
145 #**********************************************************************
146 # Initially, I thought LaTeXML Packages should try to be like perl modules:
147 # once loaded, you didn't need to re-load them, only `initialize' them to
148 # install their definitions into the current stomach. I tried to achieve
149 # that through various package tricks.
150 # But ultimately, most of a package _is_ installing defns in the stomach,
151 # and it's probably better to allow a more TeX-like evaluation of definitions
152 # in order, so \let and such work as expected.
153 # So, it got simpler!
154 # Still, it would be nice if there were `compiled' forms of .ltxml files!
155 #**********************************************************************
156  
157 sub UTF {
158 my ($code) = @_;
159 return pack('U', $code); }
160  
161 sub coerceCS {
162 my ($cs) = @_;
163 if ((ref $cs) && (ref $cs ne 'LaTeXML::Core::Token')) {
164 $cs = ToString($cs); }
165 if (ref $cs) { }
166 elsif ($cs =~ s/^\\csname\s+(.*)\\endcsname//) {
167 $cs = T_CS('\\' . $1); }
168 else {
169 $cs = T_CS($cs); }
170 return $cs; }
171  
172 sub parsePrototype {
173 my ($proto) = @_;
174 my $oproto = $proto;
175 if (ref $proto eq 'LaTeXML::Core::Token') {
176 return ($proto, undef); }
177 my $cs;
178 if ($proto =~ s/^\\csname\s+(.*)\\endcsname//) {
179 $cs = T_CS('\\' . $1); }
180 elsif ($proto =~ s/^(\\[a-zA-Z@]+)//) { # Match a cs
181 $cs = T_CS($1); }
182 elsif ($proto =~ s/^(\\.)//) { # Match a single char cs, env name,...
183 $cs = T_CS($1); }
184 elsif ($proto =~ s/^(.)//) { # Match an active char
185 ($cs) = TokenizeInternal($1)->unlist; }
186 else {
187 Error('misdefined', $proto, $STATE->getStomach,
188 "Definition prototype doesn't have proper control sequence: \"$proto\"");
189 $proto = ''; }
190 $proto =~ s/^\s*//;
191 return ($cs, parseParameters($proto, $cs)); }
192  
193 # If a ReadFoo function exists (accessible from LaTeXML::Package::Pool),
194 # then the parameter spec:
195 # Foo : will invoke it and use the result for the corresponding argument.
196 # it will complain if ReadFoo returns undef.
197 # SkipFoo : will invoke SkipFoo, if it is defined, else ReadFoo,
198 # but in either case, will ignore the result
199 # OptionalFoo : will invoke ReadOptionalFoo if defined, else ReadFoo
200 # but will not complain if the reader returns undef.
201 # In all cases, there is the provision to supply an additional parameter to the reader:
202 # "Foo:stuff" effectively invokes ReadFoo(Tokenize('stuff'))
203 # similarly for the other variants. What the 'stuff" means depends on the type.
204 sub parseParameters {
205 my ($proto, $for) = @_;
206 my $p = $proto;
207 my @params = ();
208 $p =~ s/^\s+//; $p =~ s/\s+$//;
209 while ($p) {
210 # Handle possibly nested cases, such as {Number}
211 if ($p =~ s/^(\{([^\}]*)\})\s*//) {
212 my ($spec, $inner_spec) = ($1, $2);
213 my $inner = ($inner_spec ? parseParameters($inner_spec, $for) : undef);
214 # If single inner spec is optional, make whole thing optional
215 my $opt = $inner && (scalar(@$inner) == 1) && $$inner[0]{optional};
216 push(@params, LaTeXML::Core::Parameter->new('Plain', $spec, extra => [$inner],
217 optional => $opt)); }
218 elsif ($p =~ s/^(\[([^\]]*)\])\s*//) { # Ditto for Optional
219 my ($spec, $inner_spec) = ($1, $2);
220 if ($inner_spec =~ /^Default:(.*)$/) {
221 push(@params, LaTeXML::Core::Parameter->new('Optional', $spec,
222 extra => [TokenizeInternal($1), undef])); }
223 elsif ($inner_spec) {
224 push(@params, LaTeXML::Core::Parameter->new('Optional', $spec,
225 extra => [undef, parseParameters($inner_spec, $for)])); }
226 else {
227 push(@params, LaTeXML::Core::Parameter->new('Optional', $spec)); } }
228 elsif ($p =~ s/^((\w*)(:([^\s\{\[]*))?)\s*//) {
229 my ($spec, $type, $extra) = ($1, $2, $4);
230 my @extra = map { TokenizeInternal($_) } split('\|', $extra || '');
231 push(@params, LaTeXML::Core::Parameter->new($type, $spec, extra => [@extra])); }
232 else {
233 Error('misdefined', $for, undef, "Unrecognized parameter specification at \"$proto\""); } }
234 return (@params ? LaTeXML::Core::Parameters->new(@params) : undef); }
235  
236 # Convert a LaTeX-style argument spec to our Package form.
237 # Ie. given $nargs and $optional, being the two optional arguments to
238 # something like \newcommand, convert it to the form we use
239 sub convertLaTeXArgs {
240 my ($nargs, $optional) = @_;
241 $nargs = $nargs->toString if ref $nargs;
242 $nargs = 0 unless $nargs;
243 my @params = ();
244 if ($optional) {
245 push(@params, LaTeXML::Core::Parameter->new('Optional',
246 "[Default:" . UnTeX($optional) . "]",
247 extra => [$optional, undef]));
248 $nargs--; }
249 push(@params, map { LaTeXML::Core::Parameter->new('Plain', '{}') } 1 .. $nargs);
250 return (@params ? LaTeXML::Core::Parameters->new(@params) : undef); }
251  
252 #======================================================================
253 # Convenience functions for writing definitions.
254 #======================================================================
255  
256 sub LookupValue {
257 my ($name) = @_;
258 return $STATE->lookupValue($name); }
259  
260 sub AssignValue {
261 my ($name, $value, $scope) = @_;
262 $STATE->assignValue($name, $value, $scope); return; }
263  
264 sub PushValue {
265 my ($name, @values) = @_;
266 $STATE->pushValue($name, @values);
267 return; }
268  
269 sub PopValue {
270 my ($name) = @_;
271 return $STATE->popValue($name); }
272  
273 sub UnshiftValue {
274 my ($name, @values) = @_;
275 $STATE->unshiftValue($name, @values);
276 return; }
277  
278 sub ShiftValue {
279 my ($name) = @_;
280 return $STATE->shiftValue($name); }
281  
282 sub LookupMapping {
283 my ($map, $key) = @_;
284 return $STATE->lookupMapping($map, $key); }
285  
286 sub AssignMapping {
287 my ($map, $key, $value) = @_;
288 return $STATE->assignMapping($map, $key, $value); }
289  
290 sub LookupMappingKeys {
291 my ($map) = @_;
292 return $STATE->lookupMappingKeys($map); }
293  
294 sub LookupCatcode {
295 my ($char) = @_;
296 return $STATE->lookupCatcode($char); }
297  
298 sub AssignCatcode {
299 my ($char, $catcode, $scope) = @_;
300 $STATE->assignCatcode($char, $catcode, $scope);
301 return; }
302  
303 sub LookupMeaning {
304 my ($name) = @_;
305 return $STATE->lookupMeaning($name); }
306  
307 sub LookupDefinition {
308 my ($name) = @_;
309 return $STATE->lookupDefinition($name); }
310  
311 sub InstallDefinition {
312 my ($name, $definition, $scope) = @_;
313 $STATE->installDefinition($name, $definition, $scope);
314 return }
315  
316 sub XEquals {
317 my ($token1, $token2) = @_;
318 my $def1 = LookupMeaning($token1); # token, definition object or undef
319 my $def2 = LookupMeaning($token2); # ditto
320 if (defined $def1 != defined $def2) { # False, if only one has 'meaning'
321 return 0; }
322 elsif (!defined $def1 && !defined $def2) { # true if both undefined
323 return 1; }
324 elsif ($def1->equals($def2)) { # If both have defns, must be same defn!
325 return 1; }
326 return 0; }
327  
328 # Is defined in the LaTeX-y sense of also not being let to \relax.
329 sub IsDefined {
330 my ($name) = @_;
331 my $cs = (ref $name ? $name : T_CS($name));
332 my $meaning = $STATE->lookupMeaning($cs);
333 return $meaning
334 && ($meaning->isa('LaTeXML::Core::Token') || ($meaning->getCSName ne '\relax'))
335 && $meaning; }
336  
337 sub LookupMathcode {
338 my ($char) = @_;
339 return $STATE->lookupMathcode($char); }
340  
341 sub AssignMathcode {
342 my ($char, $mathcode, $scope) = @_;
343 $STATE->assignMathcode($char, $mathcode, $scope);
344 return; }
345  
346 sub LookupSFcode {
347 my ($char) = @_;
348 return $STATE->lookupSFcode($char); }
349  
350 sub AssignSFcode {
351 my ($char, $sfcode, $scope) = @_;
352 $STATE->assignSFcode($char, $sfcode, $scope);
353 return; }
354  
355 sub LookupLCcode {
356 my ($char) = @_;
357 return $STATE->lookupLCcode($char); }
358  
359 sub AssignLCcode {
360 my ($char, $lccode, $scope) = @_;
361 $STATE->assignLCcode($char, $lccode, $scope);
362 return; }
363  
364 sub LookupUCcode {
365 my ($char) = @_;
366 return $STATE->lookupUCcode($char); }
367  
368 sub AssignUCcode {
369 my ($char, $uccode, $scope) = @_;
370 $STATE->assignUCcode($char, $uccode, $scope);
371 return; }
372  
373 sub LookupDelcode {
374 my ($char) = @_;
375 return $STATE->lookupDelcode($char); }
376  
377 sub AssignDelcode {
378 my ($char, $delcode, $scope) = @_;
379 $STATE->assignDelcode($char, $delcode, $scope);
380 return; }
381  
382 sub Let {
383 my ($token1, $token2, $scope) = @_;
384 # If strings are given, assume CS tokens (most common case)
385 $token1 = T_CS($token1) unless ref $token1;
386 $token2 = T_CS($token2) unless ref $token2;
387 $STATE->assignMeaning($token1, $STATE->lookupMeaning($token2), $scope);
388 AfterAssignment();
389 return; }
390  
391 sub Digest {
392 my (@stuff) = @_;
393 return $STATE->getStomach->digest(Tokens(map { (ref $_ ? $_ : TokenizeInternal($_)) } @stuff)); }
394  
395 sub DigestText {
396 my (@stuff) = @_;
397 my $stomach = $STATE->getStomach;
398 $stomach->beginMode('text');
399 my $result = $stomach->digest(Tokens(map { (ref $_ ? $_ : TokenizeInternal($_)) } @stuff));
400 $stomach->endMode('text');
401 return $result; }
402  
403 # probably need to export this, as well?
404 sub DigestLiteral {
405 my (@stuff) = @_;
406 # Perhaps should do StartSemiverbatim, but is it safe to push a frame? (we might cover over valid changes of state!)
407 my $stomach = $STATE->getStomach;
408 $stomach->beginMode('text');
409 my $font = LookupValue('font');
410 AssignValue(font => $font->merge(encoding => 'ASCII'), 'local'); # try to stay as ASCII as possible
411 my $value = $STATE->getStomach->digest(Tokens(map { (ref $_ ? $_ : Tokenize($_)) } @stuff));
412 AssignValue(font => $font);
413 $stomach->endMode('text');
414 return $value; }
415  
416 sub DigestIf {
417 my ($token) = @_;
418 $token = T_CS($token) unless ref $token;
419 if (my $defn = $STATE->lookupDefinition($token)) {
420 return $STATE->getStomach->digest($token); }
421 else {
422 return; } }
423  
424 sub ReadParameters {
425 my ($gullet, $spec) = @_;
426 my $for = T_OTHER("Anonymous");
427 my $parm = parseParameters($spec, $for);
428 return ($parm ? $parm->readArguments($gullet, $for) : ()); }
429  
430 # Merge the current font with the style specifications
431 sub MergeFont {
432 my (@kv) = @_;
433 AssignValue(font => LookupValue('font')->merge(@kv), 'local');
434 return; }
435  
436 # Dumb place for this, but where else...
437 # The TeX way! (bah!! hint: try a large number)
438 my @rmletters = ('i', 'v', 'x', 'l', 'c', 'd', 'm'); # [CONSTANT]
439  
440 sub roman_aux {
441 my ($n) = @_;
442 # We used to have a expl3-code.tex bug here with
443 # input: -1
444 # output: cmxcix
445 # TeX proper returns empty on negative integers
446 return '' unless $n && ($n > 0);
447 my $div = 1000;
448 my $s = ($n > $div ? ('m' x int($n / $div)) : '');
449 my $p = 4;
450 while ($n %= $div) {
451 $div /= 10;
452 my $d = int($n / $div);
453 if ($d % 5 == 4) { $s .= $rmletters[$p]; $d++; }
454 if ($d > 4) { $s .= $rmletters[$p + int($d / 5)]; $d %= 5; }
455 if ($d) { $s .= $rmletters[$p] x $d; }
456 $p -= 2; }
457 return $s; }
458  
459 # Convert the number to lower case roman numerals, returning a list of LaTeXML::Core::Token
460 sub roman {
461 my (@stuff) = @_;
462 return ExplodeText(roman_aux(@stuff)); }
463 # Convert the number to upper case roman numerals, returning a list of LaTeXML::Core::Token
464 sub Roman {
465 my (@stuff) = @_;
466 return ExplodeText(uc(roman_aux(@stuff))); }
467  
468 #======================================================================
469 # Cleaners
470 #======================================================================
471  
472 sub CleanID {
473 my ($key) = @_;
474 $key = ToString($key);
475 $key =~ s/^\s+//s; $key =~ s/\s+$//s; # Trim leading/trailing, in any case
476 $key =~ s/\s//sg;
477 # Remove common idiom:
478 $key =~ s/\$\{\}\^\{(.*?)\}\$/$1/g;
479 # transform some forbidden chars
480 $key =~ s/:/../g; # No colons!
481 $key =~ s/@/-at-/g;
482 $key =~ s/\*/-star-/g;
483 $key =~ s/\$/-dollar-/g;
484 $key =~ s/,/-comma-/g;
485 $key =~ s/%/-pct-/g;
486 $key =~ s/&/-amp-/g;
487 $key = unidecode($key);
488 $key =~ s/[^\w\_\-.]//g; # remove everything else.
489  
490 if ($key =~ /^[^a-zA-Z\_]/) {
491 # in case we are missing a prefix and have a leading ., default to X
492 $key = "X$key";
493 }
494 return $key; }
495  
496 sub CleanLabel {
497 my ($label, $prefix) = @_;
498 my $key = ToString($label);
499 $key =~ s/^\s+//s; $key =~ s/\s+$//s; # Trim leading/trailing, in any case
500 $key =~ s/\s+/_/sg;
501 return (defined $prefix ? ($prefix ? $prefix . ':' . $key : $key) : 'LABEL:' . $key); }
502  
503 sub CleanIndexKey {
504 my ($key) = @_;
505 $key = ToString($key);
506 $key =~ s/^\s+//s; $key =~ s/\s+$//s; # Trim leading/trailing, in any case
507 # We don't want accented chars (do we?) but we need to decompose the accents!
508 ## No, leave in the unicode at this point (strip them later)
509 ## $key = NFD($key);
510 ## $key =~ s/[^a-zA-Z0-9]//g;
511 $key = NFC($key); # just to be safe(?)
512 ## Shouldn't be case insensitive?
513 ## $key =~ tr|A-Z|a-z|;
514 $key =~ s/[\.\,\;]+$//; # Remove trailing punctuation
515 return $key; }
516  
517 sub CleanClassName {
518 my ($key) = @_;
519 $key = ToString($key);
520 $key =~ s/^\s+//s; $key =~ s/\s+$//s; # Trim leading/trailing, in any case
521 # We don't want accented chars (do we?) but we need to decompose the accents!
522 $key = NFD($key);
523 $key =~ s/[^a-zA-Z0-9]//g;
524 $key = NFC($key); # just to be safe(?)
525 return $key; }
526  
527 sub CleanBibKey {
528 my ($key) = @_;
529 $key = ToString($key); # Originally lc() here, but let's preserve case till Postproc.
530 $key =~ s/^\s+//s; $key =~ s/\s+$//s; # Trim leading/trailing, in any case
531 $key =~ s/\s//sg;
532 return $key; }
533  
534 # Return the bibkey in a form to ACTUALLY lookup.
535 # Usually use CleanBibKey to preserve key in the original form (case)
536 sub NormalizeBibKey {
537 my ($key) = @_;
538 return ($key ? lc(CleanBibKey($key)) : undef); }
539  
540 sub CleanURL {
541 my ($url) = @_;
542 $url = ToString($url);
543 $url =~ s/^\s+//s; $url =~ s/\s+$//s; # Trim leading/trailing, in any case
544 $url =~ s/\\~\{\}/~/g;
545 return $url; }
546  
547 sub ComposeURL {
548 my ($base, $url, $fragid) = @_;
549 $base = ToString($base); $base =~ s/\/$// if $base; # remove trailing /
550 $url = ToString($url);
551 $fragid = ToString($fragid);
552 return CleanURL(join('',
553 ($base ?
554 ($url =~ /^\w+:/ ? '' # already has protocol, so is absolute url
555 : $base . ($url =~ /^\// ? '' : '/')) # else start w/base, possibly /
556 : ''),
557 $url,
558 ($fragid ? '#' . CleanID($fragid) : ''))); }
559  
560 #======================================================================
561 # Defining new Control-sequence Parameter types.
562 #======================================================================
563  
564 my $parameter_options = { # [CONSTANT]
565 nargs => 1, reversion => 1, optional => 1, novalue => 1,
566 beforeDigest => 1, afterDigest => 1,
567 semiverbatim => 1, undigested => 1 };
568  
569 sub DefParameterType {
570 my ($type, $reader, %options) = @_;
571 CheckOptions("DefParameterType $type", $parameter_options, %options);
572 AssignMapping('PARAMETER_TYPES', $type, { reader => $reader, %options });
573 return; }
574  
575 sub DefColumnType {
576 my ($proto, $expansion) = @_;
577 if ($proto =~ s/^(.)//) {
578 my $char = $1;
579 $proto =~ s/^\s*//;
580 # Defer
581 # $expansion = TokenizeInternal($expansion) unless ref $expansion;
582 $proto = parseParameters($proto, $char);
583 DefMacroI(T_CS('\NC@rewrite@' . $char), $proto, $expansion); }
584 else {
585 Warn('expected', 'character', undef, "Expected Column specifier"); }
586 return; }
587  
588 #======================================================================
589 # Allocated registers.
590 # We ASSUME the same set of \count positions used by TeX & LaTeX
591 # for recording the next available position in \count,\dimen,\skip,\muskip.
592 our %allocations = (
593 '\count' => '\count10', '\dimen' => '\count11', '\skip' => '\count12', '\muskip' => '\count13',
594 '\box' => '\count14', '\toks' => '\count15');
595  
596 sub allocateRegister {
597 my ($type) = @_;
598 if (my $addr = $allocations{$type}) { # $addr is a Register but MUST be stored as \count<#>
599 if (my $n = $STATE->lookupValue($addr)) {
600 my $next = $n->valueOf + 1;
601 $STATE->assignValue($addr => Number($next), 'global');
602 return $type . $next; }
603 else { # If allocations not set up, punt to unallocated register
604 return; } }
605 else {
606 Error('misdefined', $type, undef, "Type $type is not an allocated register type");
607 return; } }
608  
609 #======================================================================
610 # Counters
611 #======================================================================
612 # This is modelled on LaTeX's counter mechanisms, but since it also
613 # provides support for ID's, even where there is no visible reference number,
614 # it is defined in general.
615 # These id's should be both unique, and parallel the visible reference numbers
616 # (as much as possible). Also, for consistency, we add id's to unnumbered
617 # document elements (eg from \section*); this requires an additional counter
618 # (eg. UNsection) and mechanisms to track it.
619  
620 # Defines a new counter named $ctr.
621 # If $within is defined, $ctr will be reset whenever $within is incremented.
622 # Keywords:
623 # idprefix : specifies a prefix to be used in formatting ID's for document structure elements
624 # counted by this counter. Ie. subsection 3 in section 2 might get: id="S2.SS3"
625 # idwithin : specifies that the ID is composed from $idwithin's ID,, even though
626 # the counter isn't numbered within it. (mainly to avoid duplicated ids)
627 # nested : a list of counters that correspond to scopes which are "inside" this one.
628 # Whenever any definitions scoped to this counter are deactivated,
629 # the inner counter's scopes are also deactivated.
630 # NOTE: I'm not sure this is even a sensible implementation,
631 # or why inner should be different than the counters reset by incrementing this counter.
632  
633 sub NewCounter {
634 my ($ctr, $within, %options) = @_;
635 my $unctr = "UN$ctr"; # UNctr is counter for generating ID's for UN-numbered items.
636 if ($within && ($within ne 'document') && !LookupDefinition(T_CS("\\c\@$within"))) {
637 NewCounter($within); }
638 my $cs = T_CS("\\c\@$ctr");
639 DefRegisterI($cs, undef, Number(0), allocate => '\count');
640 AfterAssignment();
641 AssignValue("\\cl\@$ctr" => Tokens(), 'global') unless LookupValue("\\cl\@$ctr");
642 DefRegisterI(T_CS("\\c\@$unctr"), undef, Number(0));
643 AssignValue("\\cl\@$unctr" => Tokens(), 'global') unless LookupValue("\\cl\@$unctr");
644 my $x;
645 AssignValue("\\cl\@$within" =>
646 Tokens(T_CS($ctr), T_CS($unctr), (($x = LookupValue("\\cl\@$within")) ? $x->unlist : ())),
647 'global') if $within;
648 AssignValue("\\cl\@UN$within" =>
649 Tokens(T_CS($unctr), (($x = LookupValue("\\cl\@UN$within")) ? $x->unlist : ())),
650 'global') if $within;
651 AssignValue('nested_counters_' . $ctr => $options{nested}, 'global') if $options{nested};
652 # default is equivalent to \arabic{ctr}, but w/o using the LaTeX macro!
653 DefMacroI(T_CS("\\the$ctr"), undef, sub {
654 ExplodeText(CounterValue($ctr)->valueOf); },
655 scope => 'global');
656 if (!LookupDefinition(T_CS("\\p\@$ctr"))) {
657 DefMacroI(T_CS("\\p\@$ctr"), undef, Tokens(), scope => 'global'); }
658 my $prefix = $options{idprefix};
659 AssignValue('@ID@prefix@' . $ctr => $prefix, 'global') if $prefix;
660 $prefix = LookupValue('@ID@prefix@' . $ctr) || $ctr unless $prefix;
661 $prefix = CleanID($prefix);
662 if (defined $prefix) {
663 if (my $idwithin = $options{idwithin} || $within) {
664 DefMacroI(T_CS("\\the$ctr\@ID"), undef,
665 "\\expandafter\\ifx\\csname the$idwithin\@ID\\endcsname\\\@empty"
666 . "\\else\\csname the$idwithin\@ID\\endcsname.\\fi"
667 . " $prefix\\csname \@$ctr\@ID\\endcsname",
668 scope => 'global'); }
669 else {
670 DefMacroI(T_CS("\\the$ctr\@ID"), undef, "$prefix\\csname \@$ctr\@ID\\endcsname",
671 scope => 'global'); }
672 DefMacroI(T_CS("\\\@$ctr\@ID"), undef, "0", scope => 'global'); }
673 return; }
674  
675 sub CounterValue {
676 my ($ctr) = @_;
677 $ctr = ToString(Expand($ctr)) if ref $ctr;
678 my $value = LookupRegister('\c@' . $ctr);
679 if (!$value) {
680 Warn('undefined', $ctr, $STATE->getStomach,
681 "Counter '$ctr' was not defined; assuming 0");
682 $value = Number(0); }
683 return $value; }
684  
685 sub AfterAssignment {
686 if (my $after = $STATE->lookupValue('afterAssignment')) {
687 $STATE->assignValue(afterAssignment => undef, 'global');
688 $STATE->getStomach->getGullet->unread($after); } # primitive returns boxes, so these need to be digested!
689 return; }
690  
691 sub SetCounter {
692 my ($ctr, $value) = @_;
693 $ctr = ToString(Expand($ctr)) if ref $ctr;
694 AssignRegister('\c@' . $ctr => $value, 'global');
695 AfterAssignment();
696 DefMacroI(T_CS("\\\@$ctr\@ID"), undef, Tokens(Explode($value->valueOf)), scope => 'global');
697 return; }
698  
699 sub AddToCounter {
700 my ($ctr, $value) = @_;
701 $ctr = ToString(Expand($ctr)) if ref $ctr;
702 my $v = CounterValue($ctr)->add($value);
703 AssignRegister('\c@' . $ctr => $v, 'global');
704 AfterAssignment();
705 DefMacroI(T_CS("\\\@$ctr\@ID"), undef, Tokens(Explode($v->valueOf)), scope => 'global');
706 return; }
707  
708 sub StepCounter {
709 my ($ctr, $noreset) = @_;
710 my $value = CounterValue($ctr);
711 my $newvalue = $value->add(Number(1));
712 AssignRegister("\\c\@$ctr" => $newvalue, 'global');
713 AfterAssignment();
714 DefMacroI(T_CS("\\\@$ctr\@ID"), undef, Tokens(Explode($newvalue->valueOf)),
715 scope => 'global');
716 # and reset any within counters!
717 if (!$noreset) {
718 if (my $nested = LookupValue("\\cl\@$ctr")) {
719 foreach my $c ($nested->unlist) {
720 ResetCounter(ToString($c)); } } }
721 # DigestIf(T_CS("\\the$ctr"));
722 return; }
723  
724 # HOW can we retract this?
725 sub RefStepCounter {
726 my ($type, $noreset) = @_;
727 my $ctr = LookupMapping('counter_for_type', $type) || $type;
728 $ctr = ToString(Expand($ctr)) if ref $ctr;
729 StepCounter($ctr, $noreset);
730 maybePreemptRefnum($ctr);
731 my $iddef = $STATE->lookupDefinition(T_CS("\\the$ctr\@ID"));
732 my $has_id = $iddef && ((!defined $iddef->getParameters) || ($iddef->getParameters->getNumArgs == 0));
733  
734 DefMacroI(T_CS('\@currentlabel'), undef, T_CS("\\the$ctr"), scope => 'global');
735 DefMacroI(T_CS('\@currentID'), undef, T_CS("\\the$ctr\@ID"), scope => 'global') if $has_id;
736  
737 my $id = $has_id && CleanID(ToString(DigestLiteral(T_CS("\\the$ctr\@ID"))));
738  
739 my $refnum = DigestText(T_CS("\\the$ctr"));
740 my $tags = Digest(Invocation(T_CS('\lx@make@tags'), $type));
741 # Any scopes activated for previous value of this counter (& any nested counters) must be removed.
742 # This may also include scopes activated for \label
743 deactivateCounterScope($ctr);
744 # And install the scope (if any) for this reference number.
745 AssignValue(current_counter => $ctr, 'local');
746 my $scope = $ctr . ':' . ToString($refnum);
747 AssignValue('scopes_for_counter:' . $ctr => [$scope], 'local');
748 $STATE->activateScope($scope);
749 return (
750 ($tags ? (tags => $tags) : ()),
751 ($has_id ? (id => $id) : ())); }
752  
753 # Internal: Use a label-derived reference number and/or ID
754 # instead of the traditional counter based ones.
755 # Since the \label{} determins the reference number and ID,
756 # we MUST sniff out the label BEFORE we call RefStepCounter/RefStepID !!!!!
757 # (see MaybePeekLabel below; and also MaybeNoteLabel for use within
758 # captions & certain equation environments)
759 # Assign a sub to LABEL_MAPPING_HOOK: &sub($label,$counter,$norefnum)
760 # to return the desired refnum and id for a given object.
761 sub maybePreemptRefnum {
762 my ($ctr, $norefnum) = @_;
763 if (my $mapper = LookupValue('LABEL_MAPPING_HOOK')) {
764 my $hj_refnum = T_CS('\_PREEMPTED_REFNUM_' . $ctr);
765 my $hj_id = T_CS('\_PREEMPTED_ID_' . $ctr);
766 # First, restore the \the<ctr> and \the<ctr>@ID macros to defaults
767 if (!$norefnum && LookupMeaning($hj_refnum)) {
768 Let(T_CS('\the' . $ctr), $hj_refnum, 'global'); }
769 if (LookupMeaning($hj_id)) {
770 Let(T_CS('\the' . $ctr . '@ID'), $hj_id, 'global'); }
771 my $label = LookupValue('PEEKED_LABEL');
772 my ($fixedrefnum, $fixedid) = &$mapper($label, $ctr, $norefnum);
773 if (!$norefnum && $fixedrefnum) {
774 if (!LookupMeaning($hj_refnum)) { # Save for later
775 Let($hj_refnum, T_CS('\the' . $ctr), 'global'); }
776 DefMacroI('\the' . $ctr, undef, $fixedrefnum, scope => 'global'); }
777 if ($fixedid) {
778 if (!LookupMeaning($hj_id)) { # Save for later
779 Let($hj_id, T_CS('\the' . $ctr . '@ID'), 'global'); }
780 DefMacroI('\the' . $ctr . '@ID', undef, $fixedid, scope => 'global'); }
781 AssignValue(PEEKED_LABEL => undef, 'global'); # CONSUME the label
782 AssignValue(PROCESSED_LABEL => $label, 'global'); # Note that we've consumed the label
783 }
784 return; }
785  
786 # Use to peek for FOLLOWING \label{...} to support label-derived refererence numbers
787 sub MaybePeekLabel {
788 if (LookupValue('LABEL_MAPPING_HOOK')) {
789 my $gullet = $STATE->getStomach->getGullet;
790 my $peek = $gullet->readNonSpace;
791 if (Equals($peek, T_CS('\label'))) {
792 StartSemiverbatim();
793 my $arg = $gullet->readArg();
794 EndSemiverbatim();
795 my $label = CleanLabel($arg, '');
796 AssignValue(PEEKED_LABEL => $label, 'global');
797 $gullet->unread(T_BEGIN, $arg, T_END); }
798 else {
799 AssignValue(PROCESSED_LABEL => undef, 'global');
800 AssignValue(PEEKED_LABEL => undef, 'global'); }
801 $gullet->unread($peek); }
802 return; }
803  
804 # Use to note a discovered label to support label-derived refererence numbers
805 # Can by used by \label, among others. Note we only record the label
806 # if it hasn't already been peeked, and consumed.
807 sub MaybeNoteLabel {
808 my ($label) = @_;
809 if (LookupValue('LABEL_MAPPING_HOOK')) {
810 $label = CleanLabel($label, '');
811 my $processed = LookupValue('PROCESSED_LABEL');
812 if (!$processed || ($processed ne $label)) { # Only if not already processed
813 AssignValue(PROCESSED_LABEL => undef, 'global');
814 AssignValue(PEEKED_LABEL => $label, 'global'); } }
815 return; }
816  
817 sub deactivateCounterScope {
818 my ($ctr) = @_;
819 if (my $scopes = LookupValue('scopes_for_counter:' . $ctr)) {
820 map { $STATE->deactivateScope($_) } @$scopes; }
821 foreach my $inner_ctr (@{ LookupValue('nested_counters_' . $ctr) || [] }) {
822 deactivateCounterScope($inner_ctr); }
823 return; }
824  
825 # For UN-numbered units
826 sub RefStepID {
827 my ($type) = @_;
828 my $ctr = LookupMapping('counter_for_type', $type) || $type;
829 my $unctr = "UN$ctr";
830 StepCounter($unctr);
831 maybePreemptRefnum($ctr, 1);
832 DefMacroI(T_CS("\\\@$ctr\@ID"), undef,
833 Tokens(T_OTHER('x'), Explode(LookupValue('\c@' . $unctr)->valueOf)),
834 scope => 'global');
835 DefMacroI(T_CS('\@currentID'), undef, T_CS("\\the$ctr\@ID"));
836 my $id = CleanID(ToString(DigestLiteral(T_CS("\\the$ctr\@ID"))));
837 return (id => $id); }
838  
839 sub ResetCounter {
840 my ($ctr) = @_;
841 AssignRegister('\c@' . $ctr => Number(0), 'global');
842 AssignRegister('\c@UN' . $ctr => Number(0), 'global') unless $ctr =~ /^UN/; # but not UNUN
843 DefMacroI(T_CS("\\\@$ctr\@ID"), undef, Tokens(T_OTHER('0')),
844 scope => 'global');
845 # and reset any within counters!
846 if (my $nested = LookupValue("\\cl\@$ctr")) {
847 foreach my $c ($nested->unlist) {
848 ResetCounter(ToString($c)); } }
849 return; }
850  
851 #**********************************************************************
852 # This function computes an xml:id for a node, if it hasn't already got one.
853 # It is suitable for use in Tag afterOpen as
854 # Tag('ltx:para',afterOpen=>sub { GenerateID(@_,'p'); });
855 # It generates an id of the form <parentid>.<prefix><number>
856 # The parent node (the one with ID=<parentid>) also maintains a counter
857 # stored in an attribute _ID_counter_<prefix> recording the last used
858 # <number> for <prefix> amongst its descendents.
859 sub GenerateID {
860 my ($document, $node, $whatsit, $prefix) = @_;
861 # If node doesn't already have an id, and can have one
862 # make a "sensible" id for it. Avoid adding unneeded/unwanted ids until as late as possible,
863 # since it causes lots of book-keeping when rearranging XML (you have to monitor id references!)
864 if (!$node->hasAttribute('xml:id') && $document->canHaveAttribute($node, 'xml:id')
865 # but isn't a _Capture_ node (which ultimately should disappear)
866 && ($document->getNodeQName($node) ne 'ltx:_Capture_')) {
867 my $id = '';
868 if (my $prelim_id = $node->getAttribute('_pregenerated_id_')) {
869 $id = $prelim_id; } # Or an id generated while id'ing a child
870 else {
871 my @p = ();
872 my $p = $node->parentNode;
873 # Walk up to root or an id'd node...
874 while ($p && ($p->nodeType == XML_ELEMENT_NODE)) {
875 if ($document->getNodeQName($p) ne 'ltx:_Capture_') {
876 push(@p, $p);
877 last if $id = $p->getAttribute('xml:id'); }
878 $p = $p->parentNode; }
879 $prefix = 'id' unless $prefix || $id;
880 if (LookupValue('GENERATE_IDS') && @p) {
881 # If generating ALL ids, prepare a chain of ids back down to the current node
882 while ($p = pop(@p)) {
883 $id = generateID_nextid($p, (@p ? '' : $prefix), $id);
884 $p[-1]->setAttribute('_pregenerated_id_', $id) if @p; } }
885 else {
886 # Or base the id on the id'd ancestor's id.
887 $id = generateID_nextid($p[-1] || $document->documentElement, $prefix, $id); } }
888 # We may still be in a case where we got a raw numeric id. If so, guard with a prefix:
889 $id = "id$id" if $id =~ /^\d/;
890 $document->setAttribute($node, 'xml:id' => $id); }
891 return; }
892  
893 sub generateID_nextid {
894 my ($parent, $prefix, $id_sofar) = @_;
895 my $ctrkey = '_ID_counter_' . ($prefix ? $prefix . '_' : '');
896 my $ctr = $parent->getAttribute($ctrkey) || 0;
897 $id_sofar = ($id_sofar ? $id_sofar . '.' : '') . ($prefix ? $prefix : '') . (++$ctr);
898 $parent->setAttribute($ctrkey => $ctr);
899 return $id_sofar; }
900  
901 #======================================================================
902 #
903 #======================================================================
904  
905 # Return $tokens with all tokens expanded
906 sub Expand {
907 my (@tokens) = @_;
908 return () unless @tokens;
909 return $STATE->getStomach->getGullet->readingFromMouth(LaTeXML::Core::Mouth->new(), sub {
910 my ($gullet) = @_;
911 $gullet->unread(@tokens);
912 my @expanded = ();
913 while (defined(my $t = $gullet->readXToken(0))) {
914 push(@expanded, $t); }
915 return Tokens(@expanded); }); }
916  
917 sub Invocation {
918 my ($token, @args) = @_;
919 $token = (ref $token ? $token : T_CS($token));
920 # Note: $token may have been \let to another defn!
921 if (my $defn = $STATE->lookupDefinition($token)) {
922 my $params = $defn->getParameters;
923 return Tokens($token, ($params ? $params->revertArguments(@args) : ())); }
924 else {
925 $STATE->generateErrorStub(undef, $token, convertLaTeXArgs(scalar(@args), 0));
926 return Tokens($token, map { ($_ ? (T_BEGIN, $_->unlist, T_END) : ()) } @args); } }
927  
928 sub RawTeX {
929 my ($text) = @_;
930 # It could be as simple as this, except if catcodes get changed, it's too late!!!
931 # Digest(TokenizeInternal($text));
932 my $stomach = $STATE->getStomach;
933 my $savedcc = $STATE->lookupCatcode('@');
934 $STATE->assignCatcode('@' => CC_LETTER);
935  
936 $stomach->getGullet->readingFromMouth(LaTeXML::Core::Mouth->new($text,
937 fordefinitions => 1, at_letter => 1), sub {
938 my ($gullet) = @_;
939 my $token;
940 while ($token = $gullet->readXToken(0)) {
941 next if $token->equals(T_SPACE);
942 $stomach->invokeToken($token); } });
943  
944 $STATE->assignCatcode('@' => $savedcc);
945 return; }
946  
947 sub StartSemiverbatim {
948 my (@chars) = @_;
949 $STATE->beginSemiverbatim(@chars);
950 return; }
951  
952 sub EndSemiverbatim {
953 $STATE->endSemiverbatim;
954 return; }
955  
956 # WARNING: These two utilities bind $STATE to simple State objects with known fixed catcodes.
957 # The State normally contains ALL the bindings, etc and links to other important objects.
958 # We CAN do that here, since we are ONLY tokenizing from a new Mouth, bypassing stomach & gullet.
959 # However, be careful with any changes.
960 our $STD_CATTABLE;
961 our $STY_CATTABLE;
962  
963 # Tokenize($string); Tokenizes the string using the standard cattable, returning a LaTeXML::Core::Tokens
964 sub Tokenize {
965 my ($string) = @_;
966 $STD_CATTABLE = LaTeXML::Core::State->new(catcodes => 'standard') unless $STD_CATTABLE;
967 local $STATE = $STD_CATTABLE;
968 return LaTeXML::Core::Mouth->new($string)->readTokens; }
969  
970 # TokenizeInternal($string); Tokenizes the string using the internal cattable, returning a LaTeXML::Core::Tokens
971 sub TokenizeInternal {
972 my ($string) = @_;
973 $STY_CATTABLE = LaTeXML::Core::State->new(catcodes => 'style') unless $STY_CATTABLE;
974 local $STATE = $STY_CATTABLE;
975 return LaTeXML::Core::Mouth->new($string)->readTokens; }
976  
977 # Check whether all these things are "empty" (spaces are NOT empty!!)
978 # short-circuit: return 0 quickly if anything is NOT empty.
979 sub IsEmpty {
980 my (@things) = @_;
981 foreach my $thing (@things) {
982 my $ref = ref $thing;
983 if (!$thing) { }
984 elsif ($ref eq 'LaTeXML::Core::Comment') { }
985 elsif ($ref eq 'LaTeXML::Core::Tokens') {
986 return 0 unless IsEmpty($thing->unlist); }
987 elsif ($ref eq 'LaTeXML::Core::Token') {
988 my $cc = $$thing[1];
989 return 0 if ($cc == CC_LETTER) || ($cc == CC_OTHER) || ($cc == CC_ACTIVE) || ($cc == CC_CS); }
990 elsif (!$thing->getProperty('isEmpty')) {
991 if ($ref eq 'LaTeXML::Core::Box') {
992 my $s = $thing->getString;
993 return 0 if (defined $s) && length($s); }
994 elsif ($ref eq 'LaTeXML::Core::List') {
995 return 0 unless IsEmpty($thing->unlist); }
996 elsif ($ref eq 'LaTeXML::Core::Whatsit') {
997 # Sneaky Whatsit property for something (an arg) that stands-in for the whatsit's content.
998 if (my $body = $thing->getProperty('content_box')) {
999 return 0 unless IsEmpty($body); }
1000 else {
1001 return 0; } } } }
1002 return 1; }
1003  
1004 #======================================================================
1005 # Non-exported support for defining forms.
1006 #======================================================================
1007 sub CheckOptions {
1008 my ($operation, $allowed, %options) = @_;
1009 my @badops = grep { !$$allowed{$_} } keys %options;
1010 Error('misdefined', $operation, $STATE->getStomach,
1011 "$operation does not accept options:" . join(', ', @badops)) if @badops;
1012 return; }
1013  
1014 sub requireMath {
1015 my ($cs) = @_;
1016 $cs = ToString($cs);
1017 Warn('unexpected', $cs, $STATE->getStomach,
1018 "$cs should only appear in math mode") unless LookupValue('IN_MATH');
1019 return; }
1020  
1021 sub forbidMath {
1022 my ($cs) = @_;
1023 $cs = ToString($cs);
1024 Warn('unexpected', $cs, $STATE->getStomach,
1025 "$cs should not appear in math mode") if LookupValue('IN_MATH');
1026 return; }
1027  
1028 #**********************************************************************
1029 # Definitions
1030 #**********************************************************************
1031 sub DefAutoload {
1032 my ($cs, $defnfile) = @_;
1033 my $csname = (ref $cs ? ToString($cs) : $cs);
1034 $csname = '\\' . $csname unless $cs =~ /^\\/;
1035 $cs = T_CS($csname) unless ref $cs;
1036 $defnfile =~ s/\.ltxml$//;
1037 if ($defnfile =~ /^(.*?)\.(pool|sty|cls)$/) {
1038 my ($name, $type) = ($1, $2);
1039 # if already loaded, or set, DONT redefine!
1040 if (!(
1041 LookupValue($name . '.' . $type . '_loaded') ||
1042 LookupValue($name . '.' . $type . '.ltxml_loaded') ||
1043 LookupMeaning($cs))) {
1044 AssignMapping('autoload_' . $defnfile, $csname => 1);
1045 DefMacroI($cs, undef, sub {
1046 ClearAutoLoad($defnfile);
1047 if ($type eq 'pool') { LoadPool($name); } # Load appropriate definitions
1048 elsif ($type eq 'cls') { LoadClass($name); }
1049 else { RequirePackage($name); }
1050 ($cs); }); } } # Then return the original cs, so that it's be re-tried.
1051 else {
1052 Warning('unexpected', $defnfile, undef, "Don't know how to autoload $csname from $defnfile"); }
1053 return; }
1054  
1055 # Undefine ALL autoload triggers for this definition file.
1056 sub ClearAutoLoad {
1057 my ($defnfile) = @_;
1058 $defnfile =~ s/\.ltxml$//;
1059 foreach my $trigger (LookupMappingKeys('autoload_' . $defnfile)) {
1060 $STATE->assign_internal('meaning', $trigger => undef, 'global'); }
1061 return; }
1062 #======================================================================
1063 # Defining Expandable Control Sequences.
1064 #======================================================================
1065 # Define an expandable control sequence. It will be expanded in the Gullet.
1066 # The $replacement should be a LaTeXML::Core::Tokens (the arguments will be
1067 # substituted for any #1,...), or a sub which returns a list of tokens (or just return;).
1068 # Those tokens, if any, will be reinserted into the input.
1069 # There are no options to these definitions.
1070 my $expandable_options = { # [CONSTANT]
1071 scope => 1, locked => 1 };
1072  
1073 sub DefExpandable {
1074 my ($proto, $expansion, %options) = @_;
1075 Warn('deprecated', 'DefExpandable', $STATE->getStomach,
1076 "DefExpandable ($proto) is deprecated; use DefMacro");
1077 DefMacro($proto, $expansion, %options);
1078 return; }
1079  
1080 # Define a Macro: Essentially an alias for DefExpandable
1081 # For convenience, the $expansion can be a string which will be tokenized.
1082 my $macro_options = { # [CONSTANT]
1083 scope => 1, locked => 1, mathactive => 1,
1084 protected => 1, robust => 1, outer => 1, long => 1,
1085 nopackParameters => 1 };
1086  
1087 # Defines $cs as protected call to the mangled name "\cs ", which it returns
1088 sub defRobustCS {
1089 my ($cs, %options) = @_;
1090 my $defcs = T_CS($_[0]->getString . ' ');
1091 $STATE->installDefinition(LaTeXML::Core::Definition::Expandable->new($cs, undef,
1092 Tokens(T_CS('\protect'), $defcs), locked => $options{locked}),
1093 $options{scope}); # should be \x@protect?
1094 return $defcs; }
1095  
1096 sub DefMacro {
1097 my ($proto, $expansion, %options) = @_;
1098 CheckOptions("DefMacro ($proto)", $macro_options, %options);
1099 DefMacroI(parsePrototype($proto), $expansion, %options);
1100 return; }
1101  
1102 sub DefMacroI {
1103 my ($cs, $paramlist, $expansion, %options) = @_;
1104 if (!defined $expansion) { $expansion = Tokens(); }
1105 # Optimization: Defer till macro actually used
1106 # elsif (!ref $expansion) { $expansion = TokenizeInternal($expansion); }
1107 if ((length($cs) == 1) && $options{mathactive}) {
1108 $STATE->assignMathcode($cs => 0x8000, $options{scope}); }
1109 $cs = coerceCS($cs);
1110 $paramlist = parseParameters($paramlist, $cs) if defined $paramlist && !ref $paramlist;
1111 my $defcs = ($options{robust} ? defRobustCS($cs, %options) : $cs);
1112 $STATE->installDefinition(LaTeXML::Core::Definition::Expandable->new($defcs, $paramlist, $expansion, %options),
1113 $options{scope});
1114 AssignValue(ToString($cs) . ":locked" => 1, 'global') if $options{locked};
1115 return; }
1116  
1117 #======================================================================
1118 # Defining Conditional Control Sequences.
1119 #======================================================================
1120 # Define a conditional control sequence. Its processing takes place in
1121 # the Gullet. The test is applied to the arguments (if any),
1122 # which determines which branch is executed.
1123 # If the test is undefined, the conditional is a "user defined" one;
1124 # Two additional primitives are defined \footrue and \foofalse;
1125 # the test is then determined by the most recently called of those.
1126  
1127 # If you supply a skipper instead of a test, it is also applied to the arguments
1128 # and should skip to the right place in the following \or, \else, \fi.
1129 # This is ONLY used for \ifcase.
1130 my $conditional_options = { # [CONSTANT]
1131 scope => 1, locked => 1, skipper => 1 };
1132  
1133 sub DefConditional {
1134 my ($proto, $test, %options) = @_;
1135 CheckOptions("DefConditional ($proto)", $conditional_options, %options);
1136 DefConditionalI(parsePrototype($proto), $test, %options);
1137 return; }
1138  
1139 sub DefConditionalI {
1140 my ($cs, $paramlist, $test, %options) = @_;
1141 $cs = coerceCS($cs);
1142 my $csname = ToString($cs);
1143 # Special cases...
1144 if ($csname eq '\fi') {
1145 $STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new(
1146 $cs, undef, undef, conditional_type => 'fi', %options),
1147 $options{scope}); }
1148 elsif ($csname eq '\else') {
1149 $STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new(
1150 $cs, undef, undef, conditional_type => 'else', %options),
1151 $options{scope}); }
1152 elsif ($csname eq '\or') {
1153 $STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new(
1154 $cs, undef, undef, conditional_type => 'or', %options),
1155 $options{scope}); }
1156 elsif ($csname eq '\unless') {
1157 $STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new($cs, $paramlist, $test,
1158 conditional_type => 'unless', %options),
1159 $options{scope}); }
1160 elsif ($csname =~ /^\\(..)(.*)$/) {
1161 my ($prefix, $name) = ($1, $2);
1162 if ($prefix ne 'if') {
1163 Warn('misdefined', $cs, $STATE->getStomach,
1164 "The conditional " . Stringify($cs) . " is being defined but doesn't start with \\if"); }
1165 if ((defined $name) && ($name ne 'case')
1166 && (!defined $test)) { # user-defined conditional, like with \newif
1167 DefMacroI(T_CS('\\' . $name . 'true'), undef, Tokens(T_CS('\let'), $cs, T_CS('\iftrue')));
1168 DefMacroI(T_CS('\\' . $name . 'false'), undef, Tokens(T_CS('\let'), $cs, T_CS('\iffalse')));
1169 Let($cs, T_CS('\iffalse')); }
1170 else {
1171 # For \ifcase, the parameter list better be a single Number !!
1172 $paramlist = parseParameters($paramlist, $cs) if defined $paramlist && !ref $paramlist;
1173 $STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new($cs, $paramlist, $test,
1174 conditional_type => 'if', %options),
1175 $options{scope}); }
1176 }
1177 else {
1178 Error('misdefined', $cs, $STATE->getStomach,
1179 "The conditional " . Stringify($cs) . " is being defined but doesn't start with \\if"); }
1180 AssignValue(ToString($cs) . ":locked" => 1) if $options{locked};
1181 return; }
1182  
1183 sub IfCondition {
1184 my ($if, @args) = @_;
1185 my $gullet = $STATE->getStomach->getGullet;
1186 $if = coerceCS($if);
1187 my ($defn, $test);
1188 if (($defn = $STATE->lookupDefinition($if))
1189 && (($$defn{conditional_type} || '') eq 'if') && ($test = $defn->getTest)) {
1190 return &$test($gullet, @args); }
1191 elsif (XEquals($if, T_CS('\iftrue'))) {
1192 return 1; }
1193 elsif (XEquals($if, T_CS('\iffalse'))) {
1194 return 0; }
1195 else {
1196 Error('expected', 'conditional', $gullet,
1197 "Expected a conditional, got '" . ToString($if) . "'");
1198 return; } }
1199  
1200 # Used only for regular \newif type conditions
1201 sub SetCondition {
1202 my ($if, $value, $scope) = @_;
1203 my ($defn, $test);
1204 # We'll accept any conditional \ifxxx, providing it takes no arguments
1205 if (($defn = $STATE->lookupDefinition($if)) && (($$defn{conditional_type} || '') eq 'if')
1206 && !$defn->getParameters) {
1207 Let($if, ($value ? T_CS('\iftrue') : T_CS('\iffalse')), $scope) }
1208 else {
1209 Error('expected', 'conditional', $STATE->getStomach,
1210 "Expected a conditional defined by \\newif, got '" . ToString($if) . "'"); }
1211 return; }
1212  
1213 #======================================================================
1214 # Define a primitive control sequence.
1215 #======================================================================
1216 # Primitives are executed in the Stomach.
1217 # The $replacement should be a sub which returns nothing, or a list of Box's or Whatsit's.
1218 # The options are:
1219 # isPrefix : 1 for things like \global, \long, etc.
1220 # registerType : for parameters (but needs to be worked into DefParameter, below).
1221  
1222 my $primitive_options = { # [CONSTANT]
1223 isPrefix => 1, scope => 1, mode => 1, font => 1,
1224 requireMath => 1, forbidMath => 1,
1225 beforeDigest => 1, afterDigest => 1,
1226 bounded => 1, locked => 1, alias => 1, robust => 1,
1227 outer => 1, long => 1 };
1228  
1229 sub DefPrimitive {
1230 my ($proto, $replacement, %options) = @_;
1231 CheckOptions("DefPrimitive ($proto)", $primitive_options, %options);
1232 DefPrimitiveI(parsePrototype($proto), $replacement, %options);
1233 return; }
1234  
1235 sub DefPrimitiveI {
1236 my ($cs, $paramlist, $replacement, %options) = @_;
1237 $cs = coerceCS($cs);
1238 $paramlist = parseParameters($paramlist, $cs) if defined $paramlist && !ref $paramlist;
1239 my $mode = $options{mode};
1240 my $bounded = $options{bounded};
1241 # Not sure robust entirely makes sense for Primitives, other than LaTeXML vs LaTeX mismatch
1242 my $defcs = ($options{robust} ? defRobustCS($cs, %options) : $cs);
1243 $STATE->installDefinition(LaTeXML::Core::Definition::Primitive
1244 ->new($defcs, $paramlist, $replacement,
1245 beforeDigest => flatten(($options{requireMath} ? (sub { requireMath($cs); }) : ()),
1246 ($options{forbidMath} ? (sub { forbidMath($cs); }) : ()),
1247 ($mode ? (sub { $_[0]->beginMode($mode); })
1248 : ($bounded ? (sub { $_[0]->bgroup; }) : ())),
1249 ($options{font} ? (sub { MergeFont(%{ $options{font} }); }) : ()),
1250 $options{beforeDigest}),
1251 afterDigest => flatten($options{afterDigest},
1252 ($mode ? (sub { $_[0]->endMode($mode) })
1253 : ($bounded ? (sub { $_[0]->egroup; }) : ()))),
1254 outer => $options{outer},
1255 long => $options{long},
1256 isPrefix => $options{isPrefix},
1257 alias => $options{alias},
1258 ),
1259 $options{scope});
1260 AssignValue(ToString($cs) . ":locked" => 1) if $options{locked};
1261 return; }
1262  
1263 my $register_options = { # [CONSTANT]
1264 readonly => 1, getter => 1, setter => 1, address => 1, allocate => 1 };
1265 my %register_types = ( # [CONSTANT]
1266 'LaTeXML::Common::Number' => 'Number',
1267 'LaTeXML::Common::Dimension' => 'Dimension',
1268 'LaTeXML::Common::Glue' => 'Glue',
1269 'LaTeXML::Core::MuGlue' => 'MuGlue',
1270 'LaTeXML::Core::Tokens' => 'Tokens',
1271 'LaTeXML::Core::Token' => 'Token',
1272 );
1273  
1274 sub DefRegister {
1275 my ($proto, $value, %options) = @_;
1276 CheckOptions("DefRegister ($proto)", $register_options, %options);
1277 DefRegisterI(parsePrototype($proto), $value, %options);
1278 return; }
1279  
1280 sub DefRegisterI {
1281 my ($cs, $paramlist, $value, %options) = @_;
1282 $cs = coerceCS($cs);
1283 $paramlist = parseParameters($paramlist, $cs) if defined $paramlist && !ref $paramlist;
1284 my $type = $register_types{ ref $value };
1285 my $address = ($options{address} ? ToString($options{address})
1286 : ($options{allocate} ? allocateRegister($options{allocate}) : undef));
1287 $address = ToString($cs) unless $address;
1288 if ((defined $value) && ((!defined $options{address}) || !defined LookupValue($address))) {
1289 AssignValue($address => $value, 'global'); } # Assign, but do not RE-assign
1290 $STATE->installDefinition(LaTeXML::Core::Definition::Register->new($cs, $paramlist,
1291 address => $address,
1292 registerType => $type,
1293 getter => $options{getter}, setter => $options{setter},
1294 default => $value,
1295 readonly => $options{readonly}),
1296 'global');
1297 return; }
1298  
1299 sub LookupRegister {
1300 my ($cs, @parameters) = @_;
1301 my $defn;
1302 $cs = T_CS($cs) unless ref $cs;
1303 if (($defn = $STATE->lookupDefinition($cs)) && $defn->isRegister) {
1304 return $defn->valueOf(@parameters); }
1305 else {
1306 Warn('expected', 'register', $STATE->getStomach,
1307 "The control sequence " . ToString($cs) . " is not a register"); }
1308 return; }
1309  
1310 sub LookupDimension {
1311 my ($cs) = @_;
1312 $cs = T_CS($cs) unless ref $cs;
1313 if (my $defn = $STATE->lookupDefinition($cs)) {
1314 if ($defn->isRegister) { # Easy (and proper) case.
1315 return $defn->valueOf; }
1316 else {
1317 $STATE->getStomach->getGullet->readingFromMouth(LaTeXML::Core::Mouth->new(), sub { # start with empty mouth
1318 my ($gullet) = @_;
1319 $gullet->unread($cs); # but put back tokens to be read
1320 return $gullet->readDimension; }); } }
1321 else {
1322 Warn('expected', 'register', $STATE->getStomach,
1323 "The control sequence " . ToString($cs) . " is not a register"); }
1324 return Dimension(0); }
1325  
1326 sub AssignRegister {
1327 my ($cs, $value, $scope, @parameters) = @_;
1328 my $defn;
1329 $cs = T_CS($cs) unless ref $cs;
1330 if (($defn = $STATE->lookupDefinition($cs)) && $defn->isRegister) {
1331 return $defn->setValue($value, $scope, @parameters); }
1332 else {
1333 Warn('expected', 'register', $STATE->getStomach,
1334 "The control sequence " . ToString($cs) . " is not a register");
1335 return; } }
1336  
1337 sub flatten {
1338 my (@stuff) = @_;
1339 return [map { (defined $_ ? (ref $_ eq 'ARRAY' ? @$_ : ($_)) : ()) } @stuff]; }
1340  
1341 #======================================================================
1342 # Define a constructor control sequence.
1343 #======================================================================
1344 # The arguments, if any, will be collected and processed in the Stomach, and
1345 # a Whatsit will be constructed.
1346 # It is the Whatsit that will be processed in the Document: It is responsible
1347 # for constructing XML Nodes. The $replacement should be a sub which inserts nodes,
1348 # or a string specifying a constructor pattern (See somewhere).
1349 #
1350 # Options are:
1351 # bounded : any side effects of before/after daemans are bounded; they are
1352 # automatically enclosed by bgroup/egroup pair.
1353 # mode : causes a switch into the given mode during the Whatsit building in the stomach.
1354 # reversion : a string representing the preferred TeX form of the invocation.
1355 # beforeDigest : code to be executed (in the stomach) before parsing & constructing the Whatsit.
1356 # Can be used for changing modes, beginning groups, etc.
1357 # afterDigest : code to be executed (in the stomach) after parsing & constructing the Whatsit.
1358 # useful for setting Whatsit properties,
1359 # properties : a hashref listing default values of properties to assign to the Whatsit.
1360 # These properties can be used in the constructor.
1361 my $constructor_options = { # [CONSTANT]
1362 mode => 1, requireMath => 1, forbidMath => 1, font => 1,
1363 alias => 1, reversion => 1, sizer => 1, properties => 1,
1364 nargs => 1,
1365 beforeDigest => 1, afterDigest => 1, beforeConstruct => 1, afterConstruct => 1,
1366 captureBody => 1, scope => 1, bounded => 1, locked => 1,
1367 outer => 1, long => 1, robust => 1 };
1368  
1369 sub inferSizer {
1370 my ($sizer, $reversion) = @_;
1371 return (defined $sizer ? $sizer
1372 : ((defined $reversion) && (!ref $reversion) && ($reversion =~ /^(?:#\w+)*$/)
1373 ? $reversion : undef)); }
1374  
1375 sub DefConstructor {
1376 my ($proto, $replacement, %options) = @_;
1377 CheckOptions("DefConstructor ($proto)", $constructor_options, %options);
1378 DefConstructorI(parsePrototype($proto), $replacement, %options);
1379 return; }
1380  
1381 sub DefConstructorI {
1382 my ($cs, $paramlist, $replacement, %options) = @_;
1383 $cs = coerceCS($cs);
1384 $paramlist = parseParameters($paramlist, $cs) if defined $paramlist && !ref $paramlist;
1385 my $mode = $options{mode};
1386 my $bounded = $options{bounded};
1387 # Not sure robust entirely makes sense for Constructors, other than LaTeXML vs LaTeX mismatch
1388 my $defcs = ($options{robust} ? defRobustCS($cs, %options) : $cs);
1389 $STATE->installDefinition(LaTeXML::Core::Definition::Constructor
1390 ->new($defcs, $paramlist, $replacement,
1391 beforeDigest => flatten(($options{requireMath} ? (sub { requireMath($cs); }) : ()),
1392 ($options{forbidMath} ? (sub { forbidMath($cs); }) : ()),
1393 ($mode ? (sub { $_[0]->beginMode($mode); })
1394 : ($bounded ? (sub { $_[0]->bgroup; }) : ())),
1395 ($options{font} ? (sub { MergeFont(%{ $options{font} }); }) : ()),
1396 $options{beforeDigest}),
1397 afterDigest => flatten($options{afterDigest},
1398 ($mode ? (sub { $_[0]->endMode($mode) })
1399 : ($bounded ? (sub { $_[0]->egroup; }) : ()))),
1400 beforeConstruct => flatten($options{beforeConstruct}),
1401 afterConstruct => flatten($options{afterConstruct}),
1402 nargs => $options{nargs},
1403 alias => (defined $options{alias} ? $options{alias}
1404 : ($options{robust} ? $cs : undef)),
1405 reversion => $options{reversion},
1406 sizer => inferSizer($options{sizer}, $options{reversion}),
1407 captureBody => $options{captureBody},
1408 properties => $options{properties} || {},
1409 outer => $options{outer},
1410 long => $options{long}),
1411 $options{scope});
1412 AssignValue(ToString($cs) . ":locked" => 1) if $options{locked};
1413 return; }
1414  
1415 #======================================================================
1416 # Support for XMDual
1417  
1418 # Perhaps it would be better to use a label(-like) indirection here,
1419 # so all ID's can stay in the desired format?
1420 sub getXMArgID {
1421 StepCounter('@XMARG');
1422 DefMacroI(T_CS('\@@XMARG@ID'), undef, Tokens(Explode(LookupRegister('\c@@XMARG')->valueOf)),
1423 scope => 'global');
1424 return Expand(T_CS('\the@XMARG@ID')); }
1425  
1426 # Given a list of Tokens (to be expanded into mathematical objects)
1427 # return two lists:
1428 # (1) The Tokens' wrapped in an XMAarg, with an ID added
1429 # (2) a corresponding list of Tokens creating XMRef's to those IDs
1430 # Ah, but there are complications!!!
1431 # On the one hand, arguments may be hidden, never appearing on the presentation side
1432 # (all will be passed to the content side); This argues for putting the XMArg's on the content side.
1433 # OTOH, they ought to be on the presentation side, so that they can be expanded & digested in
1434 # the proper context they will be presented, and pick up all the styling (font size, displaystyle..)
1435 # I don't know how to work around the latter, so we'll put args on the presentation side,
1436 # UNLESS they are hidden, in which case they'll be on the content side.
1437 # So, how do we know if they're hidden? We'll scan the presentation for #\d, that's how!
1438 sub dualize_arglist {
1439 my ($presentation, @args) = @_;
1440 my %used = ();
1441 $presentation = ToString($presentation);
1442 $presentation =~ s/#(\d)/{ $used{$1}++; }/ge; # Get the args that were actually used!
1443 my (@cargs, @pargs);
1444 my $i = 0;
1445 foreach my $arg (@args) {
1446 $i++;
1447 if (!(defined $arg) || IsEmpty($arg)) { # undefined or empty args, just pass through
1448 push(@pargs, $arg);
1449 push(@cargs, $arg); }
1450 elsif ($used{$i}) { # used in presentation?
1451 my $id = getXMArgID();
1452 push(@pargs, Invocation(T_CS('\lx@xmarg'), $id, $arg)); # put XMArg in presentation
1453 push(@cargs, Invocation(T_CS('\lx@xmref'), $id)); }
1454 else { # Hidden arg, put XMArg in content.
1455 my $id = getXMArgID();
1456 push(@cargs, Invocation(T_CS('\lx@xmarg'), $id, $arg));
1457 push(@pargs, Invocation(T_CS('\lx@xmref'), $id)); } }
1458 return ([@cargs], [@pargs]); }
1459  
1460 # Given a list of XML nodes (either libxml nodes, or array representations)
1461 # return a list of XMRef's referring to those nodes;
1462 # ensure each source node has an ID (if already instanciated as XML)
1463 # or _xmkey if still in array rep. since it will get an ID later, and the connection re-made)
1464 # Note that ltx:XMHint nodes are ephemeral and shouldn't be ref'd!
1465 # likewise, we avoid creating XMRefs to XMRefs
1466 sub createXMRefs {
1467 my ($document, @args) = @_;
1468 my @refs = ();
1469 foreach my $arg (@args) {
1470 my $isarray = (ref $arg eq 'ARRAY');
1471 my $qname = ($isarray ? $$arg[0] : $document->getNodeQName($arg));
1472 my $box = ($isarray ? $$arg[1]{_box} : $document->getNodeBox($arg));
1473 # XMHint's are ephemeral, they may disappear; so just clone it w/o id
1474 if ($qname eq 'ltx:XMHint') {
1475 my %attr = ($isarray ? %{ $$arg[1] }
1476 : (map { $document->getNodeQName($_) => $_->getValue } $arg->attributes));
1477 delete $attr{'xml:id'};
1478 push(@refs, [$qname, {%attr}]); }
1479 # Likewise, clone an XMRef (w/o any attributes or id ?) rather than create an XMRef to an XMRef.
1480 elsif ($qname eq 'ltx:XMRef') {
1481 my $key = ($isarray ? $$arg[1]{_xmkey} : $arg->getAttribute('_xmkey'));
1482 my $id = ($isarray ? $$arg[1]{idref} : $arg->getAttribute('idref'));
1483 push(@refs, [$qname, { _xmkey => $key, idref => $id, _box => $box }]); }
1484 else {
1485 if (my $id = ($isarray ? $$arg[1]{'xml:id'} : $arg->getAttribute('xml:id'))) {
1486 # $arg already has id, so refer to it.
1487 push(@refs, ['ltx:XMRef', { 'idref' => $id, _box => $box }]); }
1488 elsif ($isarray) {
1489 # $arg is not yet instanciated, so hasn't had chance to get auto-id; use _xmkey
1490 my $key = ToString(getXMArgID());
1491 $$arg[1]{'_xmkey'} = $key;
1492 push(@refs, ['ltx:XMRef', { '_xmkey' => $key, _box => $box }]); }
1493 else {
1494 # If arg is already XML, it's too late to get automatic ID's
1495 GenerateID($document, $arg, undef, '');
1496 push(@refs, ['ltx:XMRef', { 'idref' => $arg->getAttribute('xml:id'), _box => $box }]); } } }
1497 return @refs; }
1498  
1499 # DefMath Define a Mathematical symbol or function.
1500 # There are two sets of cases:
1501 # (1) If the presentation appears to be TeX code, we create an XMDual,
1502 # since the presentation may end up with structure, etc.
1503 # (2) But if the presentation is a simple string, or unicode,
1504 # it is just the content of the symbol; even if the function takes arguments.
1505 # ALSO
1506 # arrange that the operator token gets cs="$cs"
1507 # ALSO
1508 # Possibly some trick with SUMOP/INTOP affecting limits ?
1509 # Well, not exactly, but....
1510 # HMM.... Still fishy.
1511 # When to make a dual ?
1512 # If the $presentation seems to be TeX (ie. it involves #1... but not ONLY!)
1513 my $math_options = { # [CONSTANT]
1514 name => 1, meaning => 1, omcd => 1, reversion => 1, sizer => 1, alias => 1,
1515 role => 1, operator_role => 1, reorder => 1, dual => 1, decl_id => 1,
1516 mathstyle => 1, font => 1,
1517 scriptpos => 1, operator_scriptpos => 1,
1518 stretchy => 1, operator_stretchy => 1,
1519 lpadding => 1, rpadding => 1,
1520 beforeDigest => 1, afterDigest => 1,
1521 scope => 1, nogroup => 1, locked => 1,
1522 protected => 1, robust => 1,
1523 revert_as => 1,
1524 hide_content_reversion => 1 }; # DEPRECATE!
1525 my $simpletoken_options = { # [CONSTANT]
1526 name => 1, meaning => 1, omcd => 1, role => 1, mathstyle => 1,
1527 protected => 1, robust => 1,
1528 lpadding => 1, rpadding => 1,
1529 font => 1, scriptpos => 1, scope => 1, locked => 1 };
1530  
1531 sub DefMath {
1532 my ($proto, $presentation, %options) = @_;
1533 CheckOptions("DefMath ($proto)", $math_options, %options);
1534 DefMathI(parsePrototype($proto), $presentation, %options);
1535 return; }
1536  
1537 DebuggableFeature('defmath', 'DefMath definitions');
1538  
1539 sub DefMathI {
1540 my ($cs, $paramlist, $presentation, %options) = @_;
1541 $cs = coerceCS($cs);
1542 $paramlist = parseParameters($paramlist, $cs) if defined $paramlist && !ref $paramlist;
1543 my $nargs = ($paramlist ? scalar($paramlist->getParameters) : 0);
1544 my $csname = $cs->getString;
1545 my $meaning = $options{meaning};
1546 my $name = $options{alias} || $csname;
1547 # Avoid undefs specifically, we'll be doing string comparisons
1548 $presentation = '' unless defined $presentation;
1549 $meaning = '' unless defined $meaning;
1550 $name =~ s/^\\//;
1551 $name = $options{name} if defined $options{name};
1552 $name = undef if (defined $name)
1553 && (($name eq $presentation) || ($name eq '')
1554 || ($meaning eq $name));
1555 $options{name} = $name;
1556 $options{role} = 'UNKNOWN'
1557 if ($nargs == 0) && !defined $options{role};
1558 $options{operator_role} = 'UNKNOWN'
1559 if ($nargs > 0) && !defined $options{operator_role};
1560 $options{revert_as} = 'context' if $options{hide_content_reversion};
1561 # Store some data for introspection
1562 defmath_introspective($cs, $paramlist, $presentation, %options);
1563  
1564 # If single character, handle with a rewrite rule
1565 if (length($csname) == 1) {
1566 Debug("Defining " . Stringify($cs) . " as rewrite") if $LaTeXML::DEBUG{defmath};
1567 if ($csname ne ToString($presentation)) {
1568 $options{replace} = $presentation;
1569 delete $options{name}; }
1570 defmath_rewrite($cs, %options); }
1571 # If the macro involves arguments,
1572 # we will create an XMDual to separate simple content application
1573 # from the (likely) convoluted presentation.
1574 elsif ((ref $presentation eq 'CODE')
1575 || ((ref $presentation) && grep { $$_[1] == CC_ARG || $_->equals(T_PARAM) } $presentation->unlist)
1576 || (!(ref $presentation) && ($presentation =~ /\#\d|\\./))) {
1577 Debug("Defining " . Stringify($cs) . " as dual") if $LaTeXML::DEBUG{defmath};
1578 defmath_dual($cs, $paramlist, $presentation, %options); }
1579 # If no arguments, but the presentation involves macros, presumably with internal structure,
1580 # we'll wrap the presentation in ordet to capture the various semantic attributes
1581 elsif ((ref $presentation) && (grep { $_->isExecutable } $presentation->unlist)) {
1582 Debug("Defining " . Stringify($cs) . " as wrapped") if $LaTeXML::DEBUG{defmath};
1583 defmath_wrapped($cs, $presentation, %options); }
1584  
1585 # EXPERIMENT: Introduce an intermediate case for simple symbols
1586 # Define a primitive that will create a Box with the appropriate set of XMTok attributes.
1587 elsif (($nargs == 0) && !grep { !$$simpletoken_options{$_} } keys %options) {
1588 Debug("Defining " . Stringify($cs) . " as primitive") if $LaTeXML::DEBUG{defmath};
1589 defmath_prim($cs, $paramlist, $presentation, %options); }
1590 else {
1591 Debug("Defining " . Stringify($cs) . " as constructor") if $LaTeXML::DEBUG{defmath};
1592 defmath_cons($cs, $paramlist, $presentation, %options); }
1593 AssignValue($csname . ":locked" => 1) if $options{locked};
1594 return; }
1595  
1596 sub defmath_introspective {
1597 my ($cs, $paramlist, $presentation, %options) = @_;
1598 # Store some data for introspection [should be optional?]
1599 my $nargs = ($paramlist ? scalar($paramlist->getParameters) : 0);
1600 AssignValue(join("##", "math_definition", $cs->getString, $nargs,
1601 $options{role} || $options{operator_role} || '', $options{name} || '',
1602 (defined $options{meaning} ? $options{meaning} : ''),
1603 $STATE->getStomach->getGullet->getMouth->getSource,
1604 (ref $presentation ? '' : $presentation)) => 1, global => 1);
1605 return; }
1606  
1607 sub defmath_rewrite {
1608 my ($cs, %options) = @_;
1609 my $csname = $cs->getString;
1610 #### $STATE->assignMathcode($csname=>0x8000, $options{scope}); }
1611 # No, do NOT make mathactive; screws up things like babel french, or... ?
1612 # EXPERIMENT: store XMTok attributes for if this char ends up a Math Token.
1613 # But only some DefMath options make sense!
1614 my $rw_options = { name => 1, meaning => 1, omcd => 1, decl_id => 1, role => 1,
1615 replace => 1, mathstyle => 1, stretchy => 1 }; # (well, mathstyle?)
1616 CheckOptions("DefMath reimplemented as DefRewrite ($csname)", $rw_options, %options);
1617 AssignValue('math_token_attributes_' . $csname => {%options}, 'global');
1618 return; }
1619  
1620 sub defmath_common_constructor_options {
1621 my ($cs, $presentation, %options) = @_;
1622 my $sizer = inferSizer($options{sizer}, $options{reversion});
1623 my $presentation_s = $presentation && ToString($presentation);
1624 return (
1625 alias => $options{alias} || $cs->getString,
1626 (defined $options{reversion} ? (reversion => $options{reversion}) : ()),
1627 (defined $sizer ? (sizer => $sizer) : ()),
1628 beforeDigest => flatten(sub { requireMath($cs->getString); },
1629 ($options{nogroup} ? () : (sub { $_[0]->bgroup; })),
1630 ($options{font} ? (sub { MergeFont(%{ $options{font} }); }) : ()),
1631 $options{beforeDigest}),
1632 afterDigest => flatten($options{afterDigest},
1633 ($options{nogroup} ? () : (sub { $_[0]->egroup; }))),
1634 beforeConstruct => flatten($options{beforeConstruct}),
1635 afterConstruct => flatten($options{afterConstruct}),
1636 properties => {
1637 name => $options{name},
1638 meaning => $options{meaning},
1639 omcd => $options{omcd},
1640 role => $options{role},
1641 decl_id => $options{decl_id},
1642 operator_role => $options{operator_role},
1643 mathstyle => $options{mathstyle},
1644 scriptpos => $options{scriptpos},
1645 operator_scriptpos => $options{operator_scriptpos},
1646 stretchy => $options{stretchy},
1647 operator_stretchy => $options{operator_stretchy},
1648 font => ($options{mathstyle}
1649 ? sub { LookupValue('font')->merge(mathstyle => $options{mathstyle})->specialize($presentation_s); }
1650 : sub { LookupValue('font')->specialize($presentation_s); }),
1651 lpadding => $options{lpadding},
1652 rpadding => $options{rpadding} },
1653 scope => $options{scope}); }
1654  
1655 # If the presentation is complex, and involves arguments,
1656 # we will create an XMDual to separate content & presentation.
1657 # This involves creating 3 control sequences:
1658 # \cs macro that expands into \lxdual{pres}{content}
1659 # \cs@content constructor creates the content branch
1660 # \cs@presentation macro that expands into code in the presentation branch.
1661 # OK, this is getting a bit out-of-hand; I can't, myself, predict whether XMDual gets involved!
1662 # The basic distinction seems to be whether the arguments are explicitly involved
1663 # in the presentation form;
1664 # This excludes (at least?) (OVER|UNDER)ACCENT's
1665 sub defmath_dual {
1666 my ($cs, $paramlist, $presentation, %options) = @_;
1667 my $csname = $cs->getString;
1668 my $cont_cs = T_CS($csname . "\@content");
1669 my $pres_cs = T_CS($csname . "\@presentation");
1670 my $defcs = ($options{robust} ? defRobustCS($cs, %options) : $cs);
1671 # Make the original CS expand into a DUAL invoking a presentation macro and content constructor
1672 $STATE->installDefinition(LaTeXML::Core::Definition::Expandable->new($defcs, $paramlist, sub {
1673 my ($self, @args) = @_;
1674 my ($cargs, $pargs) = dualize_arglist($presentation, @args);
1675 Invocation(T_CS('\lx@dual'),
1676 Tokens(
1677 ($options{role}
1678 ? (T_OTHER('role'), T_OTHER('='), T_OTHER($options{role})) : ()),
1679 ($options{role} && $options{revert_as} ? (T_OTHER(',')) : ()),
1680 ($options{revert_as}
1681 ? (T_OTHER('revert_as'), T_OTHER('='), T_OTHER($options{revert_as})) : ())),
1682 Invocation($cont_cs, @$cargs),
1683 Invocation($pres_cs, @$pargs))->unlist; },
1684 protected => $options{protected}),
1685 $options{scope});
1686 # Make the presentation macro.
1687 $presentation = TokenizeInternal($presentation) unless ref $presentation;
1688 $STATE->installDefinition(LaTeXML::Core::Definition::Expandable->new($pres_cs, $paramlist,
1689 $presentation,
1690 protected => $options{protected}),
1691 $options{scope});
1692 my $nargs = ($paramlist ? scalar($paramlist->getParameters) : 0);
1693 my $cons_attr = "name='#name' meaning='#meaning' omcd='#omcd' decl_id='#decl_id' mathstyle='#mathstyle' lpadding='#lpadding' rpadding='#rpadding'";
1694  
1695 $STATE->installDefinition(LaTeXML::Core::Definition::Constructor->new($cont_cs, $paramlist,
1696 ($nargs == 0
1697 ? "<ltx:XMTok $cons_attr role='#role' scriptpos='#scriptpos' stretchy='#stretchy'/>"
1698 : "<ltx:XMApp role='#role' scriptpos='#scriptpos'>"
1699 . "<ltx:XMTok $cons_attr role='#operator_role'"
1700 . " scriptpos='#operator_scriptpos' stretchy='#operator_stretchy'/>"
1701 . join('', map { "#$_" }
1702 ($options{reorder} ? @{ $options{reorder} } : (1 .. $nargs)))
1703 . "</ltx:XMApp>"),
1704 defmath_common_constructor_options($cs, $presentation, %options)), $options{scope});
1705 return; }
1706  
1707 # The case where there are NO arguments, but the presentation is (potentially) complex.
1708 sub defmath_wrapped {
1709 my ($cs, $presentation, %options) = @_;
1710 my $csname = $cs->getString;
1711 my $wrap_cs = T_CS($csname . "\@wrapper");
1712 my $pres_cs = T_CS($csname . "\@presentation");
1713 my $defcs = ($options{robust} ? defRobustCS($cs, %options) : $cs);
1714 # Make the original CS expand into a wrapper constructor invoking a presentation
1715 $STATE->installDefinition(LaTeXML::Core::Definition::Expandable->new($defcs, undef,
1716 Tokens($wrap_cs, T_BEGIN, $pres_cs, T_END),
1717 protected => $options{protected}),
1718 $options{scope});
1719 # Make the presentation macro.
1720 $presentation = TokenizeInternal($presentation) unless ref $presentation;
1721 $STATE->installDefinition(LaTeXML::Core::Definition::Expandable->new($pres_cs, undef,
1722 $presentation,
1723 protected => $options{protected}),
1724 $options{scope});
1725 # Make the wrapper constructor
1726 my $cons_attr = "name='#name' meaning='#meaning' omcd='#omcd' decl_id='#decl_id' mathstyle='#mathstyle' lpadding='#lpadding' rpadding='#rpadding'";
1727 $STATE->installDefinition(LaTeXML::Core::Definition::Constructor->new($wrap_cs,
1728 parseParameters('{}', $csname),
1729 "<ltx:XMWrap $cons_attr role='#role' scriptpos='#scriptpos' stretchy='#stretchy'>"
1730 . "#1"
1731 . "</ltx:XMWrap>",
1732 defmath_common_constructor_options($cs, $presentation, %options),
1733 reversion => sub { (($LaTeXML::DUAL_BRANCH || '') eq 'content' ? $cs : Revert($_[1])); }),
1734 $options{scope});
1735 return; }
1736  
1737 sub defmath_prim {
1738 my ($cs, $paramlist, $presentation, %options) = @_;
1739 my $string = ToString($presentation);
1740 my $reqfont = $options{font} || {};
1741 delete $options{locked};
1742 delete $options{font};
1743 $STATE->installDefinition(LaTeXML::Core::Definition::Primitive->new($cs, undef, sub {
1744 my ($stomach) = @_;
1745 my $locator = $stomach->getGullet->getLocator;
1746 my %properties = %options;
1747 my $font = LookupValue('font')->merge(%$reqfont)->specialize($string);
1748 my $mode = (LookupValue('IN_MATH') ? 'math' : 'text');
1749 foreach my $key (keys %properties) {
1750 my $value = $properties{$key};
1751 if (ref $value eq 'CODE') {
1752 $properties{$key} = &$value(); } }
1753 LaTeXML::Core::Box->new($string, $font, $locator,
1754 ((!defined $options{reversion}) && (($options{revert_as} || '') eq 'presentation')
1755 ? $presentation : $cs),
1756 mode => $mode, %properties); }));
1757 return; }
1758  
1759 sub defmath_cons {
1760 my ($cs, $paramlist, $presentation, %options) = @_;
1761 # do we need to do anything about digesting the presentation?
1762 my $qpresentation = $presentation && ToString($presentation); # Quote any constructor specials
1763 $qpresentation =~ s/(\#|\&|\?|\\|<|>)/\\$1/g if $presentation;
1764 my $end_tok = (defined $presentation ? '>' . $qpresentation . '</ltx:XMTok>' : "/>");
1765 my $cons_attr = "name='#name' meaning='#meaning' omcd='#omcd' decl_id='#decl_id' mathstyle='#mathstyle' lpadding='#lpadding' rpadding='#rpadding'";
1766 my $nargs = ($paramlist ? scalar($paramlist->getParameters) : 0);
1767 my $defcs = ($options{robust} ? defRobustCS($cs, %options) : $cs);
1768 if ((!defined $options{reversion}) && !$nargs && !(defined $options{alias})) {
1769 $options{reversion} = sub {
1770 (!$options{revert_as}
1771 || ($options{revert_as} eq 'content')
1772 || (($options{revert_as} eq 'context') && (($LaTeXML::DUAL_BRANCH || 'content') eq 'content'))
1773 ? $cs : $presentation->unlist); }; }
1774 $STATE->installDefinition(LaTeXML::Core::Definition::Constructor->new($defcs, $paramlist,
1775 ($nargs == 0
1776 # If trivial presentation, allow it in Text
1777 ? ($presentation !~ /(?:\(|\)|\\)/
1778 ? "?#isMath(<ltx:XMTok role='#role' scriptpos='#scriptpos' stretchy='#stretchy'"
1779 . " font='#font' $cons_attr$end_tok)"
1780 . "($qpresentation)"
1781 : "<ltx:XMTok role='#role' scriptpos='#scriptpos' stretchy='#stretchy'"
1782 . " font='#font' $cons_attr$end_tok")
1783 : "<ltx:XMApp role='#role' scriptpos='#scriptpos' stretchy='#stretchy'>"
1784 . "<ltx:XMTok $cons_attr font='#font' role='#operator_role'"
1785 . " scriptpos='#operator_scriptpos' stretchy='#operator_stretchy' $end_tok"
1786 . join('', map { "<ltx:XMArg>#$_</ltx:XMArg>" } 1 .. $nargs)
1787 . "</ltx:XMApp>"),
1788 defmath_common_constructor_options($cs, $presentation,
1789 sizer => sub {
1790 # my $font = $_[1]->getFont || LaTeXML::Common::Font->mathDefault;
1791 my $font = LaTeXML::Common::Font->mathDefault;
1792 $font->computeStringSize($presentation); },
1793 %options)), $options{scope});
1794 return; }
1795  
1796 #======================================================================
1797 # Define a LaTeX environment
1798 # Note that the body of the environment is treated is the 'body' parameter in the constructor.
1799 my $environment_options = { # [CONSTANT]
1800 mode => 1, requireMath => 1, forbidMath => 1,
1801 properties => 1, nargs => 1, font => 1,
1802 beforeDigest => 1, afterDigest => 1,
1803 afterDigestBegin => 1, beforeDigestEnd => 1, afterDigestBody => 1,
1804 beforeConstruct => 1, afterConstruct => 1,
1805 reversion => 1, sizer => 1, scope => 1, locked => 1 };
1806  
1807 sub DefEnvironment {
1808 my ($proto, $replacement, %options) = @_;
1809 CheckOptions("DefEnvironment ($proto)", $environment_options, %options);
1810 my ($name, $paramlist) = Text::Balanced::extract_bracketed($proto, '{}');
1811 $name =~ s/[\{\}]//g;
1812 $paramlist =~ s/^\s*//;
1813 DefEnvironmentI($name, $paramlist, $replacement, %options);
1814 return; }
1815  
1816 sub DefEnvironmentI {
1817 my ($name, $paramlist, $replacement, %options) = @_;
1818 my $mode = $options{mode};
1819 $name = ToString($name) if ref $name;
1820 $paramlist = parseParameters($paramlist, $name) if defined $paramlist && !ref $paramlist;
1821 # Magic form: CS with name \begin{env} bypasses some LaTeX
1822 # However, in pure LaTeX would usually have expanded to \env
1823 # and would have skipped spaces before parsing args, if any.
1824 my $paramlist_skips;
1825 if ($paramlist && $paramlist->getNumArgs) {
1826 $paramlist_skips = LaTeXML::Core::Parameters->new(
1827 LaTeXML::Core::Parameter->new('SkipSpaces', 'SkipSpaces'),
1828 $paramlist->getParameters); }
1829 # This is for the common case where the environment is opened by \begin{env}
1830 my $sizer = inferSizer($options{sizer}, $options{reversion});
1831 $STATE->installDefinition(LaTeXML::Core::Definition::Constructor
1832 ->new(T_CS("\\begin{$name}"), $paramlist_skips, $replacement,
1833 beforeDigest => flatten(($options{requireMath} ? (sub { requireMath($name); }) : ()),
1834 ($options{forbidMath} ? (sub { forbidMath($name); }) : ()),
1835 sub { $_[0]->bgroup; },
1836 sub { my $b = LookupValue('@environment@' . $name . '@atbegin');
1837 ($b ? Digest(@$b) : ()); },
1838 ($mode ? (sub { $_[0]->setMode($mode); }) : ()),
1839 sub { AssignValue(current_environment => $name);
1840 DefMacroI('\@currenvir', undef, $name); },
1841 ($options{font} ? (sub { MergeFont(%{ $options{font} }); }) : ()),
1842 $options{beforeDigest}),
1843 afterDigest => flatten($options{afterDigestBegin}),
1844 afterDigestBody => flatten($options{afterDigestBody}),
1845 beforeConstruct => flatten(sub { $STATE->pushFrame; }, $options{beforeConstruct}),
1846 # Curiously, it's the \begin whose afterConstruct gets called.
1847 afterConstruct => flatten($options{afterConstruct}, sub { $STATE->popFrame; }),
1848 nargs => $options{nargs},
1849 captureBody => 1,
1850 properties => $options{properties} || {},
1851 (defined $options{reversion} ? (reversion => $options{reversion}) : ()),
1852 (defined $sizer ? (sizer => $sizer) : ()),
1853 ), $options{scope});
1854 $STATE->installDefinition(LaTeXML::Core::Definition::Constructor
1855 ->new(T_CS("\\end{$name}"), "", "",
1856 beforeDigest => flatten($options{beforeDigestEnd},
1857 sub { my $e = LookupValue('@environment@' . $name . '@atend');
1858 ($e ? Digest(@$e) : ()); },
1859 ),
1860 afterDigest => flatten($options{afterDigest},
1861 sub { my $env = LookupValue('current_environment');
1862 if (!$env || ($name ne $env)) {
1863 my @lines = ();
1864 my $nf = $STATE->getFrameDepth;
1865 for (my $f = 0 ; $f <= $nf ; $f++) { # Get currently open environments & locators
1866 if (my $e = $STATE->isValueBound('current_environment', $f)
1867 && $STATE->valueInFrame('current_environment', $f)) {
1868 my $locator = ToString($STATE->valueInFrame('groupInitiatorLocator', $f));
1869 push(@lines, $e . ' ' . $locator); } }
1870 Error('unexpected', "\\end{$name}", $_[0],
1871 "Can't close environment $name;", "Current are:", @lines); }
1872 return; },
1873 sub { $_[0]->egroup; },
1874 ),
1875 ), $options{scope});
1876 # For the uncommon case opened by \csname env\endcsname
1877 $STATE->installDefinition(LaTeXML::Core::Definition::Constructor
1878 ->new(T_CS("\\$name"), $paramlist, $replacement,
1879 beforeDigest => flatten(($options{requireMath} ? (sub { requireMath($name); }) : ()),
1880 ($options{forbidMath} ? (sub { forbidMath($name); }) : ()),
1881 ($mode ? (sub { $_[0]->beginMode($mode); }) : ()),
1882 ($options{font} ? (sub { MergeFont(%{ $options{font} }); }) : ()),
1883 $options{beforeDigest}),
1884 afterDigest => flatten($options{afterDigestBegin}),
1885 afterDigestBody => flatten($options{afterDigestBody}),
1886 beforeConstruct => flatten(sub { $STATE->pushFrame; }, $options{beforeConstruct}),
1887 # Curiously, it's the \begin whose afterConstruct gets called.
1888 afterConstruct => flatten($options{afterConstruct}, sub { $STATE->popFrame; }),
1889 nargs => $options{nargs},
1890 captureBody => T_CS("\\end$name"), # Required to capture!!
1891 properties => $options{properties} || {},
1892 (defined $options{reversion} ? (reversion => $options{reversion}) : ()),
1893 (defined $sizer ? (sizer => $sizer) : ()),
1894 ), $options{scope});
1895 $STATE->installDefinition(LaTeXML::Core::Definition::Constructor
1896 ->new(T_CS("\\end$name"), "", "",
1897 beforeDigest => flatten($options{beforeDigestEnd}),
1898 afterDigest => flatten($options{afterDigest},
1899 ($mode ? (sub { $_[0]->endMode($mode); }) : ())),
1900 ), $options{scope});
1901 if ($options{locked}) {
1902 AssignValue("\\begin{$name}:locked" => 1);
1903 AssignValue("\\end{$name}:locked" => 1);
1904 AssignValue("\\$name:locked" => 1);
1905 AssignValue("\\end$name:locked" => 1); }
1906 return; }
1907  
1908 #======================================================================
1909 # Declaring and Adjusting the Document Model.
1910 #======================================================================
1911  
1912 # Specify the properties of a Node tag.
1913 my $tag_options = { # [CONSTANT]
1914 autoOpen => 1, autoClose => 1, afterOpen => 1, afterClose => 1,
1915 'afterOpen:early' => 1, 'afterClose:early' => 1,
1916 'afterOpen:late' => 1, 'afterClose:late' => 1 };
1917 my $tag_prepend_options = { # [CONSTANT]
1918 'afterOpen:early' => 1, 'afterClose:early' => 1 };
1919 my $tag_append_options = { # [CONSTANT]
1920 'afterOpen' => 1, 'afterClose' => 1,
1921 'afterOpen:late' => 1, 'afterClose:late' => 1 };
1922  
1923 sub Tag {
1924 my ($tag, %properties) = @_;
1925 CheckOptions("Tag ($tag)", $tag_options, %properties);
1926 my $model = $STATE->getModel;
1927 AssignMapping('TAG_PROPERTIES', $tag => {}) unless LookupMapping('TAG_PROPERTIES', $tag);
1928 my $props = LookupMapping('TAG_PROPERTIES', $tag);
1929 foreach my $key (keys %properties) {
1930 my $new = $properties{$key};
1931 my $old = $$props{$key};
1932 # These keys accumulate information which should not carry over daemon frames.
1933 if ($$tag_prepend_options{$key}) {
1934 $new = flatten($new, $old); }
1935 elsif ($$tag_append_options{$key}) {
1936 $new = flatten($old, $new); }
1937 $$props{$key} = $new; }
1938 return; }
1939  
1940 sub DocType {
1941 my ($rootelement, $pubid, $sysid, %namespaces) = @_;
1942 my $model = $STATE->getModel;
1943 $model->setDocType($rootelement, $pubid, $sysid);
1944 foreach my $prefix (keys %namespaces) {
1945 $model->registerDocumentNamespace($prefix => $namespaces{$prefix}); }
1946 return; }
1947  
1948 # What verb here? Set, Choose,...
1949 sub RelaxNGSchema {
1950 my ($schema, %namespaces) = @_;
1951 my $model = $STATE->getModel;
1952 $model->setRelaxNGSchema($schema,);
1953 foreach my $prefix (keys %namespaces) {
1954 $model->registerDocumentNamespace($prefix => $namespaces{$prefix}); }
1955 return; }
1956  
1957 sub RegisterNamespace {
1958 my ($prefix, $namespace) = @_;
1959 $STATE->getModel->registerNamespace($prefix => $namespace);
1960 return; }
1961  
1962 sub RegisterDocumentNamespace {
1963 my ($prefix, $namespace) = @_;
1964 $STATE->getModel->registerDocumentNamespace($prefix => $namespace);
1965 return; }
1966  
1967 #======================================================================
1968 # Package, Class and File Loading
1969 #======================================================================
1970  
1971 # Does this test even make sense (or can it?)
1972 # Shouldn't this more likely be dependent on the context?
1973 # Ah, but what about \InputFileIfExists type stuff...
1974 # should we assume a raw type can be processed if being read from within a raw type????
1975 # yeah, that sounds about right...
1976 my %definition_name = ( # [CONSTANT]
1977 sty => 'package', cls => 'class', clo => 'class options',
1978 'cnf' => 'configuration', 'cfg' => 'configuration',
1979 'ldf' => 'language definitions', 'def' => 'definitions', 'dfu' => 'definitions');
1980  
1981 my $findfile_options = { # [CONSTANT]
1982 type => 1, notex => 1, noltxml => 1, searchpaths_only => 1 };
1983  
1984 sub FindFile {
1985 my ($file, %options) = @_;
1986 $file = ToString($file);
1987 if ($options{raw}) {
1988 delete $options{raw};
1989 Warn('deprecated', 'raw', $STATE->getStomach->getGullet,
1990 "FindFile option raw is deprecated; it is not needed"); }
1991 CheckOptions("FindFile ($file)", $findfile_options, %options);
1992 if (pathname_is_literaldata($file)) { # If literal protocol return immediately (unless notex!)
1993 return ($options{notex} ? undef : $file); }
1994 # If a known special protocol return immediately
1995 elsif (pathname_is_literaldata($file) || pathname_is_url($file)) {
1996 return $file; }
1997 # Otherwise, it's some kind of "real" file, and we might have to search for it
1998 if ($options{type}) { # Specific type requested? Search for it.
1999 # Add the extension, if it isn't already there.
2000 $file = $file . "." . $options{type} unless $file =~ /\.\Q$options{type}\E$/;
2001 return FindFile_aux($file, %options); }
2002 # If no type given, we MAY expect .tex, or maybe NOT!!
2003 elsif ($file =~ /\.tex$/) { # No requested type, then .tex; Of course, it may already have it!
2004 return FindFile_aux($file, %options); }
2005 else {
2006 return FindFile_aux("$file.tex", %options) || FindFile_aux($file, %options); } }
2007  
2008 sub FindFile_aux {
2009 my ($file, %options) = @_;
2010 my $path;
2011 # If cached, return simple path (it's a key into the cache)
2012 if (defined LookupValue($file . '_contents')) {
2013 return $file; }
2014 if (pathname_is_absolute($file)) { # And if we've got an absolute path,
2015 if (!$options{noltxml}) {
2016 return $file . '.ltxml' if -f ($file . '.ltxml'); } # No need to search, just check if it exists.
2017 return $file if -f $file; # No need to search, just check if it exists.
2018 return; } # otherwise we're never going to find it.
2019  
2020 # Note that the strategy is complicated by the fact that
2021 # (1) we prefer .ltxml bindings, if present
2022 # (2) those MAY be present in kpsewhich's DB (although our searchpaths take precedence!)
2023 # (3) BUT we want to avoid kpsewhich if we can, since it's slower
2024 # (4) depending on switches we may EXCLUDE .ltxml OR raw tex OR allow both.
2025 # (5) we may allow interpreting raw TeX/sty/whatever files individually or broadly
2026 # (6) but we may also want to override an apparently "versioned" file, preferring the ltxml
2027 my $paths = LookupValue('SEARCHPATHS') // [];
2028 my $urlbase = LookupValue('URLBASE');
2029 my $nopaths = LookupValue('REMOTE_REQUEST');
2030 my $ltxml_paths = $nopaths ? [] : $paths;
2031 my $interpreting = LookupValue('INTERPRETING_DEFINITIONS'); # Globally allow interpretation
2032 my $interpretable = LookupMapping('INTERPRETABLE_SOURCES', $file); # Specifically allow
2033  
2034 # If we're looking for ltxml, look within our paths & installation first (faster than kpse)
2035 if (!$options{noltxml}
2036 && ($path = pathname_find("$file.ltxml", paths => $ltxml_paths, installation_subdir => 'Package'))) {
2037 return $path; }
2038 # Else if we're interpreting rawtex, and can find the file as is, take it.
2039 elsif (!$options{notex} && ($interpreting || $interpretable)
2040 && ($path = pathname_find($file, paths => $paths))) {
2041 return $path; }
2042 # Else, look for similar fallback ltxml bindings
2043 elsif (!$options{noltxml} && !$interpretable
2044 && ($path = FindFile_fallback($file, $ltxml_paths, %options))) {
2045 return $path; }
2046 # Finally, look for raw tex in our paths, even if we're not interpreting(?) (faster than kpse)
2047 elsif (!$options{notex} && !$interpreting
2048 && ($path = pathname_find($file, paths => $paths))) {
2049 return $path; }
2050  
2051 # Otherwise, pass on to kpsewhich
2052 # Depending on flags, maybe search for ltxml in texmf or for plain tex in ours!
2053 # The main point, though, is to we make only ONE (more) call.
2054 # Do we need to sanitize these environment variables?
2055 my @candidates = (((!$options{noltxml} && !$nopaths) ? ("$file.ltxml") : ()),
2056 (!$options{notex} ? ($file) : ()));
2057 local $ENV{TEXINPUTS} = join($Config::Config{'path_sep'},
2058 @$paths, $ENV{TEXINPUTS} || $Config::Config{'path_sep'});
2059 if (my $result = (!$options{searchpaths_only}) && pathname_kpsewhich(@candidates)) {
2060 return (-f $result ? $result : undef); }
2061 if ($urlbase && ($path = url_find($file, urlbase => $urlbase))) {
2062 return $path; }
2063 return; }
2064  
2065 # A fallback mechanism aiming to load the applicable pieces of arXiv's long-tail
2066 # suffixes preceded by a separator
2067 our @find_fallback_suffixes = (
2068 # arxiv-specific suffixes
2069 'arx', 'arxiv', 'conference', 'workshop',
2070 'tmp', 'alternate', 'preprint', 'fixed',
2071 # arbitrary 1,2-letter trailing markers
2072 # tragically this is too general:
2073 # -- tikz-cd.sty is a real package
2074 # '\w\w?',
2075 #
2076 # version-oriented suffixes
2077 '[vV]?[-_.\d]+',
2078 # mixed
2079 'old', 'new', 'final', 'clean',
2080 'mine', 'priv', 'rev', 'mod',
2081 'modified', 'edited', 'custom',
2082 'altered', 'rtx'
2083 );
2084 # suffixes without a separator
2085 our @find_fallback_glued_suffixes = (
2086 # version-oriented suffixes
2087 '[vV]?[-_.\d]+',
2088 # long domain-specific words
2089 # that DO NOT conflict with names of packages
2090 # e.g. we have no binding matching '*arxiv*'
2091 'arxiv'
2092 );
2093 our @find_fallback_prefixes = (
2094 # see e.g. astro-ph/0002461 for rw_
2095 'rw', 'my', 'preprint',
2096 );
2097  
2098 sub FindFile_fallback {
2099 my ($file, $ltxml_paths, %options) = @_;
2100 my $fallback_file = $file;
2101 my $type = $options{type};
2102 if ($fallback_file =~ s/\.(sty|cls)$//) {
2103 # if we provide the type, that remains primary.
2104 $type = $1 unless $type; }
2105 if ($type) { # if we know what we're dealing with...
2106 my $prefixes_str = '^((?:' . join("|", @find_fallback_prefixes) . ')[-_.]?)';
2107 my $prefixes_rx = qr/$prefixes_str/i;
2108 # Note that we also remove numbers glued directly onto the name without a separator.
2109 my $suffixes_str = '([._-](?:' . join("|", @find_fallback_suffixes) . '))$';
2110 my $suffixes_rx = qr/$suffixes_str/i;
2111 my $glued_suffixes_str = '(' . join("|", @find_fallback_glued_suffixes) . ')$';
2112 my $glued_suffixes_rx = qr/$glued_suffixes_str/i;
2113 my ($discard_pre, $discard_post) = ('', '');
2114 # First look at delimited suffixes, then glued ones, and finally prefixes
2115 while ($fallback_file) {
2116 if ($fallback_file =~ s/$suffixes_rx//) {
2117 $discard_post = "$1$discard_post";
2118 next; }
2119 if ($fallback_file =~ s/$glued_suffixes_rx//) {
2120 $discard_post = "$1$discard_post";
2121 next; }
2122 if ($fallback_file =~ s/$prefixes_rx//) {
2123 $discard_pre .= $1;
2124 next; }
2125 last; }
2126 $discard_pre .= '...' if $discard_pre && $discard_post;
2127 my $discard = $discard_pre . $discard_post;
2128 if ($discard) { # we had something to discard, so a new query is needed
2129 my $fallback_query = "$fallback_file.$type";
2130 if (my $path =
2131 pathname_find("$fallback_query.ltxml", paths => $ltxml_paths, installation_subdir => 'Package')) {
2132 Info('fallback', $file, $STATE->getStomach->getGullet,
2133 "Interpreted $discard as a versioned package/class name, falling back to generic $fallback_query\n");
2134 return $path; } } }
2135 else {
2136 return; } }
2137  
2138 sub maybeReportSearchPaths {
2139 if (LookupValue('SEARCHPATHS_REPORTED')) {
2140 return (); }
2141 else {
2142 AssignValue('SEARCHPATHS_REPORTED' => 1, 'global');
2143 return ("search paths are " . join(', ', @{ LookupValue('SEARCHPATHS') })); } }
2144  
2145 my $inputcontent_options = { # [CONSTANT]
2146 noerror => 1, type => 1 };
2147  
2148 sub InputContent {
2149 my ($request, %options) = @_;
2150 CheckOptions("InputContent ($request)", $inputcontent_options, %options);
2151 if (my $path = FindFile($request, type => $options{type}, noltxml => 1)) {
2152 loadTeXContent($path); }
2153 elsif (!$options{noerror}) {
2154 # Consider it an error if we can't find a file of Content (in contrast to Definitions)
2155 Error('missing_file', $request, $STATE->getStomach->getGullet,
2156 "Can't find TeX file $request",
2157 maybeReportSearchPaths()); }
2158 return; }
2159  
2160 # This is essentially the \input equivalent;
2161 # we are most likely expecting to get actual content,
2162 # (possibly with definitions included, as well)
2163 # but might actually be getting pure definitions,
2164 # (like a proper style file)
2165 # in which case we may really want to load a latexml binding.
2166 # Note that generic style files (non-latex) often have a .tex extension.
2167 # But we may have implemented a .sty.ltxml, so we override the .tex.
2168 # Is this actually safe, or should we be explicilty providing .tex.ltxml ?
2169  
2170 my $input_options = { reloadable => 1 }; # [CONSTANT]
2171  
2172 sub Input {
2173 my ($request, %options) = @_;
2174 $request = ToString($request);
2175 $request =~ s/^("+)(.+)\g1$/$2/; # unwrap if in quotes \input{"file name"}
2176 CheckOptions("Input ($request)", $input_options, %options);
2177 # HEURISTIC! First check if equivalent style file, but only under very specific circumstances
2178 if (pathname_is_literaldata($request)) {
2179 my ($dir, $name, $type) = pathname_split($request);
2180 my $file = $name; $file .= '.' . $type if $type;
2181 my $path;
2182 # Firstly, check if we are going to OVERRIDE the requested raw .tex file
2183 # with a latexml binding to a style file.
2184 if ((!$dir) && (!$type || ($type eq 'tex')) # No SPECIFIC directory, but a raw tex file.
2185 # AND, in preamble; SHOULD be style file, OR also if we can't find the raw file.
2186 && (LookupValue('inPreamble') || !FindFile($file))
2187 && ($path = FindFile($name, type => 'sty', notex => 1))) { # AND there IS such a style file
2188 Info('ignore', $request, $STATE->getStomach->getGullet,
2189 "Ignoring input of tex $request, using package $name instead");
2190 RequirePackage($name); # Then override, assuming we'll find $name as a package file!
2191 return; } }
2192 # Next special case: If we were currently reading a "known" style or binding file,
2193 # then this file, even if .tex, must also be definitions rather than content.!!(?)
2194 if (LookupValue('INTERPRETING_DEFINITIONS')) {
2195 InputDefinitions($request, %options); }
2196 elsif (my $path = FindFile($request)) { # Found something plausible..
2197 my ($ignoredir, $type);
2198 if (pathname_is_literaldata($path)) {
2199 $type = 'tex'; }
2200 else {
2201 ($ignoredir, $request, $type) = pathname_split($path); }
2202 # Should we be doing anything about options in the next 2 cases?..... I kinda think not, but?
2203 if ($type eq 'ltxml') { # it's a LaTeXML binding.
2204 loadLTXML($request, $path, reloadable => $options{reloadable}); }
2205 # Else some sort of "known" definitions type file, but not simply 'tex'
2206 elsif (($type ne 'tex') && (pathname_is_raw($path))) {
2207 loadTeXDefinitions($request, $path, fordefinitions => 1, notes => 1, reloadable => $options{reloadable}); }
2208 else {
2209 loadTeXContent($path); } }
2210 else { # Couldn't find anything?
2211 $STATE->noteStatus(missing => $request);
2212 # We presumably are trying to input Content; an error if we can't find it (contrast to Definitions)
2213 Error('missing_file', $request, $STATE->getStomach->getGullet,
2214 "Can't find TeX file $request",
2215 maybeReportSearchPaths()); }
2216 return; }
2217  
2218 # Pass in the "requested path" to the next two, since that's what gets
2219 # recorded as having been loaded (by \@ifpackageloade, eg).
2220 sub loadLTXML {
2221 my ($request, $pathname, %options) = @_;
2222 # Note: $type will typically be ltxml and $name will include the .sty, .cls or whatever.
2223 # Note: we're NOT expecting (allowing?) either literal nor remote data objects here.
2224 if (my $p = pathname_is_literaldata($pathname) || pathname_is_url($pathname)) {
2225 Error('misdefined', 'loadLTXML', $STATE->getStomach->getGullet,
2226 "You can't load LaTeXML binding using protocol $p");
2227 return; }
2228 $pathname = pathname_absolute($pathname);
2229 my ($dir, $name, $type) = pathname_split($pathname);
2230 my $ltxname = $name . '.ltxml';
2231 # Don't load if the requested path was loaded (with or without the .ltxml)
2232 # We want to check against the original request, but WITH the type
2233 $request .= '.' . $type unless $request =~ /\Q.$type\E$/; # make sure the .ltxml is added here
2234 my $trequest = $request; $trequest =~ s/\.ltxml$//; # and NOT added here!
2235 return if !$options{reloadable}
2236 && (LookupValue($request . '_loaded') || LookupValue($trequest . '_loaded')
2237 || LookupValue($name . '_loaded') || LookupValue($ltxname . '_loaded'));
2238 # Note (only!) that the ltxml version of this was loaded; still could load raw tex!
2239 AssignValue($request . '_loaded' => 1, 'global');
2240 AssignValue($ltxname . '_loaded' => 1, 'global') if $ltxname ne $request;
2241 ClearAutoLoad($request);
2242 $STATE->getStomach->getGullet->readingFromMouth(LaTeXML::Core::Mouth::Binding->new($pathname), sub {
2243 do $pathname;
2244 Fatal('die', $pathname, $STATE->getStomach->getGullet,
2245 "File $pathname had an error:\n $@") if $@;
2246 # If we've opened anything, we should read it in completely.
2247 # But we'll assume that anything opened has already been processed by loadTeXDefinitions.
2248 });
2249 Let(T_CS('\ver@' . $trequest), T_CS('\fmtversion'), 'global');
2250 return; }
2251  
2252 my $loadtexdefinitions_options = { fordefinitions => 1, at_letter => 1, notes => 1,
2253 reloadable => 1 }; # [CONSTANT]
2254  
2255 sub loadTeXDefinitions {
2256 my ($request, $pathname, %options) = @_;
2257 # FILTER, not check options!
2258 my %mouth_options = map { ($_ => (exists $options{$_} ? $options{$_} : 1)) }
2259 keys %$loadtexdefinitions_options;
2260 # We can't analyze literal data's pathnames!
2261 if (!pathname_is_literaldata($pathname)) {
2262 # Don't load if we've already loaded it before.
2263 # Note that we'll still load it if we've already loaded only the ltxml version
2264 # since someone's presumably asking _explicitly_ for the raw TeX version.
2265 # It's probably even the ltxml version is asking for it!!
2266 # Of course, now it will be marked and wont get reloaded!
2267 #
2268 return if LookupValue($request . '_loaded') && !$options{reloadable};
2269 AssignValue($request . '_loaded' => 1, 'global');
2270 ClearAutoLoad($request); }
2271  
2272 my $stomach = $STATE->getStomach;
2273 # Note that we are reading definitions (and recursive input is assumed also definitions)
2274 my $was_interpreting = LookupValue('INTERPRETING_DEFINITIONS');
2275 # And that if we're interpreting this TeX file of definitions,
2276 # we probably should interpret any TeX files IT loads.
2277 my $was_including_styles = LookupValue('INCLUDE_STYLES');
2278 AssignValue('INTERPRETING_DEFINITIONS' => 1);
2279 # If we're reading in these definitions, probaly will accept included ones?
2280 # (but not forbid ltxml ?)
2281 AssignValue('INCLUDE_STYLES' => 1);
2282 # When set, this variable allows redefinitions of locked defns.
2283 # It is set in before/after methods to allow local rebinding of commands
2284 # but loading of sources & bindings is typically done in before/after methods of constructors!
2285 # This re-locks defns during reading of TeX packages.
2286 local $LaTeXML::Core::State::UNLOCKED = 0;
2287 $stomach->getGullet->readingFromMouth(
2288 LaTeXML::Core::Mouth->create($pathname, %mouth_options,
2289 content => LookupValue($pathname . '_contents')),
2290 sub {
2291 my ($gullet) = @_;
2292 my $token;
2293 while ($token = $gullet->readXToken(0)) {
2294 next if $token->equals(T_SPACE);
2295 $stomach->invokeToken($token); } });
2296 AssignValue('INTERPRETING_DEFINITIONS' => $was_interpreting);
2297 AssignValue('INCLUDE_STYLES' => $was_including_styles);
2298 Let(T_CS('\ver@' . $request), T_CS('\fmtversion'), 'global');
2299 return; }
2300  
2301 sub loadTeXContent {
2302 my ($pathname) = @_;
2303 my $gullet = $STATE->getStomach->getGullet;
2304 # If there is a file-specific declaration file (name.latexml), load it first!
2305 my $file = $pathname;
2306 $file =~ s/\.tex//;
2307 if (my $conf = !pathname_is_literaldata($pathname)
2308 && pathname_find("$file.latexml", paths => LookupValue('SEARCHPATHS'))) {
2309 loadLTXML($conf, $conf); }
2310 $gullet->openMouth(LaTeXML::Core::Mouth->create($pathname, notes => 1,
2311 content => LookupValue($pathname . '_contents')), 0);
2312 return; }
2313  
2314 #======================================================================
2315 # Option Handling for Packages and Classes
2316  
2317 # Declare an option for the current package or class
2318 # If $option is undef, it is the default.
2319 # $code can be a sub (as a primitive), or a string to be expanded.
2320 # (effectively a macro)
2321  
2322 DebuggableFeature('packageoptions', 'Processing package & class options');
2323  
2324 sub DeclareOption {
2325 my ($option, $code) = @_;
2326 $option = ToString($option) if ref $option;
2327 PushValue('@declaredoptions', $option) if $option;
2328 my $cs = ($option ? '\ds@' . $option : '\default@ds');
2329 Debug("Declaring option: " . ($option ? $option : '<default>')) if $LaTeXML::DEBUG{packageoptions};
2330 if ((!defined $code) || (ref $code eq 'CODE')) {
2331 DefPrimitiveI($cs, undef, $code); }
2332 else {
2333 DefMacroI($cs, undef, $code); }
2334 return; }
2335  
2336 # Pass the sequence of @options to the package $name (if $ext is 'sty'),
2337 # or class $name (if $ext is 'cls').
2338 sub PassOptions {
2339 my ($name, $ext, @options) = @_;
2340 PushValue('opt@' . $name . '.' . $ext, map { ToString($_) } @options);
2341 Debug("Passing to $name.$ext options: " . join(', ', @options)) if $LaTeXML::DEBUG{packageoptions};
2342 return; }
2343  
2344 # Process the options passed to the currently loading package or class.
2345 # If inorder=>1, they are processed in the order given (like \ProcessOptions*),
2346 # otherwise, they are processed in the order declared.
2347 # Unless noundefine=>1 (like for \ExecuteOptions), all option definitions
2348 # undefined after execution.
2349 my $processoptions_options = { # [CONSTANT]
2350 inorder => 1, keysets => 1 };
2351  
2352 sub ProcessOptions {
2353 my (%options) = @_;
2354 CheckOptions("ProcessOptions", $processoptions_options, %options);
2355 my $name = $STATE->lookupDefinition(T_CS('\@currname')) && ToString(Expand(T_CS('\@currname')));
2356 my $ext = $STATE->lookupDefinition(T_CS('\@currext')) && ToString(Expand(T_CS('\@currext')));
2357 my @declaredoptions = @{ LookupValue('@declaredoptions') };
2358 my @curroptions = @{ (defined($name) && defined($ext)
2359 && LookupValue('opt@' . $name . '.' . $ext)) || [] };
2360 my @classoptions = @{ LookupValue('class_options') || [] };
2361 Debug("ProcessOptions for $name.$ext\n"
2362 . " declared: " . join(',', @declaredoptions) . "\n"
2363 . " provided: " . join(',', @curroptions) . "\n"
2364 . " class: " . join(',', @classoptions)) if $LaTeXML::DEBUG{packageoptions};
2365  
2366 my $defaultcs = T_CS('\default@ds');
2367 # Execute options in declared order (unless \ProcessOptions*)
2368  
2369 if ($options{inorder}) { # Execute options in the order passed in (eg. \ProcessOptions*)
2370 foreach my $option (@classoptions) { # process global options, but no error
2371 if (executeOption_internal($option, %options)) { } }
2372  
2373 foreach my $option (@curroptions) {
2374 if (executeOption_internal($option, %options)) { }
2375 elsif (executeDefaultOption_internal($option)) { } } }
2376 else { # Execute options in declared order (eg. \ProcessOptions)
2377 foreach my $option (@declaredoptions) {
2378 if (grep { $option eq $_ } @curroptions, @classoptions) {
2379 @curroptions = grep { $option ne $_ } @curroptions; # Remove it, since it's been handled.
2380 executeOption_internal($option, %options); } }
2381 # Now handle any remaining options (eg. default options), in the given order.
2382 foreach my $option (@curroptions) {
2383 executeDefaultOption_internal($option); } }
2384 # Now, undefine the handlers?
2385 foreach my $option (@declaredoptions) {
2386 Let('\ds@' . $option, '\relax'); }
2387 return; }
2388  
2389 sub executeOption_internal {
2390 my ($option, %options) = @_;
2391 my $cs = T_CS('\ds@' . $option);
2392 # Simplified keyval options for classes & packages
2393 # Note that the option is a string with an "=" at this point.
2394 if ($options{keysets} && ($option =~ /^(.*)=(.*)$/)) {
2395 my ($key, $value) = ($1, $2);
2396 foreach my $keyset (@{ $options{keysets} }) {
2397 my $qname = keyval_qname('KV', $keyset, $key);
2398 if (my $keytype = keyval_get($qname, 'type')) {
2399 Debug("PROCESS KeyVal OPTION $key => $value") if $LaTeXML::DEBUG{packageoptions};
2400 Digest(Tokens(T_CS('\\' . $qname), T_BEGIN, Revert($value), T_END));
2401 return 1; } } }
2402 if ($STATE->lookupDefinition($cs)) {
2403 Debug("PROCESS OPTION $option") if $LaTeXML::DEBUG{packageoptions};
2404 DefMacroI('\CurrentOption', undef, $option);
2405 AssignValue('@unusedoptionlist',
2406 [grep { $_ ne $option } @{ LookupValue('@unusedoptionlist') || [] }]);
2407 Digest($cs);
2408 return 1; }
2409 else {
2410 return; } }
2411  
2412 sub executeDefaultOption_internal {
2413 my ($option) = @_;
2414 Debug("PROCESS DEFAULT OPTION $option") if $LaTeXML::DEBUG{packageoptions};
2415 # presumably should NOT remove from @unusedoptionlist ?
2416 DefMacroI('\CurrentOption', undef, $option);
2417 Digest(T_CS('\default@ds'));
2418 return 1; }
2419  
2420 sub ExecuteOptions {
2421 my (@options) = @_;
2422 my %unhandled = ();
2423 foreach my $option (@options) {
2424 if (executeOption_internal($option)) { }
2425 else {
2426 $unhandled{$option} = 1; } }
2427 foreach my $option (keys %unhandled) {
2428 Info('unexpected', $option, $STATE->getStomach->getGullet,
2429 "Unexpected options passed to ExecuteOptions '$option'"); }
2430 return; }
2431  
2432 sub resetOptions {
2433 AssignValue('@declaredoptions', []);
2434 Let('\default@ds',
2435 (ToString(Expand(T_CS('\@currext'))) eq 'cls'
2436 ? '\OptionNotUsed' : '\@unknownoptionerror'));
2437 return; }
2438  
2439 sub AddToMacro {
2440 my ($cs, @tokens) = @_;
2441 $cs = T_CS($cs) unless ref $cs;
2442 @tokens = map { (ref $_ ? $_ : TokenizeInternal($_)) } @tokens;
2443 # Needs error checking!
2444 my $defn = $STATE->lookupDefinition($cs);
2445 if (!defined $defn || !$defn->isExpandable) {
2446 Warn('unexpected', $cs, $STATE->getStomach->getGullet,
2447 ToString($cs) . " is not an expandable control sequence", "Ignoring addition"); }
2448 else {
2449 DefMacroI($cs, undef, Tokens(map { $_->unlist }
2450 map { (blessed $_ ? $_ : TokenizeInternal($_)) } ($defn->getExpansion, @tokens)),
2451 nopackParameters => 1, scope => 'global', locked => $$defn{locked}); }
2452 return; }
2453  
2454 #======================================================================
2455 my $inputdefinitions_options = { # [CONSTANT]
2456 options => 1, withoptions => 1, handleoptions => 1,
2457 type => 1, as_class => 1, noltxml => 1, notex => 1, noerror => 1, after => 1,
2458 at_letter => 1, searchpaths_only => 1, reloadable => 1 };
2459 # options=>[options...]
2460 # withoptions=>boolean : pass options from calling class/package
2461 # after=>code or tokens or string as $name.$type-h@@k macro. (executed after the package is loaded)
2462 # Returns the path that was loaded, or undef, if none found.
2463 sub InputDefinitions {
2464 my ($name, %options) = @_;
2465 $name = ToString($name) if ref $name;
2466 $name =~ s/^\s*//; $name =~ s/\s*$//;
2467 CheckOptions("InputDefinitions ($name)", $inputdefinitions_options, %options);
2468  
2469 my $prevname = $options{handleoptions} && $STATE->lookupDefinition(T_CS('\@currname')) && ToString(Expand(T_CS('\@currname')));
2470 my $prevext = $options{handleoptions} && $STATE->lookupDefinition(T_CS('\@currext')) && ToString(Expand(T_CS('\@currext')));
2471  
2472 # This file will be treated somewhat as if it were a class
2473 # IF as_class is true
2474 # OR if it is loaded by such a class, and has withoptions true!!! (yikes)
2475 $options{as_class} = 1 if $options{handleoptions} && $options{withoptions}
2476 && grep { $prevname eq $_ } @{ LookupValue('@masquerading@as@class') || [] };
2477  
2478 $options{raw} = 1 if $options{noltxml}; # so it will be read as raw by Gullet.!L!
2479 my $astype = ($options{as_class} ? 'cls' : $options{type} || 'sty');
2480  
2481 if ($astype eq 'cls' and $options{options}) {
2482 PushValue(class_options => @{ $options{options} });
2483 # ? Expand {\zap@space#2 \@empty}%
2484 DefMacroI('\@classoptionslist', undef, join(',', @{ $options{options} })); }
2485  
2486 my $filename = $name;
2487 $filename .= '.' . $options{type} if $options{type};
2488 if ($options{options} && scalar(@{ $options{options} })) {
2489 if (my $prevoptions = LookupValue($filename . '_loaded_with_options')) {
2490 my $curroptions = join(',', @{ $options{options} });
2491 Info('unexpected', 'options', $STATE->getStomach->getGullet,
2492 "Option clash for file $filename with options '$curroptions'",
2493 "previously loaded with '$prevoptions'") unless $curroptions eq $prevoptions; } }
2494 if (my $file = FindFile($filename, type => $options{type},
2495 notex => $options{notex}, noltxml => $options{noltxml}, searchpaths_only => $options{searchpaths_only})) {
2496 my $pushpop = LookupDefinition(T_CS('\@pushfilename'))
2497 && LookupDefinition(T_CS('\@popfilename'));
2498 if ($options{handleoptions}) {
2499 # Bookkeeping of what is being loaded so that LaTeX can run hooks.
2500 # Tricky: expl3 wants to know the fill CURRENTLY being read; \@currname,\@currext set LATER.
2501 # Recent expl3 appends \@expl@push@filename@aux@@ which takes THREE arguments!!!
2502 # These arguments mysteriously appear in \@onefilewith@ptions, MUCH later than \@pushfilename
2503 # We place the neaded data after \@pushfilename, but since we're Digesting in isolation,
2504 # they'll disappear if they aren't consumed by expl3. Whew!
2505 Digest(Tokens(T_CS('\@pushfilename'),
2506 T_BEGIN, T_END, T_BEGIN, T_END, T_BEGIN, Explode($name), T_END))
2507 if $pushpop;
2508 # For \RequirePackageWithOptions, pass the options from the outer class/style to the inner one.
2509 if (my $passoptions = $options{withoptions} && $prevname
2510 && LookupValue('opt@' . $prevname . "." . $prevext)) {
2511 # Only pass those class options that are declared by the package!
2512 my @declaredoptions = @{ LookupValue('@declaredoptions') };
2513 my @topass = ();
2514 foreach my $op (@$passoptions) {
2515 push(@topass, $op) if grep { $op eq $_ } @declaredoptions; }
2516 PassOptions($name, $astype, @topass) if @topass; }
2517 DefMacroI('\@currname', undef, Tokens(Explode($name)));
2518 DefMacroI('\@currext', undef, Tokens(Explode($astype)));
2519 # reset options (Note reset & pass were in opposite order in LoadClass ????)
2520 resetOptions();
2521 PassOptions($name, $astype, @{ $options{options} || [] }); # passed explicit options.
2522 # Note which packages are pretending to be classes.
2523 PushValue('@masquerading@as@class', $name) if $options{as_class};
2524 DefMacroI(T_CS('\\' . $name . '.' . $astype . '-h@@k'), undef, $options{after} || '');
2525 DefMacroI(T_CS('\opt@' . $name . '.' . $astype), undef,
2526 Tokens(Explode(join(',', @{ LookupValue('opt@' . $name . "." . $astype) }))));
2527 }
2528 AssignValue($filename . '_loaded_with_options' => join(',', @{ $options{options} }), 'global')
2529 if $options{options};
2530  
2531 my ($fdir, $fname, $ftype) = pathname_split($file);
2532 if ($options{handleoptions}) {
2533 # Add an appropriately faked entry into \@filelist
2534 my ($d, $n, $e) = ($fdir, $fname, $ftype); # If ftype is ltxml, reparse to get sty/cls!
2535 ($d, $n, $e) = pathname_split(pathname_concat($d, $n)) if $e eq 'ltxml'; # Fake it???
2536 my @p = ($STATE->lookupDefinition(T_CS('\@filelist'))
2537 ? Expand(T_CS('\@filelist'))->unlist : ());
2538 my @n = Explode($e ? $n . '.' . $e : $n);
2539 DefMacroI('\@filelist', undef, (@p ? Tokens(@p, T_OTHER(','), @n) : Tokens(@n))); }
2540 if ($ftype eq 'ltxml') {
2541 loadLTXML($filename, $file, reloadable => $options{reloadable}); } # Perl module.
2542 else {
2543 # Special case -- add a default resource if we're loading a raw .cls file as a first choice.
2544 # Raw class interpretations needs _some_ styling as baseline.
2545 if (!$options{noltxml} && ($file =~ /\.cls$/)) {
2546 RelaxNGSchema("LaTeXML");
2547 RequireResource('ltx-article.css'); }
2548 loadTeXDefinitions($filename, $file, %options); }
2549 if ($options{handleoptions}) {
2550 Digest(T_CS('\\' . $name . '.' . $astype . '-h@@k'));
2551 DefMacroI('\@currname', undef, Tokens(Explode($prevname))) if $prevname;
2552 DefMacroI('\@currext', undef, Tokens(Explode($prevext))) if $prevext;
2553 Digest(T_CS('\@popfilename')) if $pushpop;
2554 resetOptions(); } # And reset options afterwards, too.
2555 return $file; }
2556 elsif (!$options{noerror}) {
2557 $STATE->noteStatus(missing => $name . ($options{type} ? '.' . $options{type} : ''));
2558 # We'll only warn about a missing file of definitions: it may be ignorable or never used.
2559 # if there ARE problems, they'll likely produce their own errors!
2560 Warn('missing_file', $name, $STATE->getStomach->getGullet,
2561 "Can't find "
2562 . ($options{notex} ? "binding for " : "")
2563 . (($options{type} && $definition_name{ $options{type} }) || 'definitions') . ' '
2564 . $name,
2565 "Anticipate undefined macros or environments",
2566 maybeReportSearchPaths()); }
2567 return; }
2568  
2569 my $require_options = { # [CONSTANT]
2570 options => 1, withoptions => 1, type => 1, as_class => 1,
2571 noltxml => 1, notex => 1, raw => 1, after => 1, searchpaths_only => 1 };
2572 # This (& FindFile) needs to evolve a bit to support reading raw .sty (.def, etc) files from
2573 # the standard texmf directories. Maybe even use kpsewhich itself (INSTEAD of pathname_find ???)
2574 # Another potentially useful option might be that if we are reading a raw file,
2575 # perhaps it should just get digested immediately, since it shouldn't contribute any boxes.
2576 sub RequirePackage {
2577 my ($package, %options) = @_;
2578 $package = ToString($package) if ref $package;
2579 if ($options{raw}) {
2580 delete $options{raw}; $options{notex} = 0;
2581 Warn('deprecated', 'raw', $STATE->getStomach->getGullet,
2582 "RequirePackage option raw is obsolete; it is not needed"); }
2583 CheckOptions("RequirePackage ($package)", $require_options, %options);
2584 # We'll usually disallow raw TeX, unless the option explicitly given, or globally set.
2585 $options{notex} = 1
2586 if !defined $options{notex} && !LookupValue('INCLUDE_STYLES') && !$options{noltxml};
2587 # Top-level requires can be limited to local sources via searchpaths_only => 1
2588 $options{searchpaths_only} //= (!$options{notex}) && ((LookupValue('INCLUDE_STYLES') || '') eq 'searchpaths');
2589 my $success = InputDefinitions($package, type => $options{type} || 'sty', handleoptions => 1,
2590 # Pass classes options if we have NONE!
2591 withoptions => !($options{options} && @{ $options{options} }),
2592 %options);
2593 maybeRequireDependencies($package, $options{type} || 'sty') unless $success;
2594 return; }
2595  
2596 my $loadclass_options = { # [CONSTANT]
2597 options => 1, withoptions => 1, after => 1, notex => 1, searchpaths_only => 1 };
2598  
2599 sub LoadClass {
2600 my ($class, %options) = @_;
2601 $options{notex} = 1
2602 if !defined $options{notex} && !LookupValue('INCLUDE_CLASSES') && !$options{noltxml};
2603 # Top-level requires can be limited to local sources via searchpaths_only => 1
2604 $options{searchpaths_only} //= (!$options{notex}) && ((LookupValue('INCLUDE_CLASSES') || '') eq 'searchpaths');
2605  
2606 $class = ToString($class) if ref $class;
2607 CheckOptions("LoadClass ($class)", $loadclass_options, %options);
2608 # Note that we'll handle errors specifically for this case.
2609 if (my $success = InputDefinitions($class, type => 'cls', notex => $options{notex}, handleoptions => 1, noerror => 1,
2610 %options)) {
2611 return $success; }
2612 else {
2613 $STATE->noteStatus(missing => $class . '.cls');
2614 # Try guessing at an alternative class that we do have!
2615 # Find all class bindings (pathname_name twice for .cls.ltxml!!!)
2616 my @classes = sort { -(length($a) <=> length($b)) }
2617 map { pathname_name($_) } map { pathname_name($_) }
2618 pathname_findall('*', type => 'cls.ltxml', paths => LookupValue('SEARCHPATHS'),
2619 installation_subdir => 'Package');
2620 my ($alternate) = grep { $class =~ /^\Q$_\E/ } @classes;
2621 $alternate = 'OmniBus' unless $alternate;
2622 # Only Warn for missing style/class: we'll punt with an alternative;
2623 # there may come other errors from undefined macros, though.
2624 Warn('missing_file', $class, $STATE->getStomach->getGullet,
2625 "Can't find binding for class $class (using $alternate)",
2626 "Anticipate undefined macros or environments",
2627 maybeReportSearchPaths());
2628 if (my $success = InputDefinitions($alternate, type => 'cls', noerror => 1, handleoptions => 1, %options)) {
2629 maybeRequireDependencies($class, 'cls');
2630 return $success; }
2631 else {
2632 Fatal('missing_file', $alternate . '.cls.ltxml', $STATE->getStomach->getGullet,
2633 "Can't find binding for class $alternate (installation error)");
2634 return; } } }
2635  
2636 sub LoadPool {
2637 my ($pool) = @_;
2638 $pool = ToString($pool) if ref $pool;
2639 if (my $success = InputDefinitions($pool, type => 'pool', notex => 1, noerror => 1)) {
2640 return $success; }
2641 else {
2642 Error('missing_file', "$pool.pool.ltxml", $STATE->getStomach->getGullet,
2643 "Can't find binding for pool $pool (installation error)",
2644 maybeReportSearchPaths());
2645 return; } }
2646  
2647 # Somewhat an act of desperation in contexts like arXiv
2648 # where we may have a bunch of random styles & classes that load other packages
2649 # whose macros are then expected to be present.
2650 # We scan the source for \RequirePackage & \usepackage and load the ones that have bindings.
2651 # This is almost safe: the packages may only be loaded unconditionally, and we don't notice that!
2652 sub maybeRequireDependencies {
2653 my ($file, $type) = @_;
2654 if (my $path = FindFile($file, type => $type, noltxml => 1)) {
2655 local $/ = undef;
2656 my $IN;
2657 if (open($IN, '<', $path)) {
2658 my $code = <$IN>;
2659 close($IN);
2660 my @classes = ();
2661 my @packages = ();
2662 my %dups = ();
2663 my $collect = sub {
2664 my ($packages, $options) = @_;
2665 foreach my $p (split(/\s*,\s*/, $packages)) {
2666 if (!$dups{$p} && !LookupValue($p . '.sty.ltxml_loaded')) {
2667 push(@packages, [$p, $options]); $dups{$p} = 1; } } };
2668 # Yes, Regexps on TeX code! Ugh!!! Well, this is an act of desperation anyway :>
2669 $code =~ s/%[^\n]*\n//gs; # strip comments
2670 $code =~ s/\\RequirePackage\s*(?:\[([^\]]*)\])?\s*\{([^\}]*)\}/ &$collect($2,$1); /xegs;
2671 # Ugh. \usepackage, too
2672 $code =~ s/\\usepackage\s*(?:\[([^\]]*)\])?\s*\{([^\}]*)\}/ &$collect($2,$1); /xegs;
2673 # Even more ugh; \LoadClass
2674 if ($type eq 'cls') {
2675 $code =~ s/\\LoadClass\s*(?:\[([^\]]*)\])?\s*\{([^\}]*)\}/ push(@classes,[$2,$1]); /xegs; }
2676  
2677 Info('dependencies', 'dependencies', undef,
2678 "Loading dependencies for $path: " . join(',', map { $$_[0]; } @classes, @packages)) if scalar(@classes) || scalar(@packages);
2679 foreach my $pair (@classes) {
2680 my ($class, $options) = @$pair;
2681 if (FindFile($class, type => 'cls', notex => 1)) {
2682 LoadClass($class, ($options ? (options => [split(/\s*,\s*/, $options)]) : ())); } }
2683 foreach my $pair (@packages) {
2684 my ($package, $options) = @$pair;
2685 if (FindFile($package, type => 'sty', notex => 1)) {
2686 RequirePackage($package, ($options ? (options => [split(/\s*,\s*/, $options)]) : ())); } } }
2687 else {
2688 Warn('I/O', 'read', undef, "Couldn't open $path to scan dependencies", $!); } }
2689 return; }
2690  
2691 sub AtBeginDocument {
2692 my (@operations) = @_;
2693 AssignValue('@at@begin@document', []) unless LookupValue('@at@begin@document');
2694 foreach my $op (@operations) {
2695 next unless $op;
2696 my $t = ref $op;
2697 if (!$t) { # Presumably String?
2698 $op = TokenizeInternal($op); }
2699 elsif ($t eq 'CODE') {
2700 my $tn = T_CS(ToString($op));
2701 DefMacroI($tn, undef, $op);
2702 $op = $tn; }
2703 PushValue('@at@begin@document', $op->unlist); }
2704 return; }
2705  
2706 sub AtEndDocument {
2707 my (@operations) = @_;
2708 AssignValue('@at@end@document', []) unless LookupValue('@at@end@document');
2709 foreach my $op (@operations) {
2710 next unless $op;
2711 my $t = ref $op;
2712 if (!$t) { # Presumably String?
2713 $op = TokenizeInternal($op); }
2714 elsif ($t eq 'CODE') {
2715 my $tn = T_CS(ToString($op));
2716 DefMacroI($tn, undef, $op);
2717 $op = $tn; }
2718 PushValue('@at@end@document', $op->unlist); }
2719 return; }
2720  
2721 #======================================================================
2722 #
2723 my $fontmap_options = { # [CONSTANT]
2724 family => 1 };
2725  
2726 sub DeclareFontMap {
2727 my ($name, $map, %options) = @_;
2728 CheckOptions("DeclareFontMap", $fontmap_options, %options);
2729 my $mapname = ToString($name)
2730 . ($options{family} ? '_' . $options{family} : '')
2731 . '_fontmap';
2732 AssignValue($mapname => $map, 'global');
2733 return; }
2734  
2735 # Decode a codepoint using the fontmap for a given font and/or fontencoding.
2736 # If $encoding not provided, then lookup according to the current font's
2737 # encoding; the font family may also be used to choose the fontmap (think tt fonts!).
2738 # When $implicit is false, we are "explicitly" asking for a decoding, such as
2739 # with \char, \mathchar, \symbol, DeclareTextSymbol and such cases.
2740 # In such cases, only codepoints specifically within the map are covered; the rest are undef.
2741 # If $implicit is true, we'll decode token content that has made it to the stomach:
2742 # We're going to assume that SOME sort of handling of input encoding is taking place,
2743 # so that if anything above 128 comes in, it must already be Unicode!.
2744 # The lower half plane still needs to go through decoding, though, to deal
2745 # with TeX's rearrangement of ASCII...
2746 sub FontDecode {
2747 my ($code, $encoding, $implicit) = @_;
2748 return if !defined $code || ($code < 0);
2749 my ($map, $font);
2750 if (!$encoding) {
2751 $font = LookupValue('font');
2752 $encoding = $font->getEncoding || 'OT1'; }
2753 if ($encoding && ($map = LoadFontMap($encoding))) { # OK got some map.
2754 my ($family, $fmap);
2755 if ($font && ($family = $font->getFamily) && ($fmap = LookupValue($encoding . '_' . $family . '_fontmap'))) {
2756 $map = $fmap; } } # Use the family specific map, if any.
2757 if ($implicit) {
2758 if ($map && ($code < 128)) {
2759 return $$map[$code]; }
2760 else {
2761 return pack('U', $code); } }
2762 else {
2763 return ($map ? $$map[$code] : undef); } }
2764  
2765 sub FontDecodeString {
2766 my ($string, $encoding, $implicit) = @_;
2767 return if !defined $string;
2768 my ($map, $font);
2769 if (!$encoding) {
2770 $font = LookupValue('font');
2771 $encoding = $font->getEncoding; }
2772 if ($encoding && ($map = LoadFontMap($encoding))) { # OK got some map.
2773 my ($family, $fmap);
2774 if ($font && ($family = $font->getFamily) && ($fmap = LookupValue($encoding . '_' . $family . '_fontmap'))) {
2775 $map = $fmap; } } # Use the family specific map, if any.
2776  
2777 return join('', grep { defined $_ }
2778 map { ($implicit ? (($map && ($_ < 128)) ? $$map[$_] : pack('U', $_))
2779 : ($map ? $$map[$_] : undef)) }
2780 map { ord($_) } split(//, $string)); }
2781  
2782 sub LoadFontMap {
2783 my ($encoding) = @_;
2784 my $map = LookupValue($encoding . '_fontmap');
2785 if (!$map && !LookupValue($encoding . '_fontmap_failed_to_load')) {
2786 AssignValue($encoding . '_fontmap_failed_to_load' => 1); # Stop recursion?
2787 InputDefinitions(lc($encoding), type => 'fontmap', noerror => 1);
2788 if ($map = LookupValue($encoding . '_fontmap')) { # Got map?
2789 AssignValue($encoding . '_fontmap_failed_to_load' => 0); }
2790 else {
2791 Info('fontmap', $encoding, undef, "Couldn't find fontmap for '$encoding'");
2792 AssignValue($encoding . '_fontmap_failed_to_load' => 1, 'global'); } }
2793 return $map; }
2794  
2795 #======================================================================
2796 # Color
2797 sub LookupColor {
2798 my ($name) = @_;
2799 if (my $color = LookupValue('color_' . $name)) {
2800 return $color; }
2801 else {
2802 Error('undefined', $name, $STATE->getStomach, "color '$name' is undefined...");
2803 return Black; } }
2804  
2805 sub DefColor {
2806 my ($name, $color, $scope) = @_;
2807 return unless ref $color;
2808 my ($model, @spec) = @$color;
2809 $scope = 'global' if $STATE->lookupDefinition(T_CS('\ifglobalcolors')) && IfCondition(T_CS('\ifglobalcolors'));
2810 AssignValue('color_' . $name => $color, $scope);
2811 # We could store these pieces separately,or in a list for above,
2812 # so that extract could use them more reasonably?
2813 # This is perhaps too xcolor specific?
2814 DefMacroI('\\\\color@' . $name, undef,
2815 '\relax\relax{' . join(' ', $model, @spec) . '}{' . $model . '}{' . join(',', @spec) . '}',
2816 scope => $scope);
2817 return; }
2818  
2819 # Need 3 things for Derived Models:
2820 # derivedfrom : the core model that this model is "derived from"
2821 # convertto : code to convert to the (a) core model
2822 # convertfrom : code to convert from the core model
2823 sub DefColorModel {
2824 my ($model, $coremodel, $tocore, $fromcore) = @_;
2825 AssignValue('derived_color_model_' . $model => [$coremodel, $tocore, $fromcore], 'global');
2826 return; }
2827  
2828 #======================================================================
2829 # Defining Rewrite rules that act on the DOM
2830 # These are applied after the document is completely constructed
2831 my $rewrite_options = { # [CONSTANT]
2832 label => 1, scope => 1, xpath => 1, match => 1,
2833 attributes => 1, replace => 1, regexp => 1, select => 1 };
2834  
2835 sub DefRewrite {
2836 my (@specs) = @_;
2837 CheckOptions("DefRewrite", $rewrite_options, @specs);
2838 PushValue('DOCUMENT_REWRITE_RULES',
2839 LaTeXML::Core::Rewrite->new('text', processRewriteSpecs(0, @specs)));
2840 return; }
2841  
2842 sub DefMathRewrite {
2843 my (@specs) = @_;
2844 CheckOptions("DefMathRewrite", $rewrite_options, @specs);
2845 PushValue('DOCUMENT_REWRITE_RULES',
2846 LaTeXML::Core::Rewrite->new('math', processRewriteSpecs(1, @specs)));
2847 return; }
2848  
2849 sub processRewriteSpecs {
2850 my ($math, @specs) = @_;
2851 my @procspecs = ();
2852 my $delimiter = ($math ? '$' : '');
2853 while (@specs) {
2854 my $k = shift(@specs);
2855 my $v = shift(@specs);
2856 # Make sure match & replace are (at least) tokenized
2857 if (($k eq 'match') || ($k eq 'replace')) {
2858 if (ref $v eq 'ARRAY') {
2859 $v = [map { (ref $_ ? $_ : Tokenize($delimiter . $_ . $delimiter)) } @$v]; }
2860 elsif (!ref $v) {
2861 $v = Tokenize($delimiter . $v . $delimiter); } }
2862 push(@procspecs, $k, $v); }
2863 return @procspecs; }
2864  
2865 #======================================================================
2866 # Defining "Ligatures" rules that act on the DOM
2867 # These are actually a sort of rewrite that is applied while the doom
2868 # is being constructed, in particular as each node is closed.
2869  
2870 my $ligature_options = { # [CONSTANT]
2871 fontTest => 1 };
2872  
2873 sub DefLigature {
2874 my ($regexp, $replacement, %options) = @_;
2875 CheckOptions("DefLigature", $ligature_options, %options);
2876 UnshiftValue('TEXT_LIGATURES',
2877 { regexp => $regexp,
2878 code => sub { $_[0] =~ s/$regexp/$replacement/g; $_[0]; },
2879 %options });
2880 return; }
2881  
2882 my $math_ligature_options = { matcher => 1, role => 1, name => 1, meaning => 1 }; # [CONSTANT]
2883  
2884 sub DefMathLigature {
2885 my (%options) = @_;
2886 my $matcher = $options{matcher};
2887 delete $options{matcher};
2888 my ($pattern) = grep { !$$math_ligature_options{$_} } keys %options;
2889 my $replacement = $pattern && $options{$pattern};
2890 delete $options{$pattern} if $replacement;
2891 CheckOptions("DefMathLigature", $math_ligature_options, %options); # Check remaining options
2892 if ($matcher && $pattern) {
2893 Error('misdefined', 'MathLigature', undef,
2894 "DefMathLigature only gets one of matcher or pattern=>replacement keywords");
2895 return; }
2896 elsif ($pattern) {
2897 my @chars = reverse(split(//, $pattern));
2898 my $ntomatch = scalar(@chars);
2899 my %attr = %options;
2900 $matcher = sub {
2901 my ($document, $node) = @_;
2902 foreach my $char (@chars) {
2903 return unless
2904 ($node
2905 && ($document->getModel->getNodeQName($node) eq 'ltx:XMTok')
2906 && (($node->textContent || '') eq $char));
2907 $node = $node->previousSibling; }
2908 return ($ntomatch, $replacement, %attr); }; }
2909 elsif (!$matcher) {
2910 Error('misdefined', 'MathLigature', undef,
2911 "DefMathLigature missing matcher or pattern=>replacement keywords");
2912 return; }
2913 UnshiftValue('MATH_LIGATURES', { matcher => $matcher }); # Install it...
2914 return; }
2915  
2916 #======================================================================
2917 # Support for requiring "Resources", ie CSS, Javascript, whatever
2918  
2919 my $resource_options = { # [CONSTANT]
2920 type => 1, media => 1, content => 1 };
2921 my $resource_types = { # [CONSTANT]
2922 css => 'text/css', js => 'text/javascript' };
2923  
2924 sub RequireResource {
2925 my ($resource, %options) = @_;
2926 CheckOptions("RequireResource", $resource_options, %options);
2927 if (!$options{content} && !$resource) {
2928 Warn('expected', 'resource', undef, "Resource must have a resource pathname or content; skipping");
2929 return; }
2930 if (!$options{type}) {
2931 my $ext = $resource && pathname_type($resource);
2932 $options{type} = $ext && $$resource_types{$ext}; }
2933 if (!$options{type}) {
2934 my $ext = $resource && pathname_type($resource);
2935 my $t = $ext && $$resource_types{$ext};
2936 Warn('expected', 'type', undef, "Resource must have a mime-type; skipping"); return; }
2937  
2938 if ($LaTeXML::DOCUMENT) { # If we've got a document, go ahead & put the resource in.
2939 addResource($LaTeXML::DOCUMENT, $resource, %options); }
2940 else {
2941 AssignValue(PENDING_RESOURCES => [], 'global') unless LookupValue('PENDING_RESOURCES');
2942 PushValue(PENDING_RESOURCES => [$resource, %options]); }
2943 return; }
2944  
2945 # No checking...
2946 sub addResource {
2947 my ($document, $resource, %options) = @_;
2948 my $savenode = $document->floatToElement('ltx:resource');
2949 $document->insertElement('ltx:resource', $options{content},
2950 src => $resource, type => $options{type}, media => $options{media});
2951 $document->setNode($savenode) if $savenode;
2952 return; }
2953  
2954 sub ProcessPendingResources {
2955 my ($document) = @_;
2956 if (my $resources = LookupValue('PENDING_RESOURCES')) {
2957 my %seen = ();
2958 my @unique_resources = grep { my $new = !$seen{$_}; $seen{$_} = 1; $new; } @$resources;
2959 for my $resource (@unique_resources) {
2960 addResource($document, @$resource); }
2961 AssignValue(PENDING_RESOURCES => [], 'global'); }
2962 return; }
2963  
2964 #**********************************************************************
2965 1;
2966  
2967 __END__
« lib/LaTeXML/Core/Stomach.pm ↑ Summary lib/LaTeXML/Common/Font/StandardMetrics.pm »