Skip to content

Commit 77f4e6a

Browse files
onoxonox
committed
Add an example (code) to Usage in README.md
Signed-off-by: onox <denkpadje@gmail.com>
1 parent 9be165e commit 77f4e6a

File tree

1 file changed

+77
-56
lines changed

1 file changed

+77
-56
lines changed

‎README.md‎

Lines changed: 77 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -14,72 +14,93 @@ Unicode may not be supported yet.
1414

1515
## Usage
1616

17-
To parse a JSON text, first instantiate `JSON.Parsers`:
18-
1917
```ada
20-
package Types is new JSON.Types (Long_Integer, Long_Float);
21-
package Parsers is new JSON.Parsers (Types);
18+
with Ada.Command_Line;
19+
with Ada.Text_IO;
20+
21+
with JSON.Parsers;
22+
with JSON.Streams;
23+
with JSON.Types;
24+
25+
procedure Example is
26+
package Types is new JSON.Types (Long_Integer, Long_Float);
27+
package Parsers is new JSON.Parsers (Types);
28+
29+
Text : constant JSON.Streams.Stream_Element_Array_Controlled :=
30+
JSON.Streams.Get_Stream_Element_Array (Ada.Command_Line.Argument (1));
31+
32+
Parser : Parsers.Parser := Parsers.Create (JSON.Streams.Create_Stream (Text.Pointer));
33+
Value : constant Types.JSON_Value := Parser.Parse;
34+
35+
use Types;
36+
begin
37+
-- The data type of a Value can be retrieved with `Value.Kind`. The value
38+
-- can be one of:
39+
--
40+
-- Null_Kind, Boolean_Kind, Integer_Kind, Float_Kind, String_Kind,
41+
-- Array_Kind, or Object_Kind.
42+
case Value.Kind is
43+
when Array_Kind | Object_Kind =>
44+
-- Query the length of a JSON array or object with the function `Length`
45+
Ada.Text_IO.Put_Line (Value.Length'Image);
46+
47+
-- A JSON object provides the function `Contains`
48+
if Value.Kind = Object_Kind and then Value.Contains ("foo") then
49+
-- To get an element of a JSON array or object write `Value.Get (Index_Or_Key)`
50+
-- or use Ada 2012's indexing syntax `Value (Index_Or_Key)`.
51+
--
52+
-- If Value is a JSON object, you can call `Get_Array_Or_Empty`,
53+
-- `Get_Object_Or_Empty`, or `Get` (with an additional parameter containing
54+
-- the default value).
55+
Ada.Text_IO.Put_Line (Value ("foo").Kind'Image);
56+
end if;
57+
58+
-- Iterate over a JSON array or object by using the
59+
-- Ada 2012 iterator syntax `for Element_Or_Key of Value`. The type is a
60+
-- JSON_Value and represents an element of the array or the key of an object.
61+
for Element of Value loop
62+
-- To get the image of JSON_Value (to serialize it), use function `Image`:
63+
Ada.Text_IO.Put_Line (Element.Image);
64+
end loop;
65+
when Float_Kind =>
66+
declare
67+
-- Get the value (String, generic Integer_Type or Float_Type, or Boolean)
68+
-- of a Value by calling `Value.Value`. An Invalid_Type_Error
69+
-- exception will be raised if Value has a different type than the type
70+
-- of the variable in which you try to store the result.
71+
Data : constant Long_Float := Value.Value;
72+
begin
73+
Ada.Text_IO.Put_Line (Data'Image);
74+
end;
75+
when others =>
76+
null;
77+
end case;
78+
end Example;
2279
```
2380

24-
You can replace the actual generic parameters of `JSON.Types` with your
25-
own types if you want. Specify `Maximum_Number_Length` (default is 30)
26-
when instantiating `JSON.Types` to set the maximum length in characters
27-
of numbers. The default maximum nesting depth can be specified with
28-
`Default_Maximum_Depth` (default is 10).
29-
30-
If you want to check for duplicate keys when parsing, set
31-
`Check_Duplicate_Keys` to `True` when instantiating `JSON.Parsers`. This
32-
can make parsing large JSON texts slower. If set to `False` (the default),
33-
then the `Get` operation will return the value of the first key that matches.
81+
Optional generic parameters of `JSON.Types`:
3482

35-
Then create a stream and parse it:
36-
37-
```ada
38-
Stream : JSON.Streams.Stream'Class := JSON.Streams.Create_Stream (Text'Access);
39-
Allocator : Types.Memory_Allocator (Maximum_Depth => 10);
40-
Value : constant JSON_Value := Parsers.Parse (Stream, Allocator);
41-
```
42-
43-
The actual parameter of `Create_Stream` can be an access to a `String`
44-
or an access to a `Ada.Streams.Stream_Element_Array`. Parameter `Maximum_Depth`
45-
is optional and has by default the value of the generic parameter
46-
`Default_Maximum_Depth` from the package `JSON.Types`.
83+
- `Maximum_Number_Length` (default is 30): Maximum length in characters of
84+
numbers
4785

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

52-
#### Using a `JSON_Value` object
88+
- `Default_Maximum_Depth` (default is 10)
5389

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

57-
`Null_Kind`, `Boolean_Kind`, `Integer_Kind`, `Float_Kind`, `String_Kind`,
58-
`Array_Kind`, or `Object_Kind`.
59-
60-
To check if `Value` is of a certain type (for example an array), you can write
61-
`if Value.Kind = Array_Kind then`.
62-
63-
To get the **image** of `Value` (to serialize it), write `Value.Image`.
64-
65-
**Get** the value (`String`, generic `Integer_Type` or `Float_Type`, or
66-
`Boolean`) of a `Value` by calling `Value.Value`. An `Invalid_Type_Error`
67-
exception will be raised if `Value` has a different type than the type
68-
of the variable in which you try to store the result.
69-
70-
To get an element of a JSON array or object write `Value.Get (Index_Or_Key)`
71-
or use Ada 2012's indexing syntax `Value (Index_Or_Key)`.
72-
73-
If `Value` is a JSON object, you can call `Get_Array_Or_Empty`,
74-
`Get_Object_Or_Empty`, or `Get` (with an additional parameter containing
75-
the default value).
94+
The actual parameter of `Create_Stream` can be an access to a `String`
95+
or an access to a `Ada.Streams.Stream_Element_Array`.
7696

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

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

84105
## Dependencies
85106

0 commit comments

Comments
 (0)