caml_named_value returns const value pointer in OCaml 4.09+

[ocaml-augeas.git] / augeas.mli

diff --git a/augeas.mli b/augeas.mli
index bada127..8cbeae1 100644 (file)
--- a/augeas.mli
+++ b/augeas.mli
@@ -21,10 +21,6 @@
 type t
   (** Augeas library handle. *)
 
-exception Error of string
-  (** This exception is thrown when the underlying Augeas library
-      returns an error. *)
-
 type flag =
   | AugSaveBackup                      (** Rename original with .augsave *)
   | AugSaveNewFile                     (** Save changes to .augnew *)
@@ -32,8 +28,44 @@ type flag =
   | AugNoStdinc
   | AugSaveNoop
   | AugNoLoad
+  | AugNoModlAutoload
+  | AugEnableSpan
+  | AugNoErrClose
+  | AugTraceModuleLoading
   (** Flags passed to the {!create} function. *)
 
+type error_code =
+  | AugErrInternal             (** Internal error (bug) *)
+  | AugErrPathX                        (** Invalid path expression *)
+  | AugErrNoMatch              (** No match for path expression *)
+  | AugErrMMatch               (** Too many matches for path expression *)
+  | AugErrSyntax               (** Syntax error in lens file *)
+  | AugErrNoLens               (** Lens lookup failed *)
+  | AugErrMXfm                 (** Multiple transforms *)
+  | AugErrNoSpan               (** No span for this node *)
+  | AugErrMvDesc               (** Cannot move node into its descendant *)
+  | AugErrCmdRun               (** Failed to execute command *)
+  | AugErrBadArg               (** Invalid argument in funcion call *)
+  | AugErrLabel                        (** Invalid label *)
+  | AugErrCpDesc               (** Cannot copy node into its descendant *)
+  | AugErrUnknown of int
+  (** Possible error codes. *)
+
+type transform_mode =
+  | Include
+  | Exclude
+  (** The operation mode for the {!transform} function. *)
+
+exception Error of error_code * string * string * string * string
+  (** This exception is thrown when the underlying Augeas library
+      returns an error.  The tuple represents:
+      - the Augeas error code
+      - the ocaml-augeas error string
+      - the Augeas error message
+      - the human-readable explanation of the Augeas error, if available
+      - a string with details of the Augeas error
+   *)
+
 type path = string
   (** A path expression.
 
@@ -63,6 +95,15 @@ val close : t -> unit
 
       Do not use the handle after closing it. *)
 
+val defnode : t -> string -> string -> string option -> int * bool
+  (** [defnode t name expr value] defines [name] whose value is the
+      result of evaluating [expr], which is a nodeset. *)
+
+val defvar : t -> string -> string option -> int option
+  (** [defvar t name expr] defines [name] whose value is the result
+      of evaluating [expr], replacing the old value if existing.
+      [None] as [expr] removes the variable [name]. *)
+
 val get : t -> path -> value option
   (** [get t path] returns the value at [path], or [None] if there
       is no value. *)
@@ -75,6 +116,12 @@ val insert : t -> ?before:bool -> path -> string -> unit
       of [path].  By default it is inserted after [path], unless
       [~before:true] is specified. *)
 
+val label : t -> path -> string option
+  (** [label t path] gets the label of [path].
+
+      Returns [Some value] when [path] matches only one node, and
+      that has an associated label. *)
+
 val rm : t -> path -> int
   (** [rm t path] removes all nodes matching [path].
 
@@ -84,9 +131,34 @@ val matches : t -> path -> path list
   (** [matches t path] returns a list of path expressions
       of all nodes matching [path]. *)
 
+val mv : t -> path -> path -> unit
+  (** [mv t src dest] moves a node. *)
+
 val count_matches : t -> path -> int
   (** [count_matches t path] counts the number of nodes matching
       [path] but does not return them (see {!matches}). *)
 
 val save : t -> unit
   (** [save t] saves all pending changes to disk. *)
+
+val load : t -> unit
+  (** [load t] loads files into the tree. *)
+
+val set : t -> path -> value option -> unit
+  (** [set t path] sets [value] as new value at [path]. *)
+
+val setm : t -> path -> string option -> value option -> int
+  (** [setm t base sub value] sets [value] as new value for all the
+      nodes under [base] that match [sub] (or all, if [sub] is
+      [None]).
+
+      Returns the number of nodes modified. *)
+
+val transform : t -> string -> string -> transform_mode -> unit
+  (** [transform t lens file mode] adds or removes (depending on
+      [mode]) the transformation of the specified [lens] for [file]. *)
+
+val source : t -> path -> path option
+  (** [source t path] returns the path to the node representing the
+      file to which [path] belongs, or [None] if [path] does not
+      represent any file. *)