| 1 | # /=====================================================================\ # | ||
| 2 | # | LaTeXML::Core::Whatsit | # | ||
| 3 | # | Digested objects produced in the Stomach | # | ||
| 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 | # LaTeXML Whatsit. | ||
| 14 | # Some arbitrary object, possibly with arguments. | ||
| 15 | # Particularly as an intermediate representation for invocations of control | ||
| 16 | # sequences that do NOT get expanded or processed, but are taken to represent | ||
| 17 | # some semantic something or other. | ||
| 18 | # These get preserved in the expanded/processed token stream to be | ||
| 19 | # converted into XML objects in the document. | ||
| 20 | #********************************************************************** | ||
| 21 | package LaTeXML::Core::Whatsit; | ||
| 22 | use strict; | ||
| 23 | use warnings; | ||
| 24 | use LaTeXML::Global; | ||
| 25 | use LaTeXML::Common::Object; | ||
| 26 | use LaTeXML::Common::Locator; | ||
| 27 | use LaTeXML::Common::Error; | ||
| 28 | use LaTeXML::Core::Token; | ||
| 29 | use LaTeXML::Core::Tokens; | ||
| 30 | use LaTeXML::Core::Definition::Expandable; | ||
| 31 | use LaTeXML::Common::Dimension; | ||
| 32 | use List::Util qw(min max); | ||
| 33 | use LaTeXML::Core::List; | ||
| 34 | use base qw(LaTeXML::Core::Box); | ||
| 35 | |||
| 36 | # Specially recognized (some required?) properties: | ||
| 37 | # font : The font object | ||
| 38 | # locator : a locator object, where in the source this whatsit was created | ||
| 39 | # isMath : whether this is a math object | ||
| 40 | # id | ||
| 41 | # body | ||
| 42 | # trailer | ||
| 43 | sub new { | ||
| 44 | my ($class, $defn, $args, %properties) = @_; | ||
| 45 | return bless { definition => $defn, args => $args || [], properties => {%properties} }, $class; } | ||
| 46 | |||
| 47 | sub getDefinition { | ||
| 48 | my ($self) = @_; | ||
| 49 | return $$self{definition}; } | ||
| 50 | |||
| 51 | sub isMath { | ||
| 52 | my ($self) = @_; | ||
| 53 | return $$self{properties}{isMath}; } | ||
| 54 | |||
| 55 | sub getProperty { | ||
| 56 | my ($self, $key) = @_; | ||
| 57 | return $$self{properties}{$key}; } | ||
| 58 | |||
| 59 | sub getArg { | ||
| 60 | my ($self, $n) = @_; | ||
| 61 | return $$self{args}[$n - 1]; } | ||
| 62 | |||
| 63 | sub getArgs { | ||
| 64 | my ($self) = @_; | ||
| 65 | return @{ $$self{args} }; } | ||
| 66 | |||
| 67 | sub setArgs { | ||
| 68 | my ($self, @args) = @_; | ||
| 69 | $$self{args} = [@args]; | ||
| 70 | return; } | ||
| 71 | |||
| 72 | sub getBody { | ||
| 73 | my ($self) = @_; | ||
| 74 | return $$self{properties}{body}; } | ||
| 75 | |||
| 76 | sub setBody { | ||
| 77 | my ($self, @body) = @_; | ||
| 78 | my $trailer = pop(@body); | ||
| 79 | $$self{properties}{body} = List(@body); | ||
| 80 | $$self{properties}{body}->setProperty(mode => 'math') if $self->isMath; | ||
| 81 | $$self{properties}{trailer} = $trailer; | ||
| 82 | # And copy any otherwise undefined properties from the trailer | ||
| 83 | if ($trailer) { | ||
| 84 | $$self{properties}{locator} = LaTeXML::Common::Locator->newRange($self->getLocator, $trailer->getLocator); | ||
| 85 | my %trailerhash = $trailer->getProperties; | ||
| 86 | foreach my $prop (keys %trailerhash) { | ||
| 87 | $$self{properties}{$prop} = $trailer->getProperty($prop) unless defined $$self{properties}{$prop}; } } | ||
| 88 | return; } | ||
| 89 | |||
| 90 | sub getTrailer { | ||
| 91 | my ($self) = @_; | ||
| 92 | return $$self{properties}{trailer}; } | ||
| 93 | |||
| 94 | # So a Whatsit can stand in for a List | ||
| 95 | sub unlist { | ||
| 96 | my ($self) = @_; | ||
| 97 | return ($self); } | ||
| 98 | |||
| 99 | sub revert { | ||
| 100 | my ($self) = @_; | ||
| 101 | # WARNING: Forbidden knowledge? | ||
| 102 | # (2) caching the reversion (which is a big performance boost) | ||
| 103 | my $defn = $self->getDefinition; | ||
| 104 | my $alignment; | ||
| 105 | if (my $saved = ($LaTeXML::DUAL_BRANCH | ||
| 106 | ? $$self{dual_reversion}{$LaTeXML::DUAL_BRANCH} | ||
| 107 | : $$self{reversion})) { | ||
| 108 | return $saved->unlist; } | ||
| 109 | ## elsif($alignment = $$self{properties}{alignment}) { | ||
| 110 | elsif ((!$defn->getReversionSpec) | ||
| 111 | && ($alignment = $$self{properties}{alignment})) { | ||
| 112 | return $alignment->revert; } | ||
| 113 | else { | ||
| 114 | my $props = $$self{properties}; | ||
| 115 | # Find the appropriate reversion spec; | ||
| 116 | # content_reversion or presntation_reversion if on dual branch | ||
| 117 | # or (general) reversion, or the reversion from the definition | ||
| 118 | my $spec = $$props{'reversion'} || $defn->getReversionSpec; | ||
| 119 | my @tokens = (); | ||
| 120 | if ((defined $spec) && (ref $spec eq 'CODE')) { # If handled by CODE, call it | ||
| 121 | @tokens = $self->substituteParameters(Tokens(&$spec($self, $self->getArgs))); } | ||
| 122 | else { | ||
| 123 | if (defined $spec) { | ||
| 124 | @tokens = $self->substituteParameters($spec) | ||
| 125 | if $spec ne ''; } | ||
| 126 | else { | ||
| 127 | my $alias = $defn->getAlias; | ||
| 128 | if (defined $alias) { | ||
| 129 | push(@tokens, (ref $alias ? $alias : T_CS($alias))) if $alias ne ''; } | ||
| 130 | else { | ||
| 131 | push(@tokens, $defn->getCS); } | ||
| 132 | if (my $parameters = $defn->getParameters) { | ||
| 133 | push(@tokens, $parameters->revertArguments($self->getArgs)); } } | ||
| 134 | if (defined(my $body = $self->getBody)) { | ||
| 135 | ### if (defined(my $body = $self->getBody || $self->getProperty('alignment'))) { | ||
| 136 | push(@tokens, Revert($body)); | ||
| 137 | if (defined(my $trailer = $self->getTrailer)) { | ||
| 138 | push(@tokens, Revert($trailer)); } } } | ||
| 139 | # Now cache it, in case it's needed again | ||
| 140 | if ($LaTeXML::DUAL_BRANCH) { | ||
| 141 | $$self{dual_reversion}{$LaTeXML::DUAL_BRANCH} = Tokens(@tokens); } | ||
| 142 | else { | ||
| 143 | $$self{reversion} = Tokens(@tokens); } | ||
| 144 | return @tokens; } } | ||
| 145 | |||
| 146 | # Like Tokens-substituteParameters, but substitutes in the Whatsit's arguments OR properties! | ||
| 147 | # #<digit> is the standard TeX positional argument | ||
| 148 | # # followed by a T_OTHER(propname) specifies the property propname!! | ||
| 149 | sub substituteParameters { | ||
| 150 | my ($self, $spec) = @_; | ||
| 151 | # TODO: This is kind of unfortunate -- I am not sure what are the reasonable "entryways" into the Whatsit substituteParameters. For Expandable we now have guarantees that "#,i" has been mapped into a single T_ARG(#i), but not here. | ||
| 152 | # so for now run on each call? | ||
| 153 | my @in = $spec->unlist; | ||
| 154 | my @args = $self->getArgs; | ||
| 155 | my $props = $$self{properties}; | ||
| 156 | my @result = (); | ||
| 157 | while (@in) { | ||
| 158 | my $token = shift(@in); | ||
| 159 | if ($$token[1] != CC_ARG) { # Non '#'; copy it | ||
| 160 | push(@result, $token); } | ||
| 161 | else { | ||
| 162 | my $s = $$token[0]; | ||
| 163 | my $n = ord($s) - ord('0') - 1; | ||
| 164 | if (my $arg = (($n >= 0) && ($n < 10) ? $args[$n] : $$props{$s})) { | ||
| 165 | push(@result, Revert($arg)); } } } | ||
| 166 | return @result; } | ||
| 167 | |||
| 168 | sub toString { | ||
| 169 | my ($self) = @_; | ||
| 170 | return ToString(Tokens($self->revert)); } # What else?? | ||
| 171 | |||
| 172 | sub getString { | ||
| 173 | my ($self) = @_; | ||
| 174 | return $self->toString; } # Ditto? | ||
| 175 | |||
| 176 | # Methods for overloaded operators | ||
| 177 | sub stringify { | ||
| 178 | no warnings 'recursion'; | ||
| 179 | my ($self) = @_; | ||
| 180 | my $hasbody = defined $$self{properties}{body}; | ||
| 181 | return "Whatsit[" . join(',', $self->getDefinition->getCS->getCSName, | ||
| 182 | map { Stringify($_) } | ||
| 183 | $self->getArgs, | ||
| 184 | (defined $$self{properties}{body} | ||
| 185 | ? ($$self{properties}{body}, $$self{properties}{trailer}) | ||
| 186 | : ())) | ||
| 187 | . "]"; } | ||
| 188 | |||
| 189 | sub equals { | ||
| 190 | my ($a, $b) = @_; | ||
| 191 | return 0 unless (defined $b) && ((ref $a) eq (ref $b)); | ||
| 192 | return 0 unless $$a{definition} eq $$b{definition}; # I think we want IDENTITY here, not ->equals | ||
| 193 | my @a = @{ $$a{args} }; push(@a, $$a{properties}{body}) if $$a{properties}{body}; | ||
| 194 | my @b = @{ $$b{args} }; push(@b, $$b{properties}{body}) if $$b{properties}{body}; | ||
| 195 | while (@a && @b && ($a[0]->equals($b[0]))) { | ||
| 196 | shift(@a); shift(@b); } | ||
| 197 | return !(@a || @b); } | ||
| 198 | |||
| 199 | sub beAbsorbed { | ||
| 200 | no warnings 'recursion'; | ||
| 201 | my ($self, $document) = @_; | ||
| 202 | # Significant time is consumed here, and associated with a specific CS, | ||
| 203 | # so we should be profiling as well! | ||
| 204 | # Hopefully the csname is the same that was charged in the digestioned phase! | ||
| 205 | |||
| 206 | # Guard via the absorb limit to avoid infinite loops | ||
| 207 | if ($LaTeXML::ABSORB_LIMIT) { | ||
| 208 | my $absorb_counter = $STATE->lookupValue('absorb_count') || 0; | ||
| 209 | $STATE->assignValue(absorb_count => ++$absorb_counter, 'global'); | ||
| 210 | if ($absorb_counter > $LaTeXML::ABSORB_LIMIT) { | ||
| 211 | Fatal('timeout', 'absorb_limit', $self, | ||
| 212 | "Whatsit absorb limit of $LaTeXML::ABSORB_LIMIT exceeded, infinite loop?"); } } | ||
| 213 | |||
| 214 | my $defn = $self->getDefinition; | ||
| 215 | my $profiled = (($STATE->lookupValue('TRACING') || 0) & TRACE_PROFILE) && $defn->getCS; | ||
| 216 | LaTeXML::Core::Definition::startProfiling($profiled, 'absorb') if $profiled; | ||
| 217 | my @result = $defn->doAbsorbtion($document, $self); | ||
| 218 | LaTeXML::Core::Definition::stopProfiling($profiled, 'absorb') if $profiled; | ||
| 219 | return @result; } | ||
| 220 | |||
| 221 | # See discussion in Box.pm | ||
| 222 | sub computeSize { | ||
| 223 | my ($self, %options) = @_; | ||
| 224 | # Use #body, if any, else ALL args !?!?! | ||
| 225 | my $defn = $self->getDefinition; | ||
| 226 | my $props = $self->getPropertiesRef; | ||
| 227 | my $sizer = $defn->getSizer; | ||
| 228 | if (ref $sizer) { # If sizer is a function, call it | ||
| 229 | return &$sizer($self); } | ||
| 230 | else { # Else collect up args/body/boxes which represent this thing | ||
| 231 | my @boxes = (); | ||
| 232 | if (!defined $sizer) { # Nothing specified? use #body if any, else sum all box args | ||
| 233 | @boxes = ($$props{body} | ||
| 234 | ? ($$props{body}) | ||
| 235 | : (map { ((ref $_) && ($_->isaBox) ? $_->unlist : ()) } @{ $$self{args} })); } | ||
| 236 | elsif (($sizer eq '0') || ($sizer eq '')) { } # 0 size! | ||
| 237 | elsif ($sizer =~ /^(#\w+)*$/) { # Else if of form '#digit' or '#prop', combine sizes | ||
| 238 | while ($sizer =~ s/^#(\w+)//) { | ||
| 239 | my $arg = $1; | ||
| 240 | push(@boxes, ($arg =~ /^\d+$/ ? $self->getArg($arg) : $$props{$arg})); } | ||
| 241 | # Special case: If only a single object to be sized and it is a List, unlist it. | ||
| 242 | # This is so that whatsit's layout properties will be applied to the sequence | ||
| 243 | if ((scalar(@boxes) == 1) && ((ref $boxes[0]) eq 'LaTeXML::Core::List')) { | ||
| 244 | @boxes = $boxes[0]->unlist; } } | ||
| 245 | else { | ||
| 246 | push(@boxes, $sizer); } | ||
| 247 | no warnings 'recursion'; | ||
| 248 | return $$props{font}->computeBoxesSize([@boxes], %options); } } | ||
| 249 | |||
| 250 | #====================================================================== | ||
| 251 | 1; | ||
| 252 | |||
| 253 | __END__ |