Meeseeks

v0.11.0

Meeseeks v0.11.0 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

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

Link to this type

t() View Source 
t() :: struct()

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.

Link to this function

match(selector, node, document, context) View Source 
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.

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.