Expand macros by splicing raw argument text

Package.swift

@@ -24,7 +24,6 @@ let package = Package(
             cSettings: [
                 .headerSearchPath("."),
                 .headerSearchPath("lib"),
-                .headerSearchPath("lib/internal"),
                 .headerSearchPath("render"),
                 .headerSearchPath("render/internal"),
             ]
@@ -37,7 +36,6 @@ let package = Package(
             cSettings: [
                 .headerSearchPath("../iosMath"),
                 .headerSearchPath("../iosMath/lib"),
-                .headerSearchPath("../iosMath/lib/internal"),
                 .headerSearchPath("../iosMath/render"),
                 .headerSearchPath("../iosMath/render/internal"),
             ]
@@ -49,7 +47,6 @@ let package = Package(
             cSettings: [
                 .headerSearchPath("../iosMath"),
                 .headerSearchPath("../iosMath/lib"),
-                .headerSearchPath("../iosMath/lib/internal"),
                 .headerSearchPath("../iosMath/render"),
                 .headerSearchPath("../iosMath/render/internal"),
             ],

iosMath.xcodeproj/project.pbxproj

@@ -93,11 +93,11 @@
 		492EECFA17DAED9000939107 /* MTFontManager.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MTFontManager.m; sourceTree = "<group>"; };
 		492EECFF17DAEDB500939107 /* MTMathListBuilder.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MTMathListBuilder.m; sourceTree = "<group>"; };
 		492EED0017DAEDB500939107 /* MTMathAtomFactory.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MTMathAtomFactory.h; sourceTree = "<group>"; };
+		A1B2C3D40000000000000101 /* MTMathAtomFactory+Internal.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "MTMathAtomFactory+Internal.h"; sourceTree = "<group>"; };
 		492EED0117DAEDB500939107 /* MTMathAtomFactory.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MTMathAtomFactory.m; sourceTree = "<group>"; };
 		492EED0217DAEDB500939107 /* MTMathList.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MTMathList.h; sourceTree = "<group>"; };
 		492EED0317DAEDB500939107 /* MTMathList.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MTMathList.m; sourceTree = "<group>"; };
 		492EED0417DAEDB500939107 /* MTMathListBuilder.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MTMathListBuilder.h; sourceTree = "<group>"; };
-		C01DEC0DE20260726000001 /* MTMacroParameterAtom.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MTMacroParameterAtom.h; sourceTree = "<group>"; };
 		4987307517D546800041B02B /* libIosMath.a */ = {isa = PBXFileReference; explicitFileType = archive.ar; includeInIndex = 0; path = libIosMath.a; sourceTree = BUILT_PRODUCTS_DIR; };
 		498730AB17D548DB0041B02B /* QuartzCore.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = QuartzCore.framework; path = System/Library/Frameworks/QuartzCore.framework; sourceTree = SDKROOT; };
 		49965EFC17CBBA2700A555C5 /* iosMathExample.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = iosMathExample.app; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -287,19 +287,18 @@
 				49DEC8B51CF77B00000053CD /* MTMathListIndex.m */,
 				49DEC8B61CF77B00000053CD /* MTMathListIndex.h */,
 				492EED0017DAEDB500939107 /* MTMathAtomFactory.h */,
+				A1B2C3D40000000000000101 /* MTMathAtomFactory+Internal.h */,
 				492EED0117DAEDB500939107 /* MTMathAtomFactory.m */,
 				492EED0217DAEDB500939107 /* MTMathList.h */,
 				492EED0317DAEDB500939107 /* MTMathList.m */,
 				492EED0417DAEDB500939107 /* MTMathListBuilder.h */,
 				492EECFF17DAEDB500939107 /* MTMathListBuilder.m */,
 				49DA6BC319A05F850086B19F /* MTUnicode.h */,
 				49DA6BC619A062A30086B19F /* MTUnicode.m */,
-				C01DEC0DE20260726000004 /* internal */,
 			);
 			path = lib;
 			sourceTree = "<group>";
 		};
-		C01DEC0DE20260726000004 /* internal */ = { isa = PBXGroup; children = ( C01DEC0DE20260726000001 /* MTMacroParameterAtom.h */, ); path = internal; sourceTree = "<group>"; };
 		49965F3917CBD02000A555C5 /* render */ = {
 			isa = PBXGroup;
 			children = (

iosMath/lib/MTMathAtomFactory+Internal.h

@@ -0,0 +1,33 @@
+//
+//  MTMathAtomFactory+Internal.h
+//  iosMath
+//
+//  This software may be modified and distributed under the terms of the
+//  MIT license. See the LICENSE file for details.
+//
+
+#import "MTMathAtomFactory.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Registry value: declared arity + the LaTeX template the expansion is parsed
+/// from. Arity is declared rather than inferred from the template because a
+/// future \newcommand declares [argc] and its body may ignore arguments.
+@interface MTMacroDefinition : NSObject
+@property (nonatomic, readonly) NSUInteger argumentCount;
+@property (nonatomic, copy, readonly) NSString* templateString;
+- (instancetype)initWithArgumentCount:(NSUInteger)argumentCount
+                       templateString:(NSString*)templateString;
+@end
+
+/** Read side of the macro registry, used by the builder to expand a command.
+ `+addMacro:argumentCount:template:` is the public write side; nothing outside
+ the library needs to read a definition back. */
+@interface MTMathAtomFactory (Internal)
+
+/** The macro registered under `command`, or nil if it is not a macro. */
++ (nullable MTMacroDefinition*) macroDefinitionForCommand:(NSString*) command;
+
+@end
+
+NS_ASSUME_NONNULL_END

iosMath/lib/MTMathAtomFactory.h

@@ -38,16 +38,6 @@ typedef NS_ENUM(NSUInteger, MTStackArgRole) {
                inheritsClass:(BOOL)inheritsClass;
 @end
 
-/// Registry value: declared arity + the LaTeX template the expansion is parsed
-/// from. Arity is declared rather than inferred from the template because a
-/// future \newcommand declares [argc] and its body may ignore arguments.
-@interface MTMacroDefinition : NSObject
-@property (nonatomic, readonly) NSUInteger argumentCount;
-@property (nonatomic, copy, readonly) NSString* templateString;
-- (instancetype)initWithArgumentCount:(NSUInteger)argumentCount
-                       templateString:(NSString*)templateString;
-@end
-
 FOUNDATION_EXPORT NSString *const MTSymbolMultiplication;
 FOUNDATION_EXPORT NSString *const MTSymbolDivision;
 FOUNDATION_EXPORT NSString *const MTSymbolFractionSlash;
@@ -128,8 +118,10 @@ FOUNDATION_EXPORT NSString *const MTSymbolDegree;
 + (void) addLatexSymbol:(NSString*) name value:(MTMathAtom*) atom;
 
 /** Define a macro: a command that expands to `templateString` with `#1`...`#9` replaced by
- the arguments it is invoked with. Macros are looked up before every other command table, so
- registering a name that already exists — a macro or a built-in command — shadows it.
+ the arguments it is invoked with. As in TeX, a literal `#` in the template is written `##`.
+ Macros are looked up before the symbol tables, so registering a name that already exists —
+ a macro or a built-in symbol — shadows it. `\limits`, the `\text…` commands and the
+ font-style commands are dispatched earlier and cannot be shadowed.
  e.g. `[MTMathAtomFactory addMacro:@"half" argumentCount:0 template:@"\\frac{1}{2}"]`
 
  Carries the same setup-time contract as `+addLatexSymbol:value:` — do not call this while
@@ -138,9 +130,6 @@ FOUNDATION_EXPORT NSString *const MTSymbolDegree;
     argumentCount:(NSUInteger) argumentCount
          template:(NSString*) templateString;
 
-/** The macro registered under `command`, or nil if it is not a macro. */
-+ (nullable MTMacroDefinition*) macroDefinitionForCommand:(NSString*) command;
-
 /** Returns a list of all supported lated symbols names. */
 + (NSArray<NSString*>*) supportedLatexSymbolNames;
 

iosMath/lib/MTMathAtomFactory.m

@@ -10,6 +10,7 @@
 //
 
 #import "MTMathAtomFactory.h"
+#import "MTMathAtomFactory+Internal.h"
 #import "MTMathListBuilder.h"
 
 NSString *const MTSymbolMultiplication = @"\u00D7";
@@ -1075,14 +1076,21 @@ + (nullable MTMathAtom*) arrayTableWithAlignments:(NSArray<NSNumber*>*) columnAl
     return macros;
 }
 
+// TeX's rule for a replacement text (TeXbook Ch. 20): every # is followed by
+// 1-9 or by another #, the latter standing for a literal # that
+// -spliceTemplate:arguments: collapses. A trailing or otherwise bare # is a typo.
 + (BOOL) template:(NSString*) templateString referencesOnlyArgumentsUpTo:(NSUInteger) argumentCount
 {
-    for (NSUInteger i = 0; i + 1 < templateString.length; i++) {
+    for (NSUInteger i = 0; i < templateString.length; i++) {
         if ([templateString characterAtIndex:i] != '#') {
             continue;
         }
-        unichar digit = [templateString characterAtIndex:i + 1];
-        if (digit < '1' || digit > '9' || (NSUInteger)(digit - '0') > argumentCount) {
+        if (i + 1 >= templateString.length) {
+            return NO;
+        }
+        unichar next = [templateString characterAtIndex:i + 1];
+        if (next != '#' &&
+            (next < '1' || next > '9' || (NSUInteger)(next - '0') > argumentCount)) {
             return NO;
         }
         i++;

iosMath/lib/MTMathList.h

@@ -693,18 +693,14 @@ typedef NS_ENUM(NSUInteger, MTStrikeStyle) {
 
 @end
 
-/** An unexpanded macro invocation.
+/** A macro invocation, with its expansion already computed.
 
- `\pmod{n}` parses to exactly one `MTMacroAtom` and expands by splicing a deep
- copy of each argument into the `#N` placeholders of `templateExpression`. All
- stored lists are raw (non-finalized), parsed at parse time; the expansion is
- re-derived from them every time `-[MTMathList finalized]` runs.
-
- `#N` substitution reaches only the top level of the template. A placeholder
- nested inside a sub-list (`\frac{#1}{2}`, `{#1}`, `x^{#1}`) is not substituted
- and renders as a literal `#N` — built-in templates are all flat; user-defined
- templates (`\newcommand`) need substitution that descends into sub-lists, which
- does not exist yet.
+ `\pmod{n}` parses to exactly one `MTMacroAtom`. The expansion is computed once,
+ when the invocation is parsed: each argument's source text is spliced into the
+ template string and the result is parsed, so a `#N` anywhere in the template —
+ inside `\hat{#1}`, or carrying a script as in `#1^{#2}` — lands exactly where the
+ author would have typed it. `arguments` keeps each argument's source text only so
+ the invocation can be serialized back to `\command{…}` verbatim.
 
  @note Only `-[MTMathList finalized]` expands. `-[MTMacroAtom finalized]` on a
  lone atom returns another macro atom.
@@ -714,17 +710,15 @@ typedef NS_ENUM(NSUInteger, MTStrikeStyle) {
 /** The command name without the leading backslash, e.g. `@"pmod"`. */
 @property (nonatomic, copy, readonly) NSString* command;
 
-/** The parsed arguments in invocation order. The lists are mutable, and owned by
- this atom (deep-copied at init). */
-@property (nonatomic, copy, readonly) NSArray<MTMathList*>* arguments;
+/** Each argument's source text in invocation order, with the outer braces off. */
+@property (nonatomic, copy, readonly) NSArray<NSString*>* arguments;
 
-/** The golden expansion template: a raw, argument-free list whose `#N`
- references are internal placeholder atoms. */
-@property (nonatomic, strong, readonly) MTMathList* templateExpression;
+/** The parsed expansion: raw (non-finalized), arguments already substituted. */
+@property (nonatomic, strong, readonly) MTMathList* rawExpansion;
 
 - (instancetype)initWithCommand:(NSString*)command
-                       arguments:(NSArray<MTMathList*>*)arguments
-              templateExpression:(MTMathList*)templateExpression NS_DESIGNATED_INITIALIZER;
+                       arguments:(NSArray<NSString*>*)arguments
+                    rawExpansion:(MTMathList*)rawExpansion NS_DESIGNATED_INITIALIZER;
 
 /// The implementation additionally throws, to catch dynamic (`id`-typed) callers.
 - (instancetype)initWithType:(MTMathAtomType)type value:(NSString*)value NS_UNAVAILABLE;

iosMath/lib/MTMathList.m

@@ -12,7 +12,6 @@
 #import "MTMathList.h"
 #import "MTMathListBuilder.h"
 #import "MTMathAtomFactory.h"
-#import "MTMacroParameterAtom.h"
 
 // Returns true if the current binary operator is not really binary.
 static BOOL isNotBinaryOperator(MTMathAtom* prevNode)
@@ -194,7 +193,7 @@ + (instancetype)atomWithType:(MTMathAtomType)type value:(NSString *)value
             // The default would mint a plain MTMathAtom carrying type 22 — an atom
             // that claims to be a macro but cannot expand.
             @throw [NSException exceptionWithName:@"InvalidMethod"
-                                           reason:@"A macro atom cannot be created by type. Use -[MTMacroAtom initWithCommand:arguments:templateExpression:] instead."
+                                           reason:@"A macro atom cannot be created by type. Use -[MTMacroAtom initWithCommand:arguments:rawExpansion:] instead."
                                          userInfo:nil];
 
         default:
@@ -1795,18 +1794,18 @@ - (id)copyWithZone:(NSZone *)zone
 @implementation MTMacroAtom
 
 - (instancetype)initWithCommand:(NSString*)command
-                       arguments:(NSArray<MTMathList*>*)arguments
-              templateExpression:(MTMathList*)templateExpression
+                       arguments:(NSArray<NSString*>*)arguments
+                    rawExpansion:(MTMathList*)rawExpansion
 {
     NSParameterAssert(command);
     NSParameterAssert(arguments);
-    NSParameterAssert(templateExpression);
+    NSParameterAssert(rawExpansion);
     self = [super initWithType:kMTMathAtomMacro value:@""];
     if (self) {
         _command = [command copy];
-        // copyItems gives a deep copy: MTMathList's -copyWithZone: is deep.
-        _arguments = [[NSArray alloc] initWithArray:arguments copyItems:YES];
-        _templateExpression = [templateExpression copy];
+        // The strings are immutable, so a plain array copy is already deep.
+        _arguments = [arguments copy];
+        _rawExpansion = [rawExpansion copy];
     }
     return self;
 }
@@ -1815,18 +1814,18 @@ - (instancetype)initWithType:(MTMathAtomType)type value:(NSString*)value
 {
     // NS_UNAVAILABLE blocks statically typed callers; this catches dynamic ones.
     @throw [NSException exceptionWithName:@"InvalidMethod"
-                                   reason:@"[MTMacroAtom initWithType:value:] cannot be called. Use -initWithCommand:arguments:templateExpression: instead."
+                                   reason:@"[MTMacroAtom initWithType:value:] cannot be called. Use -initWithCommand:arguments:rawExpansion: instead."
                                  userInfo:nil];
 }
 
 - (id)copyWithZone:(NSZone *)zone
 {
     // Not [super copyWithZone:], which would call the throwing -initWithType:value:.
-    // The designated initializer deep-copies arguments and template, so only the
+    // The designated initializer copies arguments and expansion, so only the
     // MTMathAtom fields need carrying over.
     MTMacroAtom* copy = [[[self class] allocWithZone:zone] initWithCommand:self.command
                                                                   arguments:self.arguments
-                                                         templateExpression:self.templateExpression];
+                                                               rawExpansion:self.rawExpansion];
     copy.subScript = [self.subScript copyWithZone:zone];
     copy.superScript = [self.superScript copyWithZone:zone];
     copy.indexRange = self.indexRange;
@@ -1837,8 +1836,8 @@ - (id)copyWithZone:(NSZone *)zone
 - (NSString *)stringValue
 {
     NSMutableString* str = [NSMutableString stringWithFormat:@"\\%@", self.command];
-    for (MTMathList* arg in self.arguments) {
-        [str appendFormat:@"{%@}", arg.stringValue];
+    for (NSString* arg in self.arguments) {
+        [str appendFormat:@"{%@}", arg];
     }
     if (self.superScript) {
         [str appendFormat:@"^{%@}", self.superScript.stringValue];
@@ -1851,46 +1850,25 @@ - (NSString *)stringValue
 
 - (void)appendLaTeXToString:(NSMutableString *)str
 {
-    // Command-faithful, argument-canonical: arguments are re-serialized by the
-    // usual serializer. +mathListToString: appends the ^{…}/_{…} tail.
+    // Command-faithful and exact: each argument is emitted as the author wrote it.
+    // +mathListToString: appends the ^{…}/_{…} tail.
     [str appendFormat:@"\\%@", self.command];
     if (self.arguments.count == 0) {
         // Nothing would terminate the command name otherwise: a zero-argument
         // \foo followed by x would re-parse as the single command \foox.
         [str appendString:@" "];
     }
-    for (MTMathList* arg in self.arguments) {
-        [str appendFormat:@"{%@}", [MTMathListBuilder mathListToString:arg]];
+    for (NSString* arg in self.arguments) {
+        [str appendFormat:@"{%@}", arg];
     }
 }
 
 - (MTMathList *)expansion
 {
-    // Deep copies throughout, so the stored template and arguments stay pristine
-    // for serialization, for post-parse mutation, and for repeated -finalized calls.
-    MTMathList* out = [MTMathList new];
-    for (MTMathAtom* templateAtom in self.templateExpression.atoms) {
-        if (![templateAtom isKindOfClass:[MTMacroParameterAtom class]]) {
-            [out addAtom:[templateAtom copy]];
-            continue;
-        }
-        NSUInteger index = [(MTMacroParameterAtom*)templateAtom argumentIndex];
-        // Arity disagreement is a bug in the macro table, not something the LaTeX
-        // author can cause. With assertions compiled out the placeholder is
-        // carried through and renders as a visible literal "#N" rather than
-        // making an argument silently vanish.
-        NSAssert(index >= 1 && index <= self.arguments.count,
-                 @"Macro \\%@ template references #%lu but %lu argument(s) were parsed.",
-                 self.command, (unsigned long)index, (unsigned long)self.arguments.count);
-        if (index < 1 || index > self.arguments.count) {
-            [out addAtom:[templateAtom copy]];
-            continue;
-        }
-        [out append:[self.arguments[index - 1] copy]];
-    }
-    // An argument may itself contain a macro. Re-scan so the result is macro-free
-    // at its top level, and so script transfer targets a real atom.
-    MTMathList* flat = [out expandMacros];
+    // The copy is load-bearing: -expandMacros carries non-macro atoms across by
+    // reference, and transferScripts mutates one of them. Without it, a repeated
+    // -finalized would find scripts already hung on the stored expansion.
+    MTMathList* flat = [[self.rawExpansion copy] expandMacros];
     [self transferScriptsToExpansion:flat];
     return flat;
 }
@@ -1925,33 +1903,3 @@ - (void)transferScriptsToExpansion:(MTMathList *)expansion
 }
 
 @end
-
-#pragma mark - MTMacroParameterAtom
-
-@implementation MTMacroParameterAtom
-
-- (instancetype)initWithArgumentIndex:(NSUInteger)argumentIndex
-{
-    NSParameterAssert(argumentIndex >= 1 && argumentIndex <= 9);
-    // Ordinary + a visible "#N" nucleus: if a placeholder ever did leak into a
-    // rendered list, it shows up as literal "#1" rather than crashing on an
-    // unhandled enum value.
-    self = [super initWithType:kMTMathAtomOrdinary
-                         value:[NSString stringWithFormat:@"#%lu", (unsigned long)argumentIndex]];
-    if (self) {
-        _argumentIndex = argumentIndex;
-    }
-    return self;
-}
-
-- (id)copyWithZone:(NSZone *)zone
-{
-    // MTMathAtom's -copyWithZone: allocates [self class] and calls
-    // -initWithType:value:, which this class does not override — so the copy is a
-    // MTMacroParameterAtom with the right nucleus but a zero index. Restore it.
-    MTMacroParameterAtom* copy = [super copyWithZone:zone];
-    copy->_argumentIndex = self.argumentIndex;
-    return copy;
-}
-
-@end