From 97d0eda4ff9b66f6f860436cf1163116ee483c52 Mon Sep 17 00:00:00 2001 From: unknown Date: Tue, 7 Feb 2023 19:30:24 +0000 Subject: [PATCH] edited documentation for codec backend --- docs/json-codec-backend/codec-docs.md | 84 ++++++++++++++++++--------- 1 file changed, 57 insertions(+), 27 deletions(-) diff --git a/docs/json-codec-backend/codec-docs.md b/docs/json-codec-backend/codec-docs.md index e503cd4ec..4cf9c0291 100644 --- a/docs/json-codec-backend/codec-docs.md +++ b/docs/json-codec-backend/codec-docs.md @@ -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 @@ -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 ` flag : Target file location where the Morphir IR will be saved.' +3. `-f`, `--fallback-cli` : Make use of the old cli make function.