#! /usr/bin/env python
# -----------------------------------------------------------------------
# Convert a macro prototype to a LaTeX \newcommand
# By Scott Pakin <scott+nc@pakin.org>
# -----------------------------------------------------------------------
# Copyright (C) 2010 Scott Pakin, scott+nc@pakin.org
#
# This package may be distributed and/or modified under the conditions
# of the LaTeX Project Public License, either version 1.3c of this
# license or (at your option) any later version. The latest version of
# this license is in:
#
# http://www.latex-project.org/lppl.txt
#
# and version 1.3c or later is part of all distributions of LaTeX version
# 2006/05/20 or later.
# -----------------------------------------------------------------------
from spark import GenericScanner, GenericParser, GenericASTTraversal
import re
import copy
class ParseError(Exception):
"Represent any error that occurs during processing."
pass
class Token:
"Represent a single lexed token."
def __init__(self, type, charOffset, attr=None):
self.type = type
self.attr = attr
self.charOffset = charOffset
def __cmp__(self, o):
return cmp(self.type, o)
def __str__(self):
return self.attr
class AST:
"Represent an abstract syntax tree."
def __init__(self, type, charOffset, attr=None, kids=[]):
self.type = type
self.charOffset = charOffset
self.attr = attr
self.kids = kids
def __getitem__(self, child):
return self.kids[child]
def __len__(self):
return len(self.kids)
class CmdScanner(GenericScanner):
"Defines a lexer for macro prototypes."
def __init__(self):
GenericScanner.__init__(self)
self.charOffset = 0
def tokenize(self, input):
self.rv = []
GenericScanner.tokenize(self, input)
return self.rv
def t_whitespace(self, whiteSpace):
r' [\s\r\n]+ '
self.charOffset = self.charOffset + len(whiteSpace)
def t_command(self, cmd):
r' MACRO '
self.rv.append(Token(type='command',
attr=cmd,
charOffset=self.charOffset))
self.charOffset = self.charOffset + len(cmd)
def t_argument_type(self, arg):
r' OPT '
self.rv.append(Token(type='argtype',
attr=arg,
charOffset=self.charOffset))
self.charOffset = self.charOffset + len(arg)
def t_argument(self, arg):
r' \#\d+ '
self.rv.append(Token(type='argument',
attr=arg,
charOffset=self.charOffset))
self.charOffset = self.charOffset + len(arg)
def t_equal(self, equal):
r' = '
self.rv.append(Token(type=equal,
attr=equal,
charOffset=self.charOffset))
self.charOffset = self.charOffset + len(equal)
def t_quoted(self, quoted):
r' \{[^\}]*\} '
self.rv.append(Token(type='quoted',
attr=quoted,
charOffset=self.charOffset))
self.charOffset = self.charOffset + len(quoted)
def t_identifier(self, ident):
r' [A-Za-z]+ '
self.rv.append(Token(type='ident',
attr=ident,
charOffset=self.charOffset))
self.charOffset = self.charOffset + len(ident)
def t_delimiter(self, delim):
r' [()\[\]] '
self.rv.append(Token(type='delim',
attr=delim,
charOffset=self.charOffset))
self.charOffset = self.charOffset + len(delim)
def t_other(self, other):
r' [^()\[\]\{\}\#\s\r\n]+ '
self.rv.append(Token(type='other',
attr=other,
charOffset=self.charOffset))
self.charOffset = self.charOffset + len(other)
class CmdParser(GenericParser):
"Defines a parser for macro prototypes."
def __init__(self, start='decl'):
GenericParser.__init__(self, start)
def error(self, token):
raise ParseError, \
("Syntax error", 1+token.charOffset)
def p_optarg(self, args):
' optarg ::= argtype delim defvals delim '
return AST(type='optarg',
charOffset=args[0].charOffset,
attr=(args[1].attr, args[3].attr),
kids=[args[2]])
def p_rawtext(self, args):
' rawtext ::= other '
return AST(type='rawtext',
charOffset=args[0].charOffset,
attr=args[0].attr)
def p_defval(self, args):
' defval ::= argument = quoted '
return AST(type='defval',
charOffset=args[0].charOffset,
attr=(args[0].attr, args[2].attr))
def p_defvals_1(self, args):
' defvals ::= defval '
return AST(type='defvals',
charOffset=args[0].charOffset,
kids=args)
def p_defvals_2(self, args):
'''
defvals ::= defval rawtext defvals
defvals ::= defval ident defvals
defvals ::= defval quoted defvals
'''
return AST(type='defvals',
charOffset=args[0].charOffset,
attr=(args[1].type, args[1].attr, args[1].charOffset),
kids=[args[0],args[2]])
# Top-level macro argument
def p_arg_1(self, args):
'''
arg ::= quoted
arg ::= argument
'''
return AST(type='arg',
charOffset=args[0].charOffset,
attr=[args[0].type]+[args[0].attr])
def p_arg_2(self, args):
' arg ::= optarg '
return AST(type='arg',
charOffset=args[0].charOffset,
attr=[args[0].type]+[args[0].attr],
kids=args[0].kids)
def p_arg_3(self, args):
' arg ::= rawtext '
if args[0].attr != "*":
raise ParseError, \
('Literal text must be quoted between "{" and "}"',
args[0].charOffset + 1)
return AST(type='arg',
charOffset=args[0].charOffset,
attr=[args[0].type]+[args[0].attr])
def p_arglist_1(self, args):
' arglist ::= arg '
return AST(type='arglist',
charOffset=args[0].charOffset,
kids=args)
def p_arglist_2(self, args):
' arglist ::= arg arglist '
return AST(type='arglist',
charOffset=args[0].charOffset,
kids=args)
def p_decl_1(self, args):
' decl ::= command ident '
return AST(type='decl',
charOffset=args[0].charOffset,
attr=(args[0].attr, args[1].attr),
kids=[])
def p_decl_2(self, args):
' decl ::= command ident arglist '
return AST(type='decl',
charOffset=args[0].charOffset,
attr=(args[0].attr, args[1].attr),
kids=[args[2]])
def flattenAST(ast):
class FlattenAST(GenericASTTraversal):
"Flatten an AST into a list of arguments."
def __init__(self, ast):
GenericASTTraversal.__init__(self, ast)
self.postorder()
self.argList = ast.argList
def n_defval(self, node):
node.argList = (node.attr[0], node.attr[1], node.charOffset)
def n_defvals(self, node):
node.argList = [node.kids[0].argList]
if node.attr:
node.argList = node.argList + [node.attr] + node.kids[1].argList
def n_arg(self, node):
if node.attr[0] == "optarg":
node.argList = node.attr + node.kids[0].argList
else:
node.argList = tuple(node.attr + [node.charOffset])
def n_arglist(self, node):
node.argList = [node.kids[0].argList]
if len(node.kids) == 2:
node.argList = node.argList + node.kids[1].argList
def n_decl(self, node):
node.argList = [(node.attr[0], node.attr[1], node.charOffset)]
if node.kids != []:
node.argList = node.argList + node.kids[0].argList
def default(self, node):
raise ParseError, \
('Internal error -- node type "%s" was unexpected' % node.type,
1+node.charOffset)
return FlattenAST(ast).argList
def checkArgList(argList):
"Raise an error if any problems are detected with the given argument list."
def getFormals(sublist):
"Return the formal-parameter numbers in the order in which they appear."
if sublist == []:
return []
head = sublist[0]
headval = []
if head[0] == "argument":
headval = [(int(head[1][1:]), head[2])]
elif head[0][0] == "#":
headval = [(int(head[0][1:]), head[2])]
elif head[0] == "optarg":
headval = getFormals(head[2:])
return headval + getFormals(sublist[1:])
# Ensure the formals appear in strict increasing order.
formals = getFormals(argList)
prevformal = 0
for form, pos in formals:
if form != prevformal + 1:
raise ParseError, \
("Expected parameter %d but saw parameter %d" % (prevformal+1, form), 1+pos)
prevformal = form
# Ensure that "*" appears at most once at the top level.
seenStar = False
for arg in argList:
if arg[0] == "rawtext" and arg[1] == "*":
if seenStar:
raise ParseError, \
("Only one star parameter is allowed", arg[2])
seenStar = True
# Ensure that no optional argument contains more than nine formals.
for arg in argList:
if arg[0] == "optarg":
optFormals = 0
for oarg in arg[2:]:
if oarg[0][0] == "#":
optFormals += 1
if optFormals > 9:
raise ParseError, \
("An optional argument can contain at most nine formals",
oarg[2])
# Ensure that "#" is used only where it's allowed.
for arg in argList:
if arg[0] in ["rawtext", "quoted"]:
hashidx = string.find(arg[1], "#")
if hashidx == 0 or (hashidx > 0 and arg[1][hashidx-1] != "\\"):
if arg[0] == "quoted":
hashidx += 1
raise ParseError, \
('The "#" character cannot be used as a literal character unless escaped with "\\"',
arg[2] + hashidx)
elif arg[0] == "optarg":
for oarg in arg[2:]:
if oarg[0] in ["rawtext", "quoted"]:
hashidx = string.find(oarg[1], "#")
if hashidx == 0 or (hashidx > 0 and oarg[1][hashidx-1] != "\\"):
if oarg[0] == "quoted":
hashidx += 1
raise ParseError, \
('The "#" character cannot be used as a literal character unless escaped with "\\"',
oarg[2] + hashidx)
class LaTeXgenerator():
"Generate LaTeX code from a list of arguments."
def __init__(self):
"Initialize all of LaTeXgenerator's instance variables."
self.argList = [] # List of arguments provided to generate()
self.topLevelName = "???" # Base macro name
self.haveStar = False # True=need to define \ifNAME@star
self.haveAt = False # True=need to use \makeatletter...\makeatother
self.numFormals = 0 # Total number of formal arguments
self.codeList = [] # List of lines of code to output
def toRoman(self, num):
"Convert a decimal number to roman."
dec2rom = [("m", 1000),
("cm", 900),
("d", 500),
("cd", 400),
("c", 100),
("xc", 90),
("l", 50),
("xl", 40),
("x", 10),
("ix", 9),
("v", 5),
("iv", 4),
("i", 1)]
romanStr = ""
if num > 4000:
raise ParseError, ("Too many arguments", 0)
for rom, dec in dec2rom:
while num >= dec:
romanStr += rom
num -= dec
return romanStr
def partitionArgList(self):
"Group arguments, one per macro to generate."
self.argGroups = []
argIdx = 1
# Specially handle the first group because it's limited by
# \newcomand's semantics.
group = []
if len(self.argList) == 1:
# No arguments whatsoever
self.argGroups.append(group)
return
arg = self.argList[argIdx]
if arg[0] == "optarg" and arg[1] == ("[", "]") and len(arg) == 3:
group.append(arg)
argIdx += 1
while len(group) < 9 and argIdx < len(self.argList) and self.argList[argIdx][0] == "argument":
group.append(self.argList[argIdx])
argIdx += 1
self.argGroups.append(group)
# Handle the remaining groups, each ending before an optional
# argument.
group = []
numFormals = 0
for arg in self.argList[argIdx:]:
if arg[0] == "rawtext":
# Treat "*" as an optional argument.
if arg[1] == "*":
if group != []:
self.argGroups.append(group)
group = []
numFormals = 0
group.append(arg)
elif arg[0] == "quoted":
group.append(arg)
elif arg[0] == "argument":
group.append(arg)
numFormals += 1
if numFormals == 9:
if group != []:
self.argGroups.append(group)
group = []
numFormals = 0
elif arg[0] == "optarg":
# Note that we know from checkArgList() that there are
# no more than 10 formals specified within the
# optional argument.
if group != []:
self.argGroups.append(group)
group = []
numFormals = 0
optarg = arg[0:2]
for oarg in arg[2:]:
if oarg[0] in ["rawtext", "quoted"]:
optarg.append(oarg)
elif oarg[0][0] == "#":
numFormals += 1
optarg.append(oarg)
else:
optarg.append(oarg)
group.append(optarg)
if group != []:
self.argGroups.append(group)
def argsToString(self, argList, mode, argSubtract=0):
'''
Produce a string version of a list of arguments.
mode is one of "define", "call", or "calldefault".
argSubtract is subtracted from each argument number.
'''
if mode not in ["define", "call", "calldefault"]:
raise ParseError, ('Internal error (mode="%s")' % mode, argList[0][2])
argStr = ""
findArgRE = re.compile('#(\d+)')
for arg in argList:
if arg[0] == "argument":
if mode == "define":
argStr += "#%d" % (int(arg[1][1:]) - argSubtract)
else:
argStr += "{#%d}" % (int(arg[1][1:]) - argSubtract)
elif arg[0] == "rawtext":
argStr += arg[1]
elif arg[0] == "quoted":
argStr += arg[1][1:-1]
elif arg[0] == "optarg":
argStr += arg[1][0]
for oarg in arg[2:]:
if oarg[0][0] == "#":
if mode == "define":
argStr += "#%d" % (int(oarg[0][1:]) - argSubtract)
elif mode == "call":
argStr += "{#%d}" % (int(oarg[0][1:]) - argSubtract)
else:
if self.numFormals > 9:
argStr += findArgRE.sub(lambda a: "\\"+self.topLevelName+"@arg@"+self.toRoman(int(a.group(0)[1:])),
oarg[1])
else:
argStr += oarg[1]
elif oarg[0] == "quoted":
argStr += oarg[1][1:-1]
elif oarg[0] == "rawtext":
argStr += oarg[1]
else:
raise ParseError, ('Internal error ("%s")' % oarg[0],
oarg[2])
argStr += arg[1][1]
else:
raise ParseError, ('Internal error ("%s")' % arg[0], arg[2])
return argStr
def callMacro(self, macroNum):
"Return an array of strings suitable for calling macro macroNum."
if macroNum >= len(self.argGroups):
# No more macros.
return []
macroName = "\\%s@%s" % (self.topLevelName, self.toRoman(macroNum))
nextArg = self.argGroups[macroNum][0]
callSeq = []
if self.numFormals > 9:
# More than nine formal parameters
if nextArg[0] == "optarg":
callSeq.append(" \\@ifnextchar%s{%s}{%s%s}%%" % \
(nextArg[1][0], macroName, macroName,
self.argsToString([nextArg], mode="calldefault")))
elif nextArg[0] == "rawtext" and nextArg[1] == "*":
callSeq.append(" \\@ifstar{\\%s@startrue%s*}{\\%s@starfalse%s*}%%" % \
(self.topLevelName, macroName,
self.topLevelName, macroName))
else:
callSeq.append(" %s" % macroName)
else:
# Nine or fewer formal parameters
argStr = ""
for g in range(0, macroNum):
argStr += self.argsToString(self.argGroups[g], mode="call")
if nextArg[0] == "optarg":
callSeq.append(" \\@ifnextchar%s{%s%s}{%s%s%s}%%" % \
(nextArg[1][0],
macroName, argStr, macroName, argStr,
self.argsToString([nextArg], mode="calldefault")))
elif nextArg[0] == "rawtext" and nextArg[1] == "*":
callSeq.append(" \\@ifstar{\\%s@startrue%s%s*}{\\%s@starfalse%s%s*}%%" % \
(self.topLevelName, macroName, argStr,
self.topLevelName, macroName, argStr))
else:
callSeq.append(" %s%s%%" % (macroName, argStr))
return callSeq
def putCodeHere(self):
'Return an array of strings representing "Put code here".'
code = []
if self.haveStar:
code.extend([" \\if%s@star" % self.topLevelName,
' % Put code for the "*" case here.',
" \\else",
' % Put code for the non-"*" case here.',
" \\fi",
" %% Put code common to both cases here (and/or above the \\if%s@star)." % self.topLevelName])
else:
code.append(" % Put your code here.")
if self.numFormals == 0:
return code
if self.numFormals > 9:
firstArgName = "\\%s@arg@i" % self.topLevelName
lastArgName = "\\%s@arg@%s" % (self.topLevelName, self.toRoman(self.numFormals))
else:
firstArgName = "#1"
lastArgName = "#%d" % self.numFormals
if self.numFormals == 1:
code.append(" %% You can refer to the argument as %s." % firstArgName)
elif self.numFormals == 2:
code.append(" %% You can refer to the arguments as %s and %s." % (firstArgName, lastArgName))
else:
code.append(" %% You can refer to the arguments as %s through %s." % (firstArgName, lastArgName))
return code
def produceTopLevel(self):
"Generate the code for the top-level macro definition."
# Generate the macro definition.
defStr = "\\newcommand{\\%s}" % self.topLevelName
argList = self.argGroups[0]
if argList != []:
defStr += "[%d]" % len(argList)
firstArg = argList[0]
if firstArg[0] == "optarg":
defVal = firstArg[2][1][1:-1]
if string.find(defVal, "]") != -1:
defVal = "{%s}" % defVal
defStr += "[%s]" % defVal
defStr += "{%"
self.codeList.append(defStr)
# Generate the macro body.
if len(self.argGroups) == 1:
# Single macro definition.
self.codeList.extend(self.putCodeHere())
else:
# More macros are forthcoming.
if self.numFormals > 9:
# More than nine formal parameters
for f in range(1, len(argList)+1):
self.codeList.append(" \\def\\%s@arg@%s{#%d}%%" % (self.topLevelName, self.toRoman(f), f))
self.codeList.extend(self.callMacro(1))
self.codeList.append("}")
def produceRemainingMacros(self):
"Generate code for all macros except the first."
formalsSoFar = len(self.argGroups[0])
for groupNum in range(1, len(self.argGroups)):
# Generate the macro header.
self.codeList.append("")
argList = self.argGroups[groupNum]
defStr = "\\def\\%s@%s" % (self.topLevelName, self.toRoman(groupNum))
if self.numFormals > 9:
defStr += self.argsToString(argList, mode="define", argSubtract=formalsSoFar)
else:
for g in range (0, groupNum+1):
defStr += self.argsToString(self.argGroups[g], mode="define")
self.codeList.append(defStr + "{%")
# Generate the macro body.
if self.numFormals > 9:
# More than nine formal parameters
for arg in argList:
if arg[0] == "argument":
formalNum = int(arg[1][1:])
self.codeList.append(" \\def\\%s@arg@%s{#%d}%%" % \
(self.topLevelName,
self.toRoman(formalNum),
formalNum - formalsSoFar))
elif arg[0] == "optarg":
for oarg in arg[2:]:
if oarg[0][0] == "#":
formalNum = int(oarg[0][1:])
self.codeList.append(" \\def\\%s@arg@%s{#%d}%%" % \
(self.topLevelName,
self.toRoman(formalNum),
formalNum - formalsSoFar))
if groupNum == len(self.argGroups) - 1:
self.codeList.extend(self.putCodeHere())
else:
self.codeList.extend(self.callMacro(groupNum + 1))
else:
# Nine or fewer formal parameters.
if groupNum == len(self.argGroups) - 1:
self.codeList.extend(self.putCodeHere())
else:
self.codeList.extend(self.callMacro(groupNum + 1))
# Generate the macro trailer.
self.codeList.append("}")
# Increment the count of formals seen so far.
for arg in argList:
if arg[0] == "argument":
formalsSoFar += 1
elif arg[0] == "optarg":
formalsSoFar += len(filter(lambda o: o[0][0] == "#", arg[2:]))
def generate(self, argList):
"Generate LaTeX code from an argument list."
# Group arguments and identify characteristics that affect the output.
self.argList = argList
self.partitionArgList()
self.haveAt = len(self.argGroups) > 1
self.haveStar = filter(lambda arg: arg[0]=="rawtext" and arg[1]=="*", self.argList) != []
self.topLevelName = self.argList[0][1]
for arg in self.argList:
if arg[0] == "argument":
self.numFormals += 1
elif arg[0] == "optarg":
for oarg in arg[2:]:
if oarg[0][0] == "#":
self.numFormals += 1
# Output LaTeX code.
if self.haveAt:
self.codeList.append("\\makeatletter")
if self.haveStar:
self.codeList.append("\\newif\\if%s@star" % self.topLevelName)
self.produceTopLevel()
self.produceRemainingMacros()
if self.haveAt:
self.codeList.append("\\makeatother")
for codeLine in self.codeList:
print codeLine
# The buck starts here.
if __name__ == '__main__':
import sys
import string
def processLine():
"Parses the current value of oneLine."
global oneLine
try:
sys.stdout.softspace = 0 # Cancel the %$#@! space.
oneLine = string.strip(oneLine)
if oneLine=="" or oneLine[0]=="%":
return
if not isStdin:
print prompt, oneLine
scanner = CmdScanner()
parser = CmdParser()
tokens = scanner.tokenize(oneLine)
ast = parser.parse(tokens)
argList = flattenAST(ast)
checkArgList(argList)
gen = LaTeXgenerator()
gen.generate(argList)
except ParseError,(message, pos):
sys.stderr.write((" "*(len(prompt)+pos)) + "^\n")
sys.stderr.write("%s: %s.\n" % (sys.argv[0], message))
if isStdin:
print ""
sys.setrecursionlimit(5000)
prompt = "% Prototype:"
if len(sys.argv) <= 1:
isStdin = 1
print prompt + " ",
while 1:
oneLine = sys.stdin.readline()
if not oneLine:
break
processLine()
print prompt + " ",
else:
isStdin = 0
oneLine = string.join(sys.argv[1:])
processLine()