|
@@ -0,0 +1,169 @@
|
|
1
|
+\documentclass[]{scrartcl}
|
|
2
|
+
|
|
3
|
+\makeatletter
|
|
4
|
+\newcommand*\py{\texttt{listings-ext.py}}
|
|
5
|
+\newcommand*\file{\texttt}
|
|
6
|
+\newcommand*\pkg{\textsf}
|
|
7
|
+\protected\def\meta#1{\texttt{$\langle$\textit{#1}$\rangle$}}
|
|
8
|
+\protected\def\cs#1{\texttt{\expandafter\@gobble\string\\#1}}
|
|
9
|
+\newcommand*\name{\emph{name}}
|
|
10
|
+\makeatother
|
|
11
|
+
|
|
12
|
+\title{\py}
|
|
13
|
+\author{Jonathan P.\@ Spratte}
|
|
14
|
+\date{\today}
|
|
15
|
+
|
|
16
|
+\usepackage{listings}
|
|
17
|
+\usepackage{listings-ext}
|
|
18
|
+\usepackage{enumitem}
|
|
19
|
+%% call listings-ext.py with:
|
|
20
|
+%% ./listings-ext.py -o example.lst example.c
|
|
21
|
+\input{example.lst}
|
|
22
|
+
|
|
23
|
+\usepackage{xcolor}
|
|
24
|
+
|
|
25
|
+\lstdefinestyle{regex}
|
|
26
|
+ {
|
|
27
|
+ escapeinside=<>
|
|
28
|
+ ,escapebegin=$\langle$\begingroup\itshape
|
|
29
|
+ ,escapeend=\endgroup$\rangle$
|
|
30
|
+ ,otherkeywords={[,],?:,(,),\\A,\\s,\\w}
|
|
31
|
+ ,keywords=[1]{?:,(,)}
|
|
32
|
+ ,keywords=[2]{[,]}
|
|
33
|
+ ,keywords=[3]{\\A,\\s,\\w}
|
|
34
|
+ }
|
|
35
|
+\lstset
|
|
36
|
+ {%
|
|
37
|
+ basicstyle=\ttfamily
|
|
38
|
+ ,basewidth=.5em
|
|
39
|
+ ,language=html
|
|
40
|
+ ,keywordstyle=[1]{\bfseries\color{green!50!black}}
|
|
41
|
+ ,keywordstyle=[2]{\bfseries\color{red!50!black}}
|
|
42
|
+ ,keywordstyle=[3]{\bfseries\color{blue!50!black}}
|
|
43
|
+ }
|
|
44
|
+
|
|
45
|
+\begin{document}
|
|
46
|
+\maketitle
|
|
47
|
+
|
|
48
|
+\section{Introduction}
|
|
49
|
+\py\ was created because I liked the idea of the \pkg{listings-ext} package and
|
|
50
|
+the accompanying script \texttt{listings-ext.sh}, but I thought that naming the
|
|
51
|
+code blocks and getting the definitions with those names would be a more
|
|
52
|
+\LaTeX-y way, so I created this script.
|
|
53
|
+
|
|
54
|
+This script does extract lines and line ranges from a source file and outputs
|
|
55
|
+those ranges with \cs{lstdef}-calls so that \pkg{listings-ext} can understand
|
|
56
|
+them. Line ranges are marked using formatted comments.
|
|
57
|
+
|
|
58
|
+\section{File preparation}
|
|
59
|
+To make use of this script you have to mark the lines you want to be extracted.
|
|
60
|
+Those marks are formatted as a comment, and the lines containing those comments
|
|
61
|
+have to match the following regular expression:
|
|
62
|
+\begin{lstlisting}[style=regex]
|
|
63
|
+\A(?:\s+)(?:<comment char>) ([abej])e: ([\w:]+)
|
|
64
|
+\end{lstlisting}
|
|
65
|
+
|
|
66
|
+So there are four different types of mark: \texttt{ae}, \texttt{be},
|
|
67
|
+\texttt{ee}, and \texttt{je}. Each of those marks should be preceded by one
|
|
68
|
+or more space tokens followed by the appropriate \meta{comment char} of the used
|
|
69
|
+language and another space. After the mark there should be a colon and a space
|
|
70
|
+followed by a string which can consist of alphanumeric characters, underscores
|
|
71
|
+and colons, this string is considered the \name\ of that mark. The four
|
|
72
|
+different marks have the following effect:
|
|
73
|
+\begin{description}[font=\ttfamily]
|
|
74
|
+ \item[ae] the \name\ will combine \textbf{a}ll code blocks.
|
|
75
|
+ \item[be] \textbf{b}egin of code block \name.
|
|
76
|
+ \item[ee] \textbf{e}nd of code block \name.
|
|
77
|
+ \item[je] the \name\ will \textbf{j}oin together other code blocks.
|
|
78
|
+\end{description}
|
|
79
|
+So while there are four different marks, there are three categories to define a
|
|
80
|
+\name.
|
|
81
|
+
|
|
82
|
+The correct \meta{comment char} is guessed from the file extension of the file
|
|
83
|
+which is to be processed. There are a few file extensions included as a look up
|
|
84
|
+table, but the guess might be wrong or the file extensions unknown. For an
|
|
85
|
+unknown extension the regular expression
|
|
86
|
+\lstinline[style=regex]{#|%|!|;|//|/\*|--}
|
|
87
|
+is used. If the guess is wrong or that regular expression yields problems, take
|
|
88
|
+a look at the \texttt{--comment-char} parameter in section~\ref{sec:usage}.
|
|
89
|
+
|
|
90
|
+For the mark types \texttt{ae}, \texttt{be}, and \texttt{ee} everything in the
|
|
91
|
+line that follows after the \name\ will be ignored. On the other hand
|
|
92
|
+\texttt{je} will interpret the rest of the line in the following way. First
|
|
93
|
+another regular expression will be matched:
|
|
94
|
+\begin{lstlisting}[style=regex]
|
|
95
|
+(?:\s*=)[\w: ]+
|
|
96
|
+\end{lstlisting}
|
|
97
|
+This allows an optional \texttt{=} after the \name\ and a following space
|
|
98
|
+separated list of other possible names. As soon as a character that can't be
|
|
99
|
+part of a name is encountered, the rest of the line is dropped. The \name\ will
|
|
100
|
+combine the code blocks associated with the names in that space separated list.
|
|
101
|
+Subsequent calls of \texttt{je} will add the new list to the already defined
|
|
102
|
+list of names to be combined.
|
|
103
|
+
|
|
104
|
+The marks \texttt{be} and \texttt{ee} always have to be used in pairs, and
|
|
105
|
+mustn't be nested. Subsequent calls of \texttt{be} and \texttt{ee} pairs with
|
|
106
|
+the same \name\ will add the enclosed lines to that \name.
|
|
107
|
+
|
|
108
|
+The line in which you place \texttt{ae} and \texttt{je} marks doesn't matter,
|
|
109
|
+the \name\ will always act on a global scale.
|
|
110
|
+
|
|
111
|
+It is not checked whether a \name\ already defined in another category is
|
|
112
|
+redefined. A \name\ which is defined in multiple categories will be output
|
|
113
|
+multiple times, once for each category it is in, with the \texttt{ae} category
|
|
114
|
+being the first, then the \texttt{je} one, and finally the \texttt{be-ee}
|
|
115
|
+blocks.
|
|
116
|
+
|
|
117
|
+\section{Usage}\label{sec:usage}
|
|
118
|
+\py\ is called with a list of files to be processed, additionally it supports a
|
|
119
|
+few command line parameters to control its behaviour, the order doesn't matter,
|
|
120
|
+parameters can be given before or after file names. Arguments to parameters are
|
|
121
|
+always mandatory. The output will be printed
|
|
122
|
+to \texttt{stdout} by default.
|
|
123
|
+\begin{description}[font=-\ttfamily]
|
|
124
|
+ \item[a, --abs-path]
|
|
125
|
+ use the absolute file path instead of the path given as argument.
|
|
126
|
+ \item[b, --basename]
|
|
127
|
+ prefix every identifier with the processed file's basename followed by a
|
|
128
|
+ period.
|
|
129
|
+ \item[c, --comment-char=\meta{regex}]
|
|
130
|
+ use \meta{regex} as the comment starting \meta{comment char}. For instance
|
|
131
|
+ to match C-style comments this would be \lstinline{'//|/\*'}.
|
|
132
|
+ \item[h]
|
|
133
|
+ print a short help and exit
|
|
134
|
+ \item[S, --silent]
|
|
135
|
+ If used the program doesn't report which files to process and where to write
|
|
136
|
+ the output to.
|
|
137
|
+ \item[s, --spaces=\meta{choice}]
|
|
138
|
+ Defines how spaces at the begin of the line are handled. \meta{choice} must
|
|
139
|
+ be one of:
|
|
140
|
+ \begin{description}[font=\ttfamily]
|
|
141
|
+ \item['must']
|
|
142
|
+ (default) there must be spaces before the start of the comment
|
|
143
|
+ \item['can']
|
|
144
|
+ there can be spaces before the start of the comment
|
|
145
|
+ \item['none']
|
|
146
|
+ no spaces are allowed before the start of the comment
|
|
147
|
+ \end{description}
|
|
148
|
+ \item[o, --output-file=\meta{output filename}]
|
|
149
|
+ if this argument is present, the output will be written into a file
|
|
150
|
+ \meta{output filename}; if \meta{output filename} is an empty string, the
|
|
151
|
+ output is redirected into a file with a basename corresponding to the name
|
|
152
|
+ of the current directory with the extension '.lst'.
|
|
153
|
+ \item[v, --version]
|
|
154
|
+ Print some version information and exit
|
|
155
|
+\end{description}
|
|
156
|
+
|
|
157
|
+\section{Example}
|
|
158
|
+As a small example, the following file contains every mark type, the \name\
|
|
159
|
+\texttt{main} is used twice, once as \texttt{je} and once in a \texttt{be-ee}
|
|
160
|
+block.
|
|
161
|
+\lstinputlisting[numbers=left,numberstyle=\tiny,language=c]{example.c}
|
|
162
|
+The file is saved as \file{example.c} and \py\ is run using
|
|
163
|
+\begin{lstlisting}[language=sh]
|
|
164
|
+listings-ext.py -o example.lst example.c
|
|
165
|
+\end{lstlisting}
|
|
166
|
+The following is the output in \file{example.lst}:
|
|
167
|
+\lstinputlisting[language=TeX]{example.lst}
|
|
168
|
+
|
|
169
|
+\end{document}
|