Meeseeks.Selector behaviour (Meeseeks v0.17.0) 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

Types

t()

Functions

combinator(selector)

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

filters(selector)

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

match(selector, node, document, context)

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.

validate(selector)

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

validate!(selector)

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

Callbacks

combinator(selector)

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

filters(selector)

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

match( selector, node, document, context )

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.

validate(selector)

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

t()

Specs

t() :: struct()

Link to this section Functions

combinator(selector)

Specs

combinator(t()) :: Meeseeks.Selector.Combinator.t() | nil

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

filters(selector)

Specs

filters(t()) :: [t()] | nil

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

match(selector, node, document, context)

Specs

match(
  t(),
  Meeseeks.Document.node_t(),
  Meeseeks.Document.t(),
  Meeseeks.Context.t()
) ::
  boolean() | {boolean(), Meeseeks.Context.t()}

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.

validate(selector)

Specs

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.

validate!(selector)

Specs

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

combinator(selector)

Specs

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

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

filters(selector)

Specs

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.

match( selector, node, document, context )

Specs

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.

validate(selector)

Specs

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.