Skip to content

Commit 9978706

Browse files
98teg98teg
committed
Add array to doc
1 parent 56ae109 commit 9978706

File tree

2 files changed

+269
-1
lines changed

2 files changed

+269
-1
lines changed

‎doc/files/JSON-PROPERTY-ARRAY.md‎

Lines changed: 246 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,238 @@
11
# JSON Property Array
2+
3+
**extends [JSONProperty](./JSON-PROPERTY.md)**
4+
5+
**returns: [Array](https://docs.godotengine.org/en/stable/classes/class_array.html?highlight=Array)**
6+
7+
Only allows arrays.
8+
9+
## Usage
10+
11+
Once you have instantiated the class, you can set restrictions on the size of the array via the 'set_min_size' and 'set_max_size' methods. The values that these functions receive as parameters are inclusive. To remove any restriction, you can use the 'remove_min_size' and 'remove_max_size' methods.
12+
13+
You can also determine what kind of elements can be part of this array via the 'set_element_property' method, which receives a JSONProperty object as a parameter. Otherwise, the array would accept any type of data. You can return to the default behavior using the 'remove_element_property'.
14+
15+
Finally, you can determine if you want each element of the array to be unique via the 'set_uniqueness' method and passing 'true' as its first parameter. When the array contains dictionaries, it would only check if the 'unique_key', the second parameter of this method, values of the dictionaries are equal. By default, the 'unique_key' string is empty. In this case, it would compare all the fields of the dictionaries.
16+
17+
## Example
18+
19+
In this example, the configuration structure has one required property. The property 'furniture' must be a list of 2 to 3 pieces of furniture. Each piece of furniture is an object with an 'id' that needs to be unique, and a 'name'.
20+
21+
```GDScript
22+
# Create a JSON configuration file
23+
var json_config_file = JSONConfigFile.new()
24+
25+
# Create a array property, which size must be between 2 to 3
26+
var array_property = JSONPropertyArray.new()
27+
array_property.set_min_size(2)
28+
array_property.set_max_size(3)
29+
30+
var object_property = JSONPropertyObject.new()
31+
# Add a 'id' property, which is a integer
32+
object_property.add_property("id", JSONPropertyInteger.new())
33+
# Add an 'name' property, which is an string
34+
object_property.add_property("name", JSONPropertyString.new())
35+
36+
# Add the element property to the array
37+
array_property.set_element_property(object_property)
38+
# Set the array uniqueness to 'true', and set the 'unique_key' to 'id'
39+
array_property.set_uniqueness(true, "id")
40+
41+
# Add the 'furniture' property
42+
json_config_file.add_property("furniture", array_property)
43+
44+
# Validate input
45+
json_config_file.validate(json_file_path)
46+
```
47+
48+
49+
### Valid JSON
50+
51+
This JSON has the required field, which is a list of 2 to 3 pieces of furniture.:
52+
53+
```JSON
54+
{
55+
"furniture" : [
56+
{
57+
"id": 0,
58+
"name": "table"
59+
},
60+
{
61+
"id": 1,
62+
"name": "chair"
63+
},
64+
{
65+
"id": 2,
66+
"name": "bed"
67+
}
68+
]
69+
}
70+
```
71+
72+
### Incorrect JSON: Wrong type
73+
74+
This JSON contains one error. The 'furniture' property is not the correct type.
75+
76+
```JSON
77+
{
78+
"furniture": 42
79+
}
80+
```
81+
82+
Returned error:
83+
84+
```GDScript
85+
[
86+
{
87+
"error": JSONProperty.Errors.WRONG_TYPE,
88+
"expected": JSONProperty.Types.ARRAY,
89+
"context": "furniture",
90+
"as_text": "Wrong type: expected 'array', at 'furniture'."
91+
}
92+
]
93+
```
94+
95+
### Incorrect JSON: Can not be smaller than the minimum size
96+
97+
This JSON contains one error. The 'furniture' property size is less than the minimum size.
98+
99+
```JSON
100+
{
101+
"furniture": [
102+
{
103+
"id": 0,
104+
"name": "table"
105+
}
106+
]
107+
}
108+
```
109+
110+
Returned error:
111+
112+
```GDScript
113+
[
114+
{
115+
"error": JSONProperty.Errors.ARRAY_SMALLER_THAN_MIN,
116+
"size": 1,
117+
"min": 2,
118+
"context": "furniture",
119+
"as_text": "The array size (1) is smaller than the minimum allowed (2), at 'furniture'."
120+
}
121+
]
122+
```
123+
124+
### Incorrect JSON: Can not be bigger than the maximum size
125+
126+
This JSON contains one error. The 'furniture' property size is more than the maximum size.
127+
128+
```JSON
129+
{
130+
"furniture": [
131+
{
132+
"id": 0,
133+
"name": "table"
134+
},
135+
{
136+
"id": 1,
137+
"name": "chair"
138+
},
139+
{
140+
"id": 2,
141+
"name": "bed"
142+
},
143+
{
144+
"id": 3,
145+
"name": "wardrobe"
146+
}
147+
]
148+
}
149+
```
150+
151+
Returned error:
152+
153+
```GDScript
154+
[
155+
{
156+
"error": JSONProperty.Errors.ARRAY_BIGGER_THAN_MAX,
157+
"size": 4,
158+
"min": 3,
159+
"context": "furniture",
160+
"as_text": "The array size (4) is bigger than the maximum allowed (3), at 'furniture'."
161+
}
162+
]
163+
```
164+
165+
### Incorrect JSON: Wrong type in one of the elements
166+
167+
This JSON contains one error. One of the array elements is not the correct type.
168+
169+
```JSON
170+
{
171+
"furniture": [
172+
{
173+
"id": 0,
174+
"name": "table"
175+
},
176+
{
177+
"id": 1,
178+
"name": "chair"
179+
},
180+
"bed"
181+
]
182+
}
183+
```
184+
185+
Returned error:
186+
187+
```GDScript
188+
[
189+
{
190+
"error": JSONProperty.Errors.WRONG_TYPE,
191+
"expected": JSONProperty.Types.OBJECT,
192+
"context": "furniture/[2]",
193+
"as_text": "Wrong type: expected 'object', at 'furniture/[2]'."
194+
}
195+
]
196+
```
197+
198+
### Incorrect JSON: Two elements have the same id
199+
200+
This JSON contains one error. Two of the objects have the same id.
201+
202+
```JSON
203+
{
204+
"furniture" : [
205+
{
206+
"id": 0,
207+
"name": "table"
208+
},
209+
{
210+
"id": 1,
211+
"name": "chair"
212+
},
213+
{
214+
"id": 1,
215+
"name": "bed"
216+
}
217+
]
218+
}
219+
```
220+
221+
Returned error:
222+
223+
```GDScript
224+
[
225+
{
226+
"error": JSONProperty.Errors.ARRAY_TWO_ELEMENTS_ARE_EQUAL,
227+
"element_1": 1,
228+
"element_2": 2,
229+
"key": "id",
230+
"context": "furniture",
231+
"as_text": "The array contains two objects with the same 'id': [1] and [2], at 'furniture'.",
232+
}
233+
]
234+
```
235+
2236
## Functions
3237

4238
The public methods of this class are:
@@ -13,4 +247,15 @@ The public methods of this class are:
13247
| **remove_max_size** | None. | Removes any maximum size boundary. | Nothing. |
14248
| **set_element_property** | **element_property -> JSONProperty:** <br> Object with the conditions that every element of the array must satisfy. | Sets the conditions that every element of the array must satisfy. | Nothing. |
15249
| **remove_element_property** | None. | Allows the elements of the array to be anything. | Nothing. |
16-
| **set_uniqueness** | **uniqueness -> bool:** <br> Determines if every object of the array must be different from each other. <br> **unique_key -> String (""):** <br> If the array has dictionaries as its elements, 'unique_key' determines which property to use when comparing if two of then are equal. <br><br> **WARNING:** An empty 'unique_key' means that every property of the dictionaries must be the same for them to be equal. | Determines if the elements of the array have to be unique. | Nothing.
250+
| **set_uniqueness** | **uniqueness -> bool:** <br> Determines if every object of the array must be different from each other. <br> **unique_key -> String (""):** <br> If the array has dictionaries as its elements, 'unique_key' determines which property to use when comparing if two of then are equal. <br><br> **WARNING:** An empty 'unique_key' means that every property of the dictionaries must be the same for them to be equal. | Determines if the elements of the array have to be unique. | Nothing.
251+
252+
## Errors
253+
254+
This class could directly raise any of the following errors:
255+
256+
| Enum value | Description | Params | As text |
257+
|-|-|-|-|
258+
| WRONG_TYPE | The type of the input does not match the expected one. | **expected -> int:** <br> Takes the value [ARRAY](./ENUMS.md). | Wrong type: expected 'array' |
259+
| ARRAY_SMALLER_THAN_MIN | The size of the input is smaller than the minimum. | **size -> int:** <br> The array size. <br> **min -> int:** <br> The minimum size allowed. | The array size ({size}) is smaller than the minimum allowed ({min}) |
260+
| ARRAY_BIGGER_THAN_MAX | The size of the input is bigger than the maximum. | **size -> int:** <br> The array size. <br> **max -> int:** <br> The maximum size allowed. | The array size ({size}) is bigger than the maximum allowed ({max}) |
261+
| ARRAY_TWO_ELEMENTS_ARE_EQUAL | Two elements of the array are equal. | **element_1 -> int:** <br> Index of the first element. <br> **element_2 -> int:** <br> Index of the second element. <br> **key -> String:** <br> The unique key <br><br> **WARNING:** The 'key' field only appears in the error dictionary if it has determined if two dictionaries are equal. | **Without 'key':** <br> The array contains two elements that are equal: \[{element_1}] and \[element_2] <br><br> **With 'key':** <br> The array contains two objects with the same '{key}': \[{element_1}] and \[element_2]

‎doc/files/JSON-PROPERTY-OBJECT.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,29 @@ This JSON has the required fields with its corresponding types:
5151
}
5252
```
5353

54+
### Incorrect JSON: Wrong type
55+
56+
This JSON contains one error. The 'person' property is not the correct type.
57+
58+
```JSON
59+
{
60+
"person": 42
61+
}
62+
```
63+
64+
Returned error:
65+
66+
```GDScript
67+
[
68+
{
69+
"error": JSONProperty.Errors.WRONG_TYPE,
70+
"expected": JSONProperty.Types.OBJECT,
71+
"context": "person",
72+
"as_text": "Wrong type: expected 'object', at 'person'."
73+
}
74+
]
75+
```
76+
5477
### Incorrect JSON: 'person' property contains errors
5578

5679
This JSON contains multiple errors in its 'person' property. It is missing the 'name' property, the 'age' value is not the correct type, and the structure does not specify its last property:

0 commit comments

Comments
 (0)