Extractly (Extractly v0.5.1) View Source

Provide easy access to information inside the templates rendered by mix xtra

Link to this section Summary

Functions

Emits a comment including a message not to edit the created file, as it will be recreated from this template.

Returns docstring of a function Ex

Returns docstring of a macro

Returns docstring of a module

Returns the output of a mix task Ex

A convenience method to access this libraries version

Link to this section Functions

Link to this function

do_not_edit_warning(opts \\ [])

View Source

Emits a comment including a message not to edit the created file, as it will be recreated from this template.

It is a convenience to include this into your templates as follows

      <%= xtra.do_not_edit_warning %>

or I18n'ed

      <%= xtra.do_not_edit_warning, lang: :fr %>

If you are not generating html or markdown the comment can be parametrized

      <%= xtra.do_not_edit_warning, comment_start: "-- ", comment_end: "" %>

If you want to include the name of the source template use template: template option, so a call may be as complex as:

      <%= xtra.do_not_edit_warning, comment_start: "-- ", comment_end: "", template: template, lang: :it %>
Link to this function

functiondoc(name, opts \\ [])

View Source

Returns docstring of a function Ex:

  iex(1)> {:ok, lines} = Extractly.functiondoc("Extractly.moduledoc/2") |> hd()
  ...(1)> lines |> String.split("\n") |> Enum.take(3)
  ["  Returns docstring of a module", "", "  E.g. verbatim"]

We can also pass a list of functions to get their docs concatenated

  iex(2)> [{:ok, moduledoc}, {:error, message}] = Extractly.functiondoc(["Extractly.moduledoc/2", "Extactly.functiondoc/2"])
  ...(2)> moduledoc |> String.split("\n") |> Enum.take(4)
  [ "  Returns docstring of a module",
    "  E.g. verbatim",
    "",
    "      Extractly.moduledoc(\"Extractly\")"]
  ...(2)> message
  "Function doc for function Extactly.functiondoc/2 not found"

If all the functions are in the same module the following form can be used

  iex(3)> [{:ok, out}, _] = Extractly.functiondoc(["moduledoc/2", "functiondoc/2"], module: "Extractly")
  ...(3)> String.split(out, "\n") |> hd()
  "  Returns docstring of a module"

However it is convenient to add a markdown headline before each functiondoc, especially in these cases, it can be done by indicating the headline: level option

  iex(4)> [{:ok, moduledoc}, {:ok, functiondoc}] = Extractly.functiondoc(["moduledoc/2", "functiondoc/2"], module: "Extractly", headline: 2)
  ...(4)> moduledoc |> String.split("\n") |> Enum.take(3)
  [ "## Extractly.moduledoc/2",
    "",
    "  Returns docstring of a module"]
  ...(4)> functiondoc |> String.split("\n") |> Enum.take(3)
  [ "## Extractly.functiondoc/2",
    "",
    "  Returns docstring of a function"]

Often times we are interested by all public functiondocs...

  iex(5)> [{:ok, out}|_] = Extractly.functiondoc(:all, module: "Extractly", headline: 2)
  ...(5)> String.split(out, "\n") |> Enum.take(3)
  [ "## Extractly.do_not_edit_warning/1",
    "",
    "  Emits a comment including a message not to edit the created file, as it will be recreated from this template."]

We can specify a language to wrap indented code blocks into ```elixir\n...\n```

Here is an example

  iex(6)> [ok: doc] = Extractly.functiondoc("Extractly.functiondoc/2", wrap_code_blocks: "elixir")
  ...(6)> doc |> String.split("\n") |> Enum.take(10)
  [ "  Returns docstring of a function",
    "  Ex:",
    "",
    "```elixir",
    "      iex(1)> {:ok, lines} = Extractly.functiondoc(\"Extractly.moduledoc/2\") |> hd()",
    "      ...(1)> lines |> String.split(\"\\n\") |> Enum.take(3)",
    "      [\"  Returns docstring of a module\", \"\", \"  E.g. verbatim\"]",
    "```",
    "",
    "  We can also pass a list of functions to get their docs concatenated"]
Link to this function

macrodoc(name, opts \\ [])

View Source

Returns docstring of a macro

Link to this function

moduledoc(name, opts \\ [])

View Source

Returns docstring of a module

E.g. verbatim

  iex(7)> {:ok, doc} = Extractly.moduledoc("Extractly")
  ...(7)> doc
  "  Provide easy access to information inside the templates rendered by `mix xtra`\n"

We can use the same options as with functiondoc

  iex(8)> {:ok, doc} = Extractly.moduledoc("Extractly", headline: 2)
  ...(8)> doc |> String.split("\n") |> Enum.take(3)
  [
    "## Extractly", "", "  Provide easy access to information inside the templates rendered by `mix xtra`"
  ]

If we also want to use functiondoc :all, module: "Extractly" after the call of moduledoc we can include :all in the call of moduledoc, which will include function and macro docstrings as well

  iex(9)> [{:ok, moduledoc} | _] =
  ...(9)>   moduledoc("Extractly", headline: 3, include: :all)
  ...(9)> moduledoc
  "### Extractly\n\n  Provide easy access to information inside the templates rendered by `mix xtra`\n"

  iex(10)> [_, {:ok, first_functiondoc} | _] =
  ...(10)>   moduledoc("Extractly", headline: 3, include: :all)
  ...(10)> first_functiondoc |> String.split("\n") |> Enum.take(5)
  "### Extractly\n\n  Provide easy access to information inside the templates rendered by `mix xtra`\n"
  [
    "### Extractly.do_not_edit_warning/1",
    "",
    "  Emits a comment including a message not to edit the created file, as it will be recreated from this template.",
    "",
    "  It is a convenience to include this into your templates as follows"
  ]

Returns the output of a mix task Ex:

iex(11)> Extractly.task("cmd", ~W[echo 42])
"42\n"

iex(12)> try do
...(12)>   Extractly.task("xxx")
...(12)> rescue
...(12)>   e in RuntimeError -> e.message |> String.split("\n") |> hd()
...(12)> end
"The following output was produced wih error code 1"

A convenience method to access this libraries version