unikernel/duniverse/dune_/vendor/opam-file-format/opamPrinter.mli

@@ -0,0 +1,197 @@
+(**************************************************************************)
+(*                                                                        *)
+(*    Copyright 2012-2020 OCamlPro                                        *)
+(*    Copyright 2012 INRIA                                                *)
+(*                                                                        *)
+(*  All rights reserved. This file is distributed under the terms of the  *)
+(*  GNU Lesser General Public License version 2.1, with the special       *)
+(*  exception on linking described in the file LICENSE.                   *)
+(*                                                                        *)
+(**************************************************************************)
+
+(** Functions for converting parsed opam files back to strings *)
+
+
+(** [OpamPrinter] transitional module with full position types *)
+module FullPos : sig
+
+  open OpamParserTypes.FullPos
+
+  (** {2 Printers for the [value] and [opamfile] formats} *)
+
+  val relop_kind: [< relop_kind ] -> string
+  (** Converts {!OpamParserTypes.FullPos.relop_kind} to its string representation
+      ([=], [!=], ..., [~]). *)
+
+  val logop_kind: [< logop_kind ] -> string
+  (** Converts {!OpamParserTypes.FullPos.logop_kind} to its string representation
+      ([&] and [|]). *)
+
+  val pfxop_kind: [< pfxop_kind ] -> string
+  (** Converts {!OpamParserTypes.FullPos.logop_kind} to its string representation
+      ([&] and [|]). *)
+
+  val env_update_op_kind: env_update_op_kind -> string
+  (** Converts {!OpamParserTypes.FullPos.env_update_op_kind} to its string representation
+      ([=], [+=], ..., [=:]). *)
+
+
+  val relop: relop -> string
+  (** Converts {!OpamParserTypes.FullPos.relop} to its string representation
+      ([=], [!=], ..., [~]). *)
+
+  val logop: logop -> string
+  (** Converts {!OpamParserTypes.FullPos.logop} to its string representation
+      ([&] and [|]). *)
+
+  val pfxop: pfxop -> string
+  (** Converts {!OpamParserTypes.FullPos.pfxop} to its string representation
+      ([!] and [?]). *)
+
+  val env_update_op: env_update_op -> string
+  (** Converts {!OpamParserTypes.FullPos.env_update_op} to its string representation
+      ([=], [+=], ..., [=:]). *)
+
+
+  val value : value -> string
+  (** Converts {!value} to a string {b always using LF-encoding of newlines}. *)
+
+  val value_list: value list with_pos -> string
+  (** Converts a list of {!value}s to a string {b always using LF-encoding of
+      newlines}. *)
+
+  val items: opamfile_item list -> string
+  (** Converts a list of opam field/sections to a string.
+
+      @raise Invalid_argument if ["opam-version"] is greater than "2.0"
+                              and not solely the first item. *)
+
+  val opamfile: opamfile -> string
+  (** Converts an {!opamfile} to a string.
+
+      @raise Invalid_argument if ["opam-version"] is greater than "2.0"
+                              and not solely the first item. *)
+
+  val format_opamfile: Format.formatter -> opamfile -> unit
+  (** Writes an {!opamfile} to a [Format.formatter]. The function ensures that all
+      newlines are sent using [Format]'s break instructions (and so ultimately are
+      processed with the [out_newline] function of the formatter) but it is the
+      responsibility of the caller to ensure that the formatter is configured for
+      the required output, if necessary.
+
+      @raise Invalid_argument if ["opam-version"] is greater than "2.0"
+                              and not solely the first item. *)
+
+  (** {2 Normalised output for opam syntax files} *)
+
+  (** opam normalised file format, for signatures.
+
+      - each top-level field on a single line
+      - newlines are LF-encoded (including on Windows)
+      - file ends with a newline
+      - spaces only after [fieldname:], between elements in lists, before braced
+          options, between operators and their operands
+      - fields are sorted lexicographically by field name
+          (using [String.compare])
+      - newlines in strings turned to ['\n'], backslashes and double quotes
+          escaped
+      - no comments (they don't appear in the internal file format anyway)
+      - fields containing an empty list, or a singleton list containing an empty
+          list, are not printed at all
+  *)
+  module Normalise : sig
+    val escape_string : string -> string
+    val value : value -> string
+    val item : opamfile_item -> string
+    val item_order : opamfile_item -> opamfile_item -> int
+    val items : opamfile_item list -> string
+    val opamfile : opamfile -> string
+  end
+
+  (** {2 Format-preserving reprinter} *)
+
+  module Preserved : sig
+
+    val items: string -> opamfile_item list -> opamfile_item list -> string
+    (** [items str orig_its its] converts [its] to string, while attempting to
+        preserve the layout and comments of the original [str] for unmodified
+        elements. The function assumes that [str] parses to the items
+        [orig_its].
+
+        @raise Invalid_argument if ["opam-version"] is greater than "2.0"
+                                and not solely the first item in either list. *)
+
+    val opamfile: ?format_from:file_name -> opamfile -> string
+    (** [opamfile f] converts [f] to string, respecting the layout and comments in
+        the corresponding on-disk file for unmodified items. [format_from] can be
+        specified instead of using the filename specified in [f].
+
+        @raise Invalid_argument if ["opam-version"] is greater than "2.0"
+                                and not solely the first item in the list. Note that
+                                any errors in the file raise {!OpamLexer.Error} as
+                                normal. *)
+  end
+
+  (** {2 Random utility functions} *)
+
+  val value_equals: value -> value -> bool
+  (** Compares structurally, without considering file positions *)
+
+  val opamfile_item_equals: opamfile_item -> opamfile_item -> bool
+  (** Compares structurally, without considering file positions *)
+
+end
+
+open OpamParserTypes
+
+val relop: [< relop ] -> string
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.relop instead."]
+
+val logop: [< logop ] -> string
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.logop instead."]
+
+val pfxop: [< pfxop ] -> string
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.pfxop instead."]
+
+val env_update_op: env_update_op -> string
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.env_update_op instead."]
+
+val value : value -> string
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.value instead."]
+
+val value_list: value list -> string
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.value_list instead."]
+
+val items: opamfile_item list -> string
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.items instead."]
+
+val opamfile: opamfile -> string
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.opamfile instead."]
+
+val format_opamfile: Format.formatter -> opamfile -> unit
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.format_opamfile instead."]
+
+module Normalise : sig
+  val escape_string : string -> string
+  val value : value -> string
+  val item : opamfile_item -> string
+  val item_order : opamfile_item -> opamfile_item -> int
+  val items : opamfile_item list -> string
+  val opamfile : opamfile -> string
+end
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.Normalise instead."]
+
+module Preserved : sig
+  val items: string -> opamfile_item list -> opamfile_item list -> string
+
+  val opamfile: ?format_from:file_name -> opamfile -> string
+end
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.Preserved instead."]
+
+
+val value_equals: value -> value -> bool
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.value_equals instead."]
+
+val opamfile_item_equals: opamfile_item -> opamfile_item -> bool
+[@@ocaml.deprecated "Use OpamPrinter.FullPos.opamfile_item_equals instead."]
+