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

\title{\texttt{fox-listings} \\ \large Listings language definition
  for COSYScript}
\author{Eremey Valetov\\\url{https://github.com/evvaletov}}
\date{March 21, 2026\quad v1.4}

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

All keywords have been cross-checked against the pristine COSY INFINITY
v10 source (\texttt{cosy.fox} procedures, functions, and global variables)
and the FOXY compiler intrinsic tables (\texttt{foxy.f}).  Group~3 also
includes five COSYFFAG-specific configuration procedures
(\texttt{CONFIG\_SET}, etc.)\ that are not in the pristine distribution.

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

\section{Examples}

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

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

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

PROCEDURE RUN ;
   VARIABLE X 1 ;
   VARIABLE Y 1 ;
   VARIABLE B 1 ;

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

   GREET 3 4 ;

   OV 3 2 0 ;
   RP 10000 1.00728 1 ;
   B := 0.01*CONS(CHIM)*0.05 ;
   UM ;
   MQ 0.5 B 0.05 ;
   DL 24 ;
   MQ 1 -B 0.05 ;
   DL 24 ;
   MQ 0.5 B 0.05 ;
   CR ;
ENDPROCEDURE ;
RUN ; END ;
\end{lstlisting}

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

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

PROCEDURE RUN ;
   VARIABLE KF 1 ; VARIABLE KD 1 ; VARIABLE OBJ 1 ;

   OV 1 2 0 ;
   RP 10000 1.00728 1 ;
   KF :=  0.01*CONS(CHIM)*0.05 ;
   KD := -0.01*CONS(CHIM)*0.05 ;

   FIT KF KD ;
      UM ;
      MQ 0.5 KF 0.05 ;
      DL 24 ;
      MQ 1 KD 0.05 ;
      DL 24 ;
      MQ 0.5 KF 0.05 ;
      OBJ := (ME(1,2))^2 + (ME(3,4))^2 ;
   ENDFIT 1E-10 100 1 OBJ ;

   WRITE 6 'Matched KF:' KF ;
   WRITE 6 'Matched KD:' KD ;
ENDPROCEDURE ;
RUN ; END ;
\end{lstlisting}

\subsection{Tune extraction}

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

PROCEDURE COMPUTE_TUNES ;
   VARIABLE MU 100 2 ;
   VARIABLE B 1 ;
   B := 0.01*CONS(CHIM)*0.05 ;

   {Build a FODO cell transfer map}
   UM ;
   MQ 0.5 B 0.05 ;
   DL 24 ;
   MQ 1 -B 0.05 ;
   DL 24 ;
   MQ 0.5 B 0.05 ;

   {Extract tunes}
   TP MU ;
   WRITE 6 'Tunes: '&SF(CONS(MU(1)),'(F8.5)')&'  '&SF(CONS(MU(2)),'(F8.5)') ;
ENDPROCEDURE ;

PROCEDURE RUN ;
   OV 3 2 0 ;
   RP 10000 1.00728 1 ;
   COMPUTE_TUNES ;
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.

The \texttt{listings} tokenizer has no scope or context awareness, so a user
variable that shares its name with a keyword (e.g., \texttt{OV}, \texttt{MQ},
\texttt{CR}) will be highlighted as a keyword.

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