(*
Module: Quote
  Generic module providing useful primitives for quoting

Author: Raphael Pinson <raphael.pinson@camptocamp.com>

About: License
   This file is licenced under the LGPL v2+, like the rest of Augeas.

About: Lens Usage
   This is a generic module which doesn't apply to files directly.
   You can use its definitions to build lenses that require quoted values.
   It provides several levels of definitions, allowing to define more or less fine-grained quoted values:

     - the quote separators are separators that are useful to define quoted values;
     - the quoting functions are useful wrappers to easily enclose a lens in various kinds of quotes (single, double, any, optional or not);
     - 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.

About: Examples
   The <Test_Quote> file contains various examples and tests.
*)

module Quote =

(* Group: QUOTE SEPARATORS *)

(* Variable: dquote
     A double quote *)
let dquote = Util.del_str "\""

(* Variable: dquote_opt
     An optional double quote, default to double *)
let dquote_opt = del /"?/ "\""

(* Variable: dquote_opt_nil
     An optional double quote, default to nothing *)
let dquote_opt_nil = del /"?/ ""

(* Variable: squote
     A single quote *)
let squote = Util.del_str "'"

(* Variable: squote_opt
     An optional single quote, default to single *)
let squote_opt = del /'?/ "'"

(* Variable: squote_opt_nil
     An optional single quote, default to nothing *)
let squote_opt_nil = del /'?/ ""

(* Variable: quote
     A quote, either double or single, default to double *)
let quote = del /["']/ "\""

(* Variable: quote_opt
     An optional quote, either double or single, default to double *)
let quote_opt = del /["']?/ "\""

(* Variable: quote_opt_nil
     An optional quote, either double or single, default to nothing *)
let quote_opt_nil = del /["']?/ ""


(* Group: QUOTING FUNCTIONS *)

(*
View: do_dquote
  Enclose a lens in <dquote>s

  Parameters:
    body:lens - the lens to be enclosed
*)
let do_dquote (body:lens) =
  square dquote body dquote

(*
View: do_dquote_opt
  Enclose a lens in optional <dquote>s,
  use <dquote>s by default.

  Parameters:
    body:lens - the lens to be enclosed
*)
let do_dquote_opt (body:lens) =
  square dquote_opt body dquote_opt

(*
View: do_dquote_opt_nil
  Enclose a lens in optional <dquote>s,
  default to no quotes.

  Parameters:
    body:lens - the lens to be enclosed
*)
let do_dquote_opt_nil (body:lens) =
  square dquote_opt_nil body dquote_opt_nil

(*
View: do_squote
  Enclose a lens in <squote>s

  Parameters:
    body:lens - the lens to be enclosed
*)
let do_squote (body:lens) =
  square squote body squote

(*
View: do_squote_opt
  Enclose a lens in optional <squote>s,
  use <squote>s by default.

  Parameters:
    body:lens - the lens to be enclosed
*)
let do_squote_opt (body:lens) =
  square squote_opt body squote_opt

(*
View: do_squote_opt_nil
  Enclose a lens in optional <squote>s,
  default to no quotes.

  Parameters:
    body:lens - the lens to be enclosed
*)
let do_squote_opt_nil (body:lens) =
  square squote_opt_nil body squote_opt_nil

(*
View: do_quote
  Enclose a lens in <quote>s.

  Parameters:
    body:lens - the lens to be enclosed
*)
let do_quote (body:lens) =
  square quote body quote

(*
View: do_quote
  Enclose a lens in options <quote>s.

  Parameters:
    body:lens - the lens to be enclosed
*)
let do_quote_opt (body:lens) =
  square quote_opt body quote_opt

(*
View: do_quote
  Enclose a lens in options <quote>s,
  default to no quotes.

  Parameters:
    body:lens - the lens to be enclosed
*)
let do_quote_opt_nil (body:lens) =
  square quote_opt_nil body quote_opt_nil


(* Group: QUOTED VALUES *)

(* View: double
     A double-quoted value *)
let double =
     let body = store /[^\n]*/
  in do_dquote body

(* Variable: double_opt_re
     The regexp to store when value
     is optionally double-quoted *)
let double_opt_re = /[^\n\t "]([^\n"]*[^\n\t "])?/

(* View: double_opt
     An optionally double-quoted value
     Double quotes are not allowed in value
     Value cannot begin or end with spaces *)
let double_opt =
     let body = store double_opt_re
  in do_dquote_opt body

(* View: single
     A single-quoted value *)
let single =
     let body = store /[^\n]*/
  in do_squote body

(* Variable: single_opt_re
     The regexp to store when value
     is optionally single-quoted *)
let single_opt_re = /[^\n\t ']([^\n']*[^\n\t '])?/

(* View: single_opt
     An optionally single-quoted value
     Single quotes are not allowed in value
     Value cannot begin or end with spaces *)
let single_opt =
     let body = store single_opt_re
  in do_squote_opt body

(* View: any
     A quoted value *)
let any =
     let body = store /[^\n]*/
  in do_quote body

(* Variable: any_opt_re
     The regexp to store when value
     is optionally single- or double-quoted *)
let any_opt_re = /[^\n\t "']([^\n"']*[^\n\t "'])?/

(* View: any_opt
     An optionally quoted value
     Double or single quotes are not allowed in value
     Value cannot begin or end with spaces *)
let any_opt =
     let body = store any_opt_re
  in do_quote_opt body

(*
View: quote_spaces
  Make quotes mandatory if value contains spaces,
  and optional if value doesn't contain spaces.

Parameters:
  lns:lens - the lens to be enclosed
*)
let quote_spaces (lns:lens) =
     (* bare has no spaces, and is optionally quoted *)
     let bare = Quote.do_quote_opt (store /[^"' \t\n]+/)
     (* quoted has at least one space, and must be quoted *)
  in let quoted = Quote.do_quote (store /[^"'\n]*[ \t]+[^"'\n]*/)
  in [ lns . bare ] | [ lns . quoted ]

(*
View: dquote_spaces
  Make double quotes mandatory if value contains spaces,
  and optional if value doesn't contain spaces.

Parameters:
  lns:lens - the lens to be enclosed
*)
let dquote_spaces (lns:lens) =
     (* bare has no spaces, and is optionally quoted *)
     let bare = Quote.do_dquote_opt (store /[^" \t\n]+/)
     (* quoted has at least one space, and must be quoted *)
  in let quoted = Quote.do_dquote (store /[^"\n]*[ \t]+[^"\n]*/)
  in [ lns . bare ] | [ lns . quoted ]

(*
View: squote_spaces
  Make single quotes mandatory if value contains spaces,
  and optional if value doesn't contain spaces.

Parameters:
  lns:lens - the lens to be enclosed
*)
let squote_spaces (lns:lens) =
     (* bare has no spaces, and is optionally quoted *)
     let bare = Quote.do_squote_opt (store /[^' \t\n]+/)
     (* quoted has at least one space, and must be quoted *)
  in let quoted = Quote.do_squote (store /[^'\n]*[ \t]+[^'\n]*/)
  in [ lns . bare ] | [ lns . quoted ]