Skip to content

Commit

Permalink
Document Json_error
Browse files Browse the repository at this point in the history
  • Loading branch information
sim642 committed Jul 17, 2022
1 parent 618abfd commit aff918c
Show file tree
Hide file tree
Showing 4 changed files with 26 additions and 19 deletions.
2 changes: 2 additions & 0 deletions lib/common.mli
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
val version : string

exception Json_error of string
(** Exception (usually) describing a parsing failure. *)

val json_error : string -> 'a
(** @raise Json_error *)

type lexer_state = {
buf : Buffer.t;
Expand Down
23 changes: 12 additions & 11 deletions lib/read.mli
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
val prettify : ?std:bool -> string -> string
(** Combined parser and pretty-printer.
See [to_string] for the role of the optional [std] argument. *)
See [to_string] for the role of the optional [std] argument and raised exceptions. *)

val compact : ?std:bool -> string -> string
(** Combined parser and printer.
See [to_string] for the role of the optional [std] argument. *)
See [to_string] for the role of the optional [std] argument and raised exceptions. *)

(** {2 JSON readers} *)

Expand All @@ -22,6 +22,7 @@ val from_string :
@param fname data file name to be used in error messages. It does
not have to be a real file.
@param lnum number of the first line of input. Default is 1.
@raise Json_error if parsing fails.
*)

val from_channel :
Expand All @@ -30,15 +31,15 @@ val from_channel :
?lnum:int ->
in_channel -> t
(** Read a JSON value from a channel.
See [from_string] for the meaning of the optional arguments. *)
See [from_string] for the meaning of the optional arguments and raised exceptions. *)

val from_file :
?buf:Buffer.t ->
?fname:string ->
?lnum:int ->
string -> t
(** Read a JSON value from a file.
See [from_string] for the meaning of the optional arguments. *)
See [from_string] for the meaning of the optional arguments and raised exceptions. *)


type lexer_state = Lexer_state.t = {
Expand All @@ -65,7 +66,7 @@ val from_lexbuf :
Lexing.lexbuf -> t
(** Read a JSON value from a lexbuf.
A valid initial [lexer_state] can be created with [init_lexer].
See [from_string] for the meaning of the optional arguments.
See [from_string] for the meaning of the optional arguments and raised exceptions.
@param stream indicates whether more data may follow. The default value
is false and indicates that only JSON whitespace can be found between
Expand All @@ -78,7 +79,7 @@ val seq_from_string :
string -> t Seq.t
(** Input a sequence of JSON values from a string.
Whitespace between JSON values is fine but not required.
See [from_string] for the meaning of the optional arguments. *)
See [from_string] for the meaning of the optional arguments and raised exceptions. *)

val seq_from_channel :
?buf:Buffer.t ->
Expand All @@ -94,7 +95,7 @@ val seq_from_channel :
@raise Finally When the parsing and the finalizer both raised, [Finally (exn, fin_exn)]
is raised, [exn] being the parsing exception and [fin_exn] the finalizer one.
See [from_string] for the meaning of the other optional arguments. *)
See [from_string] for the meaning of the other optional arguments and other raised exceptions. *)

val seq_from_file :
?buf:Buffer.t ->
Expand All @@ -104,7 +105,7 @@ val seq_from_file :
(** Input a sequence of JSON values from a file.
Whitespace between JSON values is fine but not required.
See [from_string] for the meaning of the optional arguments. *)
See [from_string] for the meaning of the optional arguments and raised exceptions. *)

val seq_from_lexbuf :
lexer_state ->
Expand All @@ -117,7 +118,7 @@ val seq_from_lexbuf :
is raised, [exn] being the parsing exception and [fin_exn] the finalizer one.
See [seq_from_channel] for the meaning of the optional [fin]
argument. *)
argument and other raised exceptions. *)


type json_line = [ `Json of t | `Exn of exn ]
Expand All @@ -135,7 +136,7 @@ val lineseq_from_channel :
See [seq_from_channel] for the meaning of the optional [fin]
argument.
See [from_string] for the meaning of the other optional arguments. *)
See [from_string] for the meaning of the other optional arguments and returned exceptions. *)

val lineseq_from_file :
?buf:Buffer.t ->
Expand All @@ -148,7 +149,7 @@ val lineseq_from_file :
See [seq_from_channel] for the meaning of the optional [fin]
argument.
See [from_string] for the meaning of the other optional arguments. *)
See [from_string] for the meaning of the other optional arguments and returned exceptions. *)

val read_t : lexer_state -> Lexing.lexbuf -> t
(** Read a JSON value from the given lexer_state and lexing buffer and return it.
Expand Down
17 changes: 9 additions & 8 deletions lib/write.mli
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ val to_string :
refuse to print NaN and infinities,
require the root node to be either an object or an array.
Default is [false].
@raise Json_error if [float] value is not allowed in standard JSON.
*)

val to_channel :
Expand All @@ -29,7 +30,7 @@ val to_channel :
(** Write a compact JSON value to a channel.
Note: the [out_channel] is not flushed by this function.
See [to_string] for the role of the optional arguments. *)
See [to_string] for the role of the optional arguments and raised exceptions. *)

val to_output :
?buf:Buffer.t ->
Expand All @@ -39,15 +40,15 @@ val to_output :
< output : string -> int -> int -> int; .. > -> t -> unit
(** Write a compact JSON value to an OO channel.
See [to_string] for the role of the optional arguments. *)
See [to_string] for the role of the optional arguments and raised exceptions. *)

val to_file :
?len:int ->
?std:bool ->
?suf:string ->
string -> t -> unit
(** Write a compact JSON value to a file.
See [to_string] for the role of the optional arguments.
See [to_string] for the role of the optional arguments and raised exceptions.
@param suf is a suffix appended to the output Newline by default
for POSIX compliance. *)

Expand All @@ -56,7 +57,7 @@ val to_buffer :
?std:bool ->
Buffer.t -> t -> unit
(** Write a compact JSON value to an existing buffer.
See [to_string] for the role of the optional argument. *)
See [to_string] for the role of the optional argument and raised exceptions. *)

val seq_to_string :
?buf:Buffer.t ->
Expand All @@ -67,7 +68,7 @@ val seq_to_string :
(** Write a sequence of [suf]-suffixed compact one-line JSON values to
a string.
@param suf is the suffix ouf each value written. Newline by default.
See [to_string] for the role of the optional arguments. *)
See [to_string] for the role of the optional arguments and raised exceptions. *)

val seq_to_channel :
?buf:Buffer.t ->
Expand All @@ -78,7 +79,7 @@ val seq_to_channel :
(** Write a sequence of [suf]-suffixed compact one-line JSON values to
a channel.
@param suf is the suffix of each value written. Newline by default.
See [to_channel] for the role of the optional arguments. *)
See [to_channel] for the role of the optional arguments and raised exceptions. *)

val seq_to_file :
?len:int ->
Expand All @@ -88,7 +89,7 @@ val seq_to_file :
(** Write a sequence of [suf]-suffixed compact one-line JSON values to
a file.
@param suf is the suffix of each value written. Newline by default.
See [to_string] for the role of the optional arguments. *)
See [to_string] for the role of the optional arguments and raised exceptions. *)

val seq_to_buffer :
?suf:string ->
Expand All @@ -98,7 +99,7 @@ val seq_to_buffer :
(** Write a sequence of [suf]-suffixed compact one-line JSON values to
an existing buffer.
@param suf is the suffix of each value written. Newline by default.
See [to_string] for the role of the optional arguments. *)
See [to_string] for the role of the optional arguments and raised exceptions. *)

val write_t : Buffer.t -> t -> unit
(** Write the given JSON value to the given buffer.
Expand Down
3 changes: 3 additions & 0 deletions lib/write2.mli
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,18 @@
val pretty_print : ?std:bool -> Format.formatter -> t -> unit
(** Pretty-print into a {!Format.formatter}.
See [to_string] for the role of the optional [std] argument.
@raise Json_error if [float] value is not allowed in standard JSON.
@since 1.3.1 *)

val pretty_to_string : ?std:bool -> t -> string
(** Pretty-print into a string.
See [to_string] for the role of the optional [std] argument.
See [pretty_print] for raised exceptions.
*)

val pretty_to_channel : ?std:bool -> out_channel -> t -> unit
(** Pretty-print to a channel.
See [to_string] for the role of the optional [std] argument.
See [pretty_print] for raised exceptions.
*)

0 comments on commit aff918c

Please sign in to comment.