You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* add README badges to link the documentations
* use `julia-repl` syntax highlighting
* tables should be left-aligned!
* add `@ref`s to the documentation
* we don't need `@contents` blocks except for top page
* sort sections
* guides -> Guides
Copy file name to clipboardExpand all lines: docs/src/migrate.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Migration guides
1
+
# Migration Guides
2
2
3
3
This guide provides an overview of how to migrate your code from either the pre-1.0 JSON.jl package to the 1.0 release or from JSON3.jl. The 1.0 release introduces several improvements and changes, particularly in how JSON is read and written, leveraging StructUtils.jl for customization and extensibility. Below, we outline the key differences and provide step-by-step instructions for updating your code.
4
4
@@ -7,7 +7,7 @@ This guide provides an overview of how to migrate your code from either the pre-
7
7
## Migration guide from pre-1.0 -> 1.0
8
8
9
9
### Writing JSON
10
-
-`JSON.json`
10
+
-[`JSON.json`](@ref)
11
11
- What stayed the same:
12
12
- Produces a compact String by default
13
13
- Can automatically serialize basic structs in a sensible way
@@ -33,7 +33,7 @@ This guide provides an overview of how to migrate your code from either the pre-
33
33
- Utilizing multiple dispatch to combine `JSON.print` and `JSON.json` and provide convenience for writing to files
34
34
- Most opened issues over the last few years were about providing more controls around writing JSON without having to completely implement a custom serializer
35
35
- More consistency with `JSON.parse` keyword args with `allownan` and `jsonlines`
36
-
-`JSON.print`
36
+
-[`JSON.print`](@ref)
37
37
- What stayed the same:
38
38
- Technically still defined for backwards compatibility, but just calls `JSON.json` under the hood
39
39
- Why the changes:
@@ -55,12 +55,12 @@ This guide provides an overview of how to migrate your code from either the pre-
55
55
- There was often confusion about whether a custom Serialization or StructuralContext was needed and what intefaces were then required to implement
56
56
- The need to customize separators, delimiters, and indentation, while powerful, can be accomplished much simpler via keyword arguments or is not necessary at all (i.e. JSON.jl shouldn't be too concerned with how to produce anything that isn't JSON)
57
57
- Instead of overloading show_string/show_element/show_key/show_pair/show_json, `lower` can be used to accomplish any requirements of "overloading" how values are serialized; the addition of "styles" also allows customizing for non-owned types instead of needing a custom context + `show_json` method
58
-
-`JSONText`
58
+
-[`JSONText`](@ref)
59
59
- What changed:
60
60
- Nothing; `JSONText` can still be used to have a JSON-formatted string be written as-is when serializing
61
61
62
62
### Reading JSON
63
-
-`JSON.parse` / `JSON.parsefile`
63
+
-[`JSON.parse`](@ref) / [`JSON.parsefile`](@ref)
64
64
- What stayed the same:
65
65
- These functions take the same JSON input arguments (String, IO, or filename for `parsefile`)
66
66
- The `dicttype`, `allownan`, and `null` keyword arguments all remain and implement the same functionality
@@ -75,7 +75,7 @@ This guide provides an overview of how to migrate your code from either the pre-
75
75
- The `inttype` keyword argument is rare among other JSON libraries and doesn't serve a strong purpose; memory gains from possibly using smaller ints is minimal and leads to more error-prone code via overflows by trying to force integers into non-standard small types
76
76
- For the `allownan` default value change, there are many benchmarks/JSON-accuracy checking test suites that enforce adherance to the specification; following the specification by default is recommended and common across language JSON libraries
77
77
- Mmapping is an internal detail that most users shouldn't worry about anyway, and it can be done transparently without any outside affect to the user
78
-
-`JSONText`
78
+
-[`JSONText`](@ref)
79
79
-`JSONText` can now also be used while parsing, as a field type of a struct or directly to return the raw JSON (similar to how writing with `JSONText` works)
|`AbstractVector{UInt8}`| zero‑copy if already bytes |
25
22
|`IO`, `IOStream`, `Base.AbstractCmd`| stream fully read into a byte vector |
26
23
27
24
The core JSON parsing machinery is hence built around having an `AbstractVector{UInt8}` or `AbstractString` JSON input where individual bytes can be parsed to identify JSON structure, validate syntax, and ultimately produce Julia-level values.
28
25
29
-
Each entrypoint function first calls `JSON.lazy`, which will consume the JSON input until the type of the next JSON value can be identified (`{` for objects, `[` for arrays, `"` for strings, `t` for true, `f` for false, `n` for null, and `-` or a digit for numbers). `JSON.lazy` returns a `JSON.LazyValue`, which wraps the JSON input buffer (`AbstractVector{UInt8}` or `AbstractString`), and marks the byte position the value starts at, the type of the value, and any keyword arguments that were provided that may affect parsing. Currently supported parsing-specific keyword arguments to `JSON.lazy` (and thus all other entrypoint functions) include:
26
+
Each entrypoint function first calls [`JSON.lazy`](@ref), which will consume the JSON input until the type of the next JSON value can be identified (`{` for objects, `[` for arrays, `"` for strings, `t` for true, `f` for false, `n` for null, and `-` or a digit for numbers). [`JSON.lazy`](@ref) returns a [`JSON.LazyValue`](@ref), which wraps the JSON input buffer (`AbstractVector{UInt8}` or `AbstractString`), and marks the byte position the value starts at, the type of the value, and any keyword arguments that were provided that may affect parsing. Currently supported parsing-specific keyword arguments to [`JSON.lazy`](@ref) (and thus all other entrypoint functions) include:
30
27
31
28
-`allownan::Bool = false`: whether "special" float values shoudl be allowed while parsing (`NaN`, `Inf`, `-Inf`); these values are specifically _not allowed_ in the JSON spec, but many JSON libraries allow reading/writing
32
29
-`ninf::String = "-Infinity"`: the string that will be used to parse `-Inf` if `allownan=true`
33
30
-`inf::String = "Infinity"`: the string that will be used to parse `Inf` if `allownan=true`
34
31
-`nan::String = "NaN"`: the string that will be sued to parse `NaN` if `allownan=true`
35
-
-`jsonlines::Bool = false`: whether the JSON input should be treated as an implicit array, with newlines separating individual JSON elements with no leading `'['` or trailing `']'` characters. Common in logging or streaming workflows. Defaults to `true` when used with `JSON.parsefile` and the filename extension is `.jsonl` or `ndjson`. Note this ensures that parsing will _always_ return an array at the root-level.
32
+
-`jsonlines::Bool = false`: whether the JSON input should be treated as an implicit array, with newlines separating individual JSON elements with no leading `'['` or trailing `']'` characters. Common in logging or streaming workflows. Defaults to `true` when used with [`JSON.parsefile`](@ref) and the filename extension is `.jsonl` or `ndjson`. Note this ensures that parsing will _always_ return an array at the root-level.
36
33
- Materialization-specific keyword arguments (i.e. they affect materialization, but not parsing)
37
34
-`dicttype = JSON.Object{String, Any}`: type to parse JSON objects as by default (recursively)
38
35
-`null = nothing`: value to return for JSON `null` value
39
36
40
-
So what can we do with a `JSON.LazyValue`?
37
+
So what can we do with a [`JSON.LazyValue`](@ref)?
Under the hood, this `getindex` call is really calling `JSON.parse(lazyvalue)`. `JSON.parse` can also be called as a main entrypoint function with all the same input types as `JSON.lazy`. This form of `parse` is referred to as "untyped parsing" or "untyped materialization". It allocates and _materializes_ the raw JSON values into appropriate "default" Julia-level values. In particular:
127
+
Under the hood, this `getindex` call is really calling `JSON.parse(lazyvalue)`. [`JSON.parse`](@ref) can also be called as a main entrypoint function with all the same input types as [`JSON.lazy`](@ref). This form of `parse` is referred to as "untyped parsing" or "untyped materialization". It allocates and _materializes_ the raw JSON values into appropriate "default" Julia-level values. In particular:
| object |`JSON.Object{String,Any}` (order‑preserving drop-in replacement for Dict) |
135
132
| array |`Vector{Any}`|
136
133
| string |`String`|
@@ -145,7 +142,7 @@ Because `Object` uses a linked-list implementation, key lookups are `O(n)`, perf
145
142
146
143
## `JSON.parse` - Typed materialization
147
144
148
-
While untyped materialization is convenient for quick exploration, one of the most powerful features of JSON.jl is its ability to directly parse JSON into concrete Julia types. This is done by providing a type as the second argument to `JSON.parse` and opens up a world of type-safe JSON parsing with minimal boilerplate.
145
+
While untyped materialization is convenient for quick exploration, one of the most powerful features of JSON.jl is its ability to directly parse JSON into concrete Julia types. This is done by providing a type as the second argument to [`JSON.parse`](@ref) and opens up a world of type-safe JSON parsing with minimal boilerplate.
Copy file name to clipboardExpand all lines: docs/src/writing.md
+7-10Lines changed: 7 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,12 +5,9 @@ This guide to writing JSON in the JSON.jl package aims to:
5
5
- Explain the various options and configurations available for writing JSON data.
6
6
- Offer practical examples to illustrate the usage of different functions and options.
7
7
8
-
```@contents
9
-
```
10
-
11
8
## Core JSON Serialization - `JSON.json`
12
9
13
-
The main entrypoint for serializing Julia values to JSON in JSON.jl is the `JSON.json` function. This function offers flexible output options:
10
+
The main entrypoint for serializing Julia values to JSON in JSON.jl is the [`JSON.json`](@ref) function. This function offers flexible output options:
14
11
15
12
```julia
16
13
# Serialize to a String
@@ -23,10 +20,10 @@ JSON.json(io::IO, x) -> IO
23
20
JSON.json(file_name::String, x) -> String
24
21
```
25
22
26
-
The `JSON.json` function accepts a wide range of Julia types and transforms them into their JSON representation by knowing how to serialize a core set of types:
23
+
The [`JSON.json`](@ref) function accepts a wide range of Julia types and transforms them into their JSON representation by knowing how to serialize a core set of types:
0 commit comments