Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
198 changes: 191 additions & 7 deletions lib/elixir/lib/json.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
100 changes: 100 additions & 0 deletions lib/elixir/test/elixir/json_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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\"]"
Expand Down Expand Up @@ -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
Expand Down