texcheck.py

""" TeXcheck.py -- rough syntax checking on Python style LaTeX documents.

 Written by Raymond D. Hettinger <python at rcn.com>
 Copyright (c) 2003 Python Software Foundation. All rights reserved.

Designed to catch common markup errors including:
* Unbalanced or mismatched parenthesis, brackets, and braces.
* Unbalanced or mismatched \\begin and \\end blocks.
* Misspelled or invalid LaTeX commands.
* Use of forward slashes instead of backslashes for commands.
* Table line size mismatches.

Sample command line usage:
 python texcheck.py -k chapterheading -m lib/librandomtex *.tex

Options:
 -m Munge parenthesis and brackets. [0,n) would normally mismatch.
 -k keyword: Keyword is a valid LaTeX command. Do not include the backslash.
 -d: Delimiter check only (useful for non-LaTeX files).
 -h: Help
 -s lineno: Start at lineno (useful for skipping complex sections).
 -v: Verbose. Trace the matching of //begin and //end blocks.
"""

importre
importsys
importgetopt
fromitertoolsimportizip, count, islice
importglob

cmdstr=r"""
 \section \module \declaremodule \modulesynopsis \moduleauthor
 \sectionauthor \versionadded \code \class \method \begin
 \optional \var \ref \end \subsection \lineiii \hline \label
 \indexii \textrm \ldots \keyword \stindex \index \item \note
 \withsubitem \ttindex \footnote \citetitle \samp \opindex
 \noindent \exception \strong \dfn \ctype \obindex \character
 \indexiii \function \bifuncindex \refmodule \refbimodindex
 \subsubsection \nodename \member \chapter \emph \ASCII \UNIX
 \regexp \program \production \token \productioncont \term
 \grammartoken \lineii \seemodule \file \EOF \documentclass
 \usepackage \title \input \maketitle \ifhtml \fi \url \Cpp
 \tableofcontents \kbd \programopt \envvar \refstmodindex
 \cfunction \constant \NULL \moreargs \cfuncline \cdata
 \textasciicircum \n \ABC \setindexsubitem \versionchanged
 \deprecated \seetext \newcommand \POSIX \pep \warning \rfc
 \verbatiminput \methodline \textgreater \seetitle \lineiv
 \funclineni \ulink \manpage \funcline \dataline \unspecified
 \textbackslash \mimetype \mailheader \seepep \textunderscore
 \longprogramopt \infinity \plusminus \shortversion \version
 \refmodindex \seerfc \makeindex \makemodindex \renewcommand
 \indexname \appendix \protect \indexiv \mbox \textasciitilde
 \platform \seeurl \leftmargin \labelwidth \localmoduletable
 \LaTeX \copyright \memberline \backslash \pi \centerline
 \caption \vspace \textwidth \menuselection \textless
 \makevar \csimplemacro \menuselection \bfcode \sub \release
 \email \kwindex \refexmodindex \filenq \e \menuselection
 \exindex \linev \newsgroup \verbatim \setshortversion
 \author \authoraddress \paragraph \subparagraph \cmemberline
 \textbar \C \seelink
"""

defmatchclose(c_lineno, c_symbol, openers, pairmap):
"Verify that closing delimiter matches most recent opening delimiter"
try:
o_lineno, o_symbol=openers.pop()
exceptIndexError:
print"\nDelimiter mismatch. On line %d, encountered closing '%s' without corresponding open"% (c_lineno, c_symbol)
return
ifo_symbolinpairmap.get(c_symbol, [c_symbol]): return
print"\nOpener '%s' on line %d was not closed before encountering '%s' on line %d"% (o_symbol, o_lineno, c_symbol, c_lineno)
return

defcheckit(source, opts, morecmds=[]):
"""Check the LaTeX formatting in a sequence of lines.

 Opts is a mapping of options to option values if any:
 -m munge parenthesis and brackets
 -d delimiters only checking
 -v verbose trace of delimiter matching
 -s lineno: linenumber to start scan (default is 1).

 Morecmds is a sequence of LaTeX commands (without backslashes) that
 are to be considered valid in the scan.
 """

texcmd=re.compile(r'\\[A-Za-z]+')
falsetexcmd=re.compile(r'\/([A-Za-z]+)') # Mismarked with forward slash

validcmds=set(cmdstr.split())
forcmdinmorecmds:
validcmds.add('\\'+cmd)

if'-m'inopts:
pairmap= {']':'[(', ')':'(['} # Munged openers
else:
pairmap= {']':'[', ')':'('} # Normal opener for a given closer
openpunct=set('([') # Set of valid openers

delimiters=re.compile(r'\\(begin|end){([_a-zA-Z]+)}|([()\[\]])')
braces=re.compile(r'({)|(})')
doubledwords=re.compile(r'(\b[A-za-z]+\b) \b\1\b')
spacingmarkup=re.compile(r'\\(ABC|ASCII|C|Cpp|EOF|infinity|NULL|plusminus|POSIX|UNIX)\s')

openers= [] # Stack of pending open delimiters
bracestack= [] # Stack of pending open braces

tablestart=re.compile(r'\\begin{(?:long)?table([iv]+)}')
tableline=re.compile(r'\\line([iv]+){')
tableend=re.compile(r'\\end{(?:long)?table([iv]+)}')
tablelevel=''
tablestartline=0

startline=int(opts.get('-s', '1'))
lineno=0

forlineno, lineinizip(count(startline), islice(source, startline-1, None)):
line=line.rstrip()

# Check balancing of open/close parenthesis, brackets, and begin/end blocks
forbegend, name, punctindelimiters.findall(line):
if'-v'inopts:
printlineno, '|', begend, name, punct,
ifbegend=='begin'and'-d'notinopts:
openers.append((lineno, name))
elifpunctinopenpunct:
openers.append((lineno, punct))
elifbegend=='end'and'-d'notinopts:
matchclose(lineno, name, openers, pairmap)
elifpunctinpairmap:
matchclose(lineno, punct, openers, pairmap)
if'-v'inopts:
print' --> ', openers

# Balance opening and closing braces
foropen, closeinbraces.findall(line):
ifopen=='{':
bracestack.append(lineno)
ifclose=='}':
try:
bracestack.pop()
exceptIndexError:
printr'Warning, unmatched } on line %s.'% (lineno,)

# Optionally, skip LaTeX specific checks
if'-d'inopts:
continue

# Warn whenever forward slashes encountered with a LaTeX command
forcmdinfalsetexcmd.findall(line):
if'822'inlineor'.html'inline:
continue# Ignore false positives for urls and for /rfc822
if'\\'+cmdinvalidcmds:
print'Warning, forward slash used on line %d with cmd: /%s'% (lineno, cmd)

# Check for markup requiring {} for correct spacing
forcmdinspacingmarkup.findall(line):
printr'Warning, \%s should be written as \%s{} on line %d'% (cmd, cmd, lineno)

# Validate commands
nc=line.find(r'\newcommand')
ifnc!=-1:
start=line.find('{', nc)
end=line.find('}', start)
validcmds.add(line[start+1:end])
forcmdintexcmd.findall(line):
ifcmdnotinvalidcmds:
printr'Warning, unknown tex cmd on line %d: \%s'% (lineno, cmd)

# Check table levels (make sure lineii only inside tableii)
m=tablestart.search(line)
ifm:
tablelevel=m.group(1)
tablestartline=lineno
m=tableline.search(line)
ifmandm.group(1) !=tablelevel:
printr'Warning, \line%s on line %d does not match \table%s on line %d'% (m.group(1), lineno, tablelevel, tablestartline)
iftableend.search(line):
tablelevel=''

# Style guide warnings
if'e.g.'inlineor'i.e.'inline:
printr'Style warning, avoid use of i.e or e.g. on line %d'% (lineno,)

fordwindoubledwords.findall(line):
printr'Doubled word warning. "%s" on line %d'% (dw, lineno)

lastline=lineno
forlineno, symbolinopeners:
print"Unmatched open delimiter '%s' on line %d"% (symbol, lineno)
forlinenoinbracestack:
print"Unmatched { on line %d"% (lineno,)
print'Done checking %d lines.'% (lastline,)
return0

defmain(args=None):
ifargsisNone:
args=sys.argv[1:]
optitems, arglist=getopt.getopt(args, "k:mdhs:v")
opts=dict(optitems)
if'-h'inoptsorargs==[]:
print__doc__
return0

iflen(arglist) <1:
print'Please specify a file to be checked'
return1

fori, filespecinenumerate(arglist):
if'*'infilespecor'?'infilespec:
arglist[i:i+1] =glob.glob(filespec)

morecmds= [vfork,vinoptitemsifk=='-k']
err= []

forfilenameinarglist:
print'='*30
print"Checking", filename
try:
f=open(filename)
exceptIOError:
print'Cannot open file %s.'%arglist[0]
return2

try:
err.append(checkit(f, opts, morecmds))
finally:
f.close()

returnmax(err)

if__name__=='__main__':
sys.exit(main())