Add :pretty option to JSON encoding

Assisted-by: pi:deepseek-v4.1-flash

Author: gilbertwong96

CHANGELOG.md

@@ -22,6 +22,7 @@
   * [Code.Formatter] Add a `:migrate_atom_interpolations` option
   * [File] Accept an open IO device in `File.stat/2`, `File.stat!/2`, `File.regular?/2`, `File.dir?/2`, and `File.exists?/2`
   * [IO.ANSI] Add `bold/0`, `bold_off/0`, `dim/0`, `dim_off/0`, `blink/0`, `invisible/0`, `invisible_off/0`, `strikethrough/0`, `strikethrough_off/0`, `italic_off/0`, `underline_off/0`, `overline/0`, `overline_off/0`, `cursor_forward/0`, `cursor_backward/0`, and `cursor_home/0`, aligning names with Erlang/OTP
+  * [JSON] Add the `:pretty` option to `JSON.encode!/2` and `JSON.encode_to_iodata!/2`
   * [Kernel] Improve performance of type constructors and complex intersections
   * [Kernel] Warn on aliases that are never used because a later alias shadows them
   * [Kernel] Warn on binary patterns with segments that are not byte-aligned

lib/elixir/lib/json.ex

@@ -499,50 +499,234 @@ defmodule JSON do
     end
   end
 
+  @max_indent 31
+
+  @indent_specials [?{, ?}, ?[, ?], ?,, ?:, ?", ?\s, ?\t, ?\r, ?\n]
+
   @doc ~S"""
   Encodes the given term to JSON as a binary.
 
-  The second argument is a function that is recursively
-  invoked to encode a term.
+  The second argument is either a function that is recursively invoked to
+  encode a term, or a keyword list of options, described below.
 
   > #### IO and performance {: .tip}
   >
   > If you need to encode data to be sent over the network
   > or written to the filesystem, consider using the more
   > efficient `encode_to_iodata!/2`.
 
+  ## Options
+
+  When the second argument is a keyword list, the only accepted option is:
+
+    * `:pretty` - either `true` to indent nested members by two spaces,
+      or a binary of spaces and tabs to be used as the indent unit.
+      Empty containers are kept on a single line. Defaults to `false`.
+
+  Unknown options raise. A custom encoder function cannot be combined
+  with these options.
+
   ## Examples
 
       iex> JSON.encode!([123, "string", %{key: "value"}])
       "[123,\"string\",{\"key\":\"value\"}]"
 
+      iex> JSON.encode!(%{tags: []}, pretty: true)
+      "{\n  \"tags\": []\n}"
+
+      iex> JSON.encode!(%{id: "abc"}, pretty: "\t")
+      "{\n\t\"id\": \"abc\"\n}"
+
   """
-  @spec encode!(term(), encoder()) :: binary()
-  def encode!(term, encoder \\ &protocol_encode/2) do
+  @spec encode!(term(), encoder() | [pretty: boolean() | binary()]) :: binary()
+  def encode!(term, encoder_or_opts \\ &protocol_encode/2)
+
+  def encode!(term, encoder) when is_function(encoder, 2) do
     IO.iodata_to_binary(encoder.(term, encoder))
   end
 
+  def encode!(term, opts) when is_list(opts) do
+    term |> encode_to_iodata!(opts) |> IO.iodata_to_binary()
+  end
+
   @doc ~S"""
   Encodes the given term to JSON as an iodata.
 
   This is the most efficient format if the JSON is going to be
   used for IO purposes.
 
   The second argument is a function that is recursively
-  invoked to encode a term.
+  invoked to encode a term. It may also be a keyword list of
+  options, as accepted by `encode!/2`.
 
   ## Examples
 
       iex> data = JSON.encode_to_iodata!([123, "string", %{key: "value"}])
       iex> IO.iodata_to_binary(data)
       "[123,\"string\",{\"key\":\"value\"}]"
 
+      iex> data = JSON.encode_to_iodata!(%{id: "abc"}, pretty: true)
+      iex> IO.iodata_to_binary(data)
+      "{\n  \"id\": \"abc\"\n}"
+
   """
-  @spec encode_to_iodata!(term(), encoder()) :: iodata()
-  def encode_to_iodata!(term, encoder \\ &protocol_encode/2) do
+  @spec encode_to_iodata!(term(), encoder() | [pretty: boolean() | binary()]) :: iodata()
+  def encode_to_iodata!(term, encoder_or_opts \\ &protocol_encode/2)
+
+  def encode_to_iodata!(term, encoder) when is_function(encoder, 2) do
     encoder.(term, encoder)
   end
 
+  def encode_to_iodata!(term, opts) when is_list(opts) do
+    iodata = protocol_encode(term, &protocol_encode/2)
+
+    case Keyword.fetch(validate_opts!(opts), :pretty) do
+      {:ok, false} ->
+        iodata
+
+      {:ok, true} ->
+        format_iodata(iodata, "  ")
+
+      {:ok, unit} when is_binary(unit) ->
+        format_iodata(iodata, indent_unit!(unit))
+
+      {:ok, other} ->
+        raise ArgumentError,
+              "expected :pretty to be a boolean or a binary, got: #{inspect(other)}"
+
+      :error ->
+        iodata
+    end
+  end
+
+  defp validate_opts!(opts) do
+    if Keyword.keyword?(opts) do
+      case Keyword.keys(opts) -- [:pretty] do
+        [] ->
+          opts
+
+        unknown ->
+          raise ArgumentError,
+                "unknown options #{inspect(unknown)}, expected only :pretty"
+      end
+    else
+      raise ArgumentError,
+            "expected the second argument to be a function or a keyword list, " <>
+              "got: #{inspect(opts)}"
+    end
+  end
+
+  defp indent_unit!(unit) do
+    if indent_unit?(unit) do
+      unit
+    else
+      raise ArgumentError,
+            "expected :pretty to be a binary of spaces and tabs, got: #{inspect(unit)}"
+    end
+  end
+
+  defp indent_unit?(<<char, rest::binary>>) when char in ~c" \t", do: indent_unit?(rest)
+  defp indent_unit?(<<>>), do: true
+  defp indent_unit?(_), do: false
+
+  defp format_iodata(iodata, unit) do
+    # Flattening is required: the iodata mixes binaries with byte separators,
+    # so string boundaries do not line up with iodata elements.
+    indents = List.to_tuple(for depth <- 0..@max_indent, do: :binary.copy(unit, depth))
+    format_value(IO.iodata_to_binary(iodata), 0, indents, [])
+  end
+
+  defp format_value(<<>>, _depth, _pad, acc), do: acc
+
+  defp format_value(<<?", rest::binary>>, depth, indents, acc) do
+    case format_string(rest, []) do
+      {:ok, string, rest} ->
+        format_value(rest, depth, indents, [acc, ?", string, ?"])
+
+      :eof ->
+        raise ArgumentError,
+              "expected the encoder to return valid JSON, got an unterminated string"
+    end
+  end
+
+  defp format_value(<<?{, rest::binary>>, depth, indents, acc) do
+    case skip_whitespace(rest) do
+      <<?}, rest::binary>> -> format_value(rest, depth, indents, [acc, "{}"])
+      rest -> format_value(rest, depth + 1, indents, [acc, ?{, newline(depth + 1, indents)])
+    end
+  end
+
+  defp format_value(<<?[, rest::binary>>, depth, indents, acc) do
+    case skip_whitespace(rest) do
+      <<?], rest::binary>> -> format_value(rest, depth, indents, [acc, "[]"])
+      rest -> format_value(rest, depth + 1, indents, [acc, ?[, newline(depth + 1, indents)])
+    end
+  end
+
+  defp format_value(<<?}, rest::binary>>, depth, indents, acc) when depth > 0 do
+    format_value(rest, depth - 1, indents, [acc, newline(depth - 1, indents), ?}])
+  end
+
+  defp format_value(<<?], rest::binary>>, depth, indents, acc) when depth > 0 do
+    format_value(rest, depth - 1, indents, [acc, newline(depth - 1, indents), ?]])
+  end
+
+  defp format_value(<<?,, rest::binary>>, depth, indents, acc) do
+    format_value(rest, depth, indents, [acc, ?,, newline(depth, indents)])
+  end
+
+  defp format_value(<<?:, rest::binary>>, depth, indents, acc) do
+    format_value(rest, depth, indents, [acc, ": "])
+  end
+
+  defp format_value(<<char, rest::binary>>, depth, indents, acc) when char in ~c" \t\r\n" do
+    format_value(rest, depth, indents, acc)
+  end
+
+  defp format_value(<<char, _::binary>> = binary, depth, indents, acc)
+       when char not in @indent_specials do
+    length = plain_length(binary, 0)
+    rest = binary_part(binary, length, byte_size(binary) - length)
+    format_value(rest, depth, indents, [acc, binary_part(binary, 0, length)])
+  end
+
+  defp format_value(<<char, _::binary>>, 0, _pad, _acc) when char in [?}, ?]] do
+    raise ArgumentError,
+          "expected the encoder to return valid JSON, got unexpected #{<<char>>}"
+  end
+
+  defp plain_length(<<char, rest::binary>>, count) when char not in @indent_specials,
+    do: plain_length(rest, count + 1)
+
+  defp plain_length(<<_::binary>>, count), do: count
+
+  defp format_string(<<?\\, char, rest::binary>>, acc),
+    do: format_string(rest, [acc, ?\\, char])
+
+  defp format_string(<<?", rest::binary>>, acc), do: {:ok, acc, rest}
+  defp format_string(<<>>, _acc), do: :eof
+
+  defp format_string(binary, acc) do
+    length = string_length(binary, 0)
+    rest = binary_part(binary, length, byte_size(binary) - length)
+    format_string(rest, [acc, binary_part(binary, 0, length)])
+  end
+
+  defp string_length(<<char, rest::binary>>, count) when char not in [?", ?\\],
+    do: string_length(rest, count + 1)
+
+  defp string_length(<<_::binary>>, count), do: count
+
+  defp skip_whitespace(<<char, rest::binary>>) when char in ~c" \t\r\n",
+    do: skip_whitespace(rest)
+
+  defp skip_whitespace(binary), do: binary
+
+  defp newline(depth, indents) when depth < tuple_size(indents),
+    do: [?\n, elem(indents, depth)]
+
+  defp newline(depth, indents), do: [?\n, :binary.copy(elem(indents, 1), depth)]
+
   @doc """
   This is the default encode implementation passed to `encode!/1`.
 

lib/elixir/test/elixir/json_test.exs

@@ -18,6 +18,14 @@ defmodule JSONTest do
 
   doctest JSON
 
+  defmodule Malformed do
+    defstruct [:output]
+
+    defimpl JSON.Encoder do
+      def encode(%{output: output}, _encoder), do: output
+    end
+  end
+
   describe "encode" do
     test "atoms" do
       assert JSON.encode!([nil, false, true, :another]) == "[null,false,true,\"another\"]"
@@ -59,6 +67,98 @@ defmodule JSONTest do
     end
   end
 
+  describe "encode with pretty" do
+    test "indents nested members" do
+      assert JSON.encode!(%{a: [1, %{b: true}]}, pretty: true) ==
+               "{\n  \"a\": [\n    1,\n    {\n      \"b\": true\n    }\n  ]\n}"
+    end
+
+    test "keeps empty containers on a single line" do
+      assert JSON.encode!([[], %{}, [1]], pretty: true) == "[\n  [],\n  {},\n  [\n    1\n  ]\n]"
+    end
+
+    test "accepts a custom indent unit" do
+      assert JSON.encode!(%{a: 1}, pretty: "\t") == "{\n\t\"a\": 1\n}"
+      assert JSON.encode!(%{a: 1}, pretty: "    ") == "{\n    \"a\": 1\n}"
+      assert JSON.encode!(%{a: 1}, pretty: "") == "{\n\"a\": 1\n}"
+    end
+
+    test "is compact by default" do
+      assert JSON.encode!(%{a: [1]}) == "{\"a\":[1]}"
+      assert JSON.encode!(%{a: [1]}, pretty: false) == "{\"a\":[1]}"
+    end
+
+    test "preserves string contents" do
+      term = %{a: "1,2:3 {\"}]"}
+      assert term |> JSON.encode!(pretty: true) |> JSON.decode!() == %{"a" => "1,2:3 {\"}]"}
+      assert JSON.encode!(%{a: "1,2:3"}, pretty: true) == "{\n  \"a\": \"1,2:3\"\n}"
+    end
+
+    test "supports structs and calendar types" do
+      assert JSON.encode!(%{date: ~D[2024-01-01]}, pretty: true) ==
+               "{\n  \"date\": \"2024-01-01\"\n}"
+
+      assert JSON.encode!(%{nil: nil}, pretty: true) == "{\n  \"nil\": null\n}"
+
+      assert JSON.encode!(%{duration: Duration.new!(second: 1)}, pretty: true) ==
+               "{\n  \"duration\": \"PT1S\"\n}"
+    end
+
+    test "supports iodata" do
+      assert IO.iodata_to_binary(JSON.encode_to_iodata!(%{a: [1]}, pretty: true)) ==
+               "{\n  \"a\": [\n    1\n  ]\n}"
+    end
+
+    test "validates the second argument" do
+      assert_raise ArgumentError,
+                   "expected :pretty to be a boolean or a binary, got: 2",
+                   fn -> JSON.encode!(%{}, pretty: 2) end
+
+      assert_raise ArgumentError,
+                   "expected :pretty to be a binary of spaces and tabs, got: \"abc\"",
+                   fn -> JSON.encode!(%{}, pretty: "abc") end
+
+      assert_raise ArgumentError,
+                   "unknown options [:indent], expected only :pretty",
+                   fn -> JSON.encode!(%{}, indent: 4) end
+
+      assert_raise ArgumentError,
+                   "expected the second argument to be a function or a keyword list, got: [1, 2]",
+                   fn -> JSON.encode!(%{}, [1, 2]) end
+    end
+
+    test "accepts any indent width" do
+      assert JSON.encode!(%{a: 1}, pretty: String.duplicate(" ", 20)) ==
+               "{\n#{String.duplicate(" ", 20)}\"a\": 1\n}"
+    end
+
+    test "handles scalars and empty containers" do
+      assert JSON.encode!(nil, pretty: true) == "null"
+      assert JSON.encode!("abc", pretty: true) == "\"abc\""
+      assert JSON.encode!(%{}, pretty: true) == "{}"
+      assert JSON.encode!([], pretty: true) == "[]"
+    end
+
+    test "keeps escaped characters intact" do
+      assert JSON.encode!(%{a: "é"}, pretty: true) == "{\n  \"a\": \"é\"\n}"
+      assert JSON.encode!(%{a: "\u0000"}, pretty: true) == "{\n  \"a\": \"\\u0000\"\n}"
+    end
+
+    test "raises on malformed encoder output" do
+      assert_raise ArgumentError,
+                   "expected the encoder to return valid JSON, got unexpected }",
+                   fn -> JSON.encode!(struct(Malformed, output: "}]"), pretty: true) end
+
+      assert_raise ArgumentError,
+                   "expected the encoder to return valid JSON, got an unterminated string",
+                   fn -> JSON.encode!(struct(Malformed, output: ~s("abc)), pretty: true) end
+    end
+
+    test "keeps custom encoders working" do
+      assert JSON.encode!(%Token{value: 1}) == "[1]"
+    end
+  end
+
   describe "JSON.Encoder" do
     defp protocol_encode(term) do
       term