Merge pull request #51 from mediapress-ltd/master

joshnuss · web-flow · commit c684516d0189 · 2021-06-16T15:35:23.000-04:00
Add `generate_iodata` and performance improvements
diff --git a/.github/workflows/elixir.yml b/.github/workflows/elixir.yml
@@ -8,16 +8,16 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        otp: ['22.3.4']
+        otp: ['22.3']
         elixir: ['1.11.2', '1.10.4', '1.9.4', '1.8.2', '1.7.4', '1.6.6']
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-elixir@v1
+      - uses: erlef/setup-beam@v1
         with:
           otp-version: ${{matrix.otp}}
           elixir-version: ${{matrix.elixir}}
       - run: mix deps.get
       - run: mix compile --warnings-as-errors
       - run: mix format --check-formatted
       - run: mix credo --strict
-      - run: mix test
+      - run: mix test
diff --git a/README.md b/README.md
@@ -185,6 +185,49 @@ Outputs.
 <oldschool/>
 ```
 
+### Using `iodata()` directly
+
+While by default, output from `generate/2` is converted to `binary()`, you can use `generate_iodata/2` to skip this conversion. This can be convenient if you're using `IO.binwrite/2` on a `:raw` IO device, as these APIs can work with `iodata()` directly, leading to some performance gains.
+
+In some scenarios, it may be beneficial to generate part of your XML upfront, for instance when generating a `sitemap.xml`, you may have shared fields for `author`. Instead of generating this each time, you could do the following:
+
+```elixir
+import XmlBuilder
+
+entries = [%{title: "Test", url: "https://example.org/"}]
+
+# Generate static author data upfront
+author = generate_iodata(element(:author, [
+  element(:name, "John Doe"),
+  element(:uri, "https://example.org/")
+]))
+
+file = File.open!("path/to/file", [:raw])
+
+for entry <- entries do
+  iodata =
+    generate_iodata(element(:entry, [
+      # Reuse the static pre-generated fields as-is
+      {:iodata, author},
+
+      # Dynamic elements are generated for each entry
+      element(:title, entry.title),
+      element(:link, entry.url)
+    ]))
+
+  IO.binwrite(file, iodata)
+end
+```
+
+### Escaping
+
+XmlBuilder offers 3 distinct ways to control how content of tags is escaped and handled:
+
+- By default, any content is escaped, replacing reserved characters (`& " ' < >`) with their equivalent entity (`&amp;` etc.)
+- If content is wrapped in `{:cdata, cdata}`, the content in `cdata` is wrapped with `<![CDATA[...]]>`, and not escaped. You should make sure the content itself does not contain `]]>`.
+- If content is wrapped in `{:safe, data}`, the content in `data` is not escaped, but will be stringified if not a bitstring. Use this option carefully. It may be useful when data is guaranteed to be safe (numeric data).
+- If content is wrapped in `{:iodata, data}`, either in the top level or within a list, the `data` is used as `iodata()`, and will not be escaped, indented or stringified. An example of this can be seen in the "Using `iodata()` directly" example above.
+
 ### Standalone
 
 Should you need `standalone="yes"` in the XML declaration, you can pass `standalone: true` as option to the `generate/2` call.
diff --git a/lib/xml_builder.ex b/lib/xml_builder.ex
@@ -25,11 +25,11 @@ defmodule XmlBuilder do
   end
 
   defmacrop is_blank_list(list) do
-    quote do: is_nil(unquote(list)) or (is_list(unquote(list)) and unquote(list) == [])
+    quote do: is_nil(unquote(list)) or unquote(list) == []
   end
 
   defmacrop is_blank_map(map) do
-    quote do: is_nil(unquote(map)) or (is_map(unquote(map)) and map_size(unquote(map)) == 0)
+    quote do: is_nil(unquote(map)) or unquote(map) == %{}
   end
 
   @doc """
@@ -103,6 +103,9 @@ defmodule XmlBuilder do
   def element(name) when is_bitstring(name),
     do: element({nil, nil, name})
 
+  def element({:iodata, _data} = iodata),
+    do: element({nil, nil, iodata})
+
   def element(name) when is_bitstring(name) or is_atom(name),
     do: element({name})
 
@@ -211,7 +214,17 @@ defmodule XmlBuilder do
       ~s|<?xml version="1.0" encoding="ISO-8859-1"?>|
   """
   def generate(any, options \\ []),
-    do: format(any, 0, options) |> IO.chardata_to_string()
+    do: format(any, 0, options) |> IO.iodata_to_binary()
+
+  @doc """
+  Similar to `generate/2`, but returns `iodata` instead of a `binary`.
+
+  ## Examples
+
+    iex> XmlBuilder.generate_iodata(XmlBuilder.element(:person))
+    ["", '<', "person", '/>']
+  """
+  def generate_iodata(any, options \\ []), do: format(any, 0, options)
 
   defp format(:xml_decl, 0, options) do
     encoding = Keyword.get(options, :encoding, "UTF-8")
@@ -223,7 +236,7 @@ defmodule XmlBuilder do
         nil -> ""
       end
 
-    ~s|<?xml version="1.0" encoding="#{encoding}"#{standalone}?>|
+    ['<?xml version="1.0" encoding="', to_string(encoding), ?", standalone, '?>']
   end
 
   defp format({:doctype, {:system, name, system}}, 0, _options),
@@ -245,12 +258,14 @@ defmodule XmlBuilder do
 
   defp format(list, level, options) when is_list(list) do
     formatter = formatter(options)
-    list |> Enum.map(&format(&1, level, options)) |> Enum.intersperse(formatter.line_break())
+    map_intersperse(list, formatter.line_break(), &format(&1, level, options))
   end
 
   defp format({nil, nil, name}, level, options) when is_bitstring(name),
     do: [indent(level, options), to_string(name)]
 
+  defp format({nil, nil, {:iodata, iodata}}, _level, _options), do: iodata
+
   defp format({name, attrs, content}, level, options)
        when is_blank_attrs(attrs) and is_blank_list(content),
        do: [indent(level, options), '<', to_string(name), '/>']
@@ -345,15 +360,15 @@ defmodule XmlBuilder do
 
   defp format_content(children, level, options) when is_list(children) do
     format_char = formatter(options).line_break()
-    [format_char, Enum.map_join(children, format_char, &format(&1, level, options))]
+    [format_char, map_intersperse(children, format_char, &format(&1, level, options))]
   end
 
   defp format_content(content, _level, _options),
     do: escape(content)
 
   defp format_attributes(attrs),
     do:
-      Enum.map_join(attrs, " ", fn {name, value} ->
+      map_intersperse(attrs, " ", fn {name, value} ->
         [to_string(name), '=', quote_attribute_value(value)]
       end)
 
@@ -366,22 +381,17 @@ defmodule XmlBuilder do
     do: quote_attribute_value(to_string(val))
 
   defp quote_attribute_value(val) do
-    double = String.contains?(val, ~s|"|)
-    single = String.contains?(val, "'")
-    escaped = escape(val)
-
-    cond do
-      double && single ->
-        escaped |> String.replace("\"", "&quot;") |> quote_attribute_value
+    escape? = String.contains?(val, ["\"", "&", "<"])
 
-      double ->
-        "'#{escaped}'"
-
-      true ->
-        ~s|"#{escaped}"|
+    case escape? do
+      true -> [?", escape(val), ?"]
+      false -> [?", val, ?"]
     end
   end
 
+  defp escape({:iodata, iodata}), do: iodata
+  defp escape({:safe, data}) when is_bitstring(data), do: data
+  defp escape({:safe, data}), do: to_string(data)
   defp escape({:cdata, data}), do: ["<![CDATA[", data, "]]>"]
 
   defp escape(data) when is_binary(data),
@@ -404,4 +414,14 @@ defmodule XmlBuilder do
   defp escape_entity(<<"quot;"::utf8, rest::binary>>), do: ["&quot;" | escape_string(rest)]
   defp escape_entity(<<"apos;"::utf8, rest::binary>>), do: ["&apos;" | escape_string(rest)]
   defp escape_entity(rest), do: ["&amp;" | escape_string(rest)]
+
+  # Remove when support for Elixir <v1.10 is dropped
+  @compile {:inline, map_intersperse: 3}
+  if function_exported?(Enum, :map_intersperse, 3) do
+    defp map_intersperse(enumerable, separator, mapper),
+      do: Enum.map_intersperse(enumerable, separator, mapper)
+  else
+    defp map_intersperse(enumerable, separator, mapper),
+      do: enumerable |> Enum.map(mapper) |> Enum.intersperse(separator)
+  end
 end
diff --git a/test/xml_builder_test.exs b/test/xml_builder_test.exs
