Moving Triptoin comments to README

Author: bathalh

README.markdown

@@ -41,26 +41,26 @@ import DefaultJsonProtocol._ // if you don't supply your own Protocol (see below
 and do one or more of the following:
 
 * Parse a JSON string into its Abstract Syntax Tree (AST) representation
-    
+
     ```scala
     val source = """{ "some": "JSON source" }"""
     val jsonAst = source.parseJson // or JsonParser(source)
     ```
-    
+
 * Print a JSON AST back to a String using either the `CompactPrinter` or the `PrettyPrinter`
-    
+
     ```scala
     val json = jsonAst.prettyPrint // or .compactPrint
     ```
-    
+
 * Convert any Scala object to a JSON AST using the pimped `toJson` method
-    
+
     ```scala
     val jsonAst = List(1, 2, 3).toJson
     ```
-    
+
 * Convert a JSON AST to a Scala object with the `convertTo` method
-    
+
     ```scala
     val myObject = jsonAst.convertTo[MyObjectType]
     ```
@@ -95,6 +95,7 @@ important reference and collection types. As long as your code uses nothing more
 * String, Symbol
 * BigInt, BigDecimal
 * Option, Either, Tuple1 - Tuple7
+* Tription
 * List, Array
 * immutable.{Map, Iterable, Seq, IndexedSeq, LinearSeq, Set, Vector}
 * collection.{Iterable, Seq, IndexedSeq, LinearSeq, Set}
@@ -103,6 +104,30 @@ important reference and collection types. As long as your code uses nothing more
 In most cases however you'll also want to convert types not covered by the `DefaultJsonProtocol`. In these cases you
 need to provide `JsonFormat[T]`s for your custom types. This is not hard at all.
 
+### Triptions
+
+`Tription`s are "triple options": values that can either exist, be null, or be undefined.
+
+JavaScript (and JSON), unlike Java/Scala, allow `undefined` values, which are distinct from `null` values.
+For example, a PUT request may have a payload like this:
+```json
+    { "id":"234565434567898789098765",
+      "field1": "new value",
+      "field3": null,
+      "field4": undefined }
+```
+which would tell the server to update field1 to "new value", set field3 to null, and leave field2 and field4
+unchanged. With a standard scala `Option`, it is impossible to tell whether the values of field2, field3,
+and field4 in the original payload were `null` or `undefined` since any missing values translate to `None`.
+
+The `Tription` solves that problem by defining `Value` for present values, `Null` for null values, and
+`Undefined` for values which are missing or explicitly marked as undefined.
+
+`Tription`s can be used just like `Option`s:
+```scala
+case class RequestObject( id: String, field1: Tription[String], field2: Tription[Int],
+                          field3: Tription[String], field4: Tription[SubResource] )
+```
 
 ### Providing JsonFormats for Case Classes
 
@@ -158,10 +183,10 @@ object MyJsonProtocol extends DefaultJsonProtocol {
 #### NullOptions
 
 The `NullOptions` trait supplies an alternative rendering mode for optional case class members. Normally optional
-members that are undefined (`None`) are not rendered at all. By mixing in this trait into your custom JsonProtocol you
+members that are undefined (`None`/`Undefined`) are not rendered at all. By mixing in this trait into your custom JsonProtocol you
 can enforce the rendering of undefined members as `null`.
-(Note that this only affect JSON writing, spray-json will always read missing optional members as well as `null`
-optional members as `None`.)
+(Note that this only affect JSON writing, spray-json will always read missing `Option` members as well as `null`
+`Option` members as `None` and missing `Tription` members as `Undefined`.)
 
 
 ### Providing JsonFormats for other Types

src/main/scala/spray/json/Tription.scala

@@ -1,22 +1,7 @@
 package spray.json
 
 /**
-  * A Triple-Option
-  *
-  * JavaScript (and JSON), unlike Java/Scala, allow undefined values, which are distinct from null values.
-  * For example, a PUT request may have a payload like this:
-  * <code>
-  *     { "id":"234565434567898789098765",
-  *       "field1": 7,
-  *       "field3: null,
-  *       "field4": undefined }
-  * </code>
-  * which would tell the server to update field1 to 7, set field3 to null, and leave field2 and field4 alone.
-  * With a standard scala `Option`, it is impossible to tell whether the payload of the request had field2, field3,
-  * and field4 null or undefined since any missing values translate to `None`.
-  *
-  * The Tription solves that problem by defining `Value` for present values, `Null` for null values, and
-  * `Undefined` for values which are missing or explicitly marked as undefined.
+  * A Triple-Option for JSON values: `Undefined`, `Null`, or `Value(x)` See readme for more details
   *
   * Created by bathalh on 2/19/16.
   */