Improve docs for Jason.Formatter

Author: michalmuskala

README.md

@@ -127,11 +127,11 @@ Jason has a couple feature differences compared to Poison.
   * Jason follows the JSON spec more strictly, for example it does not allow
     unescaped newline characters in JSON strings - e.g. `"\"\n\""` will
     produce a decoding error.
-  * no support for pretty printing.
   * no support for decoding into data structures (the `as:` option).
   * no built-in encoders for `MapSet`, `Range` and `Stream`.
   * no support for encoding arbitrary structs - explicit implementation
     of the `Jason.Encoder` protocol is always required.
+  * different pretty-printing customisation options (default `pretty: true` works the same)
 
 If you require encoders for any of the unsupported collection types, I suggest
 adding the needed implementations directly to your project:

lib/formatter.ex

@@ -1,12 +1,10 @@
 defmodule Jason.Formatter do
   @moduledoc ~S"""
-  `Jason.Formatter` provides pretty-printing and minimizing functions for
-  JSON-encoded data.
+  Pretty-printing and minimizing functions for JSON-encoded data.
 
-  Input is required to be in an 8-bit-wide encoding such as UTF-8 or Latin-1,
-  and is accepted in `iodata` (`binary` or `iolist`) format.
-
-  Output is provided in either `binary` or `iolist` format.
+  Input is required to be in an 8-bit-wide encoding such as UTF-8 or Latin-1
+  in `t:iodata/0` format. Input must ve valid JSON, invalid JSON may produce
+  unexpected results or errors.
   """
 
   @type opts :: [
@@ -20,25 +18,21 @@ defmodule Jason.Formatter do
   defrecordp :opts, [:indent, :line, :record, :colon]
 
   @doc ~S"""
-  Returns a binary containing a pretty-printed representation of
-  JSON-encoded `iodata`.
+  Pretty-prints JSON-encoded `input`.
 
-  `iodata` may contain multiple JSON objects or arrays, optionally separated
-  by whitespace (e.g., one object per line).  Objects in `pretty_print`ed
-  output will be separated by newlines.  No trailing newline is emitted.
+  `input` may contain multiple JSON objects or arrays, optionally separated
+  by whitespace (e.g., one object per line). Objects in output will be
+  separated by newlines. No trailing newline is emitted.
 
-  Options:
+  ## Options
 
-  * `:indent` sets the indentation string used for nested objects and
-    arrays.  The default indent setting is two spaces (`"  "`).
-  * `:line_separator` sets the newline string used in nested objects.
-    The default setting is a line feed (`"\n"`).
-  * `:record_separator` sets the string printed between root-level objects
-    and arrays.  The default setting is `opts[:line_separator]`.
-  * `:after_colon` sets the string printed after a colon inside objects.
-    The default setting is one space (`" "`).
+    * `:indent` - used for nested objects and arrays (default: two spaces - `"  "`);
+    * `:line_separator` - used in nested objects (default: `"\n"`);
+    * `:record_separator` - separates root-level objects and arrays
+      (default is the value for `:line_separator` option);
+    * `:after_colon` - printed after a colon inside objects (default: one space - `" "`).
 
-  Example:
+  ## Examples
 
       iex> Jason.Formatter.pretty_print(~s|{"a":{"b": [1, 2]}}|)
       ~s|{
@@ -49,93 +43,96 @@ defmodule Jason.Formatter do
           ]
         }
       }|
+
   """
   @spec pretty_print(iodata, opts) :: binary
-  def pretty_print(iodata, opts \\ []) do
-    iodata
+  def pretty_print(input, opts \\ []) do
+    input
     |> pretty_print_to_iodata(opts)
     |> IO.iodata_to_binary()
   end
 
   @doc ~S"""
-  Returns an iolist containing a pretty-printed representation of
-  JSON-encoded `iodata`.
+  Pretty-prints JSON-encoded `input` and returns iodata.
 
-  See `pretty_print/2` for details and options.
+  This function should be preferred to `pretty_print/2`, if the pretty-printed
+  JSON will be handed over to one of the IO functions or sent
+  over the socket. The Erlang runtime is able to leverage vectorised
+  writes and avoid allocating a continuous buffer for the whole
+  resulting string, lowering memory use and increasing performance.
   """
   @spec pretty_print_to_iodata(iodata, opts) :: iodata
-  def pretty_print_to_iodata(iodata, opts \\ []) do
-    opts = parse_opts(opts, opts(indent: "  ", line: "\n", record: nil, colon: " "))
-    opts = opts(opts, record: opts(opts, :record) || opts(opts, :line))
+  def pretty_print_to_iodata(input, opts \\ []) do
+    opts = parse_opts(opts, "  ", "\n", nil, " ")
 
     depth = :first
     empty = false
 
-    {output, _state} = pp_iodata(iodata, [], depth, empty, opts)
+    {output, _state} = pp_iodata(input, [], depth, empty, opts)
 
     output
   end
 
   @doc ~S"""
-  Returns a binary containing a minimized representation of
-  JSON-encoded `iodata`.
+  Minimizes JSON-encoded `input`.
 
-  `iodata` may contain multiple JSON objects or arrays, optionally
-  separated by whitespace (e.g., one object per line).  `minimize`d
-  output will contain one object per line.  No trailing newline is emitted.
+  `input` may contain multiple JSON objects or arrays, optionally
+  separated by whitespace (e.g., one object per line). Minimized
+  output will contain one object per line. No trailing newline is emitted.
 
-  The `:record_separator` option may be given to control the string
-  used as newline (default `"\n"`).  Other options are ignored.
+  ## Options
 
-  Example:
+    * `:record_separator` - controls the string used as newline (default: `"\n"`).
+
+  ## Examples
 
       iex> Jason.Formatter.minimize(~s|{ "a" : "b" , "c": \n\n 2}|)
       ~s|{"a":"b","c":2}|
+
   """
   @spec minimize(iodata, opts) :: binary
-  def minimize(iodata, opts \\ []) do
-    iodata
+  def minimize(input, opts \\ []) do
+    input
     |> minimize_to_iodata(opts)
     |> IO.iodata_to_binary()
   end
 
   @doc ~S"""
-  Returns an iolist containing a minimized representation of
-  JSON-encoded `iodata`.
+  Minimizes JSON-encoded `input` and returns iodata.
 
-  See `minimize/2` for details and options.
+  This function should be preferred to `minimize/2`, if the minimized
+  JSON will be handed over to one of the IO functions or sent
+  over the socket. The Erlang runtime is able to leverage vectorised
+  writes and avoid allocating a continuous buffer for the whole
+  resulting string, lowering memory use and increasing performance.
   """
   @spec minimize_to_iodata(iodata, opts) :: iodata
-  def minimize_to_iodata(iodata, opts) do
-    opts = parse_opts(opts, opts(indent: "", line: "", record: "\n", colon: ""))
+  def minimize_to_iodata(input, opts) do
+    record = Keyword.get(opts, :record_separator, "\n")
+    opts = opts(indent: "", line: "", record: record, colon: "")
 
     depth = :first
     empty = false
 
-    {output, _state} = pp_iodata(iodata, [], depth, empty, opts)
+    {output, _state} = pp_iodata(input, [], depth, empty, opts)
 
     output
   end
 
-  defp parse_opts(opts, defaults) do
-    Enum.reduce(opts, defaults, fn
-      {:indent, indent}, opts ->
-        opts(opts, indent: IO.iodata_to_binary(indent))
-
-      {:line_separator, line}, opts ->
-        line = IO.iodata_to_binary(line)
-        opts(opts, line: line, record: opts(opts, :record) || line)
-
-      {:record_separator, record}, opts ->
-        opts(opts, record: IO.iodata_to_binary(record))
+  defp parse_opts([{option, value} | opts], indent, line, record, colon) do
+    value = IO.iodata_to_binary(value)
+    case option do
+      :indent -> parse_opts(opts, value, line, record, colon)
+      :record_separator -> parse_opts(opts, indent, line, value, colon)
+      :after_colon -> parse_opts(opts, indent, line, record, value)
+      :line_separator -> parse_opts(opts, indent, value, record || value, colon)
+    end
+  end
 
-      {:after_colon, colon}, opts ->
-        opts(opts, colon: IO.iodata_to_binary(colon))
-    end)
+  defp parse_opts([], indent, line, record, colon) do
+    opts(indent: indent, line: line, record: record || line, colon: colon)
   end
 
-  @spec tab(String.t(), non_neg_integer) :: iodata()
-  ## Returns an iolist containing `depth` instances of `opts[:indent]`
   for depth <- 1..16 do
     defp tab("  ", unquote(depth)), do: unquote(String.duplicate("  ", depth))
   end