buildinfo-reference-generator/template.zinza

   1 .. _buildinfo-field-reference:
   2
   3 Field Syntax Reference
   4 ======================
   5
   6 Notation
   7 ---------------
   8
   9 Field syntax is described as they are in the latest cabal file format version.
  10
  11 * terminals are enclosed in quotes and type set in typewriter script:
  12
  13   .. math::
  14
  15       \mathord{"}\mathtt{example}\mathord{"}
  16
  17 * non-terminals are type set in italic:
  18
  19   .. math::
  20
  21       \mathit{version\text-range}
  22
  23 * character sets are type set resembling regular expression notation:
  24
  25
  26   .. math::
  27
  28       [ \mathord{"}\mathtt{1}\mathord{"} \cdots \mathord{"}\mathtt{9}\mathord{"} ]
  29
  30   Character set complements have :math:`c` superscript:
  31
  32   .. math::
  33
  34       [ \mathord{"}\mathtt{1}\mathord{"} \cdots \mathord{"}\mathtt{9}\mathord{"} ]^c
  35
  36 * repetition is type set using regular expression inspired notation.
  37   Superscripts tell how many time to repeat:
  38   The generic notation is :math:`\in[n\ldots5]`, however there
  39   are common shorthands:
  40   :math:`\ast` for :math:`\in[0\ldots\infty]` (``many``),
  41   :math:`+` for :math:`\in[1\ldots\infty]` (``some``),
  42   :math:`?` for :math:`\in[0\ldots1]` (``optional``).
  43
  44   Subscripts tell the used separator:
  45
  46   .. math::
  47
  48       \mathit{digit}^+_{\mathord{"}\mathtt{.}\mathord{"}}
  49
  50   Would be ``digit(\.digit)*`` in common regex syntax.
  51
  52 * alternatives are listed in braces separated by vertical bar:
  53
  54   .. math::
  55
  56       \{ \mathit{foo} \mid \mathit{bar} \}
  57
  58   In case of multiple alternatives, the stacked notation is used
  59
  60   .. math::
  61
  62       \left\{\begin{gathered}
  63       \mathit{one} \\
  64       \mathit{two} \\
  65       \mathit{three} \\
  66       \mathit{four} \\
  67       \mathit{five}
  68       \end{gathered}\right\}
  69
  70 * parenthesis are used only for grouping:
  71
  72   .. math::
  73
  74       \left(\mathit{foo} \mid \mathit{bar}\right)^+
  75
  76 * any amount of spaces, and at least single space are type set using
  77   :math:`\circ` and :math:`\bullet` respectively.
  78   They may appear standalone, not only as binary operators.
  79
  80   .. math::
  81
  82       \mathit{module} \bullet \mathord{``}\mathtt{as}\mathord{"} \bullet \mathit{module}
  83
  84 * While notation is heavily regular expression inspired, there
  85   are also fixed points, which allow represent recursive grammars
  86
  87
  88   .. math::
  89
  90       \mathbf{fix}\; \mathit{expr}\; \mathbf{in}\; \mathit{digit}
  91       \mid \mathit{expr} \circ \mathord{``}\mathtt{+}\mathord{"} \circ \mathit{expr}
  92       \mid \mathord{``}\mathtt{(} \mathord{"} \circ \mathit{expr} \circ \mathord{``}\mathtt{)}\mathord{"}
  93
  94 Lists
  95 -----
  96
  97 Many fields in cabal file format are lists. There are three variations:
  98
  99 Space separated
 100     Are used for lists of things with simple grammars, for example :pkg-field:`ghc-options`
 101
 102     .. math::
 103         {{spaceList}}
 104
 105 Comma separated
 106     Are used for lists of things with complicated grammars, for example :pkg-field:`build-depends`
 107     There can be leading or trailing comma (but not both) since ``cabal-version: 2.2``.
 108     Note, the comma cannot exist alone.
 109
 110     .. math::
 111         \mathrm{commalist}(\mathit{element}) =
 112         {{commaList}}
 113
 114 Optional comma separated
 115     Surprisingly many fields can have optional comma separator.
 116     Since ``cabal-version: 3.0`` comma usage have to be consistent,
 117     in other words either used everywhere or nowhere.
 118     It's recommended to avoid using comma in these fields,
 119     an example field is :pkg-field:`default-extensions`.
 120
 121     .. math::
 122         \mathrm{optcommalist}(\mathit{element}) =
 123         {{optCommaList}}
 124
 125 Non-terminals
 126 -------------
 127
 128 In the syntax definitions below the following non-terminal symbols are used:
 129
 130 {% for production in productions %}
 131 {{ production.name }}
 132     {{ production.description }}
 133
 134     .. math::
 135         {{ production.syntax }}
 136
 137 {% endfor %}
 138
 139 Build info fields
 140 -----------------
 141
 142 {% for field in buildInfoFields %}
 143 {{ field.name }}
 144     * {{field.format}}
 145 {% if notNull field.default %}
 146     * Default: ``{{field.default}}``
 147 {% endif %}
 148 {% if notNull field.availableSince %}
 149     * Available since ``cabal-version: {{field.availableSince}}``.
 150 {% endif %}
 151 {% if notNull field.deprecatedSince.fst %}
 152     * Deprecated since ``cabal-version: {{field.deprecatedSince.fst}}``: {{field.deprecatedSince.snd}}
 153 {% endif %}
 154 {% if notNull field.removedIn.fst %}
 155     * Removed in ``cabal-version: {{field.removedIn.fst}}``: {{field.removedIn.snd}}
 156 {% endif %}
 157 {# We show documentation link only for non deprecated fields #}
 158 {% if null field.deprecatedSince.fst %}
 159 {% if null field.removedIn.fst %}
 160     * Documentation of :pkg-field:`{{field.name}}`
 161 {% endif %}
 162 {% endif %}
 163 {% if notNull field.syntax %}
 164
 165     .. math::
 166         {{field.syntax}}
 167 {% endif %}
 168
 169 {% endfor %}
 170
 171 Package description fields
 172 --------------------------
 173
 174 {% for field in packageDescriptionFields %}
 175 {{ field.name }}
 176     * {{field.format}}
 177 {% if notNull field.default %}
 178     * Default: ``{{field.default}}``
 179 {% endif %}
 180 {% if notNull field.availableSince %}
 181     * Available since ``cabal-version: {{field.availableSince}}``.
 182 {% endif %}
 183 {% if notNull field.deprecatedSince.fst %}
 184     * Deprecated since ``cabal-version: {{field.deprecatedSince.fst}}``: {{field.deprecatedSince.snd}}
 185 {% endif %}
 186 {% if notNull field.removedIn.fst %}
 187     * Removed in ``cabal-version: {{field.removedIn.fst}}``: {{field.removedIn.snd}}
 188 {% endif %}
 189 {# We show documentation link only for non deprecated fields #}
 190 {% if null field.deprecatedSince.fst %}
 191 {% if null field.removedIn.fst %}
 192     * Documentation of :pkg-field:`{{field.name}}`
 193 {% endif %}
 194 {% endif %}
 195 {% if notNull field.syntax %}
 196
 197     .. math::
 198         {{field.syntax}}
 199 {% endif %}
 200
 201 {% endfor %}
 202
 203 Test-suite fields
 204 -----------------
 205
 206 {% for field in testSuiteFields %}
 207 {{ field.name }}
 208     * {{field.format}}
 209 {% if notNull field.default %}
 210     * Default: ``{{field.default}}``
 211 {% endif %}
 212 {% if notNull field.availableSince %}
 213     * Available since ``cabal-version: {{field.availableSince}}``.
 214 {% endif %}
 215 {% if notNull field.deprecatedSince.fst %}
 216     * Deprecated since ``cabal-version: {{field.deprecatedSince.fst}}``: {{field.deprecatedSince.snd}}
 217 {% endif %}
 218 {% if notNull field.removedIn.fst %}
 219     * Removed in ``cabal-version: {{field.removedIn.fst}}``: {{field.removedIn.snd}}
 220 {% endif %}
 221 {# We show documentation link only for non deprecated fields #}
 222 {% if null field.deprecatedSince.fst %}
 223 {% if null field.removedIn.fst %}
 224     * Documentation of :pkg-field:`test-suite:{{field.name}}`
 225 {% endif %}
 226 {% endif %}
 227 {% if notNull field.syntax %}
 228
 229     .. math::
 230         {{field.syntax}}
 231 {% endif %}
 232
 233 {% endfor %}