Class: X::StreamRule

Inherits:
Object
  • Object
show all
Defined in:
x-streaming/lib/x/streaming/stream_rule.rb

Overview

A rule of the filtered stream: the value it matches posts against, the tag it is labelled with, and the identifier the API gave it

X::StreamingClient#rules and X::StreamingClient#add_rules return the rules the API holds, and X::StreamingClient#delete_rules deletes one by its identifier, so a rule that was read deletes itself. A rule built to be added has no identifier until the API gives it one, and is deleted by the value it matches.

It is frozen, compares equal to a rule of the same identifier, value, and tag, and matches a pattern of them, as in rule in {value: /ruby/, tag: nil}.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(value:, tag: nil, id: nil) ⇒ StreamRule

Initialize a rule

Examples:

Build a rule to add

X::StreamRule.new(value: "ruby -is:retweet", tag: "ruby")

Parameters:

  • value (String) —

    the value the rule matches posts against

  • tag (String, nil) (defaults to: nil) —

    the tag the rule is labelled with, or nil for none

  • id (Integer, String, nil) (defaults to: nil) —

    the identifier the API gave the rule, as an Integer that is not negative or as the String of digits the API sends, or nil for a rule it has not given one

Raises:

  • (ArgumentError) —

    if the value is not a String, the tag is neither a String nor nil, or the identifier is neither an Integer that is not negative, a String of digits alone, nor nil



68
69
70
71
72
73
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 68

def initialize(value:, tag: nil, id: nil)
  @id = Validator.identifier!(id) unless id.nil?
  @value = string!(:value, value)
  @tag = string!(:tag, tag) unless tag.nil?
  freeze
end

Instance Attribute Details

#id ⇒ Integer? (readonly)

The identifier the API gave the rule

The API sends it as a String, and it is read as an Integer, as the identifier of a resource of the object layer is, and as strictly: a String of digits alone, with no sign, underscore, or whitespace.

Examples:

Get the identifier

rule.id # => 1165037377523306498

Returns:

  • (Integer, nil) —

    the identifier, or nil for a rule the API has not given one



40
41
42
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 40

def id
  @id
end

#tag ⇒ String? (readonly)

The tag the rule is labelled with, which each post it matches names

Examples:

Get the tag

rule.tag # => "ruby"

Returns:

  • (String, nil) —

    the tag, or nil for a rule without one



54
55
56
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 54

def tag
  @tag
end

#value ⇒ String (readonly)

The value the rule matches posts against

Examples:

Get the value

rule.value # => "ruby -is:retweet"

Returns:

  • (String) —

    the value, in the syntax of the filtered stream



47
48
49
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 47

def value
  @value
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Check whether another rule is the same rule

Examples:

Check whether a rule was read before

streaming_client.rules.include?(rule)

Parameters:

  • other (Object) —

    the other rule

Returns:

  • (Boolean) —

    true if the other rule is a StreamRule of the same identifier, value, and tag



99
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 99

def ==(other) = other.instance_of?(self.class) && to_h.eql?(other.to_h)

#deconstruct_keys(_keys) ⇒ Hash{Symbol => Integer, String, nil}

The identifier, value, and tag of the rule, which a pattern matches against

Examples:

Match the rules without a tag

streaming_client.rules.select { |rule| rule in {tag: nil} }

Parameters:

  • _keys (Array<Symbol>, nil) —

    the keys the pattern names

Returns:

  • (Hash{Symbol => Integer, String, nil}) —

    the identifier, value, and tag



90
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 90

def deconstruct_keys(_keys) = to_h

#encode_with(coder) ⇒ void

This method returns an undefined value.

Write the state Marshal writes as YAML

YAML would write the instance variables of the rule, and read them back into a rule that is not frozen, so it says how it is written: the number of its format, then each of its parts, under the name to_h gives it.

Examples:

Write a rule as YAML

YAML.dump(rule)

Parameters:

  • coder (Psych::Coder) —

    the coder YAML writes the rule with



154
155
156
157
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 154

def encode_with(coder)
  coder["format"] = MARSHAL_FORMAT
  to_h.each { |key, value| coder[key.to_s] = value }
end

#hash ⇒ Integer

The hash of the rule, which equal rules share

Examples:

Count the distinct rules

rules.uniq.size

Returns:

  • (Integer) —

    the hash



108
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 108

def hash = [self.class, to_h].hash

#init_with(coder) ⇒ void

This method returns an undefined value.

Restore a rule YAML read, frozen, as Marshal restores one

Examples:

Read a rule written as YAML

YAML.unsafe_load(YAML.dump(rule)).value

Parameters:

  • coder (Psych::Coder) —

    the coder YAML read the rule with

Raises:



167
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 167

def init_with(coder) = marshal_load([coder["format"], coder.map.transform_keys(&:to_sym)])

#inspect ⇒ String

Summarize the rule for the console

Examples:

Inspect a rule

rule.inspect # => #<X::StreamRule id=1165037377523306498 value="ruby -is:retweet" tag="ruby">

Returns:

  • (String) —

    the class name, identifier, value, and tag



116
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 116

def inspect = "#<#{self.class} id=#{id.inspect} value=#{value.inspect} tag=#{tag.inspect}>"

#marshal_dump ⇒ Array(Integer, Hash{Symbol => Integer, String, nil})

The state Marshal writes

What is written is plain data, led by the number of its format, so that a rule written by one release of 1.x is read by a later one: its identifier, value, and tag, as to_h gives them.

Examples:

Cache the rules of the filtered stream

Rails.cache.write("rules", streaming_client.rules)

Returns:

  • (Array(Integer, Hash{Symbol => Integer, String, nil})) —

    the number of the format, then the rule as a Hash



127
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 127

def marshal_dump = [MARSHAL_FORMAT, to_h]

#marshal_load(state) ⇒ void

This method returns an undefined value.

Restore a rule Marshal read, built as the constructor builds it, frozen

Examples:

Read cached rules

Marshal.load(Marshal.dump(rule)).value

Parameters:

  • state (Array) —

    the state Marshal wrote

Raises:



137
138
139
140
141
142
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 137

def marshal_load(state)
  format, rule = state #: [Integer, {id: Integer?, value: String, tag: String?}]
  raise UnsupportedMarshalFormat, "#{self.class} reads format #{MARSHAL_FORMAT} of Marshal, not #{format.inspect}" unless MARSHAL_FORMAT.eql?(format)

  initialize(**rule.slice(:id, :value, :tag)) # steep:ignore InsufficientKeywordArguments
end

#to_h ⇒ Hash{Symbol => Integer, String, nil}

The rule as a Hash

Examples:

Store a rule

store.save(**rule.to_h)

Returns:

  • (Hash{Symbol => Integer, String, nil}) —

    the identifier, value, and tag



81
 
# File 'x-streaming/lib/x/streaming/stream_rule.rb', line 81

def to_h = {id:, value:, tag:}