@spec block_end(String.t(), non_neg_integer()) :: non_neg_integer()

Return the position of the first byte of the last line of the block that the line at a position opens

The block holds each later line with more indent than the start line, and blank lines between them. The first later line with the same indent or less ends the block. That line is the last line of the block when it starts with }, ], ) or end, as in most languages. Otherwise the last line of the block is the last line with more indent, as in Python. A start line with no line of more indent after it is a block of one line, so the block does not take the closing line of a block around it.

iex> code = "if (a) {\n  if (b) {\n    c();\n  }\n}\nd();\n"
iex> Expresso.Element.Code.block_end(code, 0)
33
iex> Expresso.Element.Code.block_end(code, 9)
29
iex> Expresso.Element.Code.block_end("def f():\n    a\n\n    b\nc\n", 0)
16
iex> Expresso.Element.Code.block_end("a\nb\n", 0)
0

@spec build(t()) :: {:ok, t()} | {:error, String.t()}

Read the source, and make the groups of lines from the reveal option

check/1 calls this function for an element with text, and Expresso.PathTransformer calls it for an element with src, after it joins the path to the root option of the deck. With src, the function reads the file, puts the lines of the lines option into text, and puts the number of the first line into first. A lines option with from and to gives its range from the text of the file. Then it puts one Expresso.Element.Lines child into elements for each item of the reveal option, in order.

The function gives an error for:

• an element with both text and src, or with neither,
• a lines option without src,
• a file that it cannot read, or a range that goes past the end of the file,
• a start text that is not in the file or that is in it more than one time, and an end text that is not in the file after the start text,
• a line number of reveal that the element does not show. Such a group shows nothing, and it takes one step of the slide, so the deck gets a step at which nothing changes,
• a whole_first option without highlight,
• an element with both reveal and highlight, a highlight with dim, a line number of highlight that the element does not show, and a line that is in two groups of highlight.

@spec check(t()) :: {:ok, t()} | {:error, String.t()}

Check the options of a code element, and build an element with text

The transform of the code entity calls this function after it makes the struct, in the DSL and in Expresso.Builder. An element with src keeps its file until Expresso.PathTransformer runs, because the root option of the deck can change the path. The function checks each option that needs no file, so the error of such an option comes from the entity.

@spec get_assigns(t()) :: map()

Make the assigns of the render function from the struct

The key overlay holds the attributes of the overlay contract, from Expresso.Overlay.Render.attributes/1. The key lines holds one triple for each line: the number of the line, the HTML of the line and the overlay attributes of its group. The key numbers holds the width of the widest number in characters, or nil for an element without the line_numbers option.

@spec lead(t()) :: 0 | 1

Return the number of steps that a code element takes before its groups

The whole_first option gives one step, and the counter of the slide then goes one further before the first group takes its step.

@spec lines(term()) ::
  {:ok, Range.t() | keyword(String.t() | :block)} | {:error, String.t()}

Make sure that a lines option is a range of line numbers, or a start text and an end text

This function is the custom type of the option. A range starts at 1 or more, and it has a step of 1. A keyword list has the key from, the key to or both, one time each, and each value is a text that is not empty. The value of to can also be :block.

iex> Expresso.Element.Code.lines(10..24)
{:ok, 10..24}

iex> Expresso.Element.Code.lines(from: "def start(", to: "end")
{:ok, [from: "def start(", to: "end"]}

iex> Expresso.Element.Code.lines(from: "def start(", to: :block)
{:ok, [from: "def start(", to: :block]}

@spec render(map()) :: Phoenix.HTML.safe()

Make the HTML of a code element

Each line goes into a span element with the class line, and the line break is inside the fragment of the line. With the line_numbers option, the number of the line goes into a span element with the class line-number at the start of the line. A screen reader does not read the number, and a copy of the text does not take it. The code element sets --line-number-width, so each number takes the width of the widest one.

@spec reveal(term()) :: {:ok, [pos_integer() | Range.t()]} | {:error, String.t()}

Make sure that a reveal option is a list of line numbers, ranges and texts

This function is the custom type of the options reveal and highlight. Each item is a positive integer, a range with a step of 1, or a keyword list with from and an optional to, each a text that is not empty, or to: :block. An item can also be [each: text], a token group, and build/1 refuses it in reveal.

iex> Expresso.Element.Code.reveal([1..2, [from: "let hit", to: "return hit;"], 7])
{:ok, [1..2, [from: "let hit", to: "return hit;"], 7]}

@spec spotlight(Expresso.Deck.t()) :: Expresso.Deck.t()

Dim the lines of each code element that are not in focus

A code element with the highlight option has one group of lines for each item of the option, and one more group for the lines in no item. The transformer gives each group of an item its step, in the on entity with the state highlight. This function gives each other group of the element an on entity with the state dim at that step. The other lines then dim, and the group in focus shows in full.

Expresso.Renderer calls this function before Expresso.Overlay.Render.identify/1, because a group needs an identity for its on entities.