| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% Copyright (C) 2014 by Julien Cretel |
| 4 |
% <jubobs.tex at gmail.com> |
| 5 |
% |
| 6 |
% This work may be distributed and/or modified under the |
| 7 |
% conditions of the LaTeX Project Public License, either version 1.3 |
| 8 |
% of this license or (at your option) any later version. |
| 9 |
% The latest version of this license is in |
| 10 |
% |
| 11 |
% http://www.latex-project.org/lppl.txt |
| 12 |
% |
| 13 |
% and version 1.3 or later is part of all distributions of LaTeX |
| 14 |
% version 2005/12/01 or later. |
| 15 |
% |
| 16 |
% \fi |
| 17 |
% |
| 18 |
% \iffalse |
| 19 |
%<package>\NeedsTeXFormat{LaTeX2e}[2011/06/27] |
| 20 |
%<package>\ProvidesPackage{sclang-prettifier} |
| 21 |
%<package> [2014/06/14 v0.1 A package for prettyprinting SuperCollider |
| 22 |
%<package> source code] |
| 23 |
% |
| 24 |
%<*driver> |
| 25 |
\documentclass[a4paper]{ltxdoc} |
| 26 |
\EnableCrossrefs |
| 27 |
\CodelineIndex |
| 28 |
\RecordChanges |
| 29 |
|
| 30 |
\usepackage[T1]{fontenc} |
| 31 |
\usepackage{lmodern} |
| 32 |
\usepackage{xcolor} |
| 33 |
\usepackage{lstdoc} |
| 34 |
\usepackage[framed,numbered]{sclang-prettifier} |
| 35 |
\usepackage{hyperref} |
| 36 |
\usepackage{cleveref} |
| 37 |
|
| 38 |
\lstset |
| 39 |
{ |
| 40 |
style = SuperCollider-IDE, |
| 41 |
basicstyle = \scttfamily\small, |
| 42 |
upquote = true, |
| 43 |
} |
| 44 |
|
| 45 |
\lstdefinestyle{nonbnoframe} |
| 46 |
{ |
| 47 |
frame = none, |
| 48 |
numbers = none, |
| 49 |
} |
| 50 |
|
| 51 |
\newcommand*{\pkg}[1]{\textsf{#1}} |
| 52 |
\newcommand*{\opt}[1]{\texttt{#1}} |
| 53 |
\newcommand\SC{SuperCollider} |
| 54 |
\newcommand\scpkg{\textsf{sclang-prettifier}} |
| 55 |
\newcommand\lstpkg{\textsf{listings}} |
| 56 |
\newcommand\scsty{\texttt{SuperCollider-IDE}} |
| 57 |
\newcommand\sclng{\texttt{SuperCollider}} |
| 58 |
\newcommand*{\sccode}[1]{% |
| 59 |
\lstinline[style=SuperCollider-IDE,basicstyle=\scttfamily]|#1| |
| 60 |
} |
| 61 |
\makeindex |
| 62 |
|
| 63 |
\begin{document} |
| 64 |
\DocInput{sclang-prettifier.dtx} |
| 65 |
\end{document} |
| 66 |
%</driver> |
| 67 |
% \fi |
| 68 |
% |
| 69 |
% \CheckSum{199} |
| 70 |
% |
| 71 |
% \CharacterTable |
| 72 |
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z |
| 73 |
% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z |
| 74 |
% Digits \0\1\2\3\4\5\6\7\8\9 |
| 75 |
% Exclamation \! Double quote \" Hash (number) \# |
| 76 |
% Dollar \$ Percent \% Ampersand \& |
| 77 |
% Acute accent \' Left paren \( Right paren \) |
| 78 |
% Asterisk \* Plus \+ Comma \, |
| 79 |
% Minus \- Point \. Solidus \/ |
| 80 |
% Colon \: Semicolon \; Less than \< |
| 81 |
% Equals \= Greater than \> Question mark \? |
| 82 |
% Commercial at \@ Left bracket \[ Backslash \\ |
| 83 |
% Right bracket \] Circumflex \^ Underscore \_ |
| 84 |
% Grave accent \` Left brace \{ Vertical bar \| |
| 85 |
% Right brace \} Tilde \~} |
| 86 |
% |
| 87 |
% \changes{v0.1}{2014/04/24}{Initial release.} |
| 88 |
% |
| 89 |
% \GetFileInfo{sclang-prettifier.sty} |
| 90 |
% |
| 91 |
% ^^A see http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex%2F3540 |
| 92 |
% \begingroup |
| 93 |
% \def\x{\#,\$,\%,\^,\_,\~,\&,\{,\},\/}%^^A |
| 94 |
% \makeatletter |
| 95 |
% \@onelevel@sanitize\x |
| 96 |
% \expandafter\endgroup\expandafter\DoNotIndex\expandafter{\x} |
| 97 |
% |
| 98 |
% \begingroup |
| 99 |
% \makeatletter |
| 100 |
% \lccode`9=32\relax |
| 101 |
% \lowercase{%^^A |
| 102 |
% \edef\x{\noexpand\DoNotIndex{\@backslashchar9}}%^^A |
| 103 |
% }%^^A |
| 104 |
% \expandafter\endgroup\x |
| 105 |
% |
| 106 |
% \DoNotIndex{\@ifpackagewith,\@ne,\@tempa,\\} |
| 107 |
% \DoNotIndex{\advance} |
| 108 |
% \DoNotIndex{\begingroup,\bfseries} |
| 109 |
% \DoNotIndex{\color,\CurrentOption} |
| 110 |
% \DoNotIndex{\DeclareOption,\def} |
| 111 |
% \DoNotIndex{\edef,\else,\endgroup,\expandafter} |
| 112 |
% \DoNotIndex{\fi,\fontfamily,\framed@scpr@true} |
| 113 |
% \DoNotIndex{\ifnum,\ifx,\iterate} |
| 114 |
% \DoNotIndex{\let,\loop,\lst@AddToHook,\lst@Key,\lst@language,\lst@mode,^^A |
| 115 |
% \lst@NormedDef,\lst@Pmode,\lst@SaveOutputDef,\lst@thestyle,\lst@token,^^A |
| 116 |
% \lstdefinelanguage,\lstdefinestyle,\lsthk@DetectKeywords,\lstum@backslash} |
| 117 |
% \DoNotIndex{\newcommand,\newcount,\newif,\newtoks,\noexpand,\normalsize,^^A |
| 118 |
% \numbered@scpr@true} |
| 119 |
% \DoNotIndex{\OptionNotUsed} |
| 120 |
% \DoNotIndex{\PackageError,\PackageWarning,\PassOptionsToPackage,^^A |
| 121 |
% \ProcessOptions} |
| 122 |
% \DoNotIndex{\relax,\renewcommand,\repeat,\RequirePackage} |
| 123 |
% \DoNotIndex{\selectfont} |
| 124 |
% \DoNotIndex{\the,\ttfamily} |
| 125 |
% \DoNotIndex{\unless} |
| 126 |
% |
| 127 |
% \title^^A |
| 128 |
% {^^A |
| 129 |
% The \scpkg{} package^^A |
| 130 |
% \thanks^^A |
| 131 |
% {^^A |
| 132 |
% This document corresponds to \scpkg~\fileversion, |
| 133 |
% dated~\filedate.^^A |
| 134 |
% }^^A |
| 135 |
% } |
| 136 |
% \author{Julien Cretel\\ \texttt{jubobs.tex at gmail.com}} |
| 137 |
% \date{\filedate} |
| 138 |
% \thispagestyle{empty} |
| 139 |
% \maketitle |
| 140 |
% |
| 141 |
% \begin{abstract} |
| 142 |
% Built on top of the \lstpkg{} package, the \scpkg{} package allows you to |
| 143 |
% effortlessly prettyprint \SC{} source code in documents typeset with |
| 144 |
% \LaTeX{} \& friends. |
| 145 |
% \end{abstract} |
| 146 |
% |
| 147 |
% \tableofcontents\newpage |
| 148 |
% |
| 149 |
% |
| 150 |
% \part{Introduction} |
| 151 |
% |
| 152 |
% \section{Why this package?} |
| 153 |
% |
| 154 |
% \href{http://supercollider.github.io}{\SC} is a programming |
| 155 |
% language for real-time audio synthesis and algorithmic composition. |
| 156 |
% In February 2014, James Harkins, a \SC{} user, |
| 157 |
% enquired on \href{http://tex.stackexchange.com}{TeX.SX} |
| 158 |
% (\href{http://tex.stackexchange.com/q/159245/21891}{here} and |
| 159 |
% \href{http://tex.stackexchange.com/q/159246/21891}{here}) |
| 160 |
% about the possibility of using the \lstpkg{} package to automatically |
| 161 |
% highlight syntactic elements of the \SC{} language such as symbols, |
| 162 |
% environment variables, and classes, without having to list them manually as |
| 163 |
% \lstpkg{} keywords. |
| 164 |
% My answers to James's questions form the basis of this package. |
| 165 |
% |
| 166 |
% |
| 167 |
% \section{\scpkg{} in action} |
| 168 |
% |
| 169 |
% The \scpkg{} package defines a \lstpkg{} style, called |
| 170 |
% \scsty{}, that mimics the style of the \SC{} IDE. |
| 171 |
% For an example, see \cref{SCsample}, which is adapted from this |
| 172 |
% \href{http://tex.stackexchange.com/q/159245/21891}{TeX.SX question}. |
| 173 |
%^^A |
| 174 |
% \iffalse |
| 175 |
%<*example> |
| 176 |
% \fi |
| 177 |
\begin{lstlisting}[ |
| 178 |
float, |
| 179 |
label=SCsample, |
| 180 |
caption={Some dummy \SC{} code}, |
| 181 |
] |
| 182 |
p.clear; |
| 183 |
|
| 184 |
"Hello World!".postln; |
| 185 |
~grains.addSpec(\tfreq, [1, 40, \exp]); |
| 186 |
~grains.addSpec(\overlap, [0.1, 10, \exp]); |
| 187 |
~grains.addSpec(\pos, [0, b.duration]); // 3.43 is nice! |
| 188 |
~grains.addSpec(\rate, [0.5, 2, 'exp']); |
| 189 |
/* |
| 190 |
Dummy block comment. |
| 191 |
*/ |
| 192 |
~grains = { |tfreq = 25, overlap = 6, pan = 0, amp = 0.2, pos = 3.43, |
| 193 |
rate = 1| |
| 194 |
var trig = Impulse.ar(tfreq); |
| 195 |
TGrains.ar(2, trig, b, rate, pos, overlap / tfreq, pan, amp) |
| 196 |
}; |
| 197 |
~grains.play; |
| 198 |
\end{lstlisting} |
| 199 |
% \iffalse |
| 200 |
%</example> |
| 201 |
% \fi |
| 202 |
% |
| 203 |
% The \scpkg{} package automatically |
| 204 |
% highlights the following syntactic elements of the \SC{} language. |
| 205 |
% |
| 206 |
% \paragraph{Keywords} |
| 207 |
% \sccode{var} |
| 208 |
% |
| 209 |
% \paragraph{To-end-of-line and block comments} |
| 210 |
% \sccode{// 3.43 is nice!} |
| 211 |
% |
| 212 |
% \paragraph{Symbols} |
| 213 |
% \lstinline[style=SuperCollider-IDE]|\tfreq|, |
| 214 |
% \lstinline[style=SuperCollider-IDE]|'exp'|, etc. |
| 215 |
% |
| 216 |
% \paragraph{Environment variables} |
| 217 |
% \lstinline[style=SuperCollider-IDE]|~grains| |
| 218 |
% |
| 219 |
% \paragraph{Classes} |
| 220 |
% \lstinline[style=SuperCollider-IDE]|Impulse|, |
| 221 |
% \lstinline[style=SuperCollider-IDE]|TGrains|, etc. |
| 222 |
% |
| 223 |
% |
| 224 |
% \part{User's guide} |
| 225 |
% |
| 226 |
% \section{Installation} |
| 227 |
% |
| 228 |
% \subsection{Package dependencies} |
| 229 |
% |
| 230 |
% \scpkg{} requires relatively up-to-date versions of packages \pkg{textcomp}, |
| 231 |
% \pkg{xcolor}, and \lstpkg{}, all three of which ship with popular \TeX{} |
| 232 |
% distributions. It loads those three packages without any options. |
| 233 |
% |
| 234 |
% \subsection{Installing \scpkg{}} |
| 235 |
% |
| 236 |
% Once the package gets officially released on |
| 237 |
% \href{http://www.ctan.org}{CTAN}, |
| 238 |
% you should be able to install it directly through your package manager. |
| 239 |
% |
| 240 |
% However, if you need to install \scpkg{} manually, you should run |
| 241 |
%^^A |
| 242 |
% \begin{verbatim} |
| 243 |
% latex sclang-prettifier.ins\end{verbatim} |
| 244 |
%^^A |
| 245 |
% and copy the |sclang-prettifier.sty| file to a path |
| 246 |
% where \LaTeX{} (or your preferred typesetting engine) can find it. |
| 247 |
% To generate the documentation, run |
| 248 |
%^^A |
| 249 |
% \begin{verbatim} |
| 250 |
% pdflatex sclang-prettifier.dtx |
| 251 |
% makeindex -s gglo.ist -o sclang-prettifier.gls sclang-prettifier.glo |
| 252 |
% makeindex -s gind.ist -o sclang-prettifier.ind sclang-prettifier.idx |
| 253 |
% pdflatex sclang-prettifier.dtx |
| 254 |
% pdflatex sclang-prettifier.dtx\end{verbatim} |
| 255 |
%^^A |
| 256 |
% |
| 257 |
% |
| 258 |
% \section{Getting started} |
| 259 |
% |
| 260 |
% As stated above, the \scpkg{} package is built on top of the \lstpkg{} |
| 261 |
% package. |
| 262 |
% If you already are a seasoned \lstpkg{} user, you should feel right at home. |
| 263 |
% If you're not, be aware that this user's guide makes use of some \lstpkg{} |
| 264 |
% functionalities (such as key-value options) without describing their usage. |
| 265 |
% For more details on those functionalities, you should consult the |
| 266 |
% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}. |
| 267 |
% |
| 268 |
% |
| 269 |
% \subsection{Loading \texorpdfstring{\scpkg{}}{sclang-prettifier}} |
| 270 |
% |
| 271 |
% Simply write |
| 272 |
%^^A |
| 273 |
% \begin{verbatim} |
| 274 |
% \usepackage{sclang-prettifier}\end{verbatim} |
| 275 |
%^^A |
| 276 |
% somewhere in your preamble. |
| 277 |
% |
| 278 |
% You may want to load the \lstpkg{} and |
| 279 |
% \pkg{xcolor} packages with some options; in that case, make sure those |
| 280 |
% options are passed to those two packages \emph{before} loading the \scpkg{} |
| 281 |
% package. |
| 282 |
% |
| 283 |
% The \scpkg{} package currently offers two options. |
| 284 |
%^^A |
| 285 |
% \begin{description} |
| 286 |
% \item[\opt{framed}]\leavevmode |
| 287 |
% |
| 288 |
% Draws (by default) a dark gray frame around each listing that uses |
| 289 |
% the \scsty{} style. |
| 290 |
% |
| 291 |
% \item[\opt{numbered}]\leavevmode |
| 292 |
% |
| 293 |
% Prints (by default) line numbers in light gray to the left of each |
| 294 |
% listing that uses the \scsty{} style. |
| 295 |
% |
| 296 |
% \end{description} |
| 297 |
% |
| 298 |
% \subsection{Displayed listings} |
| 299 |
% |
| 300 |
% To typeset a \SC{} listing embedded in your |tex| file, simply enclose |
| 301 |
% it in an |lstlisting| environment, and load the \scsty{} |
| 302 |
% style in the environment's optional argument, |
| 303 |
% using \lstpkg{}' \keyname{style} key. |
| 304 |
%^^A |
| 305 |
% \begin{verbatim} |
| 306 |
% \begin{lstlisting}[style=SuperCollider-IDE] |
| 307 |
% ... |
| 308 |
% \end{lstlisting}\end{verbatim} |
| 309 |
% |
| 310 |
% |
| 311 |
% \subsection{Standalone listings} |
| 312 |
% |
| 313 |
% In practice, though, keeping your \SC{} listings in external files^^A |
| 314 |
% ---rather than embedding them in a |tex|~file---^^A |
| 315 |
% is preferable, for maintainability reasons. |
| 316 |
% To typeset a \SC{} listing residing in an |sc| (or |scx|, or |sco|) file, |
| 317 |
% simply invoke the |
| 318 |
% |\lstinputlisting| macro, load the \scsty{} style |
| 319 |
% in the environment's optional argument, |
| 320 |
% and specify the path to the file in question in the mandatory argument. |
| 321 |
%^^A |
| 322 |
% \begin{verbatim} |
| 323 |
% \lstinputlisting[style=SuperCollider-IDE]{sample.sc}\end{verbatim} |
| 324 |
%^^A |
| 325 |
% |
| 326 |
% |
| 327 |
% \subsection{Inline listings} |
| 328 |
% |
| 329 |
% You may want to typeset fragments of \SC{} code within the main text of |
| 330 |
% your document. For instance, you may want to typeset the |
| 331 |
% \lstinline[style=SuperCollider-IDE]|var| keyword in a sentence, |
| 332 |
% in order to explain its usage. |
| 333 |
% The |\lstinline| macro can be used for typesetting such inline code. |
| 334 |
%^^A |
| 335 |
% \begin{verbatim} |
| 336 |
% \lstinline[style=SuperCollider-IDE]|var|\end{verbatim} |
| 337 |
%^^A |
| 338 |
% Arguably, typing all this only to typeset such a simple \SC{} keyword can |
| 339 |
% rapidly become tedious. |
| 340 |
% Fortunately, the \lstpkg{} allows you to define a character as a shorthand |
| 341 |
% for inline code, via the |\lstMakeShortInline| macro. |
| 342 |
% However, this character should ideally neither be used by the language |
| 343 |
% itself nor occur elsewhere in your document. |
| 344 |
% Unfortunately, because the \SC{} language already uses most (all?) ASCII |
| 345 |
% characters, your choice is limited\ldots{} |
| 346 |
% Proceed with caution. |
| 347 |
% For more details about inline code, |
| 348 |
% see subsection~4.17 in the \lstpkg{} manual. |
| 349 |
% |
| 350 |
% |
| 351 |
% \section{Advanced customization} |
| 352 |
% |
| 353 |
% \subsection{\scpkg{}'s key-value interface} |
| 354 |
% |
| 355 |
% The \lstpkg{} package provides a large number of options accessible via a |
| 356 |
% nifty key-value interface, which is described in its excellent |
| 357 |
% \href{http://www.ctan.org/pkg/listings}{documentation}. |
| 358 |
% The \scpkg{} package extends \lstpkg{}' key-value interface interface by |
| 359 |
% defining three additional keys that allow you to customize the styles |
| 360 |
% applied to \SC{} symbols, environment variables, and classes, |
| 361 |
% should you wish to do so. |
| 362 |
% All three keys are prefixed by ``|sc|'', |
| 363 |
% to help you distinguish them from native \lstpkg{} keys. |
| 364 |
% |
| 365 |
% For each of the three keys described below, |
| 366 |
% the value assigned to it in the \scsty{} style is indicated |
| 367 |
% on the right-hand side. |
| 368 |
%^^A |
| 369 |
% \begin{syntax} |
| 370 |
% |
| 371 |
% \item[0.1,{\color[RGB]{0,113,0}}] |
| 372 |
% \rkeyname{scsymbolstyle}|=|\meta{style} |
| 373 |
% |
| 374 |
% This key determines the style applied to \SC{} symbols. |
| 375 |
% The last token can be a one-parameter command, |
| 376 |
% such as |\textbf| or |\underbar|. |
| 377 |
% |
| 378 |
% \item[0.1,{\color[RGB]{147,70,14}}] |
| 379 |
% \rkeyname{scenvvarstyle}|=|\meta{style} |
| 380 |
% |
| 381 |
% This key determines the style applied to \SC{} environment variables. |
| 382 |
% The last token can be a one-parameter command, |
| 383 |
% such as |\textbf| or |\underbar|. |
| 384 |
% |
| 385 |
% \item[0.1,{\color[RGB]{0,40,211}}] |
| 386 |
% \rkeyname{scclassstyle}|=|\meta{style} |
| 387 |
% |
| 388 |
% This key determines the style applied to \SC{} classes. |
| 389 |
% The last token can be a one-parameter command, |
| 390 |
% such as |\textbf| or |\underbar|. |
| 391 |
% |
| 392 |
% \end{syntax} |
| 393 |
% |
| 394 |
% |
| 395 |
% \subsection{Changing the font of your \texorpdfstring{\SC}{SuperCollider} |
| 396 |
% listings} |
| 397 |
% |
| 398 |
% The \scpkg{} package uses the Computer Modern typewriter font by default, |
| 399 |
% which, arguably, is far from ideal. |
| 400 |
% I encourage you to switch to your favourite ``programmer font'' instead. |
| 401 |
% |
| 402 |
% For |pdflatex| users, |
| 403 |
% \scpkg{} conveniently provides a macro for easily selecting the Courier |
| 404 |
% font---which is used by default by the \SC{} IDE. |
| 405 |
%^^A |
| 406 |
% \begin{syntax} |
| 407 |
% |
| 408 |
% \item[0.1] \rcmdname\scttfamily |
| 409 |
% |
| 410 |
% selects the Courier font. |
| 411 |
% |
| 412 |
% \end{syntax} |
| 413 |
%^^A |
| 414 |
% To use Courier in your \SC{} listings, you must pass |\scttfamily| to |
| 415 |
% \lstpkg{}' \keyname{basicstyle} key (\emph{after} loading the |
| 416 |
% \scsty{} style) and also---this is important---^^A |
| 417 |
% load the \pkg{fontenc} package with option \opt{T1}: |
| 418 |
%^^A |
| 419 |
% \begin{verbatim} |
| 420 |
% \usepackage[T1]{fontenc}\end{verbatim} |
| 421 |
% |
| 422 |
% |
| 423 |
% \part{Miscellaneous} |
| 424 |
% |
| 425 |
% \section{Missing features and known issues} |
| 426 |
% |
| 427 |
% The \scpkg{} currently does not highlight numbers as the \SC{} IDE does. |
| 428 |
% Highlighting numbers in \lstpkg{} in a robust manner is notoriously |
| 429 |
% difficult; |
| 430 |
% I might implement a solution in the future, if I ever find a good one. |
| 431 |
% |
| 432 |
% |
| 433 |
% \section{Bug reports and feature suggestions} |
| 434 |
% |
| 435 |
% The development version of \scpkg{} is currently hosted on GitHub at |
| 436 |
% \href{https://github.com/Jubobs/sclang-prettifier/} |
| 437 |
% {Jubobs/sclang-prettifier}. |
| 438 |
% If you find an issue in \scpkg{} that this manual does not mention, |
| 439 |
% if you would like to see a feature implemented in the package, |
| 440 |
% or if you can think of ways in which the \scpkg{} documentation could be |
| 441 |
% improved, please add an entry to the repository's issue tracker on GitHub; |
| 442 |
% alternatively, you can send me an email at |
| 443 |
% \href{mailto:[email protected]}{[email protected]} |
| 444 |
% |
| 445 |
% \makeatletter |
| 446 |
% \def\index@prologue{\part{Index}\markboth{Index}{Index}} |
| 447 |
% \makeatother |
| 448 |
% \StopEventually{^^A |
| 449 |
% \clearpage^^A |
| 450 |
% \PrintChanges^^A |
| 451 |
% \setcounter{IndexColumns}{2}^^A |
| 452 |
% \PrintIndex^^A |
| 453 |
% } |
| 454 |
% |
| 455 |
% \section{Acknowledgments} |
| 456 |
% Thanks to the developers of the \lstpkg{} package, |
| 457 |
% without which \scpkg{} would never have existed. |
| 458 |
% I'm also in debt to many |
| 459 |
% \href{http://tex.stackexchange.com}{TeX.SX} users for their help, |
| 460 |
% encouragements, and suggestions. |
| 461 |
% Thanks in particular to |
| 462 |
% James Harkins, whose questions inspired me to write this package, |
| 463 |
% and to Marco Daniel, Enrico Gregorio (egreg), and Heiko Oberdiek, |
| 464 |
% whose contributions to TeX.SX proved particularly helpful for the |
| 465 |
% development of this package. |
| 466 |
% |
| 467 |
% |
| 468 |
% \part{Implementation} |
| 469 |
% |
| 470 |
% Be aware that, for ``namespacing'', the \scpkg{} package uses, not a prefix, |
| 471 |
% but the ``|scpr|''~suffix (preceded by an |@| character) throughout. |
| 472 |
% |
| 473 |
% |
| 474 |
% \section{Preliminary checks} |
| 475 |
% |
| 476 |
% \begin{macro}{\lstoptcheck@scpr} |
| 477 |
% Because the \lstpkg{} options \opt{noaspects}, \opt{0.21}, and |
| 478 |
% \opt{savemem} are incompatible with \pkg{sclang-prettifier}, checking |
| 479 |
% whether the \lstpkg{} package has been loaded with any of those options is |
| 480 |
% a good idea; if so, we should issue an error. |
| 481 |
% This macro checks whether \lstpkg{} was loaded with a given option |
| 482 |
% and, if so, throws an error. |
| 483 |
% \begin{macrocode} |
| 484 |
\newcommand\lstoptcheck@scpr[1] |
| 485 |
{% |
| 486 |
\@ifpackagewith{listings}{#1}% |
| 487 |
{ |
| 488 |
\PackageError{sclang-prettifier}% |
| 489 |
{incompatible listings' option #1}% |
| 490 |
{% |
| 491 |
Make sure the `listings' package |
| 492 |
doesn't get loaded with option `#1'% |
| 493 |
} |
| 494 |
} |
| 495 |
{} |
| 496 |
} |
| 497 |
% \end{macrocode} |
| 498 |
% \end{macro} |
| 499 |
% We now use this macro to make sure that none of the problematic \lstpkg{} |
| 500 |
% options has been passed to \lstpkg{} during an earlier loading of that |
| 501 |
% package. |
| 502 |
% \begin{macrocode} |
| 503 |
\lstoptcheck@scpr{noaspects} |
| 504 |
\lstoptcheck@scpr{0.21} |
| 505 |
\lstoptcheck@scpr{savemem} |
| 506 |
% \end{macrocode} |
| 507 |
% |
| 508 |
% |
| 509 |
% \section{Package options} |
| 510 |
% |
| 511 |
% \paragraph{Framed listings} |
| 512 |
% \begin{macro}{\ifframed@scpr@} |
| 513 |
% This option draws (by default) a frame around each listing that uses |
| 514 |
% the \scsty{} style. |
| 515 |
% \begin{macrocode} |
| 516 |
\newif\ifframed@scpr@ |
| 517 |
\DeclareOption{framed}{\framed@scpr@true} |
| 518 |
% \end{macrocode} |
| 519 |
% \end{macro} |
| 520 |
% |
| 521 |
% \paragraph{Numbered lines} |
| 522 |
% \begin{macro}{\ifnumbered@scpr@} |
| 523 |
% This option prints (by default) line numbers to the left of each listing |
| 524 |
% that uses the \scsty{} style. |
| 525 |
% \begin{macrocode} |
| 526 |
\newif\ifnumbered@scpr@ |
| 527 |
\DeclareOption{numbered}{\numbered@scpr@true} |
| 528 |
% \end{macrocode} |
| 529 |
% \end{macro} |
| 530 |
% |
| 531 |
% \paragraph{Draft} |
| 532 |
% This option is simply passed to \lstpkg{}. |
| 533 |
% \begin{macrocode} |
| 534 |
\DeclareOption{draft}{\PassOptionsToPackage{\CurrentOption}{listings}} |
| 535 |
% \end{macrocode} |
| 536 |
% |
| 537 |
% \paragraph{Final} |
| 538 |
% This option is simply passed to \lstpkg{}. |
| 539 |
% \begin{macrocode} |
| 540 |
\DeclareOption{final}{\PassOptionsToPackage{\CurrentOption}{listings}} |
| 541 |
% \end{macrocode} |
| 542 |
% |
| 543 |
% \paragraph{Discard undefined options} |
| 544 |
% We discard any other option passed to \scpkg{} by the user |
| 545 |
% and issue a warning. |
| 546 |
% \begin{macrocode} |
| 547 |
\DeclareOption*% |
| 548 |
{% |
| 549 |
\OptionNotUsed |
| 550 |
\PackageWarning{sclang-prettifier}{Unknown `\CurrentOption' option} |
| 551 |
} |
| 552 |
% \end{macrocode} |
| 553 |
% \paragraph{Process options} |
| 554 |
% \begin{macrocode} |
| 555 |
\ProcessOptions\relax |
| 556 |
% \end{macrocode} |
| 557 |
% |
| 558 |
% |
| 559 |
% \section{Required packages} |
| 560 |
% |
| 561 |
% The \scpkg{} package require three packages without any package option: |
| 562 |
% the \pkg{textcomp} package, in order to use \lstpkg{}' \keyname{upquote} |
| 563 |
% key; |
| 564 |
% the \pkg{xcolor} package, in order to color our \SC{} code; |
| 565 |
% and, of course, the \lstpkg{} package. |
| 566 |
% \begin{macrocode} |
| 567 |
\RequirePackage{textcomp}[2005/09/27] |
| 568 |
\RequirePackage{xcolor}[2007/01/21] |
| 569 |
\RequirePackage{listings}[2013/08/26] |
| 570 |
% \end{macrocode} |
| 571 |
% |
| 572 |
% |
| 573 |
% \section{Definition of the \texorpdfstring{\sclng}{SuperCollider} language} |
| 574 |
% |
| 575 |
% \paragraph{Language name} |
| 576 |
% \begin{macro}{\language@scpr} |
| 577 |
% To avoid code duplication in this package file, we define a macro that |
| 578 |
% expands to the name of our new language, \sclng{}. |
| 579 |
% \begin{macrocode} |
| 580 |
\newcommand\language@scpr{SuperCollider} |
| 581 |
% \end{macrocode} |
| 582 |
% \end{macro} |
| 583 |
% \begin{macro}{\languageNormedDefd@scpr} |
| 584 |
% However, because \lstpkg{} ``normalizes'' language names internally, |
| 585 |
% we also need to define a macro that expands to the normalized name of |
| 586 |
% the new language. |
| 587 |
% \begin{macrocode} |
| 588 |
\expandafter\lst@NormedDef\expandafter\languageNormedDefd@scpr% |
| 589 |
\expandafter{\language@scpr} |
| 590 |
% \end{macrocode} |
| 591 |
% \end{macro} |
| 592 |
% |
| 593 |
% \paragraph{Language definition} |
| 594 |
% We can now define our new \lstpkg{} language, using some |\expandafter| |
| 595 |
% trickery on |\lstdefinelanguage|. |
| 596 |
% \begin{macrocode} |
| 597 |
\expandafter\expandafter\expandafter\lstdefinelanguage\expandafter |
| 598 |
{\language@scpr} |
| 599 |
{% |
| 600 |
morekeywords = {var}, |
| 601 |
alsoletter = \\~, |
| 602 |
alsoother = @, |
| 603 |
sensitive = true, |
| 604 |
morecomment = [l]{//}, |
| 605 |
morecomment = [s]{/*}{*/}, |
| 606 |
morestring = [s]{"}{"}, |
| 607 |
moredelim = [s][\symbolStyle@scpr]{'}{'}, |
| 608 |
}[keywords,strings,comments] |
| 609 |
% \end{macrocode} |
| 610 |
% |
| 611 |
% \section{Symbols, classes and environment variables} |
| 612 |
% |
| 613 |
% \paragraph{Storing relevant characters} |
| 614 |
% To detect whether an identifier is an environment variable or a symbol, |
| 615 |
% we will need to test whether the identifier in question starts with a tilde |
| 616 |
% or a backslash, respectively. |
| 617 |
% \lstpkg{} developer's guide tells us that the only safe way to test |
| 618 |
% against a character is to store it in a macro using \lstpkg{}' internal |
| 619 |
% macro |\lst@SaveOutputDef|. |
| 620 |
% \begin{macro}{\tilde@scpr} |
| 621 |
% We save the tilde character thus. |
| 622 |
% \begin{macrocode} |
| 623 |
\lst@SaveOutputDef{`~}\tilde@scpr |
| 624 |
% \end{macrocode} |
| 625 |
% \end{macro} |
| 626 |
% \begin{macro}{\dollar@scpr} |
| 627 |
% We save the dollar-sign character thus. |
| 628 |
% \begin{macrocode} |
| 629 |
\lst@SaveOutputDef{`$}\dollar@scpr |
| 630 |
% \end{macrocode} |
| 631 |
% \end{macro} |
| 632 |
% |
| 633 |
% No need for such definition for the backslash: |
| 634 |
% \lstpkg{} already stores the backslash in a macro called |\lstum@backslash|. |
| 635 |
% |
| 636 |
% |
| 637 |
% \section{Using into \lstpkg{}' hooks} |
| 638 |
% |
| 639 |
% We apply some necessary patches in two \lstpkg{}' hooks; |
| 640 |
% but first, we define a couple of helper macros. |
| 641 |
% |
| 642 |
% \paragraph{Helper macros} |
| 643 |
% \begin{macro}{\getfirstchar@scpr} |
| 644 |
% \begin{macro}{\getfirstchar@@scpr} |
| 645 |
% \begin{macro}{\firstchar@scpr} |
| 646 |
% Of these three helper macros, the first two macros extract the |
| 647 |
% first character token in a given sequence of character tokens |
| 648 |
% and store it in the third macro. |
| 649 |
% This approach is adapted from this |
| 650 |
% \href{http://tex.stackexchange.com/a/159267/21891} |
| 651 |
% {TeX.SX answer by Marco Daniel}. |
| 652 |
% \begin{macrocode} |
| 653 |
\newcommand\getfirstchar@scpr{} |
| 654 |
\newcommand\getfirstchar@@scpr{} |
| 655 |
\newcommand\firstchar@scpr{} |
| 656 |
\def\getfirstchar@scpr#1{\getfirstchar@@scpr#1\relax} |
| 657 |
\def\getfirstchar@@scpr#1#2\relax{\def\firstchar@scpr{#1}} |
| 658 |
% \end{macrocode} |
| 659 |
% \end{macro} |
| 660 |
% \end{macro} |
| 661 |
% \end{macro} |
| 662 |
% |
| 663 |
% \paragraph{\hookname{Output}} |
| 664 |
% (See the |
| 665 |
% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation} |
| 666 |
% for more details on this hook.) |
| 667 |
% \begin{macro}{\addedToOutput@scpr} |
| 668 |
% We add this macro (initially empty) to \lstpkg{}' |
| 669 |
% \hookname{Output} hook. |
| 670 |
% \begin{macrocode} |
| 671 |
\newcommand\addedToOutput@scpr{} |
| 672 |
\lst@AddToHook{Output}{\addedToOutput@scpr} |
| 673 |
% \end{macrocode} |
| 674 |
% \end{macro} |
| 675 |
% \begin{macro}{\currentchar@scpr} |
| 676 |
% This count is used to test a character token against A-Z. |
| 677 |
% \begin{macrocode} |
| 678 |
\newcount\currentchar@scpr |
| 679 |
% \end{macrocode} |
| 680 |
% \end{macro} |
| 681 |
% \begin{macro}{\@ddedToOutput@scpr} |
| 682 |
% The |\addedToOutput@scpr}| macro is let to this one under certain |
| 683 |
% conditions (more details follow). |
| 684 |
% \begin{macrocode} |
| 685 |
\newcommand\@ddedToOutput@scpr |
| 686 |
{% |
| 687 |
% \end{macrocode} |
| 688 |
% If we're in \lstpkg{}' processing mode\ldots |
| 689 |
% \begin{macrocode} |
| 690 |
\ifnum\lst@mode=\lst@Pmode% |
| 691 |
% \end{macrocode} |
| 692 |
% \ldots{} we save the first character token in the identifier being processed |
| 693 |
% to a macro called |\firstchar@scpr|. |
| 694 |
% \begin{macrocode} |
| 695 |
\expandafter\getfirstchar@scpr\expandafter{\the\lst@token}% |
| 696 |
% \end{macrocode} |
| 697 |
% If that token is a backslash, we apply the style associated to symbols. |
| 698 |
% \begin{macrocode} |
| 699 |
\expandafter\ifx\firstchar@scpr\lstum@backslash% |
| 700 |
\let\lst@thestyle\symbolStyle@scpr% |
| 701 |
% \end{macrocode} |
| 702 |
% If that token is a dollar sign, we have a SuperCollider ``character''. |
| 703 |
% we apply the style associated to symbols (as in the \SC{} IDE). |
| 704 |
% \begin{macrocode} |
| 705 |
\else |
| 706 |
\expandafter\ifx\firstchar@scpr\dollar@scpr% |
| 707 |
\let\lst@thestyle\symbolStyle@scpr% |
| 708 |
% \end{macrocode} |
| 709 |
% If that that token is a tilde, we apply the style associated to environment |
| 710 |
% variables. |
| 711 |
% \begin{macrocode} |
| 712 |
\else |
| 713 |
\expandafter\ifx\firstchar@scpr\tilde@scpr% |
| 714 |
\def\lst@thestyle{\envvarStyle@scpr}% |
| 715 |
% \end{macrocode} |
| 716 |
% Otherwise, if that character is a capital letter (A-Z), we apply the style |
| 717 |
% associated to classes. |
| 718 |
% \begin{macrocode} |
| 719 |
\else |
| 720 |
\currentchar@scpr=65 |
| 721 |
\loop |
| 722 |
\expandafter\ifnum% |
| 723 |
\expandafter`\firstchar@scpr=\currentchar@scpr% |
| 724 |
\let\lst@thestyle\classStyle@scpr% |
| 725 |
\let\iterate\relax% |
| 726 |
\fi |
| 727 |
\advance\currentchar@scpr by \@ne% |
| 728 |
\unless\ifnum\currentchar@scpr>90% |
| 729 |
\repeat% |
| 730 |
\fi |
| 731 |
\fi |
| 732 |
\fi |
| 733 |
\fi |
| 734 |
% \end{macrocode} |
| 735 |
% Whatever style was applied, we still check whether the identifier is a |
| 736 |
% keyword; if it is one, the keyword style is applied to it. |
| 737 |
% \begin{macrocode} |
| 738 |
\lsthk@DetectKeywords% |
| 739 |
} |
| 740 |
% \end{macrocode} |
| 741 |
% \end{macro} |
| 742 |
% |
| 743 |
% \paragraph{\hookname{PreInit}} |
| 744 |
% (See the |
| 745 |
% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation} |
| 746 |
% for more details on this hook.) |
| 747 |
% Because the |\lst@AddToHook| affects hooks globally |
| 748 |
% (i.e.\ for all listings), |
| 749 |
% we must apply our patches only when required, i.e.\ |
| 750 |
% in listings that use \sclng{}, and not in others. |
| 751 |
% The \hookname{PreInit}, which is called at the very beginning of each |
| 752 |
% listing, is where we do that. |
| 753 |
% We check |
| 754 |
% whether |\lst@language| and |\languageNormedDefd@scpr| expand (once) to the |
| 755 |
% same replacement text and only apply our patches under that condition. |
| 756 |
% \begin{macrocode} |
| 757 |
\lst@AddToHook{PreInit} |
| 758 |
{% |
| 759 |
\ifx\lst@language\languageNormedDefd@scpr% |
| 760 |
\let\addedToOutput@scpr\@ddedToOutput@scpr% |
| 761 |
\fi |
| 762 |
} |
| 763 |
% \end{macrocode} |
| 764 |
% |
| 765 |
% |
| 766 |
% \section{Key-value interface} |
| 767 |
% |
| 768 |
% We extend \lstpkg{}' key-value interface by defining several additional |
| 769 |
% keys, which we will use to define a style similar to that of the \SC{} IDE, |
| 770 |
% and which will allow the user to customize the style of their \SC{} |
| 771 |
% listings. |
| 772 |
% |
| 773 |
% \paragraph{Symbol style} |
| 774 |
% \begin{lstkey}{scsymbolstyle} |
| 775 |
% \begin{macro}{\classStyle@scpr} |
| 776 |
% This key determines the style applied to \SC{} symbols. |
| 777 |
% \begin{macrocode} |
| 778 |
\newcommand\symbolStyle@scpr{} |
| 779 |
\lst@Key{scsymbolstyle}\relax% |
| 780 |
{\def\symbolStyle@scpr{#1}} |
| 781 |
% \end{macrocode} |
| 782 |
% \end{macro} |
| 783 |
% \end{lstkey} |
| 784 |
% |
| 785 |
% \paragraph{Environment-variable style} |
| 786 |
% \begin{lstkey}{scenvvarstyle} |
| 787 |
% \begin{macro}{\envvarStyle@scpr} |
| 788 |
% This key determines the style applied to \SC{} environment variables. |
| 789 |
% \begin{macrocode} |
| 790 |
\newcommand\envvarStyle@scpr{} |
| 791 |
\lst@Key{scenvvarstyle}\relax% |
| 792 |
{\def\envvarStyle@scpr{#1}} |
| 793 |
% \end{macrocode} |
| 794 |
% \end{macro} |
| 795 |
% \end{lstkey} |
| 796 |
% |
| 797 |
% \paragraph{Class style} |
| 798 |
% \begin{lstkey}{scclassstyle} |
| 799 |
% \begin{macro}{\classStyle@scpr} |
| 800 |
% This key determines the style applied to \SC{} classes. |
| 801 |
% \begin{macrocode} |
| 802 |
\newcommand\classStyle@scpr{} |
| 803 |
\lst@Key{scclassstyle}\relax% |
| 804 |
{\def\classStyle@scpr{#1}} |
| 805 |
% \end{macrocode} |
| 806 |
% \end{macro} |
| 807 |
% \end{lstkey} |
| 808 |
% |
| 809 |
% |
| 810 |
% \section{User-level font macro} |
| 811 |
% |
| 812 |
% \begin{macro}{\scttfamily} |
| 813 |
% This user-level macro can be used for selecting the Courier font family, |
| 814 |
% which is used by default in the \SC{} IDE (v3.6.6, at least), and which, |
| 815 |
% contrary to \TeX{} default font family (Computer Modern), |
| 816 |
% comes with a boldface version. |
| 817 |
% \begin{macrocode} |
| 818 |
\newcommand\scttfamily{\fontfamily{pcr}\selectfont} |
| 819 |
% \end{macrocode} |
| 820 |
% \end{macro} |
| 821 |
% |
| 822 |
% |
| 823 |
% \section{\texorpdfstring{\scsty{}}{SuperCollider-IDE} style} |
| 824 |
% |
| 825 |
% The \scsty{} style mimics the default style of the \SC{} IDE. |
| 826 |
% |
| 827 |
% \begin{macro}{\toks@scpr} |
| 828 |
% We allocate a token list register in which we store settings that we'll use |
| 829 |
% to define the style. |
| 830 |
% \begin{macrocode} |
| 831 |
\newtoks\toks@scpr |
| 832 |
\toks@scpr=% |
| 833 |
{ |
| 834 |
language = \languageNormedDefd@scpr, |
| 835 |
basicstyle = \color{black}\ttfamily\normalsize, |
| 836 |
breaklines = true, |
| 837 |
showspaces = false, |
| 838 |
showstringspaces = false, |
| 839 |
upquote = true, |
| 840 |
rulecolor = \color{black!67}, |
| 841 |
numberstyle = \color{black!33}, |
| 842 |
keywordstyle = \color[RGB]{000,045,231}\bfseries, |
| 843 |
commentstyle = \color[RGB]{202,018,000} , |
| 844 |
stringstyle = \color[RGB]{095,095,095} , |
| 845 |
scsymbolstyle = \color[RGB]{000,113,000} , |
| 846 |
scenvvarstyle = \color[RGB]{147,070,014} , |
| 847 |
scclassstyle = \color[RGB]{000,040,211} , |
| 848 |
} |
| 849 |
% \end{macrocode} |
| 850 |
% \end{macro} |
| 851 |
% \begin{macrocode} |
| 852 |
\ifframed@scpr@ |
| 853 |
\toks@scpr\expandafter{\the\toks@scpr frame=single,} |
| 854 |
\fi |
| 855 |
\ifnumbered@scpr@ |
| 856 |
\toks@scpr=\expandafter{\the\toks@scpr numbers=left,} |
| 857 |
\fi |
| 858 |
\begingroup\edef\@tempa{\endgroup |
| 859 |
\noexpand\lstdefinestyle{SuperCollider-IDE}{\the\toks@scpr} |
| 860 |
}\@tempa |
| 861 |
% \end{macrocode} |
| 862 |
% |
| 863 |
% \Finale |
| 864 |
\endinput |