Review JSON tutorials

Author: adpi2

_includes/_markdown/install-upickle.md

@@ -1,33 +1,33 @@
-UPickle is the library for working with JSONs in Scala Toolkit.
+uPickle is the JSON serialization library of the Scala Toolkit, it includes uJson, a Scala representation of the JSON format.
 
 {% altDetails install-info-box 'Installing upickle' %}
 
 ## Installing upickle
 
-  {% tabs upickle-install-methods %}
-    {% tab 'Scala CLI' %}
-In Scala CLI, we can install the entire toolkit in a single line:
+{% tabs upickle-install-methods %}
+{% tab 'Scala CLI' %}
+Using Scala CLI, you can install the entire toolkit in a single line:
 ```scala
 //> using toolkit
 ```
 
-Alternatively, we can install a specific version of upickle:
+Alternatively, you can install a specific version of upickle:
 ```scala
 //> using lib "com.lihaoyi::upickle:1.6.0"
 ```
-    {% endtab %}
-    {% tab 'sbt' %}
-In our build.sbt file, we add the dependency to the upickle library:
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add the dependency to the upickle library:
 ```scala
 lazy val example = project.in(file("example"))
   .settings(
     scalaVersion := "3.2.1",
     libraryDependencies += "com.lihaoyi" %% "upickle" % "1.6.0"
   )
 ```
-    {% endtab %}
-    {% tab 'Mill' %}
-In your build.sc file, we add the artifact to `ivyDeps`:
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add the dependency to the upickle library:
 ```scala
 object example extends ScalaModule {
   def scalaVersion = "3.2.1"
@@ -37,6 +37,6 @@ object example extends ScalaModule {
     )
 }
 ```
-    {% endtab %}
-  {% endtabs %}
+{% endtab %}
+{% endtabs %}
 {% endaltDetails %}

_overviews/toolkit/upickle-modify-jsons.md

@@ -9,59 +9,59 @@ next-page:
 
 {% include markdown.html path="_markdown/install-upickle.md" %}
 
-## Modifying jsons
-If you want to set, modify or remove fields of a json, you can do it with Scala Toolkit. 
-First, you have to load the json. You can either do it from a json loaded to a `String`,
-or operate on json generated from Scala values.
-
-## Loading a json text and modyfing it
-To read the `json` from text, you can use the `ujson.read` function. 
-This function returns an object representing the json that you can operate on. 
-Adding new fields and updating their values is done as a simple assignment:
+The `ujson.read` method creates a mutable representation of JSON that you can update, by adding, modifying or removing any field and element of its JSON objects and arrays.
+First you need to read the JSON string, then you can update it, and finally you can write it back to a String.
+
 ```scala
+// Read the JSON string
+val json = ujson.read("""{"name":"John","pets":["Toolkitty","Scaniel"]}""")
+
+// Update it
 json("name") = "Peter"
+json("surname") = "Scalinsky"
+json("pets").arr.remove(1)
+
+// Write it back to a String
+val result: String = ujson.write(json)
+println(result)
+// Prints {"name":"Peter","pets":["Toolkitty"],"surname":"Scalinisky"}
 ```
-The code above would set the `name` field of the object in `json` to `Peter`.
-If the field is present, then it will be updated. If not, a new one is created.
-Below, you can see an example of all these operations put together. 
-The `ujson.write` function allowed us to convert back the json object represention to a `String`.
+
+
+## Modifying and adding fields
+
+You can access the field `"name"` with `json("name")` and then assign it a new value with the `=` statement.
+If the field does not yet exist, it is added to the JSON object.
+
 ```scala
 val json = ujson.read("""{"name":"John","pets":["Toolkitty","Scaniel"]}""")
 json("name") = "Peter"
 json("surname") = "Scalinsky"
-val jsonString: String = ujson.write(json)
-println(jsonString)
-//prints "{"name":"Peter","pets":["Toolkitty","Scaniel"],"surname":"Scalinisky"}"
 ```
 
+In the above code example, we change the value of the field `"name"`, from `"John"` to `"Peter"`, and we add a new field `"surname"` with value `"Scalinsky"`.
+
 ## Removing fields
-To remove fields from json you need to declare whether you are removing them from an `Object` or an `Array`.
- - To remove a field from an object, you can use the `.obj.remove("name")` function on json object
- - To remove a field from an array, you can use the `.obj.remove(index)` function on json object
- Following the previous example, below you can see how to remove some fields from it.
+
+To remove a field from a JSON object:
+- declare that the JSON value is an object by calling the `obj` method
+- call the `remove` method with the name of the field to remove.
+
 ```scala
 val json = ujson.read("""{"name":"John","pets":["Toolkitty","Scaniel"]}""")
-json.obj.remove("name") // remove "name" field
-json("pets").arr.remove(1) // remove pet with index 1 ("Scaniel")
-val jsonString: String = ujson.write(json)
-println(jsonString) // prints {"pets":["Toolkitty"]}
+json.obj.remove("name") // Remove "name" field from object
+println(ujson.write(json))
 ```
-Above, we first removed the field `name` from the top-level object in the json.
-Then, we selected the array `pets` and removed the value with index `1` from it.
 
-## Operating on jsons generated from Scala values
-If you want to operate on jsons generate from Scala values (like in the [How to write JSONs]({% link _overviews/toolkit/upickle-write-json.md %}) tutorial), then it is possible as well.
-Usually, `upickle.write` operation outputs a `String`. But, if you replace it with `upickle.writeJs`, then it returns a json represention from `ujson`.
-Then you can operate on it in the same way as you did in the previous code snippets in this tutorial. For example:
-```scala
-import upickle.default._
+## Removing elements from arrays
 
-case class PetOwner(name: String, pets: List[String])
-given ReadWriter[PetOwner] = macroRW
-val petOwner = PetOwner("Peter", List("Toolkitty", "Scaniel"))
-val json = writeJs[PetOwner](petOwner)
-json("surname") = "Scalinsky"
-val jsonString = ujson.write(json)
-println(jsonString)
-//Prints {"name":"Peter","pets":["Toolkitty","Scaniel"],"surname":"Scalinsky"}
-```
+To remove an element from an JSON array:
+- declare that the JSON value is an array by calling the `arr` method
+- call the `remove` method with the index of the element to remove.
+
+```scala
+val json = ujson.read("""{"name":"John","pets":["Toolkitty","Scaniel"]}""")
+json("pets").arr.remove(1) // Remove pet at index 1 ("Scaniel")
+val jsonString: String = ujson.write(json)
+println(jsonString) // Prints {"name":"John","pets":["Toolkitty"]}
+```

_overviews/toolkit/upickle-read-json-typed.md

@@ -1,5 +1,5 @@
 ---
-title: How to read a JSON to typed structure?
+title: How to parse a JSON value to a data type?
 type: section
 description: How to read a JSON to typed structure with Scala Toolkit
 num: 21
@@ -9,18 +9,18 @@ next-page: upickle-write-json
 
 {% include markdown.html path="_markdown/install-upickle.md" %}
 
-In Scala Toolkit, it is possible to read a JSON and values inside of it in two ways:
- - First one offers everything you need to quickly extract data from a JSON, without requiring any specific structure. 
- This approach is described in the [How to read a JSON]({% link _overviews/toolkit/upickle-read-json.md %}) tutorial. Visit it if you want a simple and fast way to read JSONs.
- - The second approach one allows you to work with the json in a fully typed code, and even to provide your custom data structures. 
- This approach is described in this tutorial. It is more well-suited when you plan on reusing, storing and operating on the structures loaded from jsons.
-
-## Reading JSONs to a typed structure
-To perform typed operations on JSONs, you can utilize a `upickle` Toolkit library. 
-This approach has an advantage of additional safety and convenience of working with the structured data.
-As an example - if you know that your JSON contains a set of fields, where each field's value is an array of numbers, 
-you can use the `read[Map[String, List[Int]]](json)` function that will return a map of this exact type.
-You can see an example of that below
+In the Scala Toolkit, there are two ways of reading JSON: the dynamic way and the fully-typed way.
+- In the first approach, we can quickly extract data from JSON, without requiring any specific schema.
+To discover this approach read the [How to read JSON dynamically]({% link _overviews/toolkit/upickle-read-json.md %}). It is simple and fast.
+- In the second approach, you define your own data type, and transform JSON objects into instances of that data type, making sure that all the required fields are defined with valid types.
+This approach is described below.
+It is well-suited when you need to validate the JSON values, to store them or to operate on them in a safe way.
+
+## Parsing a JSON object to a Map
+To type a JSON object into a Scala `Map`, you can use the `upickle` library. 
+This approach is safe and convenient for working with structured data.
+It allows you to quiclky validate the structure of the JSON string.
+
 ```scala
 import upickle.default._
 val jsonString = """{"primes": [2, 3, 5], "evens": [2, 4, 6]} """
@@ -29,39 +29,64 @@ val primes = map("primes")
 println(primes.head) // Prints 2
 ```
 
-### Reading JSONs of your own data types
-In Scala, you can use a `case class` to define your own data type. For example, if you wanted to represent a Person with names of its pets, you could do it as follows:
+In this example, we expect the JSON string to contain an object, where each fields's value is an array of numbers.
+We call the `upickle.default.read` with the type parameter `Map[String, List[Int]]` to transform the JSON object into a map of this exact type.
+
+If the JSON value does not match the expected type, upickle throws an exception.
+
+### Parsing a JSON object to a custom data type
+
+In Scala, you can use a `case class` to define your own data type.
+For example, to represent the pets and their owner, you can do it as follows:
 ```scala
 case class PetOwner(name: String, pets: List[String])
 ```
-After defining this `case class`, you can read a JSON containing its fields. But first, you need to provide an instance of `ReadWriter` that will tell the library
-how to handle this type. Luckily, `upickle` is able to fully automate that and all have to do is:
+
+To be able to read a `PetOwner` from a JSON we need to provde a given instance of `ReadWriter[PetOwner]`.
+Luckily, `upickle` is able to fully automate that and all you need to write is:
+
 ```scala
 given ReadWriter[PetOwner] = macroRW
 ```
-`given` keyword may appear strange at first, but it just says that this value may be used later transparently in your code by some functions that needs a `ReadWriter[PetOwner]`. 
-You don't need to think about it for too long, that's the only thing you need to do - as long as this value is available, you will be able to read a JSON that conforms to the type of a `PetOwner`.
-The second part of this definition, `macroRW`, automates everything that needs to be done to provide this mechanism capable of reading these JSONs.
-After this declaration, you can put everything together and read a JSON as you inteded to:
+
+The `given` keyword may appear strange at first but is very powerful.
+Having a `given ReadWriter[PetOwner]` in the current scope allows you to ask the `upickle.default.read` method to return a value of `PetOwner`, like this `read[PetOwner](jsonString)`.
+As long as the given value is available, you will be able to read JSON that conforms to the type of a `PetOwner`.
+The second part of this definition, `macroRW`, automates the instanciation of `ReadWriter` so that we don't have to do it by hand.
+
+After this declaration, you can put everything together and read a `PetOwner` from JSON:
 ```scala
 import upickle.default._
 
 case class PetOwner(name: String, pets: List[String])
+
 given ReadWriter[PetOwner] = macroRW
+
 val jsonString = """{"name": "Peter", "pets": ["Toolkitty", "Scaniel"]}"""
 val petOwner: PetOwner = read[PetOwner](jsonString)
-val ownerName = petOwner.name
-val ownerFirstAnimal = petOwner.pets.head
-println(s"$ownerName has a pet called $ownerFirstAnimal") 
-// Prints "Peter has a pet called Toolkitty
-``` 
+val firstPet = petOwner.pets.head
+println(s"${petOwner.name} has a pet called $firstPet")
+// Prints "Peter has a pet called Toolkitty"
+```
+
+### Making the given ReadWriter globally available
 
-### Providing ReadWriter in the companion object
+The given `ReadWriter[PetOwner]` is only available in the scope in which it is defined.
+To make it available globally you can define it in the companion object of `PetOwner`.
 
-If you want to have the `ReadWriter[PetOwner]` always available with the `PetOwner`, no matter where in your project you are, you can use a Scala's feature called `companion objects`.
-Next to the `PetOwner` case class, you need to put an `object` that is called the same - `object PetOwner`. In that object, you can put the `given` ReadWriter.
-After you do that, the `ReadWriter` will be always available alongside the `PetOwner` case class.
 ```scala
+case class PetOwner(name: String, pets: List[String])
+
 object PetOwner:
-   given ReadWriter[PetOwner] = macroRW
+  given ReadWriter[PetOwner] = macroRW
+```
+
+The given `ReadWriter[PetOwner]` is now available globally.
+That means you can read a `PetOwner` from a JSON object from any file, class, or method.
+
+```scala
+import upickle.default.read
+
+def readPetOwnerFromJson(json: String): PetOwner =
+  read[PetOwner](json)
 ```

_overviews/toolkit/upickle-read-json.md

@@ -1,41 +1,49 @@
 ---
-title: How to read a JSON?
+title: How to read JSON dynamically?
 type: section
-description: How to read a JSON with Scala Toolkit.
+description: How to read JSON with Scala Toolkit.
 num: 20
 previous-page: upickle-intro
 next-page: upickle-read-json-typed
 ---
 
 {% include markdown.html path="_markdown/install-upickle.md" %}
 
-In Scala Toolkit, it is possible to read a JSON and values inside of it in two ways:
- - First one offers everything you need to quickly extract data from a JSON, without requiring any specific structure. This approach is described in this article. It is a simple and fast way to read JSONs.
- - While the second approach allows you to work with the json in a fully typed code, and even to provide your custom data structures. To discover this approach read the [How to read a JSON to typed structure]({% link _overviews/toolkit/upickle-read-json-typed.md %}) tutorial. It is more well-suited when you plan on reusing, storing and operating on the structures loaded from jsons.
+In the Scala Toolkit, there are two ways of reading JSON: the dynamic way and the fully-typed way.
+- In the first approach, we can quickly extract data from JSON, without requiring any specific schema.
+This approach is described below.
+It is simple and fast.
+ - In the second approach, you define your own data type, to parse JSON objects into instances of that data type, making sure that all the required fields are defined with the expected types.
+ To discover this approach read the [How to parse a JSON value to a data type]({% link _overviews/toolkit/upickle-read-json-typed.md %}).
+ It is well-suited when you need to validate the JSON values, to store them or to operate on them in a safe way.
 
-## Reading JSONs dynamically
-If you want to just parse a JSON and access some of its field, you may just use a `ujson` library that is included with Toolkit. 
-Function `ujson.read` allows you to read a JSON and access it afterwards. 
-You can access the fields in the returned JSON object by just providing their names exactly as you would to a standard function.
-Afterwards you have to declare what you expect to be inside the field and extract it, for example `str` extracts field's value as a `String`.
-For example, code below prints out `Peter`.
+## Reading JSON dynamically
+If you want to parse a JSON object and access some of its field, you can use the uJson library, which is brought by uPickle.
+
+The method `ujson.read` can parse a JSON string and make all of its fields available.
 ```scala
 val jsonString = """{"name": "Peter", "age": 13}"""
 val json = ujson.read(jsonString)
 println(json("name").str) // Prints out "Peter"
 ```
-You can operate on arrays similarly, accessing the indices as in the example below.
+
+You can access a field by passing its name to the `json` value, and then specifying which type you expect.
+If `name` is a field that should contain a string, you can access it using `json("name").str`.
+
+Similarly, you can access an element of an array by passing its indice, as in the example below:
 ```scala
 val jsonString = """{"name": "Peter", "pets": ["Toolkitty", "Scaniel"]}"""
 val json = ujson.read(jsonString)
 val ownerName = json("name").str
-val firstPet = json("pets")(0) .str
+val firstPet = json("pets")(0).str
 println(s"$ownerName has a pet called $firstPet")
 ```
-You can traverse the JSON structure as deeply as you want, to extract the fields you require.
+You can traverse the JSON structure as deeply as you want, to extract any nested field.
 
 ## Extracting values
-In the previous example we used the `.str` function on fields to extract a `String` from the field's value.
-Similiar operations are available to extract other types of values. Namely:
- - For the `Int`, you can use `.num` function
- - For the `Boolean`, you can use `.bool` function
+In the previous example we used the `str` method on fields to extract a `String` from the field's value.
+Similar operations are available to extract other types of values. Namely:
+ - `num` for numeric values, it returns an `Int`
+ - `bool` for boolean values, it returns a `Boolean`
+ - `arr` for arrays
+ - `obj` for objects