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

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

\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 the COSY INFINITY beam physics and differential
algebra (DA) framework 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
and~2 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 support custom number-format rules
for user-defined languages.  Fortran-style \texttt{D}-exponent notation
(e.g., \texttt{1.5D-3}) used in some COSY programs will not receive
special number highlighting.

\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}
