Extractly (Extractly v0.6.1)
View Source Provide easy access to information inside the templates rendered by mix xtra
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
Extract Table Of Contents from a markdown document
A convenience method to access this libraries version
Functions
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 %>
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), message}
{
[ " Returns docstring of a module",
"",
" E.g. verbatim", ""],
"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)> {
...(4)> moduledoc |> String.split("\n") |> Enum.take(3),
...(4)> functiondoc |> String.split("\n") |> Enum.take(3)
...(4)> }
{
[ "## Extractly.moduledoc/2",
"",
" Returns docstring of a module"],
[ "## 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"]
Returns docstring of a macro
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.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(14)> Extractly.task("cmd", ~W[echo 42])
"42\n"
iex(15)> try do
...(15)> Extractly.task("xxx")
...(15)> rescue
...(15)> e in RuntimeError -> e.message |> String.split("\n") |> hd()
...(15)> end
"The following output was produced wih error code 1"
Extract Table Of Contents from a markdown document
The files used for the following doctest can be found here
iex(11)> lines = [
...(11)> "## Usage",
...(11)> "### API",
...(11)> "#### EarmarkParser.as_ast/2",
...(11)> "### Support",
...(11)> ]
...(11)> toc(lines, gh_links: true)
{:ok, [
"- [Usage](#usage)",
" - [API](#api)",
" - [EarmarkParser.as_ast/2](#earmarkparseras_ast2)",
" - [Support](#support)",
]}
But if you do not want links
iex(12)> lines = [
...(12)> "## Usage",
...(12)> "### API",
...(12)> "#### EarmarkParser.as_ast/2",
...(12)> "### Support",
...(12)> ]
...(12)> toc(lines)
{:ok, [
"- Usage",
" - API",
" - EarmarkParser.as_ast/2",
" - Support",
]}
In case of bad options an error tuple is returned (no utf8 encoded input should ever result in an error_tuple
iex(13)> lines = [] # options are checked even if input is empty
...(13)> toc(lines, no_such_option: "x")
{:error, "Unsupported option no_such_option"}
A more detailed description can be found in Extractly.Toc
's docstrings
A convenience method to access this libraries version