1. Introduction to Circe and Json Encoding<\/strong><\/h4>\nIn many programming languages, JavaScript for example, converting back and forth between data structures and their JSON strings is quite easy. You could simply use the JSON.stringify()<\/em> function as shown below:<\/p>\n\/\/ Original User object<\/span>\r\nconst<\/span> User =<\/span> {\r\n name:<\/span> \"Kindson\"<\/span>,\r\n location:<\/span> \"Budapest\"<\/span>,\r\n department:<\/span> \"Computer Science\"<\/span>\r\n}\r\n\r\nvar<\/span> userString =<\/span> JSON.stringify(User) \/\/JSON string of User object<\/span>\r\n\r\nvar<\/span> parsedUser =<\/span> JSON.parse(userString) \/\/User object gotten from JSON string<\/span>\r\n<\/pre>\nYou can run this code and use console.log() to view the variables.<\/p>\n
In functional programming languages like Scala, things are a bit different. The\u00a0 process is more involved and that is why we need Circe<\/a>. Circe uses type classes to describe how types in Scala should be serialized and deserialized. For instance, for the User type, we can have two type classes:<\/p>\n\n- Encoder[User]<\/strong> – this encoder means that a User instance can be transformed into a Json representation (io.circe.Json<\/em>)<\/li>\n
- Decoder[User]<\/strong> – this decoder means that Json value can be transformed into DecodedResult[A]<\/li>\n<\/ul>\n
The figure below illustrates how serialization works in Circe<\/p>\n![\"Serialization](\"https:\/\/www.kindsonthegenius.com\/scala\/wp-content\/uploads\/sites\/14\/2022\/04\/circe-codec-1024x338.jpg\")
<\/a>Serialization in Scala with Circe<\/figcaption><\/figure>\n <\/p>\n
2. Encoding to Json with Circe\u00a0 – Setup<\/strong><\/h4>\nLet’s follow the procedure the build a decoder in Scala using Circe.<\/p>\n
Step 1<\/strong> – Create a Scala project in IntelliJ. (you can review the procedure to setup IntelliJ and create a project here. Setup Scala in IntelliJ<\/a>, Write Your First Scala Program<\/a>)<\/p>\nStep 2<\/strong> – Open your build.sb<\/em>t file and add the following line to add the Circe dependency to your project
\n<\/p>\nlibraryDependencies +=<\/span> \"io.circe\"<\/span> %%<\/span> \"circe-core\"<\/span> %<\/span> \"0.14.1\"<\/span>\r\nlibraryDependencies +=<\/span> \"io.circe\"<\/span> %%<\/span> \"circe-parser\"<\/span> %<\/span> \"0.14.1\"<\/span>\r\nlibraryDependencies +=<\/span> \"io.circe\"<\/span> %%<\/span> \"circe-generic\"<\/span> %<\/span> \"0.14.1\"<\/span>\r\n<\/pre>\n\n- circe-core<\/strong> – exposes the encoders and decoder type classes as well as Json structures and cursors that allow you to traverse and modify Json trees.<\/li>\n
- circe-parser<\/strong> – allows you to parse serialized Json into abstract syntax tree (AST)<\/li>\n
- circe-generic<\/strong> – allows you to derive encoders and decoders automatically using macros<\/li>\n<\/ul>\n
Step 3<\/strong> – Create an Object that extends App<\/p>\n <\/p>\n
3. Encoding to Json with Circe\u00a0 – Build JSON Values<\/strong><\/h4>\nRemember that encoder takes an instance of a data type into JSON value (io.circe.Json). So we would encode instances of the following types:<\/p>\n
\n- String<\/li>\n
- Integer<\/li>\n
- Array<\/li>\n
- Object<\/li>\n<\/ul>\n
\/\/Building Json values<\/span>\r\nval<\/span> jsonString =<\/span> \"Kindson The Genius\"<\/span>.<\/span>asJson \/\/ Json String, can be written as Json.fromString<\/span>\r\nval<\/span> jsonInt =<\/span> Json<\/span>.<\/span>fromInt(<\/span>43<\/span>);<\/span> \/\/ Json Int<\/span>\r\nval<\/span> jsonArray =<\/span> Json<\/span>.<\/span>arr(<\/span>jsonString,<\/span> jsonInt)<\/span>\/\/ Json Array<\/span>\r\n\r\nval<\/span> jsonObject =<\/span> Json<\/span>.<\/span>obj(<\/span> \/\/ Json Object<\/span>\r\n \"name\"<\/span> -><\/span>\"Tech Pro\"<\/span>.<\/span>asJson,<\/span>\r\n \"title\"<\/span> -><\/span> \"Software Engineer\"<\/span>.<\/span>asJson\r\n)<\/span>\r\n<\/pre>\nThe code above shows how you can encode various data types into Json values. I have added comments to indicate the various data types.<\/p>\n
Note:<\/strong> for the array types, we specify Json values as the elements.\u00a0 Similarly, for the object, each of the members has values that are Json values<\/p>\n <\/p>\n
4. Encoding to Json with Circe\u00a0 – Manipulating JSON Values<\/strong><\/h4>\nJson values has various methods that can be used to manipulated them. These methods are prefixed with “map”. For example:<\/p>\n
\n- mapString<\/strong><\/em> is used to manipulate Json string<\/li>\n
- mapArray<\/em><\/strong> is used to manipulate Json array<\/li>\n<\/ul>\n
To use the mapString()<\/em>, you need to call it on the Json string and pass it a function that does the transformation. In the example below, we use the function toUpperCase() to transform the given string to upper case<\/p>\njsonString.<\/span>mapString(<\/span>_<\/span>.<\/span>toUpperCase())<\/span>\r\n<\/pre>\n <\/p>\n
To use the mapArray(),<\/em> we call the mapArray()<\/em> function, then we map through each element of the array with the map()<\/em> function and for each element, we call the mapString() to transform them with the toUpperCase() function. This is shown below:<\/p>\njsonArray.<\/span>mapArray(<\/span>_<\/span>.<\/span>map(<\/span>_<\/span>.<\/span>mapString(<\/span>_<\/span>.<\/span>toUpperCase())))<\/span>\r\n<\/pre>\nNote that this is the same as the line below, without using the _. operator.<\/p>\n
jsonArray.<\/span>mapArray(<\/span>ar =><\/span>ar.<\/span>map(<\/span>el =><\/span>el.<\/span>mapString(<\/span>str =><\/span> str.<\/span>toUpperCase())))<\/span>\r\n<\/pre>\n <\/p>\n
5. Manipulating Nested Values<\/strong><\/h4>\nIn this case, we would have an object nested inside another object. In other words, the value of the field in the Json structure is an object.<\/p>\n
Let’s assume we have an object called personalData<\/em> and inside this object, we have a field called address<\/em> whose value is an object called addressObject<\/em>,\u00a0 made up of two fields: city<\/em> and street<\/em>. The addressObject<\/em> (encoded to Json) is given below:<\/p>\nval<\/span> addressObj =<\/span> Json<\/span>.<\/span>obj(<\/span>\r\n \"city\"<\/span> -><\/span> \"Akocity\"<\/span>.<\/span>asJson,<\/span>\r\n \"street\"<\/span> -><\/span> 56.<\/span>asJson\r\n)<\/span>\r\n<\/pre>\n <\/p>\n
With this, the personalData object with the nested addressObj is given below:<\/p>\n
val<\/span> personalData =<\/span> Json<\/span>.<\/span>obj(<\/span>\r\n \"name\"<\/span> -><\/span> \"Kindson\"<\/span>.<\/span>asJson,<\/span>\r\n \"address\"<\/span> -><\/span> addressObj\r\n)<\/span>\r\n<\/pre>\n <\/p>\n
So the goal is the manipulate the values inside the addressObj. <\/b><\/span>Now we would like to manipulate this object and reverse the value of city field. We have four functions to use:<\/span><\/p>\n\n- hcursor()<\/em><\/strong> – used to obtain an cursor on the object<\/li>\n
- downField()<\/strong> <\/em>– is used to capture a child field<\/li>\n
- withFocus()<\/strong> – returns an Acursor<\/em> on the nested object<\/li>\n
- top()<\/em><\/strong> – is used to step up to the top of the hierarchy<\/li>\n<\/ul>\n
The code is give below<\/p>\n
personalData.<\/span>hcursor\r\n .<\/span>downField(<\/span>\"address\"<\/span>)<\/span>.<\/span>downField(<\/span>\"city\"<\/span>)<\/span>\r\n .<\/span>withFocus(<\/span>_<\/span>.<\/span>mapString(<\/span>_<\/span>.<\/span>reverse))<\/span>\r\n .<\/span>top\r\n .<\/span>map(<\/span>_<\/span>.<\/span>spaces2)<\/span>\r\n<\/pre>\nThe code above reverses the value of the title property and returns that Json representation of the object. I recommend you watch the video for clarification.<\/p>\n
HCursor vs ACursor<\/strong> – Just like the HCursor, the ACursor also tracks the history, but and ACursor also represents the possibility of failure.<\/p>\nIn the next part, we would actually be building decoders. I recommend you watch the video tutorial for clarification.<\/p>\n","protected":false},"excerpt":{"rendered":"
In this tutorial series, you will learn how to build an encoder to encode Scala types into Json representations. We’ll first see how to used … <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[48,2],"tags":[41,43,42],"class_list":["post-231","post","type-post","status-publish","format-standard","hentry","category-circe","category-scala-programming","tag-circe","tag-encoder","tag-json"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/posts\/231","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/comments?post=231"}],"version-history":[{"count":10,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/posts\/231\/revisions"}],"predecessor-version":[{"id":272,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/posts\/231\/revisions\/272"}],"wp:attachment":[{"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/media?parent=231"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/categories?post=231"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/tags?post=231"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
\/\/ Original User object<\/span>\r\nconst<\/span> User =<\/span> {\r\n name:<\/span> \"Kindson\"<\/span>,\r\n location:<\/span> \"Budapest\"<\/span>,\r\n department:<\/span> \"Computer Science\"<\/span>\r\n}\r\n\r\nvar<\/span> userString =<\/span> JSON.stringify(User) \/\/JSON string of User object<\/span>\r\n\r\nvar<\/span> parsedUser =<\/span> JSON.parse(userString) \/\/User object gotten from JSON string<\/span>\r\n<\/pre>\nYou can run this code and use console.log() to view the variables.<\/p>\n
In functional programming languages like Scala, things are a bit different. The\u00a0 process is more involved and that is why we need Circe<\/a>. Circe uses type classes to describe how types in Scala should be serialized and deserialized. For instance, for the User type, we can have two type classes:<\/p>\n\n- Encoder[User]<\/strong> – this encoder means that a User instance can be transformed into a Json representation (io.circe.Json<\/em>)<\/li>\n
- Decoder[User]<\/strong> – this decoder means that Json value can be transformed into DecodedResult[A]<\/li>\n<\/ul>\n
The figure below illustrates how serialization works in Circe<\/p>\n<\/a>Serialization in Scala with Circe<\/figcaption><\/figure>\n <\/p>\n
2. Encoding to Json with Circe\u00a0 – Setup<\/strong><\/h4>\nLet’s follow the procedure the build a decoder in Scala using Circe.<\/p>\n
Step 1<\/strong> – Create a Scala project in IntelliJ. (you can review the procedure to setup IntelliJ and create a project here. Setup Scala in IntelliJ<\/a>, Write Your First Scala Program<\/a>)<\/p>\nStep 2<\/strong> – Open your build.sb<\/em>t file and add the following line to add the Circe dependency to your project
\n<\/p>\nlibraryDependencies +=<\/span> \"io.circe\"<\/span> %%<\/span> \"circe-core\"<\/span> %<\/span> \"0.14.1\"<\/span>\r\nlibraryDependencies +=<\/span> \"io.circe\"<\/span> %%<\/span> \"circe-parser\"<\/span> %<\/span> \"0.14.1\"<\/span>\r\nlibraryDependencies +=<\/span> \"io.circe\"<\/span> %%<\/span> \"circe-generic\"<\/span> %<\/span> \"0.14.1\"<\/span>\r\n<\/pre>\n\n- circe-core<\/strong> – exposes the encoders and decoder type classes as well as Json structures and cursors that allow you to traverse and modify Json trees.<\/li>\n
- circe-parser<\/strong> – allows you to parse serialized Json into abstract syntax tree (AST)<\/li>\n
- circe-generic<\/strong> – allows you to derive encoders and decoders automatically using macros<\/li>\n<\/ul>\n
Step 3<\/strong> – Create an Object that extends App<\/p>\n <\/p>\n
3. Encoding to Json with Circe\u00a0 – Build JSON Values<\/strong><\/h4>\nRemember that encoder takes an instance of a data type into JSON value (io.circe.Json). So we would encode instances of the following types:<\/p>\n
\n- String<\/li>\n
- Integer<\/li>\n
- Array<\/li>\n
- Object<\/li>\n<\/ul>\n
\/\/Building Json values<\/span>\r\nval<\/span> jsonString =<\/span> \"Kindson The Genius\"<\/span>.<\/span>asJson \/\/ Json String, can be written as Json.fromString<\/span>\r\nval<\/span> jsonInt =<\/span> Json<\/span>.<\/span>fromInt(<\/span>43<\/span>);<\/span> \/\/ Json Int<\/span>\r\nval<\/span> jsonArray =<\/span> Json<\/span>.<\/span>arr(<\/span>jsonString,<\/span> jsonInt)<\/span>\/\/ Json Array<\/span>\r\n\r\nval<\/span> jsonObject =<\/span> Json<\/span>.<\/span>obj(<\/span> \/\/ Json Object<\/span>\r\n \"name\"<\/span> -><\/span>\"Tech Pro\"<\/span>.<\/span>asJson,<\/span>\r\n \"title\"<\/span> -><\/span> \"Software Engineer\"<\/span>.<\/span>asJson\r\n)<\/span>\r\n<\/pre>\nThe code above shows how you can encode various data types into Json values. I have added comments to indicate the various data types.<\/p>\n
Note:<\/strong> for the array types, we specify Json values as the elements.\u00a0 Similarly, for the object, each of the members has values that are Json values<\/p>\n <\/p>\n
4. Encoding to Json with Circe\u00a0 – Manipulating JSON Values<\/strong><\/h4>\nJson values has various methods that can be used to manipulated them. These methods are prefixed with “map”. For example:<\/p>\n
\n- mapString<\/strong><\/em> is used to manipulate Json string<\/li>\n
- mapArray<\/em><\/strong> is used to manipulate Json array<\/li>\n<\/ul>\n
To use the mapString()<\/em>, you need to call it on the Json string and pass it a function that does the transformation. In the example below, we use the function toUpperCase() to transform the given string to upper case<\/p>\njsonString.<\/span>mapString(<\/span>_<\/span>.<\/span>toUpperCase())<\/span>\r\n<\/pre>\n <\/p>\n
To use the mapArray(),<\/em> we call the mapArray()<\/em> function, then we map through each element of the array with the map()<\/em> function and for each element, we call the mapString() to transform them with the toUpperCase() function. This is shown below:<\/p>\njsonArray.<\/span>mapArray(<\/span>_<\/span>.<\/span>map(<\/span>_<\/span>.<\/span>mapString(<\/span>_<\/span>.<\/span>toUpperCase())))<\/span>\r\n<\/pre>\nNote that this is the same as the line below, without using the _. operator.<\/p>\n
jsonArray.<\/span>mapArray(<\/span>ar =><\/span>ar.<\/span>map(<\/span>el =><\/span>el.<\/span>mapString(<\/span>str =><\/span> str.<\/span>toUpperCase())))<\/span>\r\n<\/pre>\n <\/p>\n
5. Manipulating Nested Values<\/strong><\/h4>\nIn this case, we would have an object nested inside another object. In other words, the value of the field in the Json structure is an object.<\/p>\n
Let’s assume we have an object called personalData<\/em> and inside this object, we have a field called address<\/em> whose value is an object called addressObject<\/em>,\u00a0 made up of two fields: city<\/em> and street<\/em>. The addressObject<\/em> (encoded to Json) is given below:<\/p>\nval<\/span> addressObj =<\/span> Json<\/span>.<\/span>obj(<\/span>\r\n \"city\"<\/span> -><\/span> \"Akocity\"<\/span>.<\/span>asJson,<\/span>\r\n \"street\"<\/span> -><\/span> 56.<\/span>asJson\r\n)<\/span>\r\n<\/pre>\n <\/p>\n
With this, the personalData object with the nested addressObj is given below:<\/p>\n
val<\/span> personalData =<\/span> Json<\/span>.<\/span>obj(<\/span>\r\n \"name\"<\/span> -><\/span> \"Kindson\"<\/span>.<\/span>asJson,<\/span>\r\n \"address\"<\/span> -><\/span> addressObj\r\n)<\/span>\r\n<\/pre>\n <\/p>\n
So the goal is the manipulate the values inside the addressObj. <\/b><\/span>Now we would like to manipulate this object and reverse the value of city field. We have four functions to use:<\/span><\/p>\n\n- hcursor()<\/em><\/strong> – used to obtain an cursor on the object<\/li>\n
- downField()<\/strong> <\/em>– is used to capture a child field<\/li>\n
- withFocus()<\/strong> – returns an Acursor<\/em> on the nested object<\/li>\n
- top()<\/em><\/strong> – is used to step up to the top of the hierarchy<\/li>\n<\/ul>\n
The code is give below<\/p>\n
personalData.<\/span>hcursor\r\n .<\/span>downField(<\/span>\"address\"<\/span>)<\/span>.<\/span>downField(<\/span>\"city\"<\/span>)<\/span>\r\n .<\/span>withFocus(<\/span>_<\/span>.<\/span>mapString(<\/span>_<\/span>.<\/span>reverse))<\/span>\r\n .<\/span>top\r\n .<\/span>map(<\/span>_<\/span>.<\/span>spaces2)<\/span>\r\n<\/pre>\nThe code above reverses the value of the title property and returns that Json representation of the object. I recommend you watch the video for clarification.<\/p>\n
HCursor vs ACursor<\/strong> – Just like the HCursor, the ACursor also tracks the history, but and ACursor also represents the possibility of failure.<\/p>\nIn the next part, we would actually be building decoders. I recommend you watch the video tutorial for clarification.<\/p>\n","protected":false},"excerpt":{"rendered":"
In this tutorial series, you will learn how to build an encoder to encode Scala types into Json representations. We’ll first see how to used … <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[48,2],"tags":[41,43,42],"class_list":["post-231","post","type-post","status-publish","format-standard","hentry","category-circe","category-scala-programming","tag-circe","tag-encoder","tag-json"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/posts\/231","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/comments?post=231"}],"version-history":[{"count":10,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/posts\/231\/revisions"}],"predecessor-version":[{"id":272,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/posts\/231\/revisions\/272"}],"wp:attachment":[{"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/media?parent=231"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/categories?post=231"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.kindsonthegenius.com\/scala\/wp-json\/wp\/v2\/tags?post=231"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}