Meeseeks v0.3.1 Meeseeks.Selector behaviour

Selector structs package some method of checking if a node matches some condition with an (optional) Meeseeks.Selector.Combinator 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) do
    String.contains?(text.content, selector.value)
  end

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

Summary

Functions

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

Checks if the selector matches the node in the context of the document

Validates selector, returning {:ok, selector} if the selector is valid or {:error, reason} if it is not

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

Callbacks

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

Invoked in order to check if the selector matches the node in the context of the document

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

Types

t()
t() :: struct

Functions

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

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

match?(selector, node, document)

Checks if the selector matches the node in the context of the document.

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

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

validate!(selector)

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

Callbacks

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

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

match?(selector, node, document)
match?(selector :: t, node :: Meeseeks.Document.node_t, document :: Meeseeks.Document.t) :: boolean

Invoked in order to check if the selector matches the node in the context of the document.

validate(selector)
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.