{"action":"created","comment":{"url":"https://api.github.com/repos/Banno/jsonz/pulls/comments/24195543","id":24195543,"diff_hunk":"@@ -1,10 +1,163 @@\n-jsonz\n-=====\n+# jsonz\n \n-A little of sjson, sjsonapp, scalaz and play's JSON libraries mixed together.\n+> A little of sjson, sjsonapp, scalaz and play's JSON libraries mixed together.\n \n-License\n-=======\n+jsonz is a library that implements json serialization and deserialization via typeclasses in scala.\n+\n+# Differences between other json parsing libraries\n+\n+## Default Values\n+\n+If a model (typically case classes) has default values, they may be omitted from json when reading that json.\n+\n+```scala\n+import jsonz._\n+import jsonz.DefaultFormats._\n+object DefaultValues {\n+  case class Foo(thing: Int, other: Option[String] = None)\n+  implicit val format = productFormat2(\"thing\", \"other\")(Foo.apply)(Foo.unapply)\n+  val json = \"\"\"{\"thing\": 1}\"\"\"\n+  Jsonz.fromJsonStr[Foo](json)\n+}\n+```\n+\n+## Failures\n+\n+Jsonz is different about failures. When parsing json failures are accumulated and delivered at the end. The type `JsonzValidation[T]` is a type alias for scalaz's `Validation[NonEmptyList[JsFailure], T]` so the user will receive either a `scalaz.Success` with an instance of the model filled in with the data from the json, or a `scalaz.Failure` that contains failures that occured duirng parsing. These failures could be from missing fields, or malformly typed elements.\n+\n+### No Exceptions\n+\n+Jsonz tries really hard to never throw exceptions. Other json libraries we encountered would throw exceptions at malformed or key-missing json. Instead jsonz will return a parsable failure for the user to parse.\n+\n+# Usage\n+\n+## Reading and Writing from models (case classes)\n+\n+Jsonz provides [ProductFormats](src/main/scala/ProductFormats.scala) for use over anything that abstracts over [`scala.Product`](http://www.scala-lang.org/api/current/scala/Product.html). This means your typical case class can be written to json and read back out.\n+\n+```scala\n+import jsonz._\n+import jsonz.DefaultFormats._\n+\n+object Example {\n+    case class Foo(thing: Int, other: String)\n+    implicit val fooFormat = productFormat2(\"thing\", \"other\")(Foo.apply)(Foo.unapply)\n+\n+    Jsonz.fromJsonStr[Foo](\"\"\"{\"thing\":12, \"other\":\"hi\"}\"\"\") // JsonzValidation[Foo]\n+    Jsonz.toJsonStr(Foo(12, \"hi\")) // JsValue\n+}\n+```\n+## Out of the box type support\n+\n+jsonz provides support for reading and writing the following types out of the box: `String`, `Short`, `Int`, `Long`, `Float`, `Double`, `BigDecimal`, `Boolean`, `JsValue`. The following types require a `Format` for the generic types to be in scope: `Option[T]`, `Map[String, V]`, `Traversable[T]`, `Array[T]`, `scalaz.NonEmptyList[T]`, `jsonz.JsFailure`, `Either[L, R]`, and `scalaz.Validation[E, A]`.\n+\n+### Enumerations\n+\n+Java's `java.lang.Enum` and Scala's `scala.Enumeration` are supported out of the box, simply mix in (or import the companion object) `jsonz.EnumerationFormats` into the scope where you wish to define the implicit format and call `javaEnumerationFormat` or `scalaEnumerationFormat` with the enumeration instance passed in.\n+\n+```java\n+// Defined in Day.java\n+public enum Day {\n+    SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY\n+}\n+```\n+\n+```scala\n+import jsonz._\n+import jsonz.DefaultFormats._\n+object Animals extends Enumeration {\n+    val Tiger = Value\n+    val Lion = Value\n+    val Swallow = Value\n+}\n+implicit val AnimalsFormat: Format[Animals.Value] = scalaEnumerationFormat(Animals)\n+implicit val DaysFormat: Format[Day] = javaEnumerationFormat[Day](Day.MONDAY)\n+```\n+\n+### Recursive Values\n+\n+Given a recursive type you will need to wrap the format in the `lazyFormat` method.\n+\n+```scala\n+import jsonz._\n+import jsonz.DefaultFormats._\n+case class RecursiveType(rs: List[RecursiveType])\n+implicit lazy val RecursiveTypeFormat: Format[RecursiveType] = lazyFormat(productFormat1(\"rs\")(RecursiveType.apply)(RecursiveType.unapply))\n+```\n+\n+### Joda-Time\n+\n+Joda-Time is typically the first library chosen for performing date/time operations on the JVM. Jsonz offers support for reading and writing it's `org.joda.time.DateTime` class via the following imports. The formats used to try and parse are: `ISO 8601` (with and without millis), `yyyy-MM-dd`, and [RFC 1123](https://tools.ietf.org/html/rfc1123) (EEE, dd MMM yyyy HH:mm:ss 'GMT').\n+\n+```scala\n+import jsonz._\n+import jsonz.joda.JodaTimeFormats._\n+```\n+\n+### Spray","path":"README.markdown","position":102,"original_position":102,"commit_id":"0e304eba8a87faca70a20103c56e91ed0220b31e","original_commit_id":"0e304eba8a87faca70a20103c56e91ed0220b31e","user":{"login":"trentio","id":50521,"avatar_url":"https://avatars.githubusercontent.com/u/50521?v=3","gravatar_id":"","url":"https://api.github.com/users/trentio","html_url":"https://github.com/trentio","followers_url":"https://api.github.com/users/trentio/followers","following_url":"https://api.github.com/users/trentio/following{/other_user}","gists_url":"https://api.github.com/users/trentio/gists{/gist_id}","starred_url":"https://api.github.com/users/trentio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/trentio/subscriptions","organizations_url":"https://api.github.com/users/trentio/orgs","repos_url":"https://api.github.com/users/trentio/repos","events_url":"https://api.github.com/users/trentio/events{/privacy}","received_events_url":"https://api.github.com/users/trentio/received_events","type":"User","site_admin":false},"body":"Isnt spray a provided dependency, that should probably be noted. \r\n","created_at":"2015-02-05T20:16:56Z","updated_at":"2015-02-05T20:16:56Z","html_url":"https://github.com/Banno/jsonz/pull/22#discussion_r24195543","pull_request_url":"https://api.github.com/repos/Banno/jsonz/pulls/22","_links":{"self":{"href":"https://api.github.com/repos/Banno/jsonz/pulls/comments/24195543"},"html":{"href":"https://github.com/Banno/jsonz/pull/22#discussion_r24195543"},"pull_request":{"href":"https://api.github.com/repos/Banno/jsonz/pulls/22"}}},"pull_request":{"url":"https://api.github.com/repos/Banno/jsonz/pulls/22","id":28756364,"html_url":"https://github.com/Banno/jsonz/pull/22","diff_url":"https://github.com/Banno/jsonz/pull/22.diff","patch_url":"https://github.com/Banno/jsonz/pull/22.patch","issue_url":"https://api.github.com/repos/Banno/jsonz/issues/22","number":22,"state":"open","locked":false,"title":"Writing a readme for jsonz.","user":{"login":"adamdecaf","id":120951,"avatar_url":"https://avatars.githubusercontent.com/u/120951?v=3","gravatar_id":"","url":"https://api.github.com/users/adamdecaf","html_url":"https://github.com/adamdecaf","followers_url":"https://api.github.com/users/adamdecaf/followers","following_url":"https://api.github.com/users/adamdecaf/following{/other_user}","gists_url":"https://api.github.com/users/adamdecaf/gists{/gist_id}","starred_url":"https://api.github.com/users/adamdecaf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/adamdecaf/subscriptions","organizations_url":"https://api.github.com/users/adamdecaf/orgs","repos_url":"https://api.github.com/users/adamdecaf/repos","events_url":"https://api.github.com/users/adamdecaf/events{/privacy}","received_events_url":"https://api.github.com/users/adamdecaf/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-02-05T20:03:04Z","updated_at":"2015-02-05T20:16:56Z","closed_at":null,"merged_at":null,"merge_commit_sha":"fe3edbac57a00c46727cc5b7bbd3644e26c741a6","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/Banno/jsonz/pulls/22/commits","review_comments_url":"https://api.github.com/repos/Banno/jsonz/pulls/22/comments","review_comment_url":"https://api.github.com/repos/Banno/jsonz/pulls/comments/{number}","comments_url":"https://api.github.com/repos/Banno/jsonz/issues/22/comments","statuses_url":"https://api.github.com/repos/Banno/jsonz/statuses/0e304eba8a87faca70a20103c56e91ed0220b31e","head":{"label":"Banno:readme","ref":"readme","sha":"0e304eba8a87faca70a20103c56e91ed0220b31e","user":{"login":"Banno","id":371161,"avatar_url":"https://avatars.githubusercontent.com/u/371161?v=3","gravatar_id":"","url":"https://api.github.com/users/Banno","html_url":"https://github.com/Banno","followers_url":"https://api.github.com/users/Banno/followers","following_url":"https://api.github.com/users/Banno/following{/other_user}","gists_url":"https://api.github.com/users/Banno/gists{/gist_id}","starred_url":"https://api.github.com/users/Banno/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Banno/subscriptions","organizations_url":"https://api.github.com/users/Banno/orgs","repos_url":"https://api.github.com/users/Banno/repos","events_url":"https://api.github.com/users/Banno/events{/privacy}","received_events_url":"https://api.github.com/users/Banno/received_events","type":"Organization","site_admin":false},"repo":{"id":4825892,"name":"jsonz","full_name":"Banno/jsonz","owner":{"login":"Banno","id":371161,"avatar_url":"https://avatars.githubusercontent.com/u/371161?v=3","gravatar_id":"","url":"https://api.github.com/users/Banno","html_url":"https://github.com/Banno","followers_url":"https://api.github.com/users/Banno/followers","following_url":"https://api.github.com/users/Banno/following{/other_user}","gists_url":"https://api.github.com/users/Banno/gists{/gist_id}","starred_url":"https://api.github.com/users/Banno/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Banno/subscriptions","organizations_url":"https://api.github.com/users/Banno/orgs","repos_url":"https://api.github.com/users/Banno/repos","events_url":"https://api.github.com/users/Banno/events{/privacy}","received_events_url":"https://api.github.com/users/Banno/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Banno/jsonz","description":"Yet another Scala json parsing library blending together the better ideas","fork":false,"url":"https://api.github.com/repos/Banno/jsonz","forks_url":"https://api.github.com/repos/Banno/jsonz/forks","keys_url":"https://api.github.com/repos/Banno/jsonz/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Banno/jsonz/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Banno/jsonz/teams","hooks_url":"https://api.github.com/repos/Banno/jsonz/hooks","issue_events_url":"https://api.github.com/repos/Banno/jsonz/issues/events{/number}","events_url":"https://api.github.com/repos/Banno/jsonz/events","assignees_url":"https://api.github.com/repos/Banno/jsonz/assignees{/user}","branches_url":"https://api.github.com/repos/Banno/jsonz/branches{/branch}","tags_url":"https://api.github.com/repos/Banno/jsonz/tags","blobs_url":"https://api.github.com/repos/Banno/jsonz/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Banno/jsonz/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Banno/jsonz/git/refs{/sha}","trees_url":"https://api.github.com/repos/Banno/jsonz/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Banno/jsonz/statuses/{sha}","languages_url":"https://api.github.com/repos/Banno/jsonz/languages","stargazers_url":"https://api.github.com/repos/Banno/jsonz/stargazers","contributors_url":"https://api.github.com/repos/Banno/jsonz/contributors","subscribers_url":"https://api.github.com/repos/Banno/jsonz/subscribers","subscription_url":"https://api.github.com/repos/Banno/jsonz/subscription","commits_url":"https://api.github.com/repos/Banno/jsonz/commits{/sha}","git_commits_url":"https://api.github.com/repos/Banno/jsonz/git/commits{/sha}","comments_url":"https://api.github.com/repos/Banno/jsonz/comments{/number}","issue_comment_url":"https://api.github.com/repos/Banno/jsonz/issues/comments/{number}","contents_url":"https://api.github.com/repos/Banno/jsonz/contents/{+path}","compare_url":"https://api.github.com/repos/Banno/jsonz/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Banno/jsonz/merges","archive_url":"https://api.github.com/repos/Banno/jsonz/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Banno/jsonz/downloads","issues_url":"https://api.github.com/repos/Banno/jsonz/issues{/number}","pulls_url":"https://api.github.com/repos/Banno/jsonz/pulls{/number}","milestones_url":"https://api.github.com/repos/Banno/jsonz/milestones{/number}","notifications_url":"https://api.github.com/repos/Banno/jsonz/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Banno/jsonz/labels{/name}","releases_url":"https://api.github.com/repos/Banno/jsonz/releases{/id}","created_at":"2012-06-28T21:31:58Z","updated_at":"2015-01-14T18:02:13Z","pushed_at":"2015-02-05T20:05:15Z","git_url":"git://github.com/Banno/jsonz.git","ssh_url":"git@github.com:Banno/jsonz.git","clone_url":"https://github.com/Banno/jsonz.git","svn_url":"https://github.com/Banno/jsonz","homepage":null,"size":615,"stargazers_count":4,"watchers_count":4,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":4,"mirror_url":null,"open_issues_count":1,"forks":4,"open_issues":1,"watchers":4,"default_branch":"master"}},"base":{"label":"Banno:master","ref":"master","sha":"fe01ad8f49aee63edfa0c708583e3423ac16b826","user":{"login":"Banno","id":371161,"avatar_url":"https://avatars.githubusercontent.com/u/371161?v=3","gravatar_id":"","url":"https://api.github.com/users/Banno","html_url":"https://github.com/Banno","followers_url":"https://api.github.com/users/Banno/followers","following_url":"https://api.github.com/users/Banno/following{/other_user}","gists_url":"https://api.github.com/users/Banno/gists{/gist_id}","starred_url":"https://api.github.com/users/Banno/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Banno/subscriptions","organizations_url":"https://api.github.com/users/Banno/orgs","repos_url":"https://api.github.com/users/Banno/repos","events_url":"https://api.github.com/users/Banno/events{/privacy}","received_events_url":"https://api.github.com/users/Banno/received_events","type":"Organization","site_admin":false},"repo":{"id":4825892,"name":"jsonz","full_name":"Banno/jsonz","owner":{"login":"Banno","id":371161,"avatar_url":"https://avatars.githubusercontent.com/u/371161?v=3","gravatar_id":"","url":"https://api.github.com/users/Banno","html_url":"https://github.com/Banno","followers_url":"https://api.github.com/users/Banno/followers","following_url":"https://api.github.com/users/Banno/following{/other_user}","gists_url":"https://api.github.com/users/Banno/gists{/gist_id}","starred_url":"https://api.github.com/users/Banno/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Banno/subscriptions","organizations_url":"https://api.github.com/users/Banno/orgs","repos_url":"https://api.github.com/users/Banno/repos","events_url":"https://api.github.com/users/Banno/events{/privacy}","received_events_url":"https://api.github.com/users/Banno/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Banno/jsonz","description":"Yet another Scala json parsing library blending together the better ideas","fork":false,"url":"https://api.github.com/repos/Banno/jsonz","forks_url":"https://api.github.com/repos/Banno/jsonz/forks","keys_url":"https://api.github.com/repos/Banno/jsonz/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Banno/jsonz/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Banno/jsonz/teams","hooks_url":"https://api.github.com/repos/Banno/jsonz/hooks","issue_events_url":"https://api.github.com/repos/Banno/jsonz/issues/events{/number}","events_url":"https://api.github.com/repos/Banno/jsonz/events","assignees_url":"https://api.github.com/repos/Banno/jsonz/assignees{/user}","branches_url":"https://api.github.com/repos/Banno/jsonz/branches{/branch}","tags_url":"https://api.github.com/repos/Banno/jsonz/tags","blobs_url":"https://api.github.com/repos/Banno/jsonz/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Banno/jsonz/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Banno/jsonz/git/refs{/sha}","trees_url":"https://api.github.com/repos/Banno/jsonz/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Banno/jsonz/statuses/{sha}","languages_url":"https://api.github.com/repos/Banno/jsonz/languages","stargazers_url":"https://api.github.com/repos/Banno/jsonz/stargazers","contributors_url":"https://api.github.com/repos/Banno/jsonz/contributors","subscribers_url":"https://api.github.com/repos/Banno/jsonz/subscribers","subscription_url":"https://api.github.com/repos/Banno/jsonz/subscription","commits_url":"https://api.github.com/repos/Banno/jsonz/commits{/sha}","git_commits_url":"https://api.github.com/repos/Banno/jsonz/git/commits{/sha}","comments_url":"https://api.github.com/repos/Banno/jsonz/comments{/number}","issue_comment_url":"https://api.github.com/repos/Banno/jsonz/issues/comments/{number}","contents_url":"https://api.github.com/repos/Banno/jsonz/contents/{+path}","compare_url":"https://api.github.com/repos/Banno/jsonz/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Banno/jsonz/merges","archive_url":"https://api.github.com/repos/Banno/jsonz/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Banno/jsonz/downloads","issues_url":"https://api.github.com/repos/Banno/jsonz/issues{/number}","pulls_url":"https://api.github.com/repos/Banno/jsonz/pulls{/number}","milestones_url":"https://api.github.com/repos/Banno/jsonz/milestones{/number}","notifications_url":"https://api.github.com/repos/Banno/jsonz/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Banno/jsonz/labels{/name}","releases_url":"https://api.github.com/repos/Banno/jsonz/releases{/id}","created_at":"2012-06-28T21:31:58Z","updated_at":"2015-01-14T18:02:13Z","pushed_at":"2015-02-05T20:05:15Z","git_url":"git://github.com/Banno/jsonz.git","ssh_url":"git@github.com:Banno/jsonz.git","clone_url":"https://github.com/Banno/jsonz.git","svn_url":"https://github.com/Banno/jsonz","homepage":null,"size":615,"stargazers_count":4,"watchers_count":4,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":4,"mirror_url":null,"open_issues_count":1,"forks":4,"open_issues":1,"watchers":4,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/Banno/jsonz/pulls/22"},"html":{"href":"https://github.com/Banno/jsonz/pull/22"},"issue":{"href":"https://api.github.com/repos/Banno/jsonz/issues/22"},"comments":{"href":"https://api.github.com/repos/Banno/jsonz/issues/22/comments"},"review_comments":{"href":"https://api.github.com/repos/Banno/jsonz/pulls/22/comments"},"review_comment":{"href":"https://api.github.com/repos/Banno/jsonz/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/Banno/jsonz/pulls/22/commits"},"statuses":{"href":"https://api.github.com/repos/Banno/jsonz/statuses/0e304eba8a87faca70a20103c56e91ed0220b31e"}}}}