LaTeXML
view release on metacpan or search on metacpan
lib/LaTeXML/Package.pm view on Meta::CPAN
# /=====================================================================\ #
# | LaTeXML::Package | #
# | Exports of Defining forms for Package writers | #
# |=====================================================================| #
# | Part of LaTeXML: | #
# | Public domain software, produced as part of work done by the | #
# | United States Government & not subject to copyright in the US. | #
# |---------------------------------------------------------------------| #
# | Bruce Miller <bruce.miller@nist.gov> #_# | #
# | http://dlmf.nist.gov/LaTeXML/ (o o) | #
# \=========================================================ooo==U==ooo=/ #
package LaTeXML::Package;
use strict;
use warnings;
use Exporter;
use Scalar::Util qw(blessed);
use LaTeXML::Global;
use LaTeXML::Common::Object;
use LaTeXML::Common::Error;
use LaTeXML::Core::Token;
use LaTeXML::Core::Tokens;
use LaTeXML::Core::Box;
use LaTeXML::Core::List;
use LaTeXML::Core::Mouth::Binding;
use LaTeXML::Core::Definition;
use LaTeXML::Core::Parameters;
use LaTeXML::Common::Number;
use LaTeXML::Common::Float;
use LaTeXML::Common::Dimension;
use LaTeXML::Common::Glue;
use LaTeXML::Core::MuDimension;
use LaTeXML::Core::MuGlue;
# Extra objects typically used in Bindings
use LaTeXML::Core::Alignment;
use LaTeXML::Core::Array;
use LaTeXML::Core::KeyVal;
use LaTeXML::Core::KeyVals;
use LaTeXML::Core::Pair;
use LaTeXML::Core::PairList;
use LaTeXML::Common::Color;
use LaTeXML::Common::Color::rgb;
# Utitlities
use LaTeXML::Util::Pathname;
use LaTeXML::Util::WWW;
use LaTeXML::Common::XML;
use LaTeXML::Core::Rewrite;
use LaTeXML::Util::Radix;
use File::Which;
use Unicode::Normalize;
use Text::Balanced;
use Text::Unidecode;
use base qw(Exporter);
our @EXPORT = (qw(&DefAutoload &DefExpandable
&DefMacro &DefMacroI
&DefConditional &DefConditionalI &IfCondition &SetCondition
&DefPrimitive &DefPrimitiveI
&DefRegister &DefRegisterI &LookupRegister &AssignRegister &LookupDimension
&DefConstructor &DefConstructorI
&dualize_arglist &createXMRefs
&DefMath &DefMathI &DefEnvironment &DefEnvironmentI
&convertLaTeXArgs),
# Class, Package and File loading.
qw(&Input &InputContent &InputDefinitions &RequirePackage &LoadClass &LoadPool &FindFile
&DeclareOption &PassOptions &ProcessOptions &ExecuteOptions
&AddToMacro &AtBeginDocument &AtEndDocument),
# Counter support
qw(&NewCounter &CounterValue &SetCounter &AddToCounter &StepCounter &RefStepCounter &RefStepID &ResetCounter
&GenerateID &AfterAssignment
&MaybePeekLabel &MaybeNoteLabel),
# Document Model
qw(&Tag &DocType &RelaxNGSchema &RegisterNamespace &RegisterDocumentNamespace),
# Document Rewriting
qw(&DefRewrite &DefMathRewrite
&DefLigature &DefMathLigature),
# Mid-level support for writing definitions.
qw(&Expand &Invocation &Digest &DigestText &DigestIf &DigestLiteral
&RawTeX &Let &StartSemiverbatim &EndSemiverbatim
&Tokenize &TokenizeInternal
&IsEmpty),
# Font encoding
qw(&DeclareFontMap &FontDecode &FontDecodeString &LoadFontMap),
# Color
qw(&DefColor &DefColorModel &LookupColor),
# Support for structured/argument readers
qw(&ReadParameters &DefParameterType &DefColumnType),
# Access to State
qw(&LookupValue &AssignValue
&PushValue &PopValue &UnshiftValue &ShiftValue
&LookupMapping &AssignMapping &LookupMappingKeys
&LookupCatcode &AssignCatcode
&LookupMeaning &LookupDefinition &InstallDefinition &XEquals &IsDefined
&LookupMathcode &AssignMathcode
&LookupSFcode &AssignSFcode
&LookupLCcode &AssignLCcode
&LookupUCcode &AssignUCcode
&LookupDelcode &AssignDelcode
),
# Random low-level token or string operations.
qw(&CleanID &CleanLabel &CleanIndexKey &CleanClassName &CleanBibKey &NormalizeBibKey &CleanURL
&ComposeURL
&UTF
&roman &Roman),
# Math & font state.
qw(&MergeFont),
qw(&CheckOptions),
# Resources
qw(&RequireResource &ProcessPendingResources),
@LaTeXML::Global::EXPORT,
# And export those things exported by these Core & Common packages.
@LaTeXML::Common::Object::EXPORT,
@LaTeXML::Common::Error::EXPORT,
@LaTeXML::Core::Token::EXPORT,
@LaTeXML::Core::Tokens::EXPORT,
@LaTeXML::Core::Box::EXPORT,
lib/LaTeXML/Package.pm view on Meta::CPAN
$key =~ s/[^a-zA-Z0-9]//g;
$key = NFC($key); # just to be safe(?)
return $key; }
sub CleanBibKey {
my ($key) = @_;
$key = ToString($key); # Originally lc() here, but let's preserve case till Postproc.
$key =~ s/^\s+//s; $key =~ s/\s+$//s; # Trim leading/trailing, in any case
$key =~ s/\s//sg;
return $key; }
# Return the bibkey in a form to ACTUALLY lookup.
# Usually use CleanBibKey to preserve key in the original form (case)
sub NormalizeBibKey {
my ($key) = @_;
return ($key ? lc(CleanBibKey($key)) : undef); }
sub CleanURL {
my ($url) = @_;
$url = ToString($url);
$url =~ s/^\s+//s; $url =~ s/\s+$//s; # Trim leading/trailing, in any case
$url =~ s/\\~\{\}/~/g;
return $url; }
sub ComposeURL {
my ($base, $url, $fragid) = @_;
$base = ToString($base); $base =~ s/\/$// if $base; # remove trailing /
$url = ToString($url);
$fragid = ToString($fragid);
return CleanURL(join('',
($base ?
($url =~ /^\w+:/ ? '' # already has protocol, so is absolute url
: $base . ($url =~ /^\// ? '' : '/')) # else start w/base, possibly /
: ''),
$url,
($fragid ? '#' . CleanID($fragid) : ''))); }
#======================================================================
# Defining new Control-sequence Parameter types.
#======================================================================
my $parameter_options = { # [CONSTANT]
nargs => 1, reversion => 1, optional => 1, novalue => 1,
beforeDigest => 1, afterDigest => 1,
semiverbatim => 1, undigested => 1 };
sub DefParameterType {
my ($type, $reader, %options) = @_;
CheckOptions("DefParameterType $type", $parameter_options, %options);
AssignMapping('PARAMETER_TYPES', $type, { reader => $reader, %options });
return; }
sub DefColumnType {
my ($proto, $expansion) = @_;
if ($proto =~ s/^(.)//) {
my $char = $1;
$proto =~ s/^\s*//;
# Defer
# $expansion = TokenizeInternal($expansion) unless ref $expansion;
$proto = parseParameters($proto, $char);
DefMacroI(T_CS('\NC@rewrite@' . $char), $proto, $expansion); }
else {
Warn('expected', 'character', undef, "Expected Column specifier"); }
return; }
#======================================================================
# Allocated registers.
# We ASSUME the same set of \count positions used by TeX & LaTeX
# for recording the next available position in \count,\dimen,\skip,\muskip.
our %allocations = (
'\count' => '\count10', '\dimen' => '\count11', '\skip' => '\count12', '\muskip' => '\count13',
'\box' => '\count14', '\toks' => '\count15');
sub allocateRegister {
my ($type) = @_;
if (my $addr = $allocations{$type}) { # $addr is a Register but MUST be stored as \count<#>
if (my $n = $STATE->lookupValue($addr)) {
my $next = $n->valueOf + 1;
$STATE->assignValue($addr => Number($next), 'global');
return $type . $next; }
else { # If allocations not set up, punt to unallocated register
return; } }
else {
Error('misdefined', $type, undef, "Type $type is not an allocated register type");
return; } }
#======================================================================
# Counters
#======================================================================
# This is modelled on LaTeX's counter mechanisms, but since it also
# provides support for ID's, even where there is no visible reference number,
# it is defined in general.
# These id's should be both unique, and parallel the visible reference numbers
# (as much as possible). Also, for consistency, we add id's to unnumbered
# document elements (eg from \section*); this requires an additional counter
# (eg. UNsection) and mechanisms to track it.
# Defines a new counter named $ctr.
# If $within is defined, $ctr will be reset whenever $within is incremented.
# Keywords:
# idprefix : specifies a prefix to be used in formatting ID's for document structure elements
# counted by this counter. Ie. subsection 3 in section 2 might get: id="S2.SS3"
# idwithin : specifies that the ID is composed from $idwithin's ID,, even though
# the counter isn't numbered within it. (mainly to avoid duplicated ids)
# nested : a list of counters that correspond to scopes which are "inside" this one.
# Whenever any definitions scoped to this counter are deactivated,
# the inner counter's scopes are also deactivated.
# NOTE: I'm not sure this is even a sensible implementation,
# or why inner should be different than the counters reset by incrementing this counter.
sub NewCounter {
my ($ctr, $within, %options) = @_;
my $unctr = "UN$ctr"; # UNctr is counter for generating ID's for UN-numbered items.
if ($within && ($within ne 'document') && !LookupDefinition(T_CS("\\c\@$within"))) {
NewCounter($within); }
my $cs = T_CS("\\c\@$ctr");
DefRegisterI($cs, undef, Number(0), allocate => '\count');
AfterAssignment();
AssignValue("\\cl\@$ctr" => Tokens(), 'global') unless LookupValue("\\cl\@$ctr");
DefRegisterI(T_CS("\\c\@$unctr"), undef, Number(0));
AssignValue("\\cl\@$unctr" => Tokens(), 'global') unless LookupValue("\\cl\@$unctr");
my $x;
AssignValue("\\cl\@$within" =>
Tokens(T_CS($ctr), T_CS($unctr), (($x = LookupValue("\\cl\@$within")) ? $x->unlist : ())),
'global') if $within;
AssignValue("\\cl\@UN$within" =>
Tokens(T_CS($unctr), (($x = LookupValue("\\cl\@UN$within")) ? $x->unlist : ())),
'global') if $within;
AssignValue('nested_counters_' . $ctr => $options{nested}, 'global') if $options{nested};
# default is equivalent to \arabic{ctr}, but w/o using the LaTeX macro!
DefMacroI(T_CS("\\the$ctr"), undef, sub {
ExplodeText(CounterValue($ctr)->valueOf); },
scope => 'global');
if (!LookupDefinition(T_CS("\\p\@$ctr"))) {
DefMacroI(T_CS("\\p\@$ctr"), undef, Tokens(), scope => 'global'); }
my $prefix = $options{idprefix};
AssignValue('@ID@prefix@' . $ctr => $prefix, 'global') if $prefix;
$prefix = LookupValue('@ID@prefix@' . $ctr) || $ctr unless $prefix;
$prefix = CleanID($prefix);
if (defined $prefix) {
if (my $idwithin = $options{idwithin} || $within) {
DefMacroI(T_CS("\\the$ctr\@ID"), undef,
"\\expandafter\\ifx\\csname the$idwithin\@ID\\endcsname\\\@empty"
. "\\else\\csname the$idwithin\@ID\\endcsname.\\fi"
. " $prefix\\csname \@$ctr\@ID\\endcsname",
scope => 'global'); }
else {
DefMacroI(T_CS("\\the$ctr\@ID"), undef, "$prefix\\csname \@$ctr\@ID\\endcsname",
scope => 'global'); }
DefMacroI(T_CS("\\\@$ctr\@ID"), undef, "0", scope => 'global'); }
return; }
sub CounterValue {
my ($ctr) = @_;
$ctr = ToString(Expand($ctr)) if ref $ctr;
my $value = LookupRegister('\c@' . $ctr);
if (!$value) {
Warn('undefined', $ctr, $STATE->getStomach,
"Counter '$ctr' was not defined; assuming 0");
$value = Number(0); }
return $value; }
sub AfterAssignment {
if (my $after = $STATE->lookupValue('afterAssignment')) {
$STATE->assignValue(afterAssignment => undef, 'global');
$STATE->getStomach->getGullet->unread($after); } # primitive returns boxes, so these need to be digested!
return; }
sub SetCounter {
my ($ctr, $value) = @_;
$ctr = ToString(Expand($ctr)) if ref $ctr;
AssignRegister('\c@' . $ctr => $value, 'global');
AfterAssignment();
DefMacroI(T_CS("\\\@$ctr\@ID"), undef, Tokens(Explode($value->valueOf)), scope => 'global');
return; }
sub AddToCounter {
my ($ctr, $value) = @_;
$ctr = ToString(Expand($ctr)) if ref $ctr;
my $v = CounterValue($ctr)->add($value);
AssignRegister('\c@' . $ctr => $v, 'global');
AfterAssignment();
DefMacroI(T_CS("\\\@$ctr\@ID"), undef, Tokens(Explode($v->valueOf)), scope => 'global');
return; }
sub StepCounter {
my ($ctr, $noreset) = @_;
my $value = CounterValue($ctr);
my $newvalue = $value->add(Number(1));
AssignRegister("\\c\@$ctr" => $newvalue, 'global');
AfterAssignment();
DefMacroI(T_CS("\\\@$ctr\@ID"), undef, Tokens(Explode($newvalue->valueOf)),
scope => 'global');
# and reset any within counters!
if (!$noreset) {
if (my $nested = LookupValue("\\cl\@$ctr")) {
foreach my $c ($nested->unlist) {
ResetCounter(ToString($c)); } } }
# DigestIf(T_CS("\\the$ctr"));
return; }
# HOW can we retract this?
sub RefStepCounter {
my ($type, $noreset) = @_;
my $ctr = LookupMapping('counter_for_type', $type) || $type;
$ctr = ToString(Expand($ctr)) if ref $ctr;
StepCounter($ctr, $noreset);
maybePreemptRefnum($ctr);
my $iddef = $STATE->lookupDefinition(T_CS("\\the$ctr\@ID"));
my $has_id = $iddef && ((!defined $iddef->getParameters) || ($iddef->getParameters->getNumArgs == 0));
DefMacroI(T_CS('\@currentlabel'), undef, T_CS("\\the$ctr"), scope => 'global');
DefMacroI(T_CS('\@currentID'), undef, T_CS("\\the$ctr\@ID"), scope => 'global') if $has_id;
my $id = $has_id && CleanID(ToString(DigestLiteral(T_CS("\\the$ctr\@ID"))));
my $refnum = DigestText(T_CS("\\the$ctr"));
my $tags = Digest(Invocation(T_CS('\lx@make@tags'), $type));
# Any scopes activated for previous value of this counter (& any nested counters) must be removed.
# This may also include scopes activated for \label
deactivateCounterScope($ctr);
# And install the scope (if any) for this reference number.
AssignValue(current_counter => $ctr, 'local');
my $scope = $ctr . ':' . ToString($refnum);
AssignValue('scopes_for_counter:' . $ctr => [$scope], 'local');
$STATE->activateScope($scope);
return (
($tags ? (tags => $tags) : ()),
($has_id ? (id => $id) : ())); }
# Internal: Use a label-derived reference number and/or ID
# instead of the traditional counter based ones.
# Since the \label{} determins the reference number and ID,
# we MUST sniff out the label BEFORE we call RefStepCounter/RefStepID !!!!!
# (see MaybePeekLabel below; and also MaybeNoteLabel for use within
# captions & certain equation environments)
# Assign a sub to LABEL_MAPPING_HOOK: &sub($label,$counter,$norefnum)
# to return the desired refnum and id for a given object.
sub maybePreemptRefnum {
my ($ctr, $norefnum) = @_;
if (my $mapper = LookupValue('LABEL_MAPPING_HOOK')) {
my $hj_refnum = T_CS('\_PREEMPTED_REFNUM_' . $ctr);
my $hj_id = T_CS('\_PREEMPTED_ID_' . $ctr);
# First, restore the \the<ctr> and \the<ctr>@ID macros to defaults
if (!$norefnum && LookupMeaning($hj_refnum)) {
Let(T_CS('\the' . $ctr), $hj_refnum, 'global'); }
if (LookupMeaning($hj_id)) {
Let(T_CS('\the' . $ctr . '@ID'), $hj_id, 'global'); }
my $label = LookupValue('PEEKED_LABEL');
my ($fixedrefnum, $fixedid) = &$mapper($label, $ctr, $norefnum);
if (!$norefnum && $fixedrefnum) {
if (!LookupMeaning($hj_refnum)) { # Save for later
Let($hj_refnum, T_CS('\the' . $ctr), 'global'); }
DefMacroI('\the' . $ctr, undef, $fixedrefnum, scope => 'global'); }
if ($fixedid) {
if (!LookupMeaning($hj_id)) { # Save for later
Let($hj_id, T_CS('\the' . $ctr . '@ID'), 'global'); }
DefMacroI('\the' . $ctr . '@ID', undef, $fixedid, scope => 'global'); }
AssignValue(PEEKED_LABEL => undef, 'global'); # CONSUME the label
AssignValue(PROCESSED_LABEL => $label, 'global'); # Note that we've consumed the label
}
return; }
# Use to peek for FOLLOWING \label{...} to support label-derived refererence numbers
sub MaybePeekLabel {
if (LookupValue('LABEL_MAPPING_HOOK')) {
my $gullet = $STATE->getStomach->getGullet;
my $peek = $gullet->readNonSpace;
if (Equals($peek, T_CS('\label'))) {
StartSemiverbatim();
my $arg = $gullet->readArg();
EndSemiverbatim();
my $label = CleanLabel($arg, '');
AssignValue(PEEKED_LABEL => $label, 'global');
$gullet->unread(T_BEGIN, $arg, T_END); }
else {
AssignValue(PROCESSED_LABEL => undef, 'global');
AssignValue(PEEKED_LABEL => undef, 'global'); }
$gullet->unread($peek); }
return; }
# Use to note a discovered label to support label-derived refererence numbers
# Can by used by \label, among others. Note we only record the label
# if it hasn't already been peeked, and consumed.
sub MaybeNoteLabel {
my ($label) = @_;
if (LookupValue('LABEL_MAPPING_HOOK')) {
$label = CleanLabel($label, '');
my $processed = LookupValue('PROCESSED_LABEL');
if (!$processed || ($processed ne $label)) { # Only if not already processed
AssignValue(PROCESSED_LABEL => undef, 'global');
AssignValue(PEEKED_LABEL => $label, 'global'); } }
return; }
sub deactivateCounterScope {
my ($ctr) = @_;
if (my $scopes = LookupValue('scopes_for_counter:' . $ctr)) {
map { $STATE->deactivateScope($_) } @$scopes; }
foreach my $inner_ctr (@{ LookupValue('nested_counters_' . $ctr) || [] }) {
deactivateCounterScope($inner_ctr); }
return; }
# For UN-numbered units
sub RefStepID {
my ($type) = @_;
my $ctr = LookupMapping('counter_for_type', $type) || $type;
my $unctr = "UN$ctr";
StepCounter($unctr);
maybePreemptRefnum($ctr, 1);
DefMacroI(T_CS("\\\@$ctr\@ID"), undef,
Tokens(T_OTHER('x'), Explode(LookupValue('\c@' . $unctr)->valueOf)),
scope => 'global');
DefMacroI(T_CS('\@currentID'), undef, T_CS("\\the$ctr\@ID"));
my $id = CleanID(ToString(DigestLiteral(T_CS("\\the$ctr\@ID"))));
return (id => $id); }
sub ResetCounter {
my ($ctr) = @_;
AssignRegister('\c@' . $ctr => Number(0), 'global');
AssignRegister('\c@UN' . $ctr => Number(0), 'global') unless $ctr =~ /^UN/; # but not UNUN
DefMacroI(T_CS("\\\@$ctr\@ID"), undef, Tokens(T_OTHER('0')),
scope => 'global');
# and reset any within counters!
if (my $nested = LookupValue("\\cl\@$ctr")) {
foreach my $c ($nested->unlist) {
ResetCounter(ToString($c)); } }
return; }
#**********************************************************************
# This function computes an xml:id for a node, if it hasn't already got one.
# It is suitable for use in Tag afterOpen as
# Tag('ltx:para',afterOpen=>sub { GenerateID(@_,'p'); });
# It generates an id of the form <parentid>.<prefix><number>
# The parent node (the one with ID=<parentid>) also maintains a counter
# stored in an attribute _ID_counter_<prefix> recording the last used
# <number> for <prefix> amongst its descendents.
sub GenerateID {
my ($document, $node, $whatsit, $prefix) = @_;
# If node doesn't already have an id, and can have one
# make a "sensible" id for it. Avoid adding unneeded/unwanted ids until as late as possible,
# since it causes lots of book-keeping when rearranging XML (you have to monitor id references!)
if (!$node->hasAttribute('xml:id') && $document->canHaveAttribute($node, 'xml:id')
# but isn't a _Capture_ node (which ultimately should disappear)
&& ($document->getNodeQName($node) ne 'ltx:_Capture_')) {
my $id = '';
if (my $prelim_id = $node->getAttribute('_pregenerated_id_')) {
$id = $prelim_id; } # Or an id generated while id'ing a child
else {
my @p = ();
my $p = $node->parentNode;
# Walk up to root or an id'd node...
while ($p && ($p->nodeType == XML_ELEMENT_NODE)) {
if ($document->getNodeQName($p) ne 'ltx:_Capture_') {
push(@p, $p);
last if $id = $p->getAttribute('xml:id'); }
$p = $p->parentNode; }
$prefix = 'id' unless $prefix || $id;
if (LookupValue('GENERATE_IDS') && @p) {
# If generating ALL ids, prepare a chain of ids back down to the current node
while ($p = pop(@p)) {
$id = generateID_nextid($p, (@p ? '' : $prefix), $id);
$p[-1]->setAttribute('_pregenerated_id_', $id) if @p; } }
else {
# Or base the id on the id'd ancestor's id.
$id = generateID_nextid($p[-1] || $document->documentElement, $prefix, $id); } }
# We may still be in a case where we got a raw numeric id. If so, guard with a prefix:
$id = "id$id" if $id =~ /^\d/;
$document->setAttribute($node, 'xml:id' => $id); }
return; }
sub generateID_nextid {
my ($parent, $prefix, $id_sofar) = @_;
my $ctrkey = '_ID_counter_' . ($prefix ? $prefix . '_' : '');
my $ctr = $parent->getAttribute($ctrkey) || 0;
$id_sofar = ($id_sofar ? $id_sofar . '.' : '') . ($prefix ? $prefix : '') . (++$ctr);
$parent->setAttribute($ctrkey => $ctr);
return $id_sofar; }
#======================================================================
#
#======================================================================
lib/LaTeXML/Package.pm view on Meta::CPAN
elsif ($ref eq 'LaTeXML::Core::Tokens') {
return 0 unless IsEmpty($thing->unlist); }
elsif ($ref eq 'LaTeXML::Core::Token') {
my $cc = $$thing[1];
return 0 if ($cc == CC_LETTER) || ($cc == CC_OTHER) || ($cc == CC_ACTIVE) || ($cc == CC_CS); }
elsif (!$thing->getProperty('isEmpty')) {
if ($ref eq 'LaTeXML::Core::Box') {
my $s = $thing->getString;
return 0 if (defined $s) && length($s); }
elsif ($ref eq 'LaTeXML::Core::List') {
return 0 unless IsEmpty($thing->unlist); }
elsif ($ref eq 'LaTeXML::Core::Whatsit') {
# Sneaky Whatsit property for something (an arg) that stands-in for the whatsit's content.
if (my $body = $thing->getProperty('content_box')) {
return 0 unless IsEmpty($body); }
else {
return 0; } } } }
return 1; }
#======================================================================
# Non-exported support for defining forms.
#======================================================================
sub CheckOptions {
my ($operation, $allowed, %options) = @_;
my @badops = grep { !$$allowed{$_} } keys %options;
Error('misdefined', $operation, $STATE->getStomach,
"$operation does not accept options:" . join(', ', @badops)) if @badops;
return; }
sub requireMath {
my ($cs) = @_;
$cs = ToString($cs);
Warn('unexpected', $cs, $STATE->getStomach,
"$cs should only appear in math mode") unless LookupValue('IN_MATH');
return; }
sub forbidMath {
my ($cs) = @_;
$cs = ToString($cs);
Warn('unexpected', $cs, $STATE->getStomach,
"$cs should not appear in math mode") if LookupValue('IN_MATH');
return; }
#**********************************************************************
# Definitions
#**********************************************************************
sub DefAutoload {
my ($cs, $defnfile) = @_;
my $csname = (ref $cs ? ToString($cs) : $cs);
$csname = '\\' . $csname unless $cs =~ /^\\/;
$cs = T_CS($csname) unless ref $cs;
$defnfile =~ s/\.ltxml$//;
if ($defnfile =~ /^(.*?)\.(pool|sty|cls)$/) {
my ($name, $type) = ($1, $2);
# if already loaded, or set, DONT redefine!
if (!(
LookupValue($name . '.' . $type . '_loaded') ||
LookupValue($name . '.' . $type . '.ltxml_loaded') ||
LookupMeaning($cs))) {
AssignMapping('autoload_' . $defnfile, $csname => 1);
DefMacroI($cs, undef, sub {
ClearAutoLoad($defnfile);
if ($type eq 'pool') { LoadPool($name); } # Load appropriate definitions
elsif ($type eq 'cls') { LoadClass($name); }
else { RequirePackage($name); }
($cs); }); } } # Then return the original cs, so that it's be re-tried.
else {
Warning('unexpected', $defnfile, undef, "Don't know how to autoload $csname from $defnfile"); }
return; }
# Undefine ALL autoload triggers for this definition file.
sub ClearAutoLoad {
my ($defnfile) = @_;
$defnfile =~ s/\.ltxml$//;
foreach my $trigger (LookupMappingKeys('autoload_' . $defnfile)) {
$STATE->assign_internal('meaning', $trigger => undef, 'global'); }
return; }
#======================================================================
# Defining Expandable Control Sequences.
#======================================================================
# Define an expandable control sequence. It will be expanded in the Gullet.
# The $replacement should be a LaTeXML::Core::Tokens (the arguments will be
# substituted for any #1,...), or a sub which returns a list of tokens (or just return;).
# Those tokens, if any, will be reinserted into the input.
# There are no options to these definitions.
my $expandable_options = { # [CONSTANT]
scope => 1, locked => 1 };
sub DefExpandable {
my ($proto, $expansion, %options) = @_;
Warn('deprecated', 'DefExpandable', $STATE->getStomach,
"DefExpandable ($proto) is deprecated; use DefMacro");
DefMacro($proto, $expansion, %options);
return; }
# Define a Macro: Essentially an alias for DefExpandable
# For convenience, the $expansion can be a string which will be tokenized.
my $macro_options = { # [CONSTANT]
scope => 1, locked => 1, mathactive => 1,
protected => 1, robust => 1, outer => 1, long => 1,
nopackParameters => 1 };
# Defines $cs as protected call to the mangled name "\cs ", which it returns
sub defRobustCS {
my ($cs, %options) = @_;
my $defcs = T_CS($_[0]->getString . ' ');
$STATE->installDefinition(LaTeXML::Core::Definition::Expandable->new($cs, undef,
Tokens(T_CS('\protect'), $defcs), locked => $options{locked}),
$options{scope}); # should be \x@protect?
return $defcs; }
sub DefMacro {
my ($proto, $expansion, %options) = @_;
CheckOptions("DefMacro ($proto)", $macro_options, %options);
DefMacroI(parsePrototype($proto), $expansion, %options);
return; }
sub DefMacroI {
my ($cs, $paramlist, $expansion, %options) = @_;
if (!defined $expansion) { $expansion = Tokens(); }
# Optimization: Defer till macro actually used
# elsif (!ref $expansion) { $expansion = TokenizeInternal($expansion); }
if ((length($cs) == 1) && $options{mathactive}) {
$STATE->assignMathcode($cs => 0x8000, $options{scope}); }
$cs = coerceCS($cs);
$paramlist = parseParameters($paramlist, $cs) if defined $paramlist && !ref $paramlist;
my $defcs = ($options{robust} ? defRobustCS($cs, %options) : $cs);
$STATE->installDefinition(LaTeXML::Core::Definition::Expandable->new($defcs, $paramlist, $expansion, %options),
$options{scope});
AssignValue(ToString($cs) . ":locked" => 1, 'global') if $options{locked};
return; }
#======================================================================
# Defining Conditional Control Sequences.
#======================================================================
# Define a conditional control sequence. Its processing takes place in
# the Gullet. The test is applied to the arguments (if any),
# which determines which branch is executed.
# If the test is undefined, the conditional is a "user defined" one;
# Two additional primitives are defined \footrue and \foofalse;
# the test is then determined by the most recently called of those.
# If you supply a skipper instead of a test, it is also applied to the arguments
# and should skip to the right place in the following \or, \else, \fi.
# This is ONLY used for \ifcase.
my $conditional_options = { # [CONSTANT]
scope => 1, locked => 1, skipper => 1 };
sub DefConditional {
my ($proto, $test, %options) = @_;
CheckOptions("DefConditional ($proto)", $conditional_options, %options);
DefConditionalI(parsePrototype($proto), $test, %options);
return; }
sub DefConditionalI {
my ($cs, $paramlist, $test, %options) = @_;
$cs = coerceCS($cs);
my $csname = ToString($cs);
# Special cases...
if ($csname eq '\fi') {
$STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new(
$cs, undef, undef, conditional_type => 'fi', %options),
$options{scope}); }
elsif ($csname eq '\else') {
$STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new(
$cs, undef, undef, conditional_type => 'else', %options),
$options{scope}); }
elsif ($csname eq '\or') {
$STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new(
$cs, undef, undef, conditional_type => 'or', %options),
$options{scope}); }
elsif ($csname eq '\unless') {
$STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new($cs, $paramlist, $test,
conditional_type => 'unless', %options),
$options{scope}); }
elsif ($csname =~ /^\\(..)(.*)$/) {
my ($prefix, $name) = ($1, $2);
if ($prefix ne 'if') {
Warn('misdefined', $cs, $STATE->getStomach,
"The conditional " . Stringify($cs) . " is being defined but doesn't start with \\if"); }
if ((defined $name) && ($name ne 'case')
&& (!defined $test)) { # user-defined conditional, like with \newif
DefMacroI(T_CS('\\' . $name . 'true'), undef, Tokens(T_CS('\let'), $cs, T_CS('\iftrue')));
DefMacroI(T_CS('\\' . $name . 'false'), undef, Tokens(T_CS('\let'), $cs, T_CS('\iffalse')));
Let($cs, T_CS('\iffalse')); }
else {
# For \ifcase, the parameter list better be a single Number !!
$paramlist = parseParameters($paramlist, $cs) if defined $paramlist && !ref $paramlist;
$STATE->installDefinition(LaTeXML::Core::Definition::Conditional->new($cs, $paramlist, $test,
conditional_type => 'if', %options),
$options{scope}); }
}
else {
Error('misdefined', $cs, $STATE->getStomach,
"The conditional " . Stringify($cs) . " is being defined but doesn't start with \\if"); }
AssignValue(ToString($cs) . ":locked" => 1) if $options{locked};
return; }
sub IfCondition {
my ($if, @args) = @_;
my $gullet = $STATE->getStomach->getGullet;
$if = coerceCS($if);
my ($defn, $test);
if (($defn = $STATE->lookupDefinition($if))
&& (($$defn{conditional_type} || '') eq 'if') && ($test = $defn->getTest)) {
return &$test($gullet, @args); }
elsif (XEquals($if, T_CS('\iftrue'))) {
return 1; }
elsif (XEquals($if, T_CS('\iffalse'))) {
return 0; }
else {
Error('expected', 'conditional', $gullet,
"Expected a conditional, got '" . ToString($if) . "'");
return; } }
# Used only for regular \newif type conditions
sub SetCondition {
my ($if, $value, $scope) = @_;
my ($defn, $test);
# We'll accept any conditional \ifxxx, providing it takes no arguments
if (($defn = $STATE->lookupDefinition($if)) && (($$defn{conditional_type} || '') eq 'if')
&& !$defn->getParameters) {
Let($if, ($value ? T_CS('\iftrue') : T_CS('\iffalse')), $scope) }
else {
Error('expected', 'conditional', $STATE->getStomach,
"Expected a conditional defined by \\newif, got '" . ToString($if) . "'"); }
return; }
#======================================================================
# Define a primitive control sequence.
#======================================================================
# Primitives are executed in the Stomach.
# The $replacement should be a sub which returns nothing, or a list of Box's or Whatsit's.
# The options are:
# isPrefix : 1 for things like \global, \long, etc.
# registerType : for parameters (but needs to be worked into DefParameter, below).
my $primitive_options = { # [CONSTANT]
isPrefix => 1, scope => 1, mode => 1, font => 1,
requireMath => 1, forbidMath => 1,
beforeDigest => 1, afterDigest => 1,
bounded => 1, locked => 1, alias => 1, robust => 1,
outer => 1, long => 1 };
lib/LaTeXML/Package.pm view on Meta::CPAN
mode => 1, requireMath => 1, forbidMath => 1, font => 1,
alias => 1, reversion => 1, sizer => 1, properties => 1,
nargs => 1,
beforeDigest => 1, afterDigest => 1, beforeConstruct => 1, afterConstruct => 1,
captureBody => 1, scope => 1, bounded => 1, locked => 1,
outer => 1, long => 1, robust => 1 };
sub inferSizer {
my ($sizer, $reversion) = @_;
return (defined $sizer ? $sizer
: ((defined $reversion) && (!ref $reversion) && ($reversion =~ /^(?:#\w+)*$/)
? $reversion : undef)); }
sub DefConstructor {
my ($proto, $replacement, %options) = @_;
CheckOptions("DefConstructor ($proto)", $constructor_options, %options);
DefConstructorI(parsePrototype($proto), $replacement, %options);
return; }
sub DefConstructorI {
my ($cs, $paramlist, $replacement, %options) = @_;
$cs = coerceCS($cs);
$paramlist = parseParameters($paramlist, $cs) if defined $paramlist && !ref $paramlist;
my $mode = $options{mode};
my $bounded = $options{bounded};
# Not sure robust entirely makes sense for Constructors, other than LaTeXML vs LaTeX mismatch
my $defcs = ($options{robust} ? defRobustCS($cs, %options) : $cs);
$STATE->installDefinition(LaTeXML::Core::Definition::Constructor
->new($defcs, $paramlist, $replacement,
beforeDigest => flatten(($options{requireMath} ? (sub { requireMath($cs); }) : ()),
($options{forbidMath} ? (sub { forbidMath($cs); }) : ()),
($mode ? (sub { $_[0]->beginMode($mode); })
: ($bounded ? (sub { $_[0]->bgroup; }) : ())),
($options{font} ? (sub { MergeFont(%{ $options{font} }); }) : ()),
$options{beforeDigest}),
afterDigest => flatten($options{afterDigest},
($mode ? (sub { $_[0]->endMode($mode) })
: ($bounded ? (sub { $_[0]->egroup; }) : ()))),
beforeConstruct => flatten($options{beforeConstruct}),
afterConstruct => flatten($options{afterConstruct}),
nargs => $options{nargs},
alias => (defined $options{alias} ? $options{alias}
: ($options{robust} ? $cs : undef)),
reversion => $options{reversion},
sizer => inferSizer($options{sizer}, $options{reversion}),
captureBody => $options{captureBody},
properties => $options{properties} || {},
outer => $options{outer},
long => $options{long}),
$options{scope});
AssignValue(ToString($cs) . ":locked" => 1) if $options{locked};
return; }
#======================================================================
# Support for XMDual
# Perhaps it would be better to use a label(-like) indirection here,
# so all ID's can stay in the desired format?
sub getXMArgID {
StepCounter('@XMARG');
DefMacroI(T_CS('\@@XMARG@ID'), undef, Tokens(Explode(LookupRegister('\c@@XMARG')->valueOf)),
scope => 'global');
return Expand(T_CS('\the@XMARG@ID')); }
# Given a list of Tokens (to be expanded into mathematical objects)
# return two lists:
# (1) The Tokens' wrapped in an XMAarg, with an ID added
# (2) a corresponding list of Tokens creating XMRef's to those IDs
# Ah, but there are complications!!!
# On the one hand, arguments may be hidden, never appearing on the presentation side
# (all will be passed to the content side); This argues for putting the XMArg's on the content side.
# OTOH, they ought to be on the presentation side, so that they can be expanded & digested in
# the proper context they will be presented, and pick up all the styling (font size, displaystyle..)
# I don't know how to work around the latter, so we'll put args on the presentation side,
# UNLESS they are hidden, in which case they'll be on the content side.
# So, how do we know if they're hidden? We'll scan the presentation for #\d, that's how!
sub dualize_arglist {
my ($presentation, @args) = @_;
my %used = ();
$presentation = ToString($presentation);
$presentation =~ s/#(\d)/{ $used{$1}++; }/ge; # Get the args that were actually used!
my (@cargs, @pargs);
my $i = 0;
foreach my $arg (@args) {
$i++;
if (!(defined $arg) || IsEmpty($arg)) { # undefined or empty args, just pass through
push(@pargs, $arg);
push(@cargs, $arg); }
elsif ($used{$i}) { # used in presentation?
my $id = getXMArgID();
push(@pargs, Invocation(T_CS('\lx@xmarg'), $id, $arg)); # put XMArg in presentation
push(@cargs, Invocation(T_CS('\lx@xmref'), $id)); }
else { # Hidden arg, put XMArg in content.
my $id = getXMArgID();
push(@cargs, Invocation(T_CS('\lx@xmarg'), $id, $arg));
push(@pargs, Invocation(T_CS('\lx@xmref'), $id)); } }
return ([@cargs], [@pargs]); }
# Given a list of XML nodes (either libxml nodes, or array representations)
# return a list of XMRef's referring to those nodes;
# ensure each source node has an ID (if already instanciated as XML)
# or _xmkey if still in array rep. since it will get an ID later, and the connection re-made)
# Note that ltx:XMHint nodes are ephemeral and shouldn't be ref'd!
# likewise, we avoid creating XMRefs to XMRefs
sub createXMRefs {
my ($document, @args) = @_;
my @refs = ();
foreach my $arg (@args) {
my $isarray = (ref $arg eq 'ARRAY');
my $qname = ($isarray ? $$arg[0] : $document->getNodeQName($arg));
my $box = ($isarray ? $$arg[1]{_box} : $document->getNodeBox($arg));
# XMHint's are ephemeral, they may disappear; so just clone it w/o id
if ($qname eq 'ltx:XMHint') {
my %attr = ($isarray ? %{ $$arg[1] }
: (map { $document->getNodeQName($_) => $_->getValue } $arg->attributes));
delete $attr{'xml:id'};
push(@refs, [$qname, {%attr}]); }
# Likewise, clone an XMRef (w/o any attributes or id ?) rather than create an XMRef to an XMRef.
elsif ($qname eq 'ltx:XMRef') {
my $key = ($isarray ? $$arg[1]{_xmkey} : $arg->getAttribute('_xmkey'));
my $id = ($isarray ? $$arg[1]{idref} : $arg->getAttribute('idref'));
lib/LaTeXML/Package.pm view on Meta::CPAN
. "($qpresentation)"
: "<ltx:XMTok role='#role' scriptpos='#scriptpos' stretchy='#stretchy'"
. " font='#font' $cons_attr$end_tok")
: "<ltx:XMApp role='#role' scriptpos='#scriptpos' stretchy='#stretchy'>"
. "<ltx:XMTok $cons_attr font='#font' role='#operator_role'"
. " scriptpos='#operator_scriptpos' stretchy='#operator_stretchy' $end_tok"
. join('', map { "<ltx:XMArg>#$_</ltx:XMArg>" } 1 .. $nargs)
. "</ltx:XMApp>"),
defmath_common_constructor_options($cs, $presentation,
sizer => sub {
# my $font = $_[1]->getFont || LaTeXML::Common::Font->mathDefault;
my $font = LaTeXML::Common::Font->mathDefault;
$font->computeStringSize($presentation); },
%options)), $options{scope});
return; }
#======================================================================
# Define a LaTeX environment
# Note that the body of the environment is treated is the 'body' parameter in the constructor.
my $environment_options = { # [CONSTANT]
mode => 1, requireMath => 1, forbidMath => 1,
properties => 1, nargs => 1, font => 1,
beforeDigest => 1, afterDigest => 1,
afterDigestBegin => 1, beforeDigestEnd => 1, afterDigestBody => 1,
beforeConstruct => 1, afterConstruct => 1,
reversion => 1, sizer => 1, scope => 1, locked => 1 };
sub DefEnvironment {
my ($proto, $replacement, %options) = @_;
CheckOptions("DefEnvironment ($proto)", $environment_options, %options);
my ($name, $paramlist) = Text::Balanced::extract_bracketed($proto, '{}');
$name =~ s/[\{\}]//g;
$paramlist =~ s/^\s*//;
DefEnvironmentI($name, $paramlist, $replacement, %options);
return; }
sub DefEnvironmentI {
my ($name, $paramlist, $replacement, %options) = @_;
my $mode = $options{mode};
$name = ToString($name) if ref $name;
$paramlist = parseParameters($paramlist, $name) if defined $paramlist && !ref $paramlist;
# Magic form: CS with name \begin{env} bypasses some LaTeX
# However, in pure LaTeX would usually have expanded to \env
# and would have skipped spaces before parsing args, if any.
my $paramlist_skips;
if ($paramlist && $paramlist->getNumArgs) {
$paramlist_skips = LaTeXML::Core::Parameters->new(
LaTeXML::Core::Parameter->new('SkipSpaces', 'SkipSpaces'),
$paramlist->getParameters); }
# This is for the common case where the environment is opened by \begin{env}
my $sizer = inferSizer($options{sizer}, $options{reversion});
$STATE->installDefinition(LaTeXML::Core::Definition::Constructor
->new(T_CS("\\begin{$name}"), $paramlist_skips, $replacement,
beforeDigest => flatten(($options{requireMath} ? (sub { requireMath($name); }) : ()),
($options{forbidMath} ? (sub { forbidMath($name); }) : ()),
sub { $_[0]->bgroup; },
sub { my $b = LookupValue('@environment@' . $name . '@atbegin');
($b ? Digest(@$b) : ()); },
($mode ? (sub { $_[0]->setMode($mode); }) : ()),
sub { AssignValue(current_environment => $name);
DefMacroI('\@currenvir', undef, $name); },
($options{font} ? (sub { MergeFont(%{ $options{font} }); }) : ()),
$options{beforeDigest}),
afterDigest => flatten($options{afterDigestBegin}),
afterDigestBody => flatten($options{afterDigestBody}),
beforeConstruct => flatten(sub { $STATE->pushFrame; }, $options{beforeConstruct}),
# Curiously, it's the \begin whose afterConstruct gets called.
afterConstruct => flatten($options{afterConstruct}, sub { $STATE->popFrame; }),
nargs => $options{nargs},
captureBody => 1,
properties => $options{properties} || {},
(defined $options{reversion} ? (reversion => $options{reversion}) : ()),
(defined $sizer ? (sizer => $sizer) : ()),
), $options{scope});
$STATE->installDefinition(LaTeXML::Core::Definition::Constructor
->new(T_CS("\\end{$name}"), "", "",
beforeDigest => flatten($options{beforeDigestEnd},
sub { my $e = LookupValue('@environment@' . $name . '@atend');
($e ? Digest(@$e) : ()); },
),
afterDigest => flatten($options{afterDigest},
sub { my $env = LookupValue('current_environment');
if (!$env || ($name ne $env)) {
my @lines = ();
my $nf = $STATE->getFrameDepth;
for (my $f = 0 ; $f <= $nf ; $f++) { # Get currently open environments & locators
if (my $e = $STATE->isValueBound('current_environment', $f)
&& $STATE->valueInFrame('current_environment', $f)) {
my $locator = ToString($STATE->valueInFrame('groupInitiatorLocator', $f));
push(@lines, $e . ' ' . $locator); } }
Error('unexpected', "\\end{$name}", $_[0],
"Can't close environment $name;", "Current are:", @lines); }
return; },
sub { $_[0]->egroup; },
),
), $options{scope});
# For the uncommon case opened by \csname env\endcsname
$STATE->installDefinition(LaTeXML::Core::Definition::Constructor
->new(T_CS("\\$name"), $paramlist, $replacement,
beforeDigest => flatten(($options{requireMath} ? (sub { requireMath($name); }) : ()),
($options{forbidMath} ? (sub { forbidMath($name); }) : ()),
($mode ? (sub { $_[0]->beginMode($mode); }) : ()),
($options{font} ? (sub { MergeFont(%{ $options{font} }); }) : ()),
$options{beforeDigest}),
afterDigest => flatten($options{afterDigestBegin}),
afterDigestBody => flatten($options{afterDigestBody}),
beforeConstruct => flatten(sub { $STATE->pushFrame; }, $options{beforeConstruct}),
# Curiously, it's the \begin whose afterConstruct gets called.
afterConstruct => flatten($options{afterConstruct}, sub { $STATE->popFrame; }),
nargs => $options{nargs},
captureBody => T_CS("\\end$name"), # Required to capture!!
properties => $options{properties} || {},
(defined $options{reversion} ? (reversion => $options{reversion}) : ()),
(defined $sizer ? (sizer => $sizer) : ()),
), $options{scope});
$STATE->installDefinition(LaTeXML::Core::Definition::Constructor
->new(T_CS("\\end$name"), "", "",
beforeDigest => flatten($options{beforeDigestEnd}),
afterDigest => flatten($options{afterDigest},
($mode ? (sub { $_[0]->endMode($mode); }) : ())),
), $options{scope});
lib/LaTeXML/Package.pm view on Meta::CPAN
# Note that we are reading definitions (and recursive input is assumed also definitions)
my $was_interpreting = LookupValue('INTERPRETING_DEFINITIONS');
# And that if we're interpreting this TeX file of definitions,
# we probably should interpret any TeX files IT loads.
my $was_including_styles = LookupValue('INCLUDE_STYLES');
AssignValue('INTERPRETING_DEFINITIONS' => 1);
# If we're reading in these definitions, probaly will accept included ones?
# (but not forbid ltxml ?)
AssignValue('INCLUDE_STYLES' => 1);
# When set, this variable allows redefinitions of locked defns.
# It is set in before/after methods to allow local rebinding of commands
# but loading of sources & bindings is typically done in before/after methods of constructors!
# This re-locks defns during reading of TeX packages.
local $LaTeXML::Core::State::UNLOCKED = 0;
$stomach->getGullet->readingFromMouth(
LaTeXML::Core::Mouth->create($pathname, %mouth_options,
content => LookupValue($pathname . '_contents')),
sub {
my ($gullet) = @_;
my $token;
while ($token = $gullet->readXToken(0)) {
next if $token->equals(T_SPACE);
$stomach->invokeToken($token); } });
AssignValue('INTERPRETING_DEFINITIONS' => $was_interpreting);
AssignValue('INCLUDE_STYLES' => $was_including_styles);
Let(T_CS('\ver@' . $request), T_CS('\fmtversion'), 'global');
return; }
sub loadTeXContent {
my ($pathname) = @_;
my $gullet = $STATE->getStomach->getGullet;
# If there is a file-specific declaration file (name.latexml), load it first!
my $file = $pathname;
$file =~ s/\.tex//;
if (my $conf = !pathname_is_literaldata($pathname)
&& pathname_find("$file.latexml", paths => LookupValue('SEARCHPATHS'))) {
loadLTXML($conf, $conf); }
$gullet->openMouth(LaTeXML::Core::Mouth->create($pathname, notes => 1,
content => LookupValue($pathname . '_contents')), 0);
return; }
#======================================================================
# Option Handling for Packages and Classes
# Declare an option for the current package or class
# If $option is undef, it is the default.
# $code can be a sub (as a primitive), or a string to be expanded.
# (effectively a macro)
DebuggableFeature('packageoptions', 'Processing package & class options');
sub DeclareOption {
my ($option, $code) = @_;
$option = ToString($option) if ref $option;
PushValue('@declaredoptions', $option) if $option;
my $cs = ($option ? '\ds@' . $option : '\default@ds');
Debug("Declaring option: " . ($option ? $option : '<default>')) if $LaTeXML::DEBUG{packageoptions};
if ((!defined $code) || (ref $code eq 'CODE')) {
DefPrimitiveI($cs, undef, $code); }
else {
DefMacroI($cs, undef, $code); }
return; }
# Pass the sequence of @options to the package $name (if $ext is 'sty'),
# or class $name (if $ext is 'cls').
sub PassOptions {
my ($name, $ext, @options) = @_;
PushValue('opt@' . $name . '.' . $ext, map { ToString($_) } @options);
Debug("Passing to $name.$ext options: " . join(', ', @options)) if $LaTeXML::DEBUG{packageoptions};
return; }
# Process the options passed to the currently loading package or class.
# If inorder=>1, they are processed in the order given (like \ProcessOptions*),
# otherwise, they are processed in the order declared.
# Unless noundefine=>1 (like for \ExecuteOptions), all option definitions
# undefined after execution.
my $processoptions_options = { # [CONSTANT]
inorder => 1, keysets => 1 };
sub ProcessOptions {
my (%options) = @_;
CheckOptions("ProcessOptions", $processoptions_options, %options);
my $name = $STATE->lookupDefinition(T_CS('\@currname')) && ToString(Expand(T_CS('\@currname')));
my $ext = $STATE->lookupDefinition(T_CS('\@currext')) && ToString(Expand(T_CS('\@currext')));
my @declaredoptions = @{ LookupValue('@declaredoptions') };
my @curroptions = @{ (defined($name) && defined($ext)
&& LookupValue('opt@' . $name . '.' . $ext)) || [] };
my @classoptions = @{ LookupValue('class_options') || [] };
Debug("ProcessOptions for $name.$ext\n"
. " declared: " . join(',', @declaredoptions) . "\n"
. " provided: " . join(',', @curroptions) . "\n"
. " class: " . join(',', @classoptions)) if $LaTeXML::DEBUG{packageoptions};
my $defaultcs = T_CS('\default@ds');
# Execute options in declared order (unless \ProcessOptions*)
if ($options{inorder}) { # Execute options in the order passed in (eg. \ProcessOptions*)
foreach my $option (@classoptions) { # process global options, but no error
if (executeOption_internal($option, %options)) { } }
foreach my $option (@curroptions) {
if (executeOption_internal($option, %options)) { }
elsif (executeDefaultOption_internal($option)) { } } }
else { # Execute options in declared order (eg. \ProcessOptions)
foreach my $option (@declaredoptions) {
if (grep { $option eq $_ } @curroptions, @classoptions) {
@curroptions = grep { $option ne $_ } @curroptions; # Remove it, since it's been handled.
executeOption_internal($option, %options); } }
# Now handle any remaining options (eg. default options), in the given order.
foreach my $option (@curroptions) {
executeDefaultOption_internal($option); } }
# Now, undefine the handlers?
foreach my $option (@declaredoptions) {
Let('\ds@' . $option, '\relax'); }
return; }
sub executeOption_internal {
my ($option, %options) = @_;
my $cs = T_CS('\ds@' . $option);
# Simplified keyval options for classes & packages
# Note that the option is a string with an "=" at this point.
if ($options{keysets} && ($option =~ /^(.*)=(.*)$/)) {
my ($key, $value) = ($1, $2);
foreach my $keyset (@{ $options{keysets} }) {
my $qname = keyval_qname('KV', $keyset, $key);
if (my $keytype = keyval_get($qname, 'type')) {
Debug("PROCESS KeyVal OPTION $key => $value") if $LaTeXML::DEBUG{packageoptions};
Digest(Tokens(T_CS('\\' . $qname), T_BEGIN, Revert($value), T_END));
return 1; } } }
if ($STATE->lookupDefinition($cs)) {
Debug("PROCESS OPTION $option") if $LaTeXML::DEBUG{packageoptions};
DefMacroI('\CurrentOption', undef, $option);
AssignValue('@unusedoptionlist',
[grep { $_ ne $option } @{ LookupValue('@unusedoptionlist') || [] }]);
Digest($cs);
return 1; }
else {
return; } }
sub executeDefaultOption_internal {
my ($option) = @_;
Debug("PROCESS DEFAULT OPTION $option") if $LaTeXML::DEBUG{packageoptions};
# presumably should NOT remove from @unusedoptionlist ?
DefMacroI('\CurrentOption', undef, $option);
Digest(T_CS('\default@ds'));
return 1; }
sub ExecuteOptions {
my (@options) = @_;
my %unhandled = ();
foreach my $option (@options) {
if (executeOption_internal($option)) { }
else {
$unhandled{$option} = 1; } }
foreach my $option (keys %unhandled) {
Info('unexpected', $option, $STATE->getStomach->getGullet,
"Unexpected options passed to ExecuteOptions '$option'"); }
return; }
sub resetOptions {
AssignValue('@declaredoptions', []);
Let('\default@ds',
(ToString(Expand(T_CS('\@currext'))) eq 'cls'
? '\OptionNotUsed' : '\@unknownoptionerror'));
return; }
sub AddToMacro {
my ($cs, @tokens) = @_;
$cs = T_CS($cs) unless ref $cs;
@tokens = map { (ref $_ ? $_ : TokenizeInternal($_)) } @tokens;
# Needs error checking!
my $defn = $STATE->lookupDefinition($cs);
if (!defined $defn || !$defn->isExpandable) {
Warn('unexpected', $cs, $STATE->getStomach->getGullet,
ToString($cs) . " is not an expandable control sequence", "Ignoring addition"); }
else {
DefMacroI($cs, undef, Tokens(map { $_->unlist }
map { (blessed $_ ? $_ : TokenizeInternal($_)) } ($defn->getExpansion, @tokens)),
nopackParameters => 1, scope => 'global', locked => $$defn{locked}); }
return; }
#======================================================================
my $inputdefinitions_options = { # [CONSTANT]
options => 1, withoptions => 1, handleoptions => 1,
type => 1, as_class => 1, noltxml => 1, notex => 1, noerror => 1, after => 1,
at_letter => 1, searchpaths_only => 1, reloadable => 1 };
# options=>[options...]
# withoptions=>boolean : pass options from calling class/package
# after=>code or tokens or string as $name.$type-h@@k macro. (executed after the package is loaded)
# Returns the path that was loaded, or undef, if none found.
sub InputDefinitions {
my ($name, %options) = @_;
$name = ToString($name) if ref $name;
$name =~ s/^\s*//; $name =~ s/\s*$//;
CheckOptions("InputDefinitions ($name)", $inputdefinitions_options, %options);
my $prevname = $options{handleoptions} && $STATE->lookupDefinition(T_CS('\@currname')) && ToString(Expand(T_CS('\@currname')));
my $prevext = $options{handleoptions} && $STATE->lookupDefinition(T_CS('\@currext')) && ToString(Expand(T_CS('\@currext')));
# This file will be treated somewhat as if it were a class
# IF as_class is true
# OR if it is loaded by such a class, and has withoptions true!!! (yikes)
$options{as_class} = 1 if $options{handleoptions} && $options{withoptions}
&& grep { $prevname eq $_ } @{ LookupValue('@masquerading@as@class') || [] };
$options{raw} = 1 if $options{noltxml}; # so it will be read as raw by Gullet.!L!
my $astype = ($options{as_class} ? 'cls' : $options{type} || 'sty');
if ($astype eq 'cls' and $options{options}) {
PushValue(class_options => @{ $options{options} });
# ? Expand {\zap@space#2 \@empty}%
DefMacroI('\@classoptionslist', undef, join(',', @{ $options{options} })); }
my $filename = $name;
$filename .= '.' . $options{type} if $options{type};
if ($options{options} && scalar(@{ $options{options} })) {
if (my $prevoptions = LookupValue($filename . '_loaded_with_options')) {
my $curroptions = join(',', @{ $options{options} });
Info('unexpected', 'options', $STATE->getStomach->getGullet,
"Option clash for file $filename with options '$curroptions'",
"previously loaded with '$prevoptions'") unless $curroptions eq $prevoptions; } }
if (my $file = FindFile($filename, type => $options{type},
notex => $options{notex}, noltxml => $options{noltxml}, searchpaths_only => $options{searchpaths_only})) {
my $pushpop = LookupDefinition(T_CS('\@pushfilename'))
&& LookupDefinition(T_CS('\@popfilename'));
if ($options{handleoptions}) {
# Bookkeeping of what is being loaded so that LaTeX can run hooks.
# Tricky: expl3 wants to know the fill CURRENTLY being read; \@currname,\@currext set LATER.
# Recent expl3 appends \@expl@push@filename@aux@@ which takes THREE arguments!!!
# These arguments mysteriously appear in \@onefilewith@ptions, MUCH later than \@pushfilename
# We place the neaded data after \@pushfilename, but since we're Digesting in isolation,
# they'll disappear if they aren't consumed by expl3. Whew!
Digest(Tokens(T_CS('\@pushfilename'),
T_BEGIN, T_END, T_BEGIN, T_END, T_BEGIN, Explode($name), T_END))
if $pushpop;
# For \RequirePackageWithOptions, pass the options from the outer class/style to the inner one.
if (my $passoptions = $options{withoptions} && $prevname
&& LookupValue('opt@' . $prevname . "." . $prevext)) {
# Only pass those class options that are declared by the package!
my @declaredoptions = @{ LookupValue('@declaredoptions') };
my @topass = ();
foreach my $op (@$passoptions) {
push(@topass, $op) if grep { $op eq $_ } @declaredoptions; }
PassOptions($name, $astype, @topass) if @topass; }
DefMacroI('\@currname', undef, Tokens(Explode($name)));
DefMacroI('\@currext', undef, Tokens(Explode($astype)));
# reset options (Note reset & pass were in opposite order in LoadClass ????)
resetOptions();
PassOptions($name, $astype, @{ $options{options} || [] }); # passed explicit options.
# Note which packages are pretending to be classes.
PushValue('@masquerading@as@class', $name) if $options{as_class};
DefMacroI(T_CS('\\' . $name . '.' . $astype . '-h@@k'), undef, $options{after} || '');
DefMacroI(T_CS('\opt@' . $name . '.' . $astype), undef,
Tokens(Explode(join(',', @{ LookupValue('opt@' . $name . "." . $astype) }))));
}
AssignValue($filename . '_loaded_with_options' => join(',', @{ $options{options} }), 'global')
if $options{options};
my ($fdir, $fname, $ftype) = pathname_split($file);
if ($options{handleoptions}) {
# Add an appropriately faked entry into \@filelist
my ($d, $n, $e) = ($fdir, $fname, $ftype); # If ftype is ltxml, reparse to get sty/cls!
($d, $n, $e) = pathname_split(pathname_concat($d, $n)) if $e eq 'ltxml'; # Fake it???
my @p = ($STATE->lookupDefinition(T_CS('\@filelist'))
? Expand(T_CS('\@filelist'))->unlist : ());
my @n = Explode($e ? $n . '.' . $e : $n);
DefMacroI('\@filelist', undef, (@p ? Tokens(@p, T_OTHER(','), @n) : Tokens(@n))); }
if ($ftype eq 'ltxml') {
loadLTXML($filename, $file, reloadable => $options{reloadable}); } # Perl module.
else {
# Special case -- add a default resource if we're loading a raw .cls file as a first choice.
# Raw class interpretations needs _some_ styling as baseline.
if (!$options{noltxml} && ($file =~ /\.cls$/)) {
RelaxNGSchema("LaTeXML");
RequireResource('ltx-article.css'); }
loadTeXDefinitions($filename, $file, %options); }
if ($options{handleoptions}) {
Digest(T_CS('\\' . $name . '.' . $astype . '-h@@k'));
DefMacroI('\@currname', undef, Tokens(Explode($prevname))) if $prevname;
DefMacroI('\@currext', undef, Tokens(Explode($prevext))) if $prevext;
Digest(T_CS('\@popfilename')) if $pushpop;
resetOptions(); } # And reset options afterwards, too.
return $file; }
elsif (!$options{noerror}) {
$STATE->noteStatus(missing => $name . ($options{type} ? '.' . $options{type} : ''));
# We'll only warn about a missing file of definitions: it may be ignorable or never used.
# if there ARE problems, they'll likely produce their own errors!
Warn('missing_file', $name, $STATE->getStomach->getGullet,
"Can't find "
. ($options{notex} ? "binding for " : "")
. (($options{type} && $definition_name{ $options{type} }) || 'definitions') . ' '
. $name,
"Anticipate undefined macros or environments",
maybeReportSearchPaths()); }
return; }
my $require_options = { # [CONSTANT]
options => 1, withoptions => 1, type => 1, as_class => 1,
noltxml => 1, notex => 1, raw => 1, after => 1, searchpaths_only => 1 };
# This (& FindFile) needs to evolve a bit to support reading raw .sty (.def, etc) files from
# the standard texmf directories. Maybe even use kpsewhich itself (INSTEAD of pathname_find ???)
# Another potentially useful option might be that if we are reading a raw file,
# perhaps it should just get digested immediately, since it shouldn't contribute any boxes.
sub RequirePackage {
my ($package, %options) = @_;
$package = ToString($package) if ref $package;
if ($options{raw}) {
delete $options{raw}; $options{notex} = 0;
Warn('deprecated', 'raw', $STATE->getStomach->getGullet,
"RequirePackage option raw is obsolete; it is not needed"); }
CheckOptions("RequirePackage ($package)", $require_options, %options);
# We'll usually disallow raw TeX, unless the option explicitly given, or globally set.
$options{notex} = 1
if !defined $options{notex} && !LookupValue('INCLUDE_STYLES') && !$options{noltxml};
# Top-level requires can be limited to local sources via searchpaths_only => 1
$options{searchpaths_only} //= (!$options{notex}) && ((LookupValue('INCLUDE_STYLES') || '') eq 'searchpaths');
my $success = InputDefinitions($package, type => $options{type} || 'sty', handleoptions => 1,
# Pass classes options if we have NONE!
withoptions => !($options{options} && @{ $options{options} }),
%options);
maybeRequireDependencies($package, $options{type} || 'sty') unless $success;
return; }
my $loadclass_options = { # [CONSTANT]
options => 1, withoptions => 1, after => 1, notex => 1, searchpaths_only => 1 };
sub LoadClass {
my ($class, %options) = @_;
$options{notex} = 1
if !defined $options{notex} && !LookupValue('INCLUDE_CLASSES') && !$options{noltxml};
# Top-level requires can be limited to local sources via searchpaths_only => 1
$options{searchpaths_only} //= (!$options{notex}) && ((LookupValue('INCLUDE_CLASSES') || '') eq 'searchpaths');
$class = ToString($class) if ref $class;
CheckOptions("LoadClass ($class)", $loadclass_options, %options);
# Note that we'll handle errors specifically for this case.
if (my $success = InputDefinitions($class, type => 'cls', notex => $options{notex}, handleoptions => 1, noerror => 1,
%options)) {
return $success; }
else {
lib/LaTeXML/Package.pm view on Meta::CPAN
else {
Error('missing_file', "$pool.pool.ltxml", $STATE->getStomach->getGullet,
"Can't find binding for pool $pool (installation error)",
maybeReportSearchPaths());
return; } }
# Somewhat an act of desperation in contexts like arXiv
# where we may have a bunch of random styles & classes that load other packages
# whose macros are then expected to be present.
# We scan the source for \RequirePackage & \usepackage and load the ones that have bindings.
# This is almost safe: the packages may only be loaded unconditionally, and we don't notice that!
sub maybeRequireDependencies {
my ($file, $type) = @_;
if (my $path = FindFile($file, type => $type, noltxml => 1)) {
local $/ = undef;
my $IN;
if (open($IN, '<', $path)) {
my $code = <$IN>;
close($IN);
my @classes = ();
my @packages = ();
my %dups = ();
my $collect = sub {
my ($packages, $options) = @_;
foreach my $p (split(/\s*,\s*/, $packages)) {
if (!$dups{$p} && !LookupValue($p . '.sty.ltxml_loaded')) {
push(@packages, [$p, $options]); $dups{$p} = 1; } } };
# Yes, Regexps on TeX code! Ugh!!! Well, this is an act of desperation anyway :>
$code =~ s/%[^\n]*\n//gs; # strip comments
$code =~ s/\\RequirePackage\s*(?:\[([^\]]*)\])?\s*\{([^\}]*)\}/ &$collect($2,$1); /xegs;
# Ugh. \usepackage, too
$code =~ s/\\usepackage\s*(?:\[([^\]]*)\])?\s*\{([^\}]*)\}/ &$collect($2,$1); /xegs;
# Even more ugh; \LoadClass
if ($type eq 'cls') {
$code =~ s/\\LoadClass\s*(?:\[([^\]]*)\])?\s*\{([^\}]*)\}/ push(@classes,[$2,$1]); /xegs; }
Info('dependencies', 'dependencies', undef,
"Loading dependencies for $path: " . join(',', map { $$_[0]; } @classes, @packages)) if scalar(@classes) || scalar(@packages);
foreach my $pair (@classes) {
my ($class, $options) = @$pair;
if (FindFile($class, type => 'cls', notex => 1)) {
LoadClass($class, ($options ? (options => [split(/\s*,\s*/, $options)]) : ())); } }
foreach my $pair (@packages) {
my ($package, $options) = @$pair;
if (FindFile($package, type => 'sty', notex => 1)) {
RequirePackage($package, ($options ? (options => [split(/\s*,\s*/, $options)]) : ())); } } }
else {
Warn('I/O', 'read', undef, "Couldn't open $path to scan dependencies", $!); } }
return; }
sub AtBeginDocument {
my (@operations) = @_;
AssignValue('@at@begin@document', []) unless LookupValue('@at@begin@document');
foreach my $op (@operations) {
next unless $op;
my $t = ref $op;
if (!$t) { # Presumably String?
$op = TokenizeInternal($op); }
elsif ($t eq 'CODE') {
my $tn = T_CS(ToString($op));
DefMacroI($tn, undef, $op);
$op = $tn; }
PushValue('@at@begin@document', $op->unlist); }
return; }
sub AtEndDocument {
my (@operations) = @_;
AssignValue('@at@end@document', []) unless LookupValue('@at@end@document');
foreach my $op (@operations) {
next unless $op;
my $t = ref $op;
if (!$t) { # Presumably String?
$op = TokenizeInternal($op); }
elsif ($t eq 'CODE') {
my $tn = T_CS(ToString($op));
DefMacroI($tn, undef, $op);
$op = $tn; }
PushValue('@at@end@document', $op->unlist); }
return; }
#======================================================================
#
my $fontmap_options = { # [CONSTANT]
family => 1 };
sub DeclareFontMap {
my ($name, $map, %options) = @_;
CheckOptions("DeclareFontMap", $fontmap_options, %options);
my $mapname = ToString($name)
. ($options{family} ? '_' . $options{family} : '')
. '_fontmap';
AssignValue($mapname => $map, 'global');
return; }
# Decode a codepoint using the fontmap for a given font and/or fontencoding.
# If $encoding not provided, then lookup according to the current font's
# encoding; the font family may also be used to choose the fontmap (think tt fonts!).
# When $implicit is false, we are "explicitly" asking for a decoding, such as
# with \char, \mathchar, \symbol, DeclareTextSymbol and such cases.
# In such cases, only codepoints specifically within the map are covered; the rest are undef.
# If $implicit is true, we'll decode token content that has made it to the stomach:
# We're going to assume that SOME sort of handling of input encoding is taking place,
# so that if anything above 128 comes in, it must already be Unicode!.
# The lower half plane still needs to go through decoding, though, to deal
# with TeX's rearrangement of ASCII...
sub FontDecode {
my ($code, $encoding, $implicit) = @_;
return if !defined $code || ($code < 0);
my ($map, $font);
if (!$encoding) {
$font = LookupValue('font');
$encoding = $font->getEncoding || 'OT1'; }
if ($encoding && ($map = LoadFontMap($encoding))) { # OK got some map.
my ($family, $fmap);
if ($font && ($family = $font->getFamily) && ($fmap = LookupValue($encoding . '_' . $family . '_fontmap'))) {
$map = $fmap; } } # Use the family specific map, if any.
if ($implicit) {
if ($map && ($code < 128)) {
return $$map[$code]; }
else {
return pack('U', $code); } }
else {
return ($map ? $$map[$code] : undef); } }
sub FontDecodeString {
my ($string, $encoding, $implicit) = @_;
return if !defined $string;
my ($map, $font);
if (!$encoding) {
$font = LookupValue('font');
$encoding = $font->getEncoding; }
if ($encoding && ($map = LoadFontMap($encoding))) { # OK got some map.
my ($family, $fmap);
if ($font && ($family = $font->getFamily) && ($fmap = LookupValue($encoding . '_' . $family . '_fontmap'))) {
$map = $fmap; } } # Use the family specific map, if any.
return join('', grep { defined $_ }
map { ($implicit ? (($map && ($_ < 128)) ? $$map[$_] : pack('U', $_))
: ($map ? $$map[$_] : undef)) }
map { ord($_) } split(//, $string)); }
sub LoadFontMap {
my ($encoding) = @_;
my $map = LookupValue($encoding . '_fontmap');
if (!$map && !LookupValue($encoding . '_fontmap_failed_to_load')) {
AssignValue($encoding . '_fontmap_failed_to_load' => 1); # Stop recursion?
InputDefinitions(lc($encoding), type => 'fontmap', noerror => 1);
if ($map = LookupValue($encoding . '_fontmap')) { # Got map?
AssignValue($encoding . '_fontmap_failed_to_load' => 0); }
else {
Info('fontmap', $encoding, undef, "Couldn't find fontmap for '$encoding'");
AssignValue($encoding . '_fontmap_failed_to_load' => 1, 'global'); } }
return $map; }
#======================================================================
# Color
sub LookupColor {
my ($name) = @_;
if (my $color = LookupValue('color_' . $name)) {
return $color; }
else {
Error('undefined', $name, $STATE->getStomach, "color '$name' is undefined...");
return Black; } }
sub DefColor {
my ($name, $color, $scope) = @_;
return unless ref $color;
my ($model, @spec) = @$color;
$scope = 'global' if $STATE->lookupDefinition(T_CS('\ifglobalcolors')) && IfCondition(T_CS('\ifglobalcolors'));
AssignValue('color_' . $name => $color, $scope);
# We could store these pieces separately,or in a list for above,
# so that extract could use them more reasonably?
# This is perhaps too xcolor specific?
DefMacroI('\\\\color@' . $name, undef,
'\relax\relax{' . join(' ', $model, @spec) . '}{' . $model . '}{' . join(',', @spec) . '}',
scope => $scope);
return; }
# Need 3 things for Derived Models:
# derivedfrom : the core model that this model is "derived from"
# convertto : code to convert to the (a) core model
# convertfrom : code to convert from the core model
sub DefColorModel {
my ($model, $coremodel, $tocore, $fromcore) = @_;
AssignValue('derived_color_model_' . $model => [$coremodel, $tocore, $fromcore], 'global');
return; }
#======================================================================
# Defining Rewrite rules that act on the DOM
# These are applied after the document is completely constructed
my $rewrite_options = { # [CONSTANT]
label => 1, scope => 1, xpath => 1, match => 1,
attributes => 1, replace => 1, regexp => 1, select => 1 };
sub DefRewrite {
my (@specs) = @_;
CheckOptions("DefRewrite", $rewrite_options, @specs);
PushValue('DOCUMENT_REWRITE_RULES',
LaTeXML::Core::Rewrite->new('text', processRewriteSpecs(0, @specs)));
return; }
sub DefMathRewrite {
my (@specs) = @_;
CheckOptions("DefMathRewrite", $rewrite_options, @specs);
PushValue('DOCUMENT_REWRITE_RULES',
LaTeXML::Core::Rewrite->new('math', processRewriteSpecs(1, @specs)));
return; }
sub processRewriteSpecs {
my ($math, @specs) = @_;
my @procspecs = ();
my $delimiter = ($math ? '$' : '');
while (@specs) {
my $k = shift(@specs);
my $v = shift(@specs);
# Make sure match & replace are (at least) tokenized
if (($k eq 'match') || ($k eq 'replace')) {
if (ref $v eq 'ARRAY') {
$v = [map { (ref $_ ? $_ : Tokenize($delimiter . $_ . $delimiter)) } @$v]; }
elsif (!ref $v) {
$v = Tokenize($delimiter . $v . $delimiter); } }
push(@procspecs, $k, $v); }
return @procspecs; }
#======================================================================
# Defining "Ligatures" rules that act on the DOM
# These are actually a sort of rewrite that is applied while the doom
# is being constructed, in particular as each node is closed.
my $ligature_options = { # [CONSTANT]
fontTest => 1 };
sub DefLigature {
my ($regexp, $replacement, %options) = @_;
lib/LaTeXML/Package.pm view on Meta::CPAN
my $ext = $resource && pathname_type($resource);
$options{type} = $ext && $$resource_types{$ext}; }
if (!$options{type}) {
my $ext = $resource && pathname_type($resource);
my $t = $ext && $$resource_types{$ext};
Warn('expected', 'type', undef, "Resource must have a mime-type; skipping"); return; }
if ($LaTeXML::DOCUMENT) { # If we've got a document, go ahead & put the resource in.
addResource($LaTeXML::DOCUMENT, $resource, %options); }
else {
AssignValue(PENDING_RESOURCES => [], 'global') unless LookupValue('PENDING_RESOURCES');
PushValue(PENDING_RESOURCES => [$resource, %options]); }
return; }
# No checking...
sub addResource {
my ($document, $resource, %options) = @_;
my $savenode = $document->floatToElement('ltx:resource');
$document->insertElement('ltx:resource', $options{content},
src => $resource, type => $options{type}, media => $options{media});
$document->setNode($savenode) if $savenode;
return; }
sub ProcessPendingResources {
my ($document) = @_;
if (my $resources = LookupValue('PENDING_RESOURCES')) {
my %seen = ();
my @unique_resources = grep { my $new = !$seen{$_}; $seen{$_} = 1; $new; } @$resources;
for my $resource (@unique_resources) {
addResource($document, @$resource); }
AssignValue(PENDING_RESOURCES => [], 'global'); }
return; }
#**********************************************************************
1;
__END__
=pod
=head1 NAME
C<LaTeXML::Package> - Support for package implementations and document customization.
=head1 SYNOPSIS
This package defines and exports most of the procedures users will need
to customize or extend LaTeXML. The LaTeXML implementation of some package
might look something like the following, but see the
installed C<LaTeXML/Package> directory for realistic examples.
package LaTeXML::Package::pool; # to put new subs & variables in common pool
use LaTeXML::Package; # to load these definitions
use strict; # good style
use warnings;
#
# Load "anotherpackage"
RequirePackage('anotherpackage');
#
# A simple macro, just like in TeX
DefMacro('\thesection', '\thechapter.\roman{section}');
#
# A constructor defines how a control sequence generates XML:
DefConstructor('\thanks{}', "<ltx:thanks>#1</ltx:thanks>");
#
# And a simple environment ...
DefEnvironment('{abstract}','<abstract>#body</abstract>');
#
# A math symbol \Real to stand for the Reals:
DefMath('\Real', "\x{211D}", role=>'ID');
#
# Or a semantic floor:
DefMath('\floor{}','\left\lfloor#1\right\rfloor');
#
# More esoteric ...
# Use a RelaxNG schema
RelaxNGSchema("MySchema");
# Or use a special DocType if you have to:
# DocType("rootelement",
# "-//Your Site//Your DocType",'your.dtd',
# prefix=>"http://whatever/");
#
# Allow sometag elements to be automatically closed if needed
Tag('prefix:sometag', autoClose=>1);
#
# Don't forget this, so perl knows the package loaded.
1;
=head1 DESCRIPTION
This module provides a large set of utilities and declarations that are useful
for writing `bindings': LaTeXML-specific implementations of a set of control
sequences such as would be defined in a LaTeX style or class file. They are also
useful for controlling and customization of LaTeXML's processing.
See the L</"See also"> section, below, for additional lower-level modules imported & re-exported.
To a limited extent (and currently only when explicitly enabled), LaTeXML can process
the raw TeX code found in style files. However, to preserve document structure
and semantics, as well as for efficiency, it is usually necessary to supply a
LaTeXML-specific `binding' for style and class files. For example, a binding
C<mypackage.sty.ltxml> would encode LaTeXML-specific implementations of
all the control sequences in C<mypackage.sty> so that C<\usepackage{mypackage}> would work.
Similarly for C<myclass.cls.ltxml>. Additionally, document-specific bindings can
be supplied: before processing a TeX source file, eg C<mydoc.tex>, LaTeXML
will automatically include the definitions and settings in C<mydoc.latexml>.
These C<.ltxml> and C<.latexml> files should be placed LaTeXML's searchpaths, where will
find them: either in the current directory or in a directory given to the --path option,
or possibly added to the variable SEARCHPATHS).
Since LaTeXML mimics TeX, a familiarity with TeX's processing model is critical.
LaTeXML models: catcodes and tokens
(See L<LaTeXML::Core::Token>, L<LaTeXML::Core::Tokens>) which are extracted
from the plain source text characters by the L<LaTeXML::Core::Mouth>;
L</Macros>, which are expanded within the L<LaTeXML::Core::Gullet>;
and L</Primitives>, which are digested within the L<LaTeXML::Core::Stomach>
to produce L<LaTeXML::Core::Box>, L<LaTeXML::Core::List>.
A key additional feature is the L</Constructors>:
when digested they generate a L<LaTeXML::Core::Whatsit> which, upon absorption by
L<LaTeXML::Core::Document>, inserts text or XML fragments in the final document tree.
I<Notation:> Many of the following forms take code references as arguments or options.
That is, either a reference to a defined sub, eg. C<\&somesub>, or an
anonymous function C<sub { ... }>. To document these cases, and the
arguments that are passed in each case, we'll use a notation like
C<I<code>($stomach,...)>.
=head2 Control Sequences
Many of the following forms define the behaviour of control sequences.
While in TeX you'll typically only define macros, LaTeXML is effectively redefining TeX itself,
so we define L</Macros> as well as L</Primitives>, L</Registers>,
L</Constructors> and L</Environments>.
These define the behaviour of these control sequences when processed during the various
phases of LaTeX's imitation of TeX's digestive tract.
=head3 Prototypes
LaTeXML uses a more convenient method of specifying parameter patterns for
control sequences. The first argument to each of these defining forms
(C<DefMacro>, C<DefPrimive>, etc) is a I<prototype> consisting of the control
sequence being defined along with the specification of parameters required by the control sequence.
Each parameter describes how to parse tokens following the control sequence into
arguments or how to delimit them. To simplify coding and capture common idioms
in TeX/LaTeX programming, latexml's parameter specifications are more expressive
than TeX's C<\def> or LaTeX's C<\newcommand>. Examples of the prototypes for
familiar TeX or LaTeX control sequences are:
DefConstructor('\usepackage[]{}',...
DefPrimitive('\multiply Variable SkipKeyword:by Number',..
DefPrimitive('\newcommand OptionalMatch:* DefToken[]{}', ...
The general syntax for parameter specification is
=over 4
=item C<{I<spec>}>
reads a regular TeX argument.
I<spec> can be omitted (ie. C<{}>).
Otherwise I<spec> is itself a parameter specification and
the argument is reparsed to accordingly.
(C<{}> is a shorthand for C<Plain>.)
=item C<[I<spec>]>
reads an LaTeX-style optional argument.
I<spec> can be omitted (ie. C<{}>).
Otherwise, if I<spec> is of the form Default:stuff, then stuff
would be the default value.
Otherwise I<spec> is itself a parameter specification
and the argument, if supplied, is reparsed according to that specification.
(C<[]> is a shorthand for C<Optional>.)
=item I<Type>
Reads an argument of the given type, where either
Type has been declared, or there exists a ReadType
function accessible from LaTeXML::Package::Pool.
See the available types, below.
=item C<I<Type>:I<value> | I<Type>:I<value1>:I<value2>...>
These forms invoke the parser for I<Type> but
pass additional Tokens to the reader function.
Typically this would supply defaults or parameters to a match.
=item C<OptionalI<Type>>
Similar to I<Type>, but it is not considered
an error if the reader returns undef.
=item C<SkipI<Type>>
Similar to C<Optional>I<Type>, but the value returned
from the reader is ignored, and does not occupy a
position in the arguments list.
=back
The predefined argument I<Type>s are as follows.
lib/LaTeXML/Package.pm view on Meta::CPAN
=item C<Undigested, Digested, DigestUntil:I<match>>
X<Undigested>X<Digested>
These types alter the usual sequence of tokenization and digestion in separate stages (like TeX).
A C<Undigested> parameter inhibits digestion completely and remains in token form.
A C<Digested> parameter gets digested until the (required) opening { is balanced; this is
useful when the content would usually need to have been protected in order to correctly deal
with catcodes. C<DigestUntil> digests tokens until a token matching I<match> is found.
=item C<Variable>
X<Variable>
Reads a token, expanding if necessary, and expects a control sequence naming
a writable register. If such is found, it returns an array of the corresponding
definition object, and any arguments required by that definition.
=item C<SkipSpaces, Skip1Space>
X<SkipSpaces>X<Skip1Space>
Skips one, or any number of, space tokens, if present, but contributes nothing to the argument list.
=back
=head3 Common Options
=over
=item C<scope=E<gt>'local' | 'global' | I<scope>>
Most defining commands accept an option to control how the definition is stored,
for global or local definitions, or using a named I<scope>
A named scope saves a set of definitions and values that can be activated at a later time.
Particularly interesting forms of scope are those that get automatically activated
upon changes of counter and label. For example, definitions that have
C<scope=E<gt>'section:1.1'> will be activated when the section number is "1.1",
and will be deactivated when that section ends.
=item C<locked=E<gt>I<boolean>>
This option controls whether this definition is locked from further
changes in the TeX sources; this keeps local 'customizations' by an author
from overriding important LaTeXML definitions and breaking the conversion.
=item C<protected=E<gt>I<boolean>>
Makes a definition "protected", in the sense of eTeX's C<\protected> directive.
This inhibits expansion under certain circumstances.
=item C<robust=E<gt>I<boolean>>
Makes a definition "robust", in the sense of LaTeX's C<\DeclareRobustCommand>.
This essentially creates an indirect macro definition which is preceded by C<\protect>.
This inhibits expansion (and argument processing!) under certain circumstances.
It usually only makes sense for macros, but may be useful for Primitives, Constructors
and DefMath in cases where LaTeX would normally have created a macro that needs protection.
=back
=head3 Macros
=over 4
=item C<DefMacro(I<prototype>, I<expansion>, I<%options>);>
X<DefMacro>
Defines the macro expansion for I<prototype>; a macro control sequence that is
expanded during macro expansion time in the L<LaTeXML::Core::Gullet>.
The I<expansion> should be one of I<tokens> | I<string> | I<code>($gullet,@args)>:
a I<string> will be tokenized upon first usage.
Any macro arguments will be substituted for parameter indicators (eg #1)
in the I<tokens> or tokenized I<string> and the result is used as the expansion
of the control sequence. If I<code> is used, it is called at expansion time
and should return a list of tokens as its result.
DefMacro options are
=over 4
=item C<scope=E<gt>I<scope>>,
=item C<locked=E<gt>I<boolean>>
See L</"Common Options">.
=item C<mathactive=E<gt>I<boolean>>
specifies a definition that will only be expanded in math mode;
the control sequence must be a single character.
=back
Examples:
DefMacro('\thefootnote','\arabic{footnote}');
DefMacro('\today',sub { ExplodeText(today()); });
=item C<DefMacroI(I<cs>, I<paramlist>, I<expansion>, I<%options>);>
X<DefMacroI>
Internal form of C<DefMacro> where the control sequence and parameter list
have already been separated; useful for definitions from within code.
Also, slightly more efficient for macros with no arguments (use C<undef> for
I<paramlist>), and useful for obscure cases like defining C<\begin{something*}>
as a Macro.
=back
=head3 Conditionals
=over 4
=item C<DefConditional(I<prototype>, I<test>, I<%options>);>
X<DefConditional>
Defines a conditional for I<prototype>; a control sequence that is
processed during macro expansion time (in the L<LaTeXML::Core::Gullet>).
A conditional corresponds to a TeX C<\if>.
If the I<test> is C<undef>, a C<\newif> type of conditional is defined,
which is controlled with control sequences like C<\footrue> and C<\foofalse>.
Otherwise the I<test> should be C<I<code>($gullet,@args)> (with the control sequence's arguments)
that is called at expand time to determine the condition.
Depending on whether the result of that evaluation returns a true or false value
(in the usual Perl sense), the result of the expansion is either the
first or else code following, in the usual TeX sense.
DefConditional options are
=over 4
=item C<scope=E<gt>I<scope>>,
=item C<locked=E<gt>I<boolean>>
See L</"Common Options">.
=item C<skipper=E<gt>I<code>($gullet)>
This option is I<only> used to define C<\ifcase>.
=back
Example:
DefConditional('\ifmmode',sub {
LookupValue('IN_MATH'); });
=item C<DefConditionalI(I<cs>, I<paramlist>, I<test>, I<%options>);>
X<DefConditionalI>
Internal form of C<DefConditional> where the control sequence and parameter list
have already been parsed; useful for definitions from within code.
Also, slightly more efficient for conditinal with no arguments (use C<undef> for
C<paramlist>).
=item C<IfCondition(I<$ifcs>,I<@args>)>
X<IfCondition>
C<IfCondition> allows you to test a conditional from within perl. Thus something like
C<if(IfCondition('\ifmmode')){ domath } else { dotext }> might be equivalent to
TeX's C<\ifmmode domath \else dotext \fi>.
=back
=head3 Primitives
lib/LaTeXML/Package.pm view on Meta::CPAN
Options for C<InputDefinitions> are:
=over
=item C<type=E<gt>I<type>>
the file type to search for.
=item C<noltxml=E<gt>I<boolean>>
inhibits searching for a LaTeXML binding; only raw TeX files will be sought and loaded.
=item C<notex=E<gt>I<boolean>>
inhibits searching for raw TeX files, only a LaTeXML binding will be sought and loaded.
=item C<noerror=E<gt>I<boolean>>
inhibits reporting an error if no appropriate file is found.
=back
The following options are primarily useful when C<InputDefinitions>
is supporting standard LaTeX package and class loading.
=over
=item C<withoptions=E<gt>I<boolean>>
indicates whether to pass in any options from the calling class or package.
=item C<handleoptions=E<gt>I<boolean>>
indicates whether options processing should be handled.
=item C<options=E<gt>[...]>
specifies a list of options (in the 'package options' sense) to be passed
(possibly in addition to any provided by the calling class or package).
=item C<after=E<gt>I<tokens> | I<code>($gullet)>
provides I<tokens> or I<code> to be processed by a C<I<name>.I<type>-h@@k> macro.
=item C<as_class=E<gt>I<boolean>>
fishy option that indicates that this definitions file should
be treated as if it were defining a class; typically shows up
in latex compatibility mode, or AMSTeX.
=back
A handy method to use most of the TeX distribution's raw TeX definitions for a package,
but override only a few with LaTeXML bindings is by defining a binding file,
say C<tikz.sty.ltxml>, to contain
InputDefinitions('tikz', type => 'sty', noltxml => 1);
which would find and read in C<tizk.sty>, and then follow it by a couple of strategic
LaTeXML definitions, C<DefMacro>, etc.
=back
=head2 Class and Packages
=over
=item C<RequirePackage(I<package>, I<%options>);>
X<RequirePackage>
Finds and loads a package implementation (usually C<I<package>.sty.ltxml>,
unless C<noltxml> is specified)for the requested I<package>.
It returns the pathname of the loaded package.
The options are:
=over
=item C<type=E<gt>I<type>>
specifies the file type (default C<sty>.
=item C<options=E<gt>[...]>
specifies a list of package options.
=item C<noltxml=E<gt>I<boolean>>
inhibits searching for the LaTeXML binding for the file (ie. C<I<name>.I<type>.ltxml>
=item C<notex=E<gt>1>
inhibits searching for raw tex version of the file.
That is, it will I<only> search for the LaTeXML binding.
=back
=item C<LoadClass(I<class>, I<%options>);>
X<LoadClass>
Finds and loads a class definition (usually C<I<class>.cls.ltxml>).
It returns the pathname of the loaded class.
The only option is
=over
=item C<options=E<gt>[...]>
specifies a list of class options.
=back
=item C<LoadPool(I<pool>, I<%options>);>
X<LoadPool>
Loads a I<pool> file (usually C<I<pool>.pool.ltxml>),
one of the top-level definition files, such as TeX, LaTeX or AMSTeX.
It returns the pathname of the loaded file.
=item C<DeclareOption(I<option>, I<tokens> | I<string> | I<code>($stomach));>
( run in 0.799 second using v1.01-cache-2.11-cpan-d8267643d1d )