Meeseeks v0.13.1 Meeseeks.Selector behaviour View Source

Selector structs package some method of checking if a node matches some condition with an optional Meeseeks.Selector.Combinator, an optional list of filter selectors, and an optional method of validating the Selector.

For instance, the css selector ul > li contains a selector ul and the associated combinator > li.

In Meeseeks, this selector could be represented as:

alias Meeseeks.Selector.Combinator
alias Meeseeks.Selector.Element

%Element{
  selectors: [%Element.Tag{value: "ul"}],
  combinator: %Combinator.ChildElements{
    selector: %Element{selectors: [%Element.Tag{value: "li"}]}}}

Extending Meeseek's ability to query is as simple as defining a struct with the Meeseeks.Selector behaviour, and selectors provide a simple target to compile dsls to.

Examples

defmodule Selector.Text.Contains do
  use Meeseeks.Selector

  alias Meeseeks.Document

  defstruct value: ""

  def match(selector, %Document.Text{} = text, _document, _context) do
    String.contains?(text.content, selector.value)
  end

  def match(_selector, _node, _document, _context) do
    false
  end
end

Link to this section Summary

Functions

Returns the selector's combinator, or nil if it does not have one

Returns the selector's filter selectors, which may be an empty list, or nil if it does not have any

Checks if the selector matches the node in the context of the document. Can return a boolean or a tuple of a boolean and a context

Validates selector, returning {:ok, selector} if the selector is valid or {:error, %Meeseeks.Error{}} if it is not

Validates selector, returning the selector if it is valid or raising a Meeseeks.Error if it is not

Callbacks

Invoked to return the selector's combinator, or nil if it does not have one

Invoked to return the selector's filter selectors, which may be an empty list, or nil if it does not have any

Invoked in order to check if the selector matches the node in the context of the document. Can return a boolean or a tuple of a boolean and a context

Invoked to validate a selector, returning {:ok, selector} if the selector is valid or {:error, reason} if it is not

Link to this section Types

Link to this section Functions

Link to this function

combinator(selector) View Source
combinator(t()) :: Meeseeks.Selector.Combinator.t() | nil

Returns the selector's combinator, or nil if it does not have one.

Link to this function

filters(selector) View Source
filters(t()) :: [t()] | nil

Returns the selector's filter selectors, which may be an empty list, or nil if it does not have any.

Checks if the selector matches the node in the context of the document. Can return a boolean or a tuple of a boolean and a context.

Link to this function

validate(selector) View Source
validate(t()) :: {:ok, t()} | {:error, Meeseeks.Error.t()}

Validates selector, returning {:ok, selector} if the selector is valid or {:error, %Meeseeks.Error{}} if it is not.

Link to this function

validate!(selector) View Source
validate!(t()) :: t() | no_return()

Validates selector, returning the selector if it is valid or raising a Meeseeks.Error if it is not.

Link to this section Callbacks

Link to this callback

combinator(selector) View Source
combinator(selector :: t()) :: Meeseeks.Selector.Combinator.t() | nil

Invoked to return the selector's combinator, or nil if it does not have one.

Link to this callback

filters(selector) View Source
filters(selector :: t()) :: [t()] | nil

Invoked to return the selector's filter selectors, which may be an empty list, or nil if it does not have any.

Filters are selectors that are applied to a list of any nodes that match the selector before they are further walked with the selector's combinator if it has one, or accumulated if it does not.

Link to this callback

match(selector, node, document, context) View Source
match(
  selector :: t(),
  node :: Meeseeks.Document.node_t(),
  document :: Meeseeks.Document.t(),
  context :: Meeseeks.Context.t()
) :: boolean() | {boolean(), Meeseeks.Context.t()}

Invoked in order to check if the selector matches the node in the context of the document. Can return a boolean or a tuple of a boolean and a context.

Link to this callback

validate(selector) View Source
validate(selector :: t()) :: {:ok, t()} | {:error, String.t()}

Invoked to validate a selector, returning {:ok, selector} if the selector is valid or {:error, reason} if it is not.

Selector validation can be useful in instances where a selector has been built dynamically (parsed from a string, for instance).

See the Meeseeks.Selector.Element.PseudoClass.* selectors for examples.

Meeseek's selection process doesn't call validate anywhere, so there is no selection-time cost for providing a validator.