bundles/sexplib/sexplib-7.0.5/lib/path.mli

   1 (******************************************************************************
   2  *                             Sexplib                                        *
   3  *                                                                            *
   4  * Copyright (C) 2005- Jane Street Holding, LLC                               *
   5  *    Contact: opensource@janestreet.com                                      *
   6  *    WWW: http://www.janestreet.com/ocaml                                    *
   7  *    Author: Markus Mottl                                                    *
   8  *                                                                            *
   9  * This library is free software; you can redistribute it and/or              *
  10  * modify it under the terms of the GNU Lesser General Public                 *
  11  * License as published by the Free Software Foundation; either               *
  12  * version 2 of the License, or (at your option) any later version.           *
  13  *                                                                            *
  14  * This library is distributed in the hope that it will be useful,            *
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of             *
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU          *
  17  * Lesser General Public License for more details.                            *
  18  *                                                                            *
  19  * You should have received a copy of the GNU Lesser General Public           *
  20  * License along with this library; if not, write to the Free Software        *
  21  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA  *
  22  *                                                                            *
  23  ******************************************************************************)
  24
  25 (** Path: Module for Substitutions within S-expressions *)
  26
  27 (** {6 Types} *)
  28
  29 (** Type of substitution elements *)
  30 type el =
  31   | Pos of int  (** [Pos n] denotes [n]th element in a tuple *)
  32   | Match of string * int
  33       (** [Match (tag, n)] denotes [n]th argument of sum matching [tag] *)
  34   | Rec of string  (** [Rec name] denotes the record field having [name] *)
  35
  36 (** Type of substitution paths *)
  37 type t = el list
  38
  39
  40 (** {6 High-level functions} *)
  41
  42 val parse : string -> t
  43 (** [parse str] @return a substitution path represented by string [str].
  44
  45     Syntax:
  46
  47       "." ->
  48         separates path elements; must be present at start of string.
  49
  50       "\[4\]" ->
  51         specifies the 4th element in a tuple.
  52
  53       "some_tag\[4\]" ->
  54         tries to match [some_tag], then denotes its 4th argument.
  55
  56       "name" ->
  57         denotes record field having [name]
  58
  59     Example from test code:
  60
  61       ".t.x.B[1]" -> choose record field with name [t], then subfield
  62       [x].  Match this value against [B], and denote its first argument.
  63
  64     @raise Failure if the path is syntactically invalid.
  65 *)
  66
  67 val get : ?path : t -> ?str : string -> Sexp.t -> Sexp.t
  68 (** [get ?path ?str sexp] if [path] is provided, use it as path.
  69     Otherwise, if [str] is provided, parse it as a path.  If neither
  70     is provided, assume an empty path.  @return the sub-expression from
  71     S-expression [sexp] denoted by the path.
  72
  73     @raise Failure if path is syntactically invalid or if the path
  74     structure clashes with the structure of the data.
  75 *)
  76
  77 val replace : ?path : t -> ?str : string -> Sexp.t -> subst : Sexp.t -> Sexp.t
  78 (** [replace ?path ?str sexp ~subst] like [get], but does not extract
  79     a sub-expression but substitutes it with [subst].  @return resulting
  80     S-expression.
  81
  82     @raise Failure if path is syntactically invalid or if the path
  83     structure clashes with the structure of the data.
  84 *)
  85
  86 val replace_no_path : str : string -> Sexp.t -> subst : Sexp.t -> Sexp.t
  87 (** [replace_no_path ~str sexp ~subst] like [replace], but does not take
  88     optional arguments.  [str] must be specified.
  89
  90     @raise Failure if path is syntactically invalid or if the path
  91     structure clashes with the structure of the data.
  92 *)
  93
  94 val subst_path : Sexp.t -> t -> (Sexp.t -> Sexp.t) * Sexp.t
  95 (** [subst_path sexp path] @return the tuple [(subst, sub)], where [subst]
  96     is a function that returns an S-expression in which the subexpression
  97     denoted by [path] in [sexp] has been substituted by its argument.
  98     [sub] is the denoted subexpression.  Note that [subst sub = sexp].
  99
 100     @raise Failure if path is syntactically invalid or if the path
 101     structure clashes with the structure of the data.
 102 *)
 103
 104
 105 (** {6 Low-level functions} *)
 106
 107 val extract_pos : int -> Sexp.t -> (Sexp.t option -> Sexp.t) * Sexp.t
 108 (** [extract_pos n sexp] @return the tuple [(subst, sub)], where [subst]
 109     is a function that returns an S-expression in which the subexpression
 110     denoted at position [n] in [sexp], which must be a list, has been
 111     substituted by [value] if the optional argument is [Some value], or
 112     removes the denoted subexpression if the optional argument is [None].
 113     [sub] is the denoted subexpression.  Note that [subst (Some sub) =
 114     sexp].
 115
 116     @raise Failure if the position cannot be resolved within the given
 117     S-expression.
 118 *)
 119
 120 val extract_match :
 121   string -> int -> Sexp.t -> (Sexp.t option -> Sexp.t) * Sexp.t
 122 (** [extract_match tag n sexp] @return the tuple [(subst, sub)], where
 123     [subst] is a function that returns an S-expression in which the
 124     subexpression denoted by matching [tag] and taking its [n]th argument
 125     in [sexp] has been substituted by [value] if the argument is [Some
 126     value], or removes the denoted subexpression if the optional argument
 127     is [None].  [sub] is the denoted subexpression.  Note that [subst
 128     (Some sub) = sexp].
 129
 130     @raise Failure if the S-expression does not represent a sum tag.
 131 *)
 132
 133 val extract_rec : string -> Sexp.t -> (Sexp.t -> Sexp.t) * Sexp.t
 134 (** [extract_rec name sexp] @return the tuple [(subst, sub)], where
 135     [subst] is a function that returns an S-expression in which the
 136     subexpression denoted by matching field name [name] in [sexp] has
 137     been substituted by its argument.  [sub] is the denoted subexpression.
 138     Note that [subst (Some sub) = sexp].
 139
 140     @raise Failure if the S-expression does not represent a record.
 141 *)