lib/LaTeXML/Core/KeyVals.pm untested

filter: Statementstmt 0.0% 0 / 279 Branchbran 0.0% 0 / 146 Conditioncond 0.0% 0 / 21 MC/DCmcdc 0.0% 0 / 14 Subroutinesub 0.0% 0 / 32 Podpod 0.0% 0 / 23 totaltotal 0.0% 0 / 515 CC 74 SCAR 47.2
CC
74
Cov
0%
setKeysExpansion
272.0
new
240.0
readFrom
210.0
CRAP 112.6
1 # /=====================================================================\ #
2 # | LaTeXML::Core::KeyVals | #
3 # | Support for key-value pairs for LaTeXML | #
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 package LaTeXML::Core::KeyVals;
13 use strict;
14 use warnings;
15 use LaTeXML::Global;
16 use LaTeXML::Common::Object;
17 use LaTeXML::Common::Error;
18 use LaTeXML::Core::Token;
19 use LaTeXML::Core::Tokens;
20 use LaTeXML::Core::KeyVal;
21 use base qw(LaTeXML::Common::Object);
22  
23 our @EXPORT = (
24 qw(&GetKeyVal &GetKeyVals)
25 );
26  
27 #======================================================================
28 # Exposed Methods
29 #======================================================================
30  
31 sub GetKeyVal {
32 my ($keyvals, $key) = @_;
33 return (defined $keyvals) && $keyvals->getValue($key); }
34  
35 sub GetKeyVals {
36 my ($keyvals) = @_;
37 return (defined $keyvals ? $keyvals->getKeyVals : {}); }
38  
39 #======================================================================
40 # The KeyVals constructor
41 #======================================================================
42 # This defines the KeyVals data object that can appear in the datastream
43 # along with tokens, boxes, etc.
44 # Thus it has to be digestible, however we may not want to digest it more
45 # than once.
46 #**********************************************************************
47  
48 sub new {
49 my ($class, $prefix, $keysets, %options) = @_;
50 # parse all the arguments
51 $prefix = defined($prefix) ? ToString($prefix) : 'KV';
52 $keysets = [split(',', ToString(defined($keysets) ? $keysets : '_anonymous_'))] unless (ref($keysets) eq 'ARRAY');
53 my $skip = $options{skip};
54 $skip = [split(',', ToString(defined($options{skip}) ? $options{skip} : ''))] unless (ref($options{skip}) eq 'ARRAY');
55 my $setAll = $options{setAll} ? 1 : 0;
56 my $setInternals = $options{setInternals} ? 1 : 0;
57 my $skipMissing = $options{skipMissing};
58 my $hookMissing = $options{hookMissing};
59 # hook missing, if defined, must be a token
60 if (defined($hookMissing) && $hookMissing) {
61 $hookMissing = ref($hookMissing) ? $hookMissing : T_CS(ToString($hookMissing)); }
62 else { $hookMissing = undef; }
63 # skip missing may be a token (=store all the missing macros there)
64 unless (ref($skipMissing)) {
65 # may be undef or 0 (= throw errors)
66 unless (defined($skipMissing)) { $skipMissing = undef; }
67 elsif ($skipMissing eq '0') { $skipMissing = undef; }
68 # may be 1 (= ignore all missing keys)
69 elsif ($skipMissing eq '1') { $skipMissing = 1; }
70 # may be a string (= store all the missing keys there)
71 else { $skipMissing = T_CS($skipMissing); } }
72 my $self = bless {
73 # which KeyVals are we parsing and how do we behave?
74 prefix => $prefix, keysets => $keysets,
75 skip => $skip, setAll => $setAll, setInternals => $setInternals,
76 skipMissing => $skipMissing, hookMissing => $hookMissing,
77 # all the internal representations
78 tuples => [], cachedPairs => [()], cachedHash => {} },
79 $class;
80 if (my $tuples = $options{tuples}) {
81 $$self{tuples} = $tuples;
82 $self->rebuild; }
83 return $self; }
84  
85 #======================================================================
86 # Resolution to KeySets
87 #======================================================================
88 # Return a list of the keysets in which this key is defined
89 sub resolveKeyValFor {
90 my ($self, $key) = @_;
91 my $prefix = $$self{prefix};
92 my @allkeysets = @{ $$self{keysets} };
93 my @keysets = grep { HasKeyVal($prefix, $_, $key); } @{ $$self{keysets} };
94 # throw an error (not really), unless we record the missing macros
95 # Since we're not as obsessive about declaring ALL keys, we'll soften the blow
96 if (scalar @keysets == 0) {
97 Info('undefined', 'Encountered unknown KeyVals key',
98 "'$key' with prefix '$prefix' not defined in '" . join(",", @allkeysets) . "', " .
99 'were you perhaps using \setkeys instead of \setkeys*?') unless defined($$self{skipMissing});
100 return; }
101 # return either the first or all of the KeyVal objects
102 return ($$self{setAll} ? @keysets : ($keysets[0])); }
103  
104 sub canResolveKeyValFor {
105 my ($self, $key) = @_;
106 my $prefix = $$self{prefix};
107 # iterate over the keysets
108 foreach my $keyset (@{ $$self{keysets} }) {
109 return 1 if HasKeyVal($prefix, $keyset, $key); }
110 return 0; }
111  
112 # Return the 1st of the keysets, or the 1st one of the KeyVals itself
113 sub getPrimaryKeyValOf {
114 my ($self, $key, @keysets) = @_;
115 return (@keysets ? $keysets[0] : $$self{keysets}[0]); }
116  
117 #======================================================================
118 # Changing contained values
119 #======================================================================
120  
121 sub addValue {
122 my ($self, $key, $value, $useDefault, $noRebuild) = @_;
123  
124 # figure out the keyset(s) for the key to be added
125 my @keysets = $self->resolveKeyValFor($key);
126 my $pkeyset = $self->getPrimaryKeyValOf($key, @keysets);
127  
128 # and add the new tuple to the set of tuples
129 push(@{ $$self{tuples} },
130 [$key, ($useDefault ? keyval_get(keyval_qname($$self{prefix}, $pkeyset, $key), 'default') : $value),
131 $useDefault, $pkeyset, [@keysets]]);
132  
133 # we now need to rebuild, unless we were asked not to
134 # TODO: Maybe only update the last element?
135 $self->rebuild unless $noRebuild;
136 return; }
137  
138 sub setValue {
139 my ($self, $key, $value, $useDefault) = @_;
140 # delete the existing values by skipping key;
141 $self->rebuild($key);
142  
143 # if we have an array, we need to push all of them
144 if (ref $value eq 'ARRAY') {
145 foreach my $val (@{$value}) {
146 $self->addValue($key, $val, $useDefault, 1); }
147 $self->rebuild(); }
148 # if we have a single value, set it normally
149 elsif (defined($value)) {
150 $self->addValue($key, $value, $useDefault); }
151 return; }
152  
153 sub rebuild {
154 my ($self, $skip) = @_;
155 # the new data structures to create
156 my @newtuples = ();
157 my @pairs = ();
158 my %hash = ();
159 foreach my $tuple (@{ $$self{tuples} }) {
160 # take all the elements we need from the stack
161 my ($key, $value, $useDefault, $keyset, $keysets) = @$tuple;
162 # if we want to skip some values, we need to store new tuples
163 if (defined($skip)) {
164 next if $key eq $skip;
165 push(@newtuples, [$key, $value, $useDefault, $keyset, $keysets]) if defined($skip); }
166 # push key / value into the pair
167 push(@pairs, $key, $value);
168 # if we do not have a value yet, set it
169 if (!defined $hash{$key}) {
170 $hash{$key} = $value; }
171 # If we get a third value, push into an array
172 # This is unlikely to be what the caller expects!! But what else?
173 elsif (ref $hash{$key} eq 'ARRAY') {
174 push(@{ $hash{$key} }, $value); }
175 # If we get a second value, make an array
176 else {
177 $hash{$key} = [$hash{$key}, $value]; } }
178 # store all of the values
179 $$self{cachedPairs} = [@pairs];
180 $$self{cachedHash} = \%hash;
181 $$self{tuples} = [@newtuples] if defined($skip);
182 return; }
183  
184 #======================================================================
185 # parsing values from a gullet
186 #======================================================================
187  
188 # A KeyVal argument MUST be delimited by either braces or brackets (if optional)
189 # This method reads the keyval pairs INCLUDING the delimiters, (rather than
190 # parsing after the fact), since some values may have special catcode needs.
191 ##my $T_EQ = T_OTHER('='); # [CONSTANT]
192 ##my $T_COMMA = T_OTHER(','); # [CONSTANT]
193  
194 sub readFrom {
195 my ($self, $gullet, $until, %options) = @_;
196  
197 # if we want to force skipMissing keys, we set it up here
198 my $silenceMissing = $options{silenceMissing} ? 1 : 0;
199 my $skipMissing = $$self{skipMissing};
200 my $hookMissing = $$self{hookMissing};
201  
202 # if we want to silence all missing errors, store them in a hook
203 if ($silenceMissing) {
204 $$self{skipMissing} = 1;
205 $$self{hookMissing} = undef; }
206  
207 # read the opening token and figure out where we are
208 my $startloc = $gullet->getLocator;
209 # set and read tokens
210 my $open = $gullet->readToken;
211 # create arrays for key-value pairs and explicit values
212 my @kv = ();
213 my @explicits = ();
214 # iterate over all the key-value pairs to read
215 while (1) {
216 # gobble leading spaces
217 $gullet->skipSpaces;
218 if ($gullet->ifNext(T_BEGIN)) { # Protect against redundant {} wrapping
219 $gullet->readToken;
220 $gullet->unread($gullet->readBalanced()->stripBraces);
221 $gullet->skipSpaces; }
222 # Read a single keyword, get a delimiter and a set of keyword tokens
223 my ($ktoks, $delim) = $self->readKeyWordFrom($gullet, $until);
224  
225 # if there was no delimiter at the end, we throw an error
226 Error('expected', $until, $gullet,
227 "Fell off end expecting " . Stringify($until) . " while reading KeyVal key",
228 "key started at " . ToString($startloc))
229 unless $delim;
230  
231 # turn the key tokens into a string and trim whitespace
232 my $key = ToString($ktoks); $key =~ s/^\s+//; $key =~ s/\s+$//;
233 # if we have a non-empty key
234 if ($key) {
235 my $value;
236 my $isDefault;
237 # if we have an '=', we explcity assign a value
238 if ($delim->equals(T_OTHER('='))) {
239 $isDefault = 0;
240 # setup the key-codes to properly read
241 my $keyset = $self->getPrimaryKeyValOf($key, $self->resolveKeyValFor($key));
242 my $keytype = keyval_get(keyval_qname($$self{prefix}, $keyset, $key), 'type');
243 $keytype->setupCatcodes if $keytype;
244 # read until comma
245 my ($tok, @toks) = ();
246 while ((!defined($delim = $gullet->readMatch(T_OTHER(','), $until)))
247 && (defined($tok = $gullet->readToken()))) { # Copy next token to args
248 push(@toks, $tok,
249 ($tok->getCatcode == CC_BEGIN ? ($gullet->readBalanced, T_END) : ())); }
250 # reparse (and expand) the tokens representing the value
251 $value = Tokens(@toks)->stripBraces;
252 $value = $keytype->reparse($gullet, $value) if $keytype && $value;
253 # and cleanup
254 $keytype->revertCatcodes if $keytype; }
255 # we did not get an '=', and thus need to read the default value
256 else { $isDefault = 1; }
257 # and store our value please
258 $self->addValue($key, $value, $isDefault, 0) if (!$silenceMissing || $self->canResolveKeyValFor($key)); }
259  
260 # we finish if we have the last element
261 last if $delim->equals($until); }
262  
263 # rebuild and return nothing
264 $self->rebuild;
265  
266 # restore all settings if we silenced the missing keys
267 if ($silenceMissing) {
268 $$self{skipMissing} = $skipMissing;
269 $$self{hookMissing} = $hookMissing; }
270  
271 return; }
272  
273 sub readKeyWordFrom {
274 my ($self, $gullet, $close) = @_;
275 my @tokens = ();
276 my @delim = ($close, T_OTHER(','), T_OTHER('='));
277 $gullet->skipSpaces; # Skip leasding spaces
278 my $token;
279 while ($token = $gullet->readXToken) {
280 # skip to the next iteration if we have a paragraph
281 next if $token->equals(T_CS('\par'));
282 # if we have one of out delimiters, we end
283 last if grep { $token->equals($_) } @delim;
284 push(@tokens, $token); }
285 # return the tokens and the last token
286 return (Tokens(@tokens), $token); }
287  
288 #======================================================================
289 # Public accessors of all the values
290 #======================================================================
291 # Note: The API of this need to be stable, as people may be using it
292  
293 # return the value of a given key. If multiple values are given, return the last one.
294 sub getValue {
295 my ($self, $key) = @_;
296 my %hash = %{ $$self{cachedHash} };
297 my $value = $hash{$key};
298 # Since we (by default) accumulate lists of values when repeated,
299 # we need to provide the "common" thing: return the last value given.
300 return (!defined $value ? undef : (ref $value eq 'ARRAY' ? $$value[-1] : $value)); }
301  
302 # return a list of values for a given key
303 sub getValues {
304 my ($self, $key) = @_;
305 my %hash = %{ $$self{cachedHash} };
306 my $value = $hash{$key};
307 return (!defined $value ? () : (ref $value eq 'ARRAY' ? @$value : ($value))); }
308  
309 # return the set of key-value pairs
310 sub getPairs {
311 my ($self) = @_;
312 return @{ $$self{cachedPairs} }; }
313  
314 # returns a key => ToString(value)
315 sub getHash {
316 my ($self) = @_;
317 return %{ $$self{cachedHash} }; }
318  
319 # return a hash of key-value pairs
320 sub getKeyVals {
321 my ($self) = @_;
322 my %hash = %{ $$self{cachedHash} };
323 return \%hash; } # A COPY ??? or can it be the real hash?
324  
325 # checks if the value for a given key exists
326 sub hasKey {
327 my ($self, $key) = @_;
328 return exists $$self{cachedHash}{$key}; }
329  
330 #======================================================================
331 # Value Related Reversion
332 #======================================================================
333  
334 # This apparently means "the expansion of \setkeys"
335 sub setKeysExpansion {
336 my ($self) = @_;
337 my @skipkeys = @{ $$self{skip} };
338 my $setInternals = $$self{setInternals};
339 my $prefix = $$self{prefix};
340 # we might have to store values in a seperate token
341 my $rmmacro = (ref $$self{skipMissing} ? $$self{skipMissing} : undef);
342 my $hookMissing = $$self{hookMissing};
343 my @rmtokens = ();
344 # read in existing tokens (if they are defined)
345 if ($rmmacro && $STATE->lookupMeaning($rmmacro)) {
346 @rmtokens = LaTeXML::Package::Expand($rmmacro)->unlist; }
347 # define some xkeyval internals
348 my @tokens = ();
349 push(@tokens,
350 T_CS('\def'), T_CS('\XKV@fams'), T_BEGIN, Explode(join(',', @{ $$self{keysets} })), T_END,
351 T_CS('\def'), T_CS('\XKV@na'), T_BEGIN, Explode(join(',', @skipkeys)), T_END)
352 if $setInternals;
353  
354 # iterate over the key-value pairs
355 foreach my $tuple (@{ $$self{tuples} }) {
356 my ($key, $value, $useDefault, $keyset, $keysets) = @$tuple;
357 next if (grep { $_ eq $key } @skipkeys); # Skip these keys
358 my @keysets = @{$keysets};
359 # we might need to save the macros that weren't saved
360 if (scalar @keysets == 0) {
361 if ($rmmacro) {
362 push(@rmtokens, $self->revertKeyVal($key, $keyset, $value, $useDefault, (@rmtokens ? 0 : 1))); }
363 my @reversion = $self->revertKeyVal($key, $keyset, $value, $useDefault);
364 push(@tokens, $hookMissing, T_BEGIN, $self->revertKeyVal($key, $keyset, $value, $useDefault, 1), T_END) if $hookMissing;
365 next; }
366  
367 # and iterate over all valid keysets
368 foreach my $keyset (@keysets) {
369 my $qname = keyval_qname($prefix, $keyset, $key);
370 if (!HasKeyVal($prefix, $keyset, $key)) {
371 Info('undefined', 'Encountered unknown KeyVals key',
372 "'" . $key . "' with prefix '" . $prefix
373 . "' not defined in '" . join(",", $keyset) . "'"); }
374 elsif (keyval_get($qname, 'disabled')) { # if we are disabled, return an empty tokens
375 Warn('undefined', "`" . $key . "' has been disabled. "); }
376 else {
377 push(@tokens, # definition of 'xkeyval' internals (if applicable)
378 T_CS('\def'), T_CS('\XKV@prefix'), T_BEGIN, Explode($prefix . '@'), T_END,
379 T_CS('\def'), T_CS('\XKV@tfam'), T_BEGIN, Explode($keyset), T_END,
380 T_CS('\def'), T_CS('\XKV@header'), T_BEGIN, Explode($prefix . '@' . $keyset . '@'), T_END,
381 T_CS('\def'), T_CS('\XKV@tkey'), T_BEGIN, Explode($key), T_END
382 ) if $setInternals;
383 if ($useDefault) { # if it was not given explicitly, call the default macro
384 push(@tokens, T_CS('\\' . $qname . '@default')); }
385 else { # we have a value given, call the appropriate macro with it
386 push(@tokens, T_CS('\\' . $qname), T_BEGIN, Revert($value), T_END); }
387 # and reset the internals (if applicable)
388 push(@tokens,
389 T_CS('\def'), T_CS('\XKV@prefix'), T_BEGIN, T_END,
390 T_CS('\def'), T_CS('\XKV@tfam'), T_BEGIN, T_END,
391 T_CS('\def'), T_CS('\XKV@header'), T_BEGIN, T_END,
392 T_CS('\def'), T_CS('\XKV@tkey'), T_BEGIN, T_END) if $setInternals;
393 } } }
394  
395 # and assign the skipmissing macro with the other keys
396 push(@tokens, T_CS('\def'), $rmmacro, T_BEGIN, @rmtokens, T_END) if $rmmacro;
397 # reset all the internals (if applicable)
398 push(@tokens,
399 T_CS('\def'), T_CS('\XKV@fams'), T_BEGIN, T_END,
400 T_CS('\def'), T_CS('\XKV@na'), T_BEGIN, T_END) if $setInternals;
401  
402 return Tokens(@tokens); }
403  
404 sub beDigested {
405 my ($self, $stomach) = @_;
406  
407 if ($$self{was_digested}) {
408 Info('ignore', 'keyvals', $self,
409 "Skipping digestion of \\setkeys as requested (did you digest a KeyVals twice?) "); }
410 else {
411 $stomach->digest($self->setKeysExpansion); }
412  
413 # iterate over the tuples, digesting the values
414 my @newtuples = ();
415 foreach my $tuple (@{ $$self{tuples} }) {
416 my ($key, $value, $useDefault, $keyset, $keysets) = @$tuple;
417 my $keytype = keyval_get(keyval_qname($$self{prefix}, $keyset, $key), 'type');
418 my $v = (defined $value ?
419 ($keytype ? $keytype->digest($stomach, $value, undef) : $value->beDigested($stomach))
420 : undef);
421 push(@newtuples, [$key, $v, $useDefault, $keyset, $keysets]); }
422  
423 # then Copy the current object
424 my $new = LaTeXML::Core::KeyVals->new(
425 $$self{prefix}, $$self{keysets},
426 setAll => $$self{setAll}, setInternals => $$self{setInternals},
427 skip => $$self{skip}, skipMissing => $$self{skipMissing},
428 hookMissing => $$self{hookMissing},
429 was_digested => 1,
430 tuples => [@newtuples]);
431 return $new; }
432  
433 sub revert {
434 my ($self) = @_;
435 # read values from class
436 my @tokens = ();
437 # iterate over the key-value pairs
438 foreach my $tuple (@{ $$self{tuples} }) {
439 my ($key, $value, $useDefault, $keyset, $keysets) = @$tuple;
440 # revert a single token
441 if ($keyset) { # when is this undef?
442 push(@tokens, $self->revertKeyVal($key, $keyset, $value, $useDefault, (@tokens ? 0 : 1))); } }
443  
444 # and return the list of tokens
445 return Tokens(@tokens); }
446  
447 # turns this object into a string
448 sub toString {
449 my ($self) = @_;
450 my @kv = $self->getPairs;
451 my $string = '';
452 while (@kv) {
453 my ($key, $value) = (shift(@kv), shift(@kv));
454 $string .= ',' if $string;
455 $string .= $key . '=' . ToString($value); }
456 return $string; }
457  
458 sub revertKeyVal {
459 my ($self, $key, $keyset, $value, $useDefault, $isFirst) = @_;
460 # get the key-value definition
461 my $keytype = keyval_get(keyval_qname($$self{prefix}, $keyset, $key), 'type');
462 # define the tokens
463 my @tokens = ();
464 # write comma and key, unless in the first iteration
465 push(@tokens, T_OTHER(',')) if !$isFirst;
466 push(@tokens, Explode($key));
467 # write the default (if applicable)
468 if (!$useDefault && $value) {
469 push(@tokens, T_OTHER('='), ($keytype ? $keytype->revert($value) : Revert($value))); }
470 return @tokens; }
471  
472 # TODO: ????
473 sub unlist {
474 my ($self) = @_;
475 return $self; }
476  
477 #======================================================================
478 1;
479  
480 __END__