package obus

  1. Overview
  2. Docs

Module OBus_matchSource

Matching rules

Rules
Sourcetype argument_filter =
  1. | AF_string of string
    (*

    AF_string str matches any string argument which is equal to str

    *)
  2. | AF_string_path of string
    (*

    AF_string_path path matches any string or object-path argument arg such that one of the following conditions hold:

    • arg is equal to path
    • path ends with '/' and is a prefix of arg
    • arg ends with '/' and is a prefix of path
    *)
  3. | AF_namespace of string
    (*

    AF_namespace namespace matches any string argument arg such that arg is a bus or interface name in the namespace of namespace. For example AF_namespace "a.b.c" matches any string of the form "a.b.c", "a.b.c.foo", "a.b.c.foo.bar", ...

    *)

Type of an argument filter. Argument filters are used in match rules to match message arguments.

Sourcetype arguments = private (int * argument_filter) list

Type of lists of argument filters. The private type ensures that such lists are always sorted by argument number, do not contain duplicates and indexes are in the range 0..63..

Sourceval make_arguments : (int * argument_filter) list -> arguments

Creates an arguments filter from a list of filters. It raises Invalid_argument if one of the argument filters use a number outside of the range 1..63

Sourceval cast_arguments : arguments -> (int * argument_filter) list

Returns the list of filters for the given arguments filter.

Sourcetype rule = {
  1. typ : [ `Signal | `Error | `Method_call | `Method_return ] option;
  2. sender : OBus_name.bus;
  3. interface : OBus_name.interface;
  4. member : OBus_name.member;
  5. path : OBus_path.t option;
  6. destination : OBus_name.bus;
  7. arguments : arguments;
  8. eavesdrop : bool option;
}

Type of a rule used to match a message

Rule projections
Sourceval typ : rule -> [ `Signal | `Error | `Method_call | `Method_return ] option
Sourceval sender : rule -> OBus_name.bus
Sourceval interface : rule -> OBus_name.interface
Sourceval path : rule -> OBus_path.t option
Sourceval destination : rule -> OBus_name.bus
Sourceval arguments : rule -> arguments
Sourceval eavesdrop : rule -> bool option
Rule construction
Sourceval rule : ?typ:[ `Signal | `Error | `Method_call | `Method_return ] -> ?sender:OBus_name.bus -> ?interface:OBus_name.interface -> ?member:OBus_name.member -> ?path:OBus_path.t -> ?destination:OBus_name.bus -> ?arguments:arguments -> ?eavesdrop:bool -> unit -> rule

Create a matching rule.

Matching
Sourceval match_message : rule -> OBus_message.t -> bool

match_message rule message returns wether message is matched by rule

Sourceval match_values : arguments -> OBus_value.V.sequence -> bool

match_values filters values returns whether values are matched by the given list of argument filters.

Comparison
Sourcetype comparison_result =
  1. | More_general
    (*

    r1 is more general than r2, i.e. any message matched by r2 is also matched by r1

    *)
  2. | Less_general
    (*

    r1 is less general than r2, i.e. any message matched by r1 is also matched by r2

    *)
  3. | Equal
    (*

    r1 and r2 are equal

    *)
  4. | Incomparable
    (*

    r1 and r2 are incomparable, i.e. there exists two message m1 and m2 such that:

    • m1 is matched by r1 but not by r2
    • m2 is matched by r2 but not by r1
    *)

Result of the comparisong of two rules r1 and r2:

Sourceval compare_rules : rule -> rule -> comparison_result

compare_rules r1 r2 compares the two matching rules r1 and r2

Parsing/printing
Sourceexception Parse_failure of string * int * string

Parse_failure(string, position, reason) is raised when parsing a rule failed

Sourceval string_of_rule : rule -> string

Returns a string representation of a matching rule.

Sourceval rule_of_string : string -> rule

Parse a string representation of a matching rule.

  • raises Failure

    if the given string does not contain a valid matching rule.

Rules and message buses
Sourceval export : ?switch:Lwt_switch.t -> OBus_connection.t -> rule -> unit Lwt.t

export ?switch connection rule registers rule on the message bus. If another rule more general than rule is already exported, then it does nothihng.

You can provide a switch to manually disable the export.