improvement: add new {:function, ... type

closes #105

Author: zachdaniel

lib/spark/elixir_sense/plugin.ex

@@ -956,6 +956,26 @@ defmodule Spark.ElixirSense.Plugin do
         end
         """
 
+      match?({:function, _}, config[:type]) ->
+        {:function, opts} = config[:type]
+        arity = opts[:arity] || length(opts[:args] || [])
+
+        if arity == 0 do
+          """
+          fn ->
+            ${0:body}
+          end
+          """
+        else
+          args = Enum.map_join(0..(arity - 1), ", ", &"arg#{&1 + 1}")
+
+          """
+          fn #{args} ->
+            ${#{arity}:body}
+          end
+          """
+        end
+
       match?(:map, config[:type]) || match?({:map, _, _}, config[:type]) ->
         "%{${1:key} => ${2:value}}"
 

lib/spark/info_generator.ex

@@ -350,6 +350,25 @@ defmodule Spark.InfoGenerator do
     [{:->, [], [args, {:any, [], Elixir}]}]
   end
 
+  def spec_for_type({:function, opts}, _opts) do
+    args =
+      if arg_types = opts[:args] do
+        Enum.map(arg_types, &spec_for_type(&1, []))
+      else
+        arity = opts[:arity] || 0
+        List.duplicate({:any, [], Elixir}, arity)
+      end
+
+    returns =
+      if return_type = opts[:returns] do
+        spec_for_type(return_type, [])
+      else
+        {:any, [], Elixir}
+      end
+
+    [{:->, [], [args, returns]}]
+  end
+
   # Treat `and` like `or` because any of the input types is valid.
   def spec_for_type({:and, subtypes}, opts), do: spec_for_type({:or, subtypes}, opts)
 

lib/spark/options/docs.ex

@@ -179,6 +179,7 @@ defmodule Spark.Options.Docs do
   defp get_raw_type_str(:fun), do: "function"
   defp get_raw_type_str({:fun, _}), do: "function"
   defp get_raw_type_str({:fun, _, _}), do: "function"
+  defp get_raw_type_str({:function, _}), do: "function"
 
   defp get_raw_type_str({:wrap_list, subtype}) do
     if subtype_str = get_raw_type_str(subtype), do: "one or a list of #{subtype_str}"
@@ -291,6 +292,28 @@ defmodule Spark.Options.Docs do
     "(#{args} -> any)"
   end
 
+  def dsl_docs_type({:function, opts}) when is_list(opts) do
+    args = opts[:args]
+    returns = opts[:returns]
+    arity = opts[:arity] || (args && length(args))
+
+    cond do
+      args && returns ->
+        args_str = Enum.map_join(args, ", ", &dsl_docs_type/1)
+        "(#{args_str} -> #{dsl_docs_type(returns)})"
+
+      args ->
+        args_str = Enum.map_join(args, ", ", &dsl_docs_type/1)
+        "(#{args_str} -> any)"
+
+      arity ->
+        dsl_docs_type({:fun, arity})
+
+      true ->
+        "(... -> any)"
+    end
+  end
+
   def dsl_docs_type({:fun, args}) when is_list(args) do
     args =
       Enum.map_join(args, ", ", &dsl_docs_type/1)
@@ -443,6 +466,18 @@ defmodule Spark.Options.Docs do
       {:fun, arg_types, return_type} ->
         function_spec(arg_types, return_type)
 
+      {:function, opts} ->
+        args = opts[:args]
+        returns = opts[:returns]
+        arity = opts[:arity] || (args && length(args))
+
+        cond do
+          args && returns -> function_spec(args, returns)
+          args -> function_spec(args)
+          arity -> function_spec(arity)
+          true -> quote(do: (... -> term()))
+        end
+
       {:in, %Range{first: first, last: last} = range} ->
         if Map.get(range, :step) in [nil, 1] do
           quote(do: unquote(first)..unquote(last))

lib/spark/options/options.ex

@@ -205,6 +205,12 @@ defmodule Spark.Options do
 
     * `{:fun, args_types, return_type}` - A function with the specified arguments and return type.
 
+    * `{:function, arity: n, args: [...], returns: type}` - A function type with named options. All keys are optional.
+      `:arity` specifies the arity, `:args` specifies argument types, and `:returns` specifies the return type.
+      For example, `{:function, args: [:map], returns: :string}` is a function taking a map and returning a string.
+      This format is preferred over the 3-tuple `{:fun, args, return_type}` as it is a 2-tuple and avoids
+      AST escaping issues when used in nested type positions.
+
     * `{:in, choices}` or `{:one_of, choices}` - A value that is a member of one of the `choices`. `choices`
       should be a list of terms or a `Range`. The value is an element in said
       list of terms, that is, `value in choices` is `true`.
@@ -1220,6 +1226,11 @@ defmodule Spark.Options do
     )
   end
 
+  defp validate_type({:function, opts}, key, value) when is_list(opts) do
+    arity = opts[:arity] || length(opts[:args] || [])
+    validate_type({:fun, arity}, key, value)
+  end
+
   defp validate_type(nil, _key, nil), do: {:ok, nil}
 
   defp validate_type(nil, key, value),
@@ -1707,7 +1718,8 @@ defmodule Spark.Options do
           "{:list, subtype}",
           "{:tuple, list_of_subtypes}",
           "{:map, key_type, value_type}",
-          "{:struct, struct_name}"
+          "{:struct, struct_name}",
+          "{:function, arity: n, args: [...], returns: type}"
         ]
 
     Enum.join(types, ", ")
@@ -1738,17 +1750,7 @@ defmodule Spark.Options do
   end
 
   def validate_type({:fun, list}) when is_list(list) do
-    Enum.reduce_while(list, {:ok, list}, fn
-      {type, _keys}, acc
-      when type in [:keyword_list, :non_empty_keyword_list, :map] ->
-        {:cont, acc}
-
-      subtype, acc ->
-        case validate_type(subtype) do
-          {:ok, _value} -> {:cont, acc}
-          {:error, reason} -> {:halt, {:error, "invalid type given to :fun type: #{reason}"}}
-        end
-    end)
+    validate_fun_arg_types(list)
   end
 
   def validate_type({:fun, list, returns}) when is_list(list) do
@@ -1778,6 +1780,35 @@ defmodule Spark.Options do
     end
   end
 
+  def validate_type({:function, opts}) when is_list(opts) do
+    arity = opts[:arity]
+    args = opts[:args]
+    returns = opts[:returns]
+
+    extra_keys = Keyword.keys(opts) -- [:arity, :args, :returns]
+
+    cond do
+      extra_keys != [] ->
+        {:error,
+         "invalid keys #{inspect(extra_keys)} in function type. Only :arity, :args, and :returns are supported"}
+
+      arity != nil && (!is_integer(arity) || arity < 0) ->
+        {:error, "expected :arity to be a non-negative integer, got: #{inspect(arity)}"}
+
+      args != nil && !is_list(args) ->
+        {:error, "expected :args to be a list of types, got: #{inspect(args)}"}
+
+      arity != nil && args != nil && length(args) != arity ->
+        {:error, "expected :args length (#{length(args)}) to match :arity (#{arity})"}
+
+      true ->
+        with {:ok, _} <- validate_fun_args(args || []),
+             {:ok, _} <- validate_fun_returns(returns) do
+          {:ok, {:function, opts}}
+        end
+    end
+  end
+
   def validate_type({:spark_type, module, builtin_function} = type)
       when is_atom(module) and is_atom(builtin_function) do
     {:ok, type}
@@ -1950,6 +1981,43 @@ defmodule Spark.Options do
     {:error, "unknown type #{inspect(value)}.\n\nAvailable types: #{available_types()}"}
   end
 
+  defp validate_fun_arg_types(list) do
+    Enum.reduce_while(list, {:ok, list}, fn
+      {type, _keys}, acc
+      when type in [:keyword_list, :non_empty_keyword_list, :map] ->
+        {:cont, acc}
+
+      subtype, acc ->
+        case validate_type(subtype) do
+          {:ok, _value} -> {:cont, acc}
+          {:error, reason} -> {:halt, {:error, "invalid type given to :fun type: #{reason}"}}
+        end
+    end)
+  end
+
+  defp validate_fun_args(args) do
+    Enum.reduce_while(args, {:ok, args}, fn
+      {type, _keys}, acc
+      when type in [:keyword_list, :non_empty_keyword_list, :map] ->
+        {:cont, acc}
+
+      subtype, acc ->
+        case validate_type(subtype) do
+          {:ok, _value} -> {:cont, acc}
+          {:error, reason} -> {:halt, {:error, "invalid type given to :fun type: #{reason}"}}
+        end
+    end)
+  end
+
+  defp validate_fun_returns(nil), do: {:ok, nil}
+
+  defp validate_fun_returns(returns) do
+    case validate_type(returns) do
+      {:ok, _} -> {:ok, returns}
+      {:error, error} -> {:error, "invalid return type given to :fun type: #{error}"}
+    end
+  end
+
   defp error_tuple(key, value, message) do
     {:error, %ValidationError{key: key, message: message, value: value}}
   end

test/info_generator_test.exs

@@ -20,4 +20,142 @@ defmodule Spark.InfoGeneratorTest do
       assert %{} = Info.my_section_map_option!(Resource)
     end
   end
+
+  describe "{:function, ...} type" do
+    test "compiles and generates info functions for {:function, args: [...], returns: ...}" do
+      assert :error = Info.my_section_callback(Resource)
+    end
+
+    test "compiles when used inside {:or, ...}" do
+      assert :error = Info.my_section_handler(Resource)
+    end
+  end
+
+  describe "{:function, ...} type validation" do
+    test "accepts args with returns" do
+      assert {:ok, {:function, args: [:map], returns: :string}} =
+               Spark.Options.validate_type({:function, args: [:map], returns: :string})
+    end
+
+    test "accepts arity only" do
+      assert {:ok, {:function, arity: 2}} =
+               Spark.Options.validate_type({:function, arity: 2})
+    end
+
+    test "accepts args only" do
+      assert {:ok, {:function, args: [:string, :integer]}} =
+               Spark.Options.validate_type({:function, args: [:string, :integer]})
+    end
+
+    test "accepts arity with matching args" do
+      assert {:ok, {:function, arity: 2, args: [:map, :string]}} =
+               Spark.Options.validate_type({:function, arity: 2, args: [:map, :string]})
+    end
+
+    test "accepts returns only" do
+      assert {:ok, {:function, returns: :string}} =
+               Spark.Options.validate_type({:function, returns: :string})
+    end
+
+    test "rejects mismatched arity and args" do
+      assert {:error, message} =
+               Spark.Options.validate_type({:function, arity: 3, args: [:map, :string]})
+
+      assert message =~ "args length"
+    end
+
+    test "rejects invalid keys" do
+      assert {:error, message} =
+               Spark.Options.validate_type({:function, foo: :bar})
+
+      assert message =~ "invalid keys"
+    end
+
+    test "rejects negative arity" do
+      assert {:error, message} =
+               Spark.Options.validate_type({:function, arity: -1})
+
+      assert message =~ "non-negative integer"
+    end
+
+    test "rejects non-integer arity" do
+      assert {:error, message} =
+               Spark.Options.validate_type({:function, arity: :two})
+
+      assert message =~ "non-negative integer"
+    end
+
+    test "rejects non-list args" do
+      assert {:error, message} =
+               Spark.Options.validate_type({:function, args: :map})
+
+      assert message =~ "list of types"
+    end
+
+    test "validates nested arg types" do
+      assert {:error, _} =
+               Spark.Options.validate_type({:function, args: [:not_a_real_type]})
+    end
+
+    test "validates nested return type" do
+      assert {:error, _} =
+               Spark.Options.validate_type({:function, returns: :not_a_real_type})
+    end
+  end
+
+  describe "{:function, ...} runtime validation" do
+    test "accepts a function matching arity from args" do
+      schema = [cb: [type: {:function, args: [:map], returns: :string}]]
+      assert {:ok, _} = Spark.Options.validate([cb: fn _ -> "ok" end], schema)
+    end
+
+    test "accepts a function matching explicit arity" do
+      schema = [cb: [type: {:function, arity: 2}]]
+      assert {:ok, _} = Spark.Options.validate([cb: fn _, _ -> :ok end], schema)
+    end
+
+    test "rejects a function with wrong arity" do
+      schema = [cb: [type: {:function, args: [:map], returns: :string}]]
+      assert {:error, _} = Spark.Options.validate([cb: fn -> "ok" end], schema)
+    end
+
+    test "rejects non-function values" do
+      schema = [cb: [type: {:function, args: [:map]}]]
+      assert {:error, _} = Spark.Options.validate([cb: "not_a_function"], schema)
+    end
+
+    test "works inside {:or, ...} at runtime" do
+      schema = [cb: [type: {:or, [:string, {:function, args: [:map]}]}]]
+      assert {:ok, _} = Spark.Options.validate([cb: "a string"], schema)
+      assert {:ok, _} = Spark.Options.validate([cb: fn _ -> :ok end], schema)
+      assert {:error, _} = Spark.Options.validate([cb: 42], schema)
+    end
+  end
+
+  describe "{:function, ...} documentation" do
+    test "dsl_docs_type with args and returns" do
+      assert "(map -> String.t)" =
+               Spark.Options.Docs.dsl_docs_type({:function, args: [:map], returns: :string})
+    end
+
+    test "dsl_docs_type with args only" do
+      assert "(map, String.t -> any)" =
+               Spark.Options.Docs.dsl_docs_type({:function, args: [:map, :string]})
+    end
+
+    test "dsl_docs_type with arity only" do
+      assert "(any, any -> any)" =
+               Spark.Options.Docs.dsl_docs_type({:function, arity: 2})
+    end
+
+    test "dsl_docs_type with zero arity" do
+      assert "(-> any)" =
+               Spark.Options.Docs.dsl_docs_type({:function, arity: 0})
+    end
+
+    test "dsl_docs_type with returns only" do
+      assert "(... -> any)" =
+               Spark.Options.Docs.dsl_docs_type({:function, returns: :string})
+    end
+  end
 end