%% Expressions over the BOX language can be constructed by
%% \emph{composing} boxes using BOX operators. These operators
%% specify the relative positioning of boxes. BOX supports several of these
%% \emph{positional} operators. Examples of positional operators are the
%% \textsf{H} and \textsf{V} operators which format their sub-boxes
%% horizontally and vertically, respectively. The exact formatting of the
%% positional operators can be controlled by means of \emph{space options}.
%% These options allow for instance, the horizontal and vertical layout
%% within the \textsf{H} and \textsf{V} operators to be controlled.
%%
%% Besides positional operators, BOX also contains
%% \emph{non-positional} operators. These operators are used to control
%% how sub-boxes are displayed. These operators include font operators to
%% specify font parameters (font family, font color, etc.) and operators for
%% cross referencing.
%%
%% \subsection{Space Options}
%%
%% Space options are used to adapt the amount of layout between boxes. The
%% horizontal, vertical, and indentation offset between boxes can be
%% adapted.

module Box-Operators
exports

  %% Deprecated, but used by Transformers.
  context-free syntax
    BOX* -> BOX-LIST

  exports
      sorts SPACE-SYMBOL S-OPTION

      context-free syntax
         SPACE-SYMBOL "=" NatCon -> S-OPTION     {cons("SOpt")}
         SPACE-SYMBOL "=" BOX    -> S-OPTION     {cons("SOptB")}

%% Below all supported space options are defined. The \textsf{hs} option is
%% used to define the horizontal layout between boxes. The \textsf{vs}
%% option defines the amount of vertical layout between boxes (the number of
%% newlines between boxes in a vertical context). The \textsf{is} option
%% defines indentation between boxes within a vertical context. Not every
%% combination of space option and BOX operator makes sense. E.g.\ the
%% modification of the vertical offset in combination of the \textsf{H}
%% operator does not make any sense.

      context-free syntax
         "vs"                    -> SPACE-SYMBOL {cons("VS")}
         "hs"                    -> SPACE-SYMBOL {cons("HS")}
         "is"                    -> SPACE-SYMBOL {cons("IS")}

%%\subsection{Positional BOX Operators}
%% Smaller boxes can be composed to form new boxes using positional BOX
%% operators that specify the relative ordering of sub boxes.
%%
%% The \textsf{H} operator is used to format a list of boxes horizontally.
%% The operator only supports the \textsf{hs} space option to control the
%% amount of horizontal layout between its sub-boxes. The \textsf{V}
%% operator is used to format a list of boxes vertically. The operator
%% supports the \textsf{vs} and \textsf{is} space options to control the
%% amount of vertical layout and the amount of indentation between its
%% sub-boxes, respectively. The \textsf{HV} operator is used to format a
%% list of boxes horizontally \emph{or} vertically, depending on the
%% available width. The operator calculates an optimal combination of
%% \textsf{H} and \textsf{V} operators in such a way that the number of
%% lines occupied is minimized. Because the \textsf{HV} is a combination of
%% the \textsf{H} and \textsf{V} operators, it supports all space
%% options of these operators (\textsf{hs}, \textsf{vs}, and \textsf{is}).

   exports
      context-free syntax
         "H" S-OPTION*  "[" BOX* "]"  -> BOX {cons("H")}
         "V" S-OPTION*  "[" BOX* "]"  -> BOX {cons("V")}
         "HV" S-OPTION* "[" BOX* "]" -> BOX {cons("HV")}

%% The \textsf{ALT} operator is used to choose between two alternative BOX
%% expressions depending on the available width. When its first argument
%% fits on the current line, that BOX expression is used. Otherwise, the
%% \textsf{ALT} operator chooses the second alternative. No space options
%% are supported by this operator.

   exports
      context-free syntax
         "ALT" "[" BOX BOX "]" -> BOX {cons("ALT")}

%% Alignments are implemented by means of two BOX operators: \textsf{A} and
%% \textsf{R}. The arguments of the \textsf{A} operator are \textsf{R}
%% boxes. Each \textsf{R} BOX represents a row, each element of an
%% \textsf{R} BOX represents an entry in the alignment. The number of
%% arguments of an
%% \textsf{R} BOX may not exceed the number of columns of the alignment. For
%% each column the user can specify whether the alignment should be left,
%% right, or centered. The number of alignment indications should be equal
%% to the number of columns. Each alignment indication can be extended with
%% space options, specifying the horizontal layout between columns. The
%% \textsf{A} operator supports the \textsf{vs} space option which defines
%% the vertical layout between individual rows.
%%
%% \textsf{R} boxes occurring outside an alignment are formatted as
%% \text{HV} operator. This behavior enables the use of an alternative
%% formatting (not based on the \textsf{A} operator) of alignments within an
%% \textsf{ALT} operator. The \textsf{R} operator therefore supports all
%% space options of the \textsf{HV} operator.

   exports
      sorts A-OPTION A-OPTIONS

      context-free syntax
         "A" A-OPTIONS S-OPTION* "[" BOX* "]" -> BOX       {cons("A")}
         "R" S-OPTION* "[" BOX* "]"           -> BOX       {cons("R")}

%% Justification of columns and horizontal layout between columns can be
%% specified using A-OPTIONS. An A-OPTION is composed of an alignment
%% indicator (\textsf{l} for left, \textsf{r} for right, and \textsf{c} for
%% centered alignment), and space options (only the \textsf{hs} option is
%% supported).

         "l" S-OPTION*                            -> A-OPTION  {cons("AL")}
         "c" S-OPTION*                            -> A-OPTION  {cons("AC")}
         "r" S-OPTION*                            -> A-OPTION  {cons("AR")}
         "(" {A-OPTION ","}* ")"                  -> A-OPTIONS {cons("AOPTIONS")}

%%\subsection{Non-Positional BOX Operators}
%%
%% There are four different types of non-positional BOX operators: font
%% operators to change the textual appearance of BOX expressions, cross
%% reference operators to create links between boxes, the comment operator
%% to indicate that a BOX expression contains comments, and the line
%% operator to draw lines of characters of arbitrary length.
%%
%%
%% BOX font operators are used to change the textual appearance of the
%% argument BOX expression. Fonts can be characterized by the parameters
%% font name (\textsf{fn}), font family (\textsf{fm}), font series
%% (\textsf{se}), font shape (\textsf{sh}), font size (\textsf{sz}), and
%% font color (\textsf{cl}). The most general font operator is \textsf{F}.
%% By means of font parameters the desired font can be controlled.

   exports
      sorts FID FONT-PARAM F-OPTION FONT-OPERATOR

      lexical syntax
         [A-Za-z]+ -> FID

      context-free syntax
         FONT-PARAM "=" NatCon     -> F-OPTION      {cons("FNAT")}
         FONT-PARAM "=" FID        -> F-OPTION      {cons("FFID")}

      context-free syntax
         "F" F-OPTION*             -> FONT-OPERATOR {cons("F")}
         FONT-OPERATOR "[" BOX "]" -> BOX           {cons("FBOX")}
         "fn"                      -> FONT-PARAM    {cons("FN")}
         "fm"                      -> FONT-PARAM    {cons("FM")}
         "se"                      -> FONT-PARAM    {cons("SE")}
         "sh"                      -> FONT-PARAM    {cons("SH")}
         "sz"                      -> FONT-PARAM    {cons("SZ")}
         "cl"                      -> FONT-PARAM    {cons("CL")}

%% By using the \textsf{F} font operator, fonts are defined statically.
%% BOX also support fonts to be defined dynamically using special
%% font operators.  These operators are used to format specific language
%% constructs like keywords and variables. The mapping from these
%% operators to fonts is deferred to the back-ends.

   exports
      context-free syntax
         "KW"   -> FONT-OPERATOR {cons("KW")}
         "VAR"  -> FONT-OPERATOR {cons("VAR")}
         "NUM"  -> FONT-OPERATOR {cons("NUM")}
         "MATH" -> FONT-OPERATOR {cons("MATH")}

%% The \textsf{LBL} operator is used to label BOX terms. A labeled BOX term
%% can be refered to using the \textsf{REF} operator.  The first argument of
%% the \textsf{LBL} and \textsf{REF} operators denote the name of the label.
%% The second argument of the \textsf{LBL} operator denotes the BOX term to
%% label. The second argument of the \textsf{REF} operator denotes the BOX
%% containing the reference. Both operators do not support any space
%% options.

   exports
      context-free syntax
         "LBL" "[" BoxLiteral BOX "]" -> BOX {cons("LBL")}
         "REF" "[" BoxLiteral BOX "]" -> BOX {cons("REF")}

%% Comments can be formatted using the \textsf{C} operator. The operator
%% supports the \textsf{is} space option to denote the indentation level of
%% comments.

   exports
      context-free syntax
         "C" S-OPTION* "[" BOX* "]" -> BOX {cons("C")}

%% The \textsf{L} operator  is used to construct horizontal bars of fixed
%% \emph{or} variable width. A bar of fixed width can be constructed by
%% specifying its width as a fixed number. A bar of variable width can be
%% constructed by specifying a BOX expressions as width parameter. The
%% second argument of the \textsf{L} operator specifies the symbol of which
%% the bar should be constructed. The \textsf{L} operator does not support
%% any space options.

   exports
      context-free syntax
         "L" "[" BOX BOX "]"    -> BOX {cons("L")}
         "L" "[" NatCon BOX "]" -> BOX {cons("LNAT")}
