\documentclass{article}
\usepackage[margin=1in]{geometry}
\usepackage{microtype}
\usepackage{booktabs}
\usepackage{hyperref}
\usepackage{fox-listings}

\title{\texttt{fox-listings} --- Listings language definition
  for COSYScript (COSY INFINITY)}
\author{Eremey Valetov\\\url{https://github.com/evvaletov}}
\date{2026/03/07\quad v1.3}

\begin{document}
\maketitle

\section{Introduction}

The \texttt{fox-listings} package provides a language definition for the
\texttt{listings} package to typeset source code in COSYScript, the
programming language of
\href{https://cosyinfinity.org}{COSY INFINITY}, a beam dynamics code
using high-order differential-algebraic (DA) transfer maps and methods,
developed at Michigan State University.
COSYScript is compiled and executed by the FOXY subsystem; source files
use the \texttt{.fox} extension.  This package uses the name \texttt{FOX}
for the \texttt{listings} language identifier and style prefixes.

The package defines six keyword groups that can be independently styled,
supports nested \texttt{\{...\}} comments and single-quoted string literals,
and provides two ready-made styles.

\section{Usage}

Load the package after \texttt{listings}:

\begin{verbatim}
\usepackage{fox-listings}
\end{verbatim}

The package automatically loads \texttt{listings} and \texttt{xcolor}.

\subsection{Color style}

\begin{verbatim}
\begin{lstlisting}[style=FOXcolor]
  ...
\end{lstlisting}
\end{verbatim}

\subsection{Monochrome style}

\begin{verbatim}
\begin{lstlisting}[style=FOXmono]
  ...
\end{lstlisting}
\end{verbatim}

\subsection{Language only (custom style)}

\begin{verbatim}
\begin{lstlisting}[language=FOX]
  ...
\end{lstlisting}
\end{verbatim}

\subsection{Inline code}

\begin{verbatim}
\lstinline[language=FOX]{VARIABLE X 1 ;}
\end{verbatim}

\section{Keyword groups}

Keywords are split into six groups so that each category can be styled
independently.  Groups~1--3 cover the general-purpose language (control
flow, math, DA algebra), group~4 covers the beam-physics command set,
group~5 covers the graphics subsystem, and group~6 covers built-in
constants and global variables.  The \texttt{FOXcolor} style assigns a
distinct color to each group; the \texttt{FOXmono} style bolds groups~1, 2, and~6, and leaves the
rest unstyled.

\begin{tabular}{cll}
\toprule
Group & Category & Examples \\
\midrule
1 & Control flow, declarations & \texttt{PROCEDURE}, \texttt{IF}, \texttt{VARIABLE}, \texttt{WRITE} \\
2 & Intrinsic functions & \texttt{SIN}, \texttt{SQRT}, \texttt{ABS}, \texttt{CONS}, \texttt{DA} \\
3 & Intrinsic procedures & \texttt{DAINI}, \texttt{VELSET}, \texttt{CONFIG\_SET} \\
4 & Beam physics & \texttt{OV}, \texttt{MQ}, \texttt{CR}, \texttt{FR}, \texttt{ER} \\
5 & Graphics & \texttt{GRMOVE}, \texttt{GRDRAW}, \texttt{GREPS}, \texttt{PP} \\
6 & Constants/globals & \texttt{PI}, \texttt{CLIGHT}, \texttt{MAP}, \texttt{RAY} \\
\bottomrule
\end{tabular}

\section{Examples}

\subsection{Color style (\texttt{FOXcolor})}

\begin{lstlisting}[style=FOXcolor]
INCLUDE 'COSY' ;
VARIABLE X 1 ;
VARIABLE Y 1 ;

{Compute and display a value}
X := SIN(0.5) ;
Y := SQRT(X) + 1 ;
WRITE 6 'Result:' Y ;

PROCEDURE GREET A B ;
   VARIABLE C 1 ;
   C := A + B ;
   WRITE 6 'Sum =' C ;
ENDPROCEDURE ;

GREET 3 4 ;

OV 3 2 0 ;
UM ;
MQ 0.5 0.1 ;
CR ;
PP -10 10 -10 10 ;

END ;
\end{lstlisting}

\subsection{Monochrome style (\texttt{FOXmono})}

\begin{lstlisting}[style=FOXmono]
INCLUDE 'COSY' ;
VARIABLE X 1 ;

PROCEDURE ORBIT_FIND ;
   VARIABLE TOL 1 ;
   TOL := 1E-10 ;
   FIT X := 0 ;
      UM ; MQ 0.5 0.1 ; CR ;
   ENDFIT 1E-12 100 1 1 ;
ENDPROCEDURE ;

ORBIT_FIND ;
WRITE 6 'Orbit:' X ;
END ;
\end{lstlisting}

\subsection{DA computation with orbit fitting}

\begin{lstlisting}[style=FOXcolor]
INCLUDE 'COSY' ;

PROCEDURE RUN ;
   VARIABLE KE 1 ;  VARIABLE NUX 1 ;  VARIABLE NUY 1 ;
   OV 3 3 0 ;
   KE := 30 ;
   RPP KE ;

   {Find closed orbit by adjusting initial conditions}
   FIT MAP(1) := 0 ; MAP(3) := 0 ;
      UM ;
      DL 0.5 ; MQ 0.3 0.12 ; DL 0.5 ;
      MQ -0.25 0.12 ;
      CR ;
   ENDFIT 1E-12 100 1 1 ;

   {Extract tunes from the one-turn transfer map}
   NUX := ACOS(CONS(MAP(1) + MAP(2+NM1))/2) / (2*PI) ;
   NUY := ACOS(CONS(MAP(3) + MAP(4+NM1))/2) / (2*PI) ;
   WRITE 6 'Tunes: '&SF(NUX,'(F8.5)')&'  '&SF(NUY,'(F8.5)') ;
ENDPROCEDURE ;
RUN ; END ;
\end{lstlisting}

\subsection{Including an external file}

Use \verb|\lstinputlisting| to typeset an external \texttt{.fox} source file:

\begin{verbatim}
\lstinputlisting[style=FOXcolor, caption={Simulation program},
  firstline=1, lastline=30]{EEFFAGsim.fox}
\end{verbatim}

\section{Known limitations}

The \texttt{listings} package does not highlight in-code numbers for
user-defined languages.  Fortran-style \texttt{D}-exponent notation
(e.g., \texttt{1.5D-3}) and standard decimal literals (\texttt{0.5},
\texttt{1E-3}) are rendered in the base style.

Because COSYScript is case-insensitive (\texttt{sensitive=false}), short
keywords such as \texttt{OV}, \texttt{MQ}, and \texttt{CR} may highlight
user variables that happen to share the same name.  This is inherent to the
\texttt{listings} tokenizer; avoiding these names for user variables is
recommended.

\section{License}

This material is subject to the \LaTeX{} Project Public License 1.3c.
See \url{https://www.latex-project.org/lppl/lppl-1-3c/}.

\end{document}
