Skip to content

Commit

Permalink
edited documentation for codec backend
Browse files Browse the repository at this point in the history
  • Loading branch information
klahnunya committed Feb 7, 2023
1 parent bfa2238 commit 97d0eda
Showing 1 changed file with 57 additions and 27 deletions.
84 changes: 57 additions & 27 deletions docs/json-codec-backend/codec-docs.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,22 @@
## Json Codec Backend
The purpose of this documentation is to give a explanation of how the Json Codec Backend works and how to use it.
The Json Codec backend is a tool that generates encoders and decoders from a Morphir IR using the Circe JSON library.
## JSON serialization support for generated Scala classes

The purpose of this documentation is to give an explanation of how the JSON Codec Backend works and how to use it.
This backend is a feature built on top of the Scala backend which allows you to read Scala types that the Scala backend generates from JSON and write to JSON.

### How to use the JSON Codec Backend

The first step to using the JSON Codec backend is to add the Circe JSON library to your project. This can be done in two ways:
1. Add the Circe JSON dependency through your build tool eg. Sbt, Mill etc.
2. Add ```morphir-jvm``` as a dependency to your project.
The first step to using the JSON Codec backend is to add the Circe JSON library and ```morphir sdk``` as dependencies to your project. The ```morphir sdk``` can be added to your project through the following ways:

1. Copy dependencies from ```morphir-jvm``` : This option allows you to copy the dependencies(morphir sdk) used by the generated code to the output path. You can achieve this by adding the ```-c``` or ```--copy-deps``` flag to the ```morphir-gen``` command.

2. Adding from `Maven Repository` : The SDK can be added from the maven repository as a dependency . It can be found at [Morphir SDK Core](https://mvnrepository.com/artifact/org.morphir/morphir-sdk-core).


#### Generating Codecs from the IR
The backend is built to generate codecs for only types so when generating an IR the ```-t``` which specifies ```--types-only``` flag should be used. Also, we want to add the ```-f``` flag to use the old CLI make function.
The ```morphir-ir.json``` is a prerequisite to generating codecs. Make sure you have that and proceed with the following steps

To generate Codecs from the IR:
1. Run ```morphir-elm make -f -t``` to generate the IR.
2. Run ```morphir-elm gen -s``` to generate the codecs
3. In the situation where you do not have ```morphir-jvm``` as a dependency in your project, you have to add the ```-c``` flag to copy dependencies from the ```morphir-jvm``` project. Complete command for this is ```morphir-elm gen -s -c```
1. Run ```morphir-elm gen --include-codecs --target Scala``` to generate the codecs
2. In the situation where you do not have ```morphir sdk``` as a dependency in your project, you have to add the ```--copy-deps``` flag to copy dependencies from the ```morphir-jvm``` project. Complete command for this is ```morphir-elm gen --iclude-codecs --copy-deps --target Scala```.

### How to use Generated Codecs
Using an example , lets describe a model structure and look at how the generated codec for this particular model will be structured
Expand All @@ -27,35 +29,63 @@ The model:
- Reference
- Model
- BooksAndRecords.elm
- morphir.json
- morphir-ir.json
- morphir.JSON
- morphir-ir.JSON


Running the command ```morphir-elm gen -s -c -o codecs/src``` to generate codecs means your codecs would be outputted into the ``` codecs/src``` folder in the structure:
Running the command ```morphir-elm gen --include-codecs --copy-deps --output codecs/src``` to generate codecs means your codecs would be outputted into the ``` codecs/src``` folder in the structure:

- reference-model
- codecs
- src
- morphir
- booksandrecords
- Codec.scala <----- This is your genereated codec
- morphir.json
- morphir-ir.json
- reference
- model
- booksandrecords
- Codec.scala <----- This is your genereated codec
- morphir.JSON
- morphir-ir.JSON

The generated codecs ```Codec.scala``` has both encoders and decoders. Encoders at the top and decoders following. This is a truncated example of how it looks:
The generated codecs ```Codec.scala``` has both encoders and decoders.

#### Importing and Using generated Codecs

In the example above the codecs where generated based on the ```BooksAndRecords.elm``` model and output in the codecs package. As an example lets say we want to use the generated codecs in a package called ```usecodecs``` with the following structure:

```
- usecodecs
- src
- UseCodecs.scala
```
package morphir.reference.model.booksandrecords

object Codec{
encoders ...
decoders ...
Inside ```UseCodecs.scala``` we need to import the codecs from the package in which it was generated ie: ```morphir.reference.model.booksandrecords``` and use the codecs from the ```Codec``` object. Below is an example of how to export and use a codec.

```
import morphir.reference.model.booksandrecords.Codec._
object UseCodecs {
def main(args: Array[Strings]): Unit = {
val bookType = BookType("HardCover")
println(encodeBookType(bookType) <--- using encoder
println(decodeBookType(bookType) <--- using decoder
}
}
```
It is required to import ```io.circe.Json``` in the situation where you want to use methods from the ```circe``` library. Libraries such as ```io.circe.parser``` and ```io.circe.generic``` are usually used to work with encoders and decoders, you would need to any additional library as a dependency to your project in order import them when using the codecs.



### Some useful flags to use with ```morphir-elm make```

The JSON codec backend generates codecs for only types , however an IR is made up of types and values and codecs would be generated for only types. Below are some optional flags you might want to use when running the ```morphir-elm make``` command

In the example above ```myproject``` is the project in which the codecs would be used.
The codecs can now be imported into ```myproject``` and used.
1. `-t`,` --types-only` flag : Only include type information in the IR, no values.
2. `-o`, `--output <path>` flag : Target file location where the Morphir IR will be saved.'
3. `-f`, `--fallback-cli` : Make use of the old cli make function.



Expand Down

0 comments on commit 97d0eda

Please sign in to comment.