diff --git a/CHANGELOG.md b/CHANGELOG.md index ca63626477..7677608fba 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/lib/elixir/lib/json.ex b/lib/elixir/lib/json.ex index f4bb84a0bc..7feb49b19f 100644 --- a/lib/elixir/lib/json.ex +++ b/lib/elixir/lib/json.ex @@ -499,11 +499,15 @@ 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} > @@ -511,17 +515,40 @@ defmodule JSON do > 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. @@ -529,7 +556,8 @@ defmodule JSON do 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 @@ -537,12 +565,168 @@ defmodule JSON do 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?(<>) 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(<>, 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(<>, depth, indents, acc) do + case skip_whitespace(rest) do + <> -> format_value(rest, depth, indents, [acc, "{}"]) + rest -> format_value(rest, depth + 1, indents, [acc, ?{, newline(depth + 1, indents)]) + end + end + + defp format_value(<>, depth, indents, acc) do + case skip_whitespace(rest) do + <> -> format_value(rest, depth, indents, [acc, "[]"]) + rest -> format_value(rest, depth + 1, indents, [acc, ?[, newline(depth + 1, indents)]) + end + end + + defp format_value(<>, depth, indents, acc) when depth > 0 do + format_value(rest, depth - 1, indents, [acc, newline(depth - 1, indents), ?}]) + end + + defp format_value(<>, depth, indents, acc) when depth > 0 do + format_value(rest, depth - 1, indents, [acc, newline(depth - 1, indents), ?]]) + end + + defp format_value(<>, depth, indents, acc) do + format_value(rest, depth, indents, [acc, ?,, newline(depth, indents)]) + end + + defp format_value(<>, depth, indents, acc) do + format_value(rest, depth, indents, [acc, ": "]) + end + + defp format_value(<>, depth, indents, acc) when char in ~c" \t\r\n" do + format_value(rest, depth, indents, acc) + end + + defp format_value(<> = 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(<>, 0, _pad, _acc) when char in [?}, ?]] do + raise ArgumentError, + "expected the encoder to return valid JSON, got unexpected #{<>}" + end + + defp plain_length(<>, count) when char not in @indent_specials, + do: plain_length(rest, count + 1) + + defp plain_length(<<_::binary>>, count), do: count + + defp format_string(<>, acc), + do: format_string(rest, [acc, ?\\, char]) + + defp format_string(<>, 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(<>, count) when char not in [?", ?\\], + do: string_length(rest, count + 1) + + defp string_length(<<_::binary>>, count), do: count + + defp skip_whitespace(<>) 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`. diff --git a/lib/elixir/test/elixir/json_test.exs b/lib/elixir/test/elixir/json_test.exs index ce8d7fc582..fbec8a2382 100644 --- a/lib/elixir/test/elixir/json_test.exs +++ b/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