From: Jacob Lifshay <programmerjake@gmail.com>
Date: Mon, 28 Aug 2017 05:37:33 +0000 (-0700)
Subject: add more documentation to json.md
X-Git-Tag: gsoc-2017~19
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=e33ca69fa14d68db1b8a2ee817bf24fb32c61af5;p=kazan.git

add more documentation to json.md
---

diff --git a/docs/json.md b/docs/json.md
index a8e3165..640b8c2 100644
--- a/docs/json.md
+++ b/docs/json.md
@@ -67,3 +67,42 @@ Represents a difference between two JSON ASTs.
 Members:
 - `element_selectors`: the indexes and/or fields needed to get from the top-level JSON value to the point where the difference is.
 - `find_difference`: finds the first difference between two JSON ASTs. Returns `util::nullopt` if the two JSON ASTs are equal.
+
+## `json/location.h`
+
+### `json::Location`
+type representing a source-code location. Designed for speed, so it holds a pointer to the `Source` and the byte-index of the represented location.
+
+## `json/parser.h`
+
+### `json::Parse_error`
+Type representing a JSON parse error. Holds a `json::Location`, which holds a pointer to the `Source`, so the `Source` needs to be still valid when this is caught, unless you don't need the `location` field.  
+Converts the `Location` to text on construction, so, if the `Source` object is destroyed before this `Location` is, it will still work.
+
+### `json::Parse_options`
+Options for parsing JSON.  
+Members:
+- `allow_infinity_and_nan`: if the parser will parse +/-`Infinity` and `NaN`. The JSON specification doesn't allow `Infinity` or `NaN`.  
+Ex: Allow parsing of `Infinity`, `-Infinity`, and `NaN`.
+- `allow_explicit_plus_sign_in_mantissa`: if the parser will parse a leading `+` on a number. The JSON specification doesn't allow a leading `+` on a number.  
+Ex: Allow parsing `+123.45` in addition to `123.45`.
+- `allow_single_quote_strings`: if the parser will parse a string delimited by `'` instead of `"`. The JSON specification requires strings to be delimited by `"`.  
+Ex: Allow parsing `'abc'` in addition to `"abc"`
+- `allow_number_to_start_with_dot`: if the parser will parse a leading `.` on a number. The JSON specification doesn't allow a leading `.` on a number, instead requiring a `0` before the `.`.  
+Ex: Allow parsing `.25` in addition to `0.25`
+- `default_options`: create a `Parse_options` that holds the defaults.
+- `relaxed_options`: create a `Parse_options` that allows parsing all of the different options in `Parse_options`.
+
+### `json::parse`
+Parse the passed-in source into the JSON AST. Throws `json::Parse_error` on parse error.
+
+## `json/source.h`
+
+### `json::Source`
+type that holds the in-memory representation of a JSON source file.  
+Members:
+- `file_name`: the name of the JSON source file.
+- `contents`: the contents of the JSON source file. Points to a buffer of size `contents_size`. Implemented as a `std::shared_ptr` so it's possible to point to a memory-mapped version of the source file for additional speed.
+- `contents_size`: the size of the memory buffer pointed to by `contents`.
+- `load_file`: loads the file indicated by the passed-in file name.
+- `load_stdin`: reads `stdin` until end-of-file, returning the source-code that was read.