feat: extensions

Author: mhanberg

lib/mix/tasks/tableau.build.ex

@@ -19,6 +19,12 @@ defmodule Mix.Tasks.Tableau.Build do
     graph = Tableau.Graph.new(mods)
     File.mkdir_p!(out)
 
+    for module <- pre_write_extensions(mods) do
+      with :error <- module.run(graph, %{site: %{}}) do
+        Logger.error("#{inspect(module)} failed to run")
+      end
+    end
+
     for mod <- Graph.vertices(graph), {:ok, :page} == Tableau.Graph.Node.type(mod) do
       content = Tableau.Document.render(graph, mod, %{site: %{}})
       permalink = mod.__tableau_permalink__()
@@ -33,4 +39,12 @@ defmodule Mix.Tasks.Tableau.Build do
       File.cp_r!(@include_dir, out)
     end
   end
+
+  defp pre_write_extensions(modules) do
+    for {mod, _, _} <- modules,
+        mod = Module.concat([to_string(mod)]),
+        match?({:ok, :pre_build}, Tableau.Extension.type(mod)) do
+      mod
+    end
+  end
 end

lib/tableau/extension.ex

@@ -0,0 +1,66 @@
+defmodule Tableau.Extension do
+  @moduledoc ~s'''
+  A tableau extension.
+
+  An extension can be used to generate other kinds of content.
+
+  There are currently the following extension types:
+
+  - `:pre_build` - executed before tableau builds your site and writes anything to disk.
+
+  ```elixir
+  defmodule MySite.PostsExtension do
+    use Tableau.Extension, type: :pre_build
+
+    def run(_graph, _site) do
+      posts = Path.wildcard("_posts/**/*.md")
+
+      for post <- post do
+        post
+        |> Markdown.render()
+        |> then(&File.write(Path.join(Path.rootname(post), "index.html"), &1))
+      end
+
+      :ok
+    end
+  end
+  ```
+  '''
+
+  @typep extension_type :: :pre_build
+
+  @doc """
+  The extension entry point.
+
+  The function is passed the layout graph and a set of default assigns.
+
+  The graph is an instance of a [Graph.t](https://hexdocs.pm/libgraph/0.16.0/Graph.html#t:t/0) from the library `libgraph`.
+  """
+  @callback run(Graph.t(), map()) :: :ok | :error
+
+  defmacro __using__(opts) do
+    opts = Keyword.validate!(opts, [:type])
+
+    prelude =
+      quote do
+        def __tableau_extension_type__, do: unquote(opts)[:type]
+      end
+
+    postlude =
+      quote do
+        @behaviour unquote(__MODULE__)
+      end
+
+    [prelude, postlude]
+  end
+
+  @doc false
+  @spec type(module()) :: extension_type()
+  def type(module) do
+    if function_exported?(module, :__tableau_extension_type__, 0) do
+      {:ok, module.__tableau_extension_type__()}
+    else
+      :error
+    end
+  end
+end

test/mix/tasks/tableau.build_test.exs

@@ -1,3 +1,20 @@
+defmodule Mix.Tasks.Tableau.LogExtension do
+  use Tableau.Extension, type: :pre_build
+
+  def run(_graph, _site) do
+    IO.puts("hi!")
+    :ok
+  end
+end
+
+defmodule Mix.Tasks.Tableau.FailExtension do
+  use Tableau.Extension, type: :pre_build
+
+  def run(_graph, _site) do
+    :error
+  end
+end
+
 defmodule Mix.Tasks.Tableau.BuildTest.About do
   import Tableau.Strung
   require EEx
@@ -85,11 +102,18 @@ end
 defmodule Mix.Tasks.Tableau.BuildTest do
   use ExUnit.Case, async: true
 
+  import ExUnit.CaptureIO
+  import ExUnit.CaptureLog
+
   alias Mix.Tasks.Tableau.Build
 
   @tag :tmp_dir
   test "renders all pages", %{tmp_dir: out} do
-    _documents = Build.run(["--out", out])
+    assert capture_io(fn ->
+             assert capture_log(fn ->
+                      _documents = Build.run(["--out", out])
+                    end) =~ "FailExtension failed to run"
+           end) =~ "hi!"
 
     # # FIXME: this is due to the way the page modules are compiled in the tests
     # assert 8 == length(documents)