lenses/quote.aug

   1 (*
   2 Module: Quote
   3   Generic module providing useful primitives for quoting
   4
   5 Author: Raphael Pinson <raphael.pinson@camptocamp.com>
   6
   7 About: License
   8    This file is licenced under the LGPL v2+, like the rest of Augeas.
   9
  10 About: Lens Usage
  11    This is a generic module which doesn't apply to files directly.
  12    You can use its definitions to build lenses that require quoted values.
  13    It provides several levels of definitions, allowing to define more or less fine-grained quoted values:
  14
  15      - the quote separators are separators that are useful to define quoted values;
  16      - the quoting functions are useful wrappers to easily enclose a lens in various kinds of quotes (single, double, any, optional or not);
  17      - the quoted values definitions are common quoted patterns. They use the quoting functions in order to provide useful shortcuts for commonly met needs. In particular, the <quote_spaces> (and similar) function force values that contain spaces to be quoted, but allow values without spaces to be unquoted.
  18
  19 About: Examples
  20    The <Test_Quote> file contains various examples and tests.
  21 *)
  22
  23 module Quote =
  24
  25 (* Group: QUOTE SEPARATORS *)
  26
  27 (* Variable: dquote
  28      A double quote *)
  29 let dquote = Util.del_str "\""
  30
  31 (* Variable: dquote_opt
  32      An optional double quote, default to double *)
  33 let dquote_opt = del /"?/ "\""
  34
  35 (* Variable: dquote_opt_nil
  36      An optional double quote, default to nothing *)
  37 let dquote_opt_nil = del /"?/ ""
  38
  39 (* Variable: squote
  40      A single quote *)
  41 let squote = Util.del_str "'"
  42
  43 (* Variable: squote_opt
  44      An optional single quote, default to single *)
  45 let squote_opt = del /'?/ "'"
  46
  47 (* Variable: squote_opt_nil
  48      An optional single quote, default to nothing *)
  49 let squote_opt_nil = del /'?/ ""
  50
  51 (* Variable: quote
  52      A quote, either double or single, default to double *)
  53 let quote = del /["']/ "\""
  54
  55 (* Variable: quote_opt
  56      An optional quote, either double or single, default to double *)
  57 let quote_opt = del /["']?/ "\""
  58
  59 (* Variable: quote_opt_nil
  60      An optional quote, either double or single, default to nothing *)
  61 let quote_opt_nil = del /["']?/ ""
  62
  63
  64 (* Group: QUOTING FUNCTIONS *)
  65
  66 (*
  67 View: do_dquote
  68   Enclose a lens in <dquote>s
  69
  70   Parameters:
  71     body:lens - the lens to be enclosed
  72 *)
  73 let do_dquote (body:lens) =
  74   square dquote body dquote
  75
  76 (*
  77 View: do_dquote_opt
  78   Enclose a lens in optional <dquote>s,
  79   use <dquote>s by default.
  80
  81   Parameters:
  82     body:lens - the lens to be enclosed
  83 *)
  84 let do_dquote_opt (body:lens) =
  85   square dquote_opt body dquote_opt
  86
  87 (*
  88 View: do_dquote_opt_nil
  89   Enclose a lens in optional <dquote>s,
  90   default to no quotes.
  91
  92   Parameters:
  93     body:lens - the lens to be enclosed
  94 *)
  95 let do_dquote_opt_nil (body:lens) =
  96   square dquote_opt_nil body dquote_opt_nil
  97
  98 (*
  99 View: do_squote
 100   Enclose a lens in <squote>s
 101
 102   Parameters:
 103     body:lens - the lens to be enclosed
 104 *)
 105 let do_squote (body:lens) =
 106   square squote body squote
 107
 108 (*
 109 View: do_squote_opt
 110   Enclose a lens in optional <squote>s,
 111   use <squote>s by default.
 112
 113   Parameters:
 114     body:lens - the lens to be enclosed
 115 *)
 116 let do_squote_opt (body:lens) =
 117   square squote_opt body squote_opt
 118
 119 (*
 120 View: do_squote_opt_nil
 121   Enclose a lens in optional <squote>s,
 122   default to no quotes.
 123
 124   Parameters:
 125     body:lens - the lens to be enclosed
 126 *)
 127 let do_squote_opt_nil (body:lens) =
 128   square squote_opt_nil body squote_opt_nil
 129
 130 (*
 131 View: do_quote
 132   Enclose a lens in <quote>s.
 133
 134   Parameters:
 135     body:lens - the lens to be enclosed
 136 *)
 137 let do_quote (body:lens) =
 138   square quote body quote
 139
 140 (*
 141 View: do_quote
 142   Enclose a lens in options <quote>s.
 143
 144   Parameters:
 145     body:lens - the lens to be enclosed
 146 *)
 147 let do_quote_opt (body:lens) =
 148   square quote_opt body quote_opt
 149
 150 (*
 151 View: do_quote
 152   Enclose a lens in options <quote>s,
 153   default to no quotes.
 154
 155   Parameters:
 156     body:lens - the lens to be enclosed
 157 *)
 158 let do_quote_opt_nil (body:lens) =
 159   square quote_opt_nil body quote_opt_nil
 160
 161
 162 (* Group: QUOTED VALUES *)
 163
 164 (* View: double
 165      A double-quoted value *)
 166 let double =
 167      let body = store /[^\n]*/
 168   in do_dquote body
 169
 170 (* Variable: double_opt_re
 171      The regexp to store when value
 172      is optionally double-quoted *)
 173 let double_opt_re = /[^\n\t "]([^\n"]*[^\n\t "])?/
 174
 175 (* View: double_opt
 176      An optionaly double-quoted value
 177      Double quotes are not allowed in value
 178      Value cannot begin or end with spaces *)
 179 let double_opt =
 180      let body = store double_opt_re
 181   in do_dquote_opt body
 182
 183 (* View: single
 184      A single-quoted value *)
 185 let single =
 186      let body = store /[^\n]*/
 187   in do_squote body
 188
 189 (* Variable: single_opt_re
 190      The regexp to store when value
 191      is optionally single-quoted *)
 192 let single_opt_re = /[^\n\t ']([^\n']*[^\n\t '])?/
 193
 194 (* View: single_opt
 195      An optionaly single-quoted value
 196      Single quotes are not allowed in value
 197      Value cannot begin or end with spaces *)
 198 let single_opt =
 199      let body = store single_opt_re
 200   in do_squote_opt body
 201
 202 (* View: any
 203      A quoted value *)
 204 let any =
 205      let body = store /[^\n]*/
 206   in do_quote body
 207
 208 (* Variable: any_opt_re
 209      The regexp to store when value
 210      is optionally single- or double-quoted *)
 211 let any_opt_re = /[^\n\t "']([^\n"']*[^\n\t "'])?/
 212
 213 (* View: any_opt
 214      An optionaly quoted value
 215      Double or single quotes are not allowed in value
 216      Value cannot begin or end with spaces *)
 217 let any_opt =
 218      let body = store any_opt_re
 219   in do_quote_opt body
 220
 221 (*
 222 View: quote_spaces
 223   Make quotes mandatory if value contains spaces,
 224   and optional if value doesn't contain spaces.
 225
 226 Parameters:
 227   lns:lens - the lens to be enclosed
 228 *)
 229 let quote_spaces (lns:lens) =
 230      (* bare has no spaces, and is optionally quoted *)
 231      let bare = Quote.do_quote_opt (store /[^"' \t\n]+/)
 232      (* quoted has at least one space, and must be quoted *)
 233   in let quoted = Quote.do_quote (store /[^"'\n]*[ \t]+[^"'\n]*/)
 234   in [ lns . bare ] | [ lns . quoted ]
 235
 236 (*
 237 View: dquote_spaces
 238   Make double quotes mandatory if value contains spaces,
 239   and optional if value doesn't contain spaces.
 240
 241 Parameters:
 242   lns:lens - the lens to be enclosed
 243 *)
 244 let dquote_spaces (lns:lens) =
 245      (* bare has no spaces, and is optionally quoted *)
 246      let bare = Quote.do_dquote_opt (store /[^" \t\n]+/)
 247      (* quoted has at least one space, and must be quoted *)
 248   in let quoted = Quote.do_dquote (store /[^"\n]*[ \t]+[^"\n]*/)
 249   in [ lns . bare ] | [ lns . quoted ]
 250
 251 (*
 252 View: squote_spaces
 253   Make single quotes mandatory if value contains spaces,
 254   and optional if value doesn't contain spaces.
 255
 256 Parameters:
 257   lns:lens - the lens to be enclosed
 258 *)
 259 let squote_spaces (lns:lens) =
 260      (* bare has no spaces, and is optionally quoted *)
 261      let bare = Quote.do_squote_opt (store /[^' \t\n]+/)
 262      (* quoted has at least one space, and must be quoted *)
 263   in let quoted = Quote.do_squote (store /[^'\n]*[ \t]+[^'\n]*/)
 264   in [ lns . bare ] | [ lns . quoted ]