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