Skip to content

Commit

Permalink
Add an example (code) to Usage in README.md
Browse files Browse the repository at this point in the history 
Signed-off-by: onox <[email protected]>
  • Loading branch information
@onox
onox committed May 5, 2020
1 parent 9be165e commit 77f4e6a
Showing 1 changed file with 77 additions and 56 deletions.
133 changes: 77 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,72 +14,93 @@ Unicode may not be supported yet.

## Usage

To parse a JSON text, first instantiate `JSON.Parsers`:

```ada
package Types is new JSON.Types (Long_Integer, Long_Float);
package Parsers is new JSON.Parsers (Types);
with Ada.Command_Line;
with Ada.Text_IO;
with JSON.Parsers;
with JSON.Streams;
with JSON.Types;
procedure Example is
package Types is new JSON.Types (Long_Integer, Long_Float);
package Parsers is new JSON.Parsers (Types);
Text : constant JSON.Streams.Stream_Element_Array_Controlled :=
JSON.Streams.Get_Stream_Element_Array (Ada.Command_Line.Argument (1));
Parser : Parsers.Parser := Parsers.Create (JSON.Streams.Create_Stream (Text.Pointer));
Value : constant Types.JSON_Value := Parser.Parse;
use Types;
begin
-- The data type of a Value can be retrieved with `Value.Kind`. The value
-- can be one of:
--
-- Null_Kind, Boolean_Kind, Integer_Kind, Float_Kind, String_Kind,
-- Array_Kind, or Object_Kind.
case Value.Kind is
when Array_Kind | Object_Kind =>
-- Query the length of a JSON array or object with the function `Length`
Ada.Text_IO.Put_Line (Value.Length'Image);
-- A JSON object provides the function `Contains`
if Value.Kind = Object_Kind and then Value.Contains ("foo") then
-- To get an element of a JSON array or object write `Value.Get (Index_Or_Key)`
-- or use Ada 2012's indexing syntax `Value (Index_Or_Key)`.
--
-- If Value is a JSON object, you can call `Get_Array_Or_Empty`,
-- `Get_Object_Or_Empty`, or `Get` (with an additional parameter containing
-- the default value).
Ada.Text_IO.Put_Line (Value ("foo").Kind'Image);
end if;
-- Iterate over a JSON array or object by using the
-- Ada 2012 iterator syntax `for Element_Or_Key of Value`. The type is a
-- JSON_Value and represents an element of the array or the key of an object.
for Element of Value loop
-- To get the image of JSON_Value (to serialize it), use function `Image`:
Ada.Text_IO.Put_Line (Element.Image);
end loop;
when Float_Kind =>
declare
-- Get the value (String, generic Integer_Type or Float_Type, or Boolean)
-- of a Value by calling `Value.Value`. An Invalid_Type_Error
-- exception will be raised if Value has a different type than the type
-- of the variable in which you try to store the result.
Data : constant Long_Float := Value.Value;
begin
Ada.Text_IO.Put_Line (Data'Image);
end;
when others =>
null;
end case;
end Example;
```

You can replace the actual generic parameters of `JSON.Types` with your
own types if you want. Specify `Maximum_Number_Length` (default is 30)
when instantiating `JSON.Types` to set the maximum length in characters
of numbers. The default maximum nesting depth can be specified with
`Default_Maximum_Depth` (default is 10).

If you want to check for duplicate keys when parsing, set
`Check_Duplicate_Keys` to `True` when instantiating `JSON.Parsers`. This
can make parsing large JSON texts slower. If set to `False` (the default),
then the `Get` operation will return the value of the first key that matches.
Optional generic parameters of `JSON.Types`:

Then create a stream and parse it:

```ada
Stream : JSON.Streams.Stream'Class := JSON.Streams.Create_Stream (Text'Access);
Allocator : Types.Memory_Allocator (Maximum_Depth => 10);
Value : constant JSON_Value := Parsers.Parse (Stream, Allocator);
```

The actual parameter of `Create_Stream` can be an access to a `String`
or an access to a `Ada.Streams.Stream_Element_Array`. Parameter `Maximum_Depth`
is optional and has by default the value of the generic parameter
`Default_Maximum_Depth` from the package `JSON.Types`.
- `Maximum_Number_Length` (default is 30): Maximum length in characters of
numbers

After parsing, elements of arrays and objects are stored in the `Allocator`
object, while strings remain stored in the `Stream` object. These two
objects must not go out of scope before any `JSON_Value` goes out of scope.
Optional generic parameters of `JSON.Parsers`:

#### Using a `JSON_Value` object
- `Default_Maximum_Depth` (default is 10)

The **data type** of a `Value` can be retrieved with `Value.Kind`. The value
can be one of:
- `Check_Duplicate_Keys` (default is False): Check for duplicate keys when
parsing. Parsing large JSON texts will be slower if enabled. If disabled
then the `Get` operation will return the value of the first key that matches.

`Null_Kind`, `Boolean_Kind`, `Integer_Kind`, `Float_Kind`, `String_Kind`,
`Array_Kind`, or `Object_Kind`.

To check if `Value` is of a certain type (for example an array), you can write
`if Value.Kind = Array_Kind then`.

To get the **image** of `Value` (to serialize it), write `Value.Image`.

**Get** the value (`String`, generic `Integer_Type` or `Float_Type`, or
`Boolean`) of a `Value` by calling `Value.Value`. An `Invalid_Type_Error`
exception will be raised if `Value` has a different type than the type
of the variable in which you try to store the result.

To get an element of a JSON array or object write `Value.Get (Index_Or_Key)`
or use Ada 2012's indexing syntax `Value (Index_Or_Key)`.

If `Value` is a JSON object, you can call `Get_Array_Or_Empty`,
`Get_Object_Or_Empty`, or `Get` (with an additional parameter containing
the default value).
The actual parameter of `Create_Stream` can be an access to a `String`
or an access to a `Ada.Streams.Stream_Element_Array`.

**Query** the length of a JSON array or object with the function `Length`.
A JSON object provides the function `Contains`.
The default maximum nesting depth can be overriden with
the optional second parameter `Maximum_Depth` of function `Create`.

**Iterate** over a JSON array or object by using the
Ada 2012 iterator syntax `for Element_Or_Key of Value`. The type is a
`JSON_Value` and represents an element of the array or the key of an object.
After parsing, elements of arrays and objects are stored in the `Parser`
object, while strings remain stored in the `String` or `Stream_Element_Array`
object. These two objects must not go out of scope before any `JSON_Value`
goes out of scope.

## Dependencies

Expand Down

0 comments on commit 77f4e6a

Please sign in to comment.