Options
All
  • Public
  • Public/Protected
  • All
Menu

Class TopicSelectors

Create TopicSelector instances for use with other API methods.

Selectors are evaluated against topic paths. A topic path is a '/' separated string of parts, which map to the topic hierarchy. Each part is formed of one or more UTF characters, except '/'. Topic paths are absolute, and evaluated from the root of the current domain.

Example:

// Create a topic selector
var selector = diffusion.selectors.parse('?foo/bar/.*');

Hierarchy

  • TopicSelectors

Index

Properties

Methods

Properties

Prefix

Prefix: Prefix = Prefix

The Prefix enum

Type

Type: Type = Type

The Type enum

Methods

parse

  • Parse an expression to create a selector.

    This function can take any number of arguments. Each argument can be a string or a TopicSelector. Alternatively, an array of strings and TopicSelectors can be passed as a single argument.

    The following types of expression are supported. The type is determined by the first character of the expression.

    Path
    Path expressions begin with the character >. The remainder of the expression must be a valid topic path. A topic path is a '/' separated string of parts. Each part is formed of one or more UTF characters, except '/'.

    A PATH selector is returned that only selects the topic with the given path.

    Abbreviated Path Expressions

    In Diffusion 5.2, an alternative syntax for path expressions was added. An abbreviated path expression is any valid topic path (see above) that begins with a character other than one of #, ?, >, *, $, %, &, or <. This syntax allows most topic paths to be used directly as selector expressions which appears more natural.

    This method converts abbreviated path expressions to standard path expressions by prepending the > character. Thus a/b is interpreted as >a/b.

    parse("a/b").expression will return ">a/b".

    Split-path pattern
    Split-path pattern expressions begin with the character ?. The remainder of the expression is split into a list of regular expressions using the / character as a separator.

    A SPLIT_PATH_PATTERN selector is returned that selects topics for which each regular expression matches each part of the topic path at the corresponding level.

    Full-path pattern
    Full-path pattern expressions begin with the character *. The remainder of the pattern is a regular expression.

    A FULL_PATH_PATTERN selector is returned that selects topics for which the regular expression matches the complete topic path.

    Full-path patterns provide a lot of expressive power but should be used sparingly since the server can evaluate split-path patterns more efficiently.

    Selector sets are the preferred way to combine expressions. parse("a", "b") is equivalent to the full-path expression " *[a|b]", but can be evaluated more efficiently by the server.

    Selector set
    Selector set expressions begin with the character #. The remainder of the expression is a list of contained selectors, formatted as described below.

    A SELECTOR_SET selector is returned that selects topics that match any of the contained selectors.

    The contained selectors are formatted as follows. First, any selector sets are expanded to produce a full list of non-selector set expressions. Then the selector expressions are concatenated, separated by the separator ////. This separator has been chosen as it is not valid in a path, and is not a useful sequence in a pattern.

    Descendant pattern qualifiers

    Split-path and full-path pattern expressions can be further modified by appending / or //. These control the behaviour of the selector with respect to the descendants of the topics that match the pattern.

    • If the expression does not end with `/` or `//`, it selects only the topics that match the pattern.
    • If the expression ends with `/`, it selects only the descendants of the matching topics, excluding the matching topics.
    • If the expression ends with `//`, it selects the matching topics and all of their descendants.

    Regular expressions

    Any Java-style regular expression can be used in split-path and full-path patterns, with the following restrictions:

    • A regular expression may not be empty.
    • A regular expression used in split-path patterns may not contain the path separator /.
    • A regular expression used in full-path patterns may not contain the selector set separator ////.

    Regular expressions that break any of these restrictions would never match a topic path, so they make no practical difference.

    Examples

    Path expressions

    Path Matches alpha/beta? Matches alpha/beta/gamma?
    >alpha/beta yes no
    >alpha/beta/gamma no yes
    >beta no no
    >.*`/.*` no no
    >/alpha/beta/ yes no

    Abbreviated path expressions

    Path Matches alpha/beta? Matches alpha/beta/gamma?
    alpha/beta yes no
    alpha/beta/gamma no yes
    beta no no
    /alpha/beta/ yes no

    Split-path pattern expressions

    Path Matches alpha/beta? Matches alpha/beta/gamma?
    ?alpha/beta yes no
    ?alpha/beta/gamma no yes
    ?beta no no
    ?.* no no
    ?.*`/.*` yes no
    ?alpha/beta/ no yes
    ?alpha/beta// yes yes
    ?alpha/.*`//` yes yes

    Full-path pattern expressions

    Path Matches alpha/beta? Matches alpha/beta/gamma?
    *alpha/beta yes no
    *alpha/beta/gamma no yes
    *beta no no
    *.*beta yes no
    *.* yes yes
    *alpha/beta/ no yes
    *alpha/beta// yes yes

    Example:

    // Simple selector
    var selector = diffusion.selectors.parse(">a/b");

    Example:

    // Creating a selector set
    var selectorSet = diffusion.selectors.parse(">a", ">b");

    Parameters

    • expression: string | TopicSelector | Array<string | TopicSelector>

      the pattern expression(s). At least one valid selector has to be specified.

    • Rest ...args: Array<string | TopicSelector>

      additional pattern expressions

    Returns TopicSelector

    the topic selector. If multiple expressions are provided, this will return a SELECTOR_SET that will match if any of the * provided selectors match.