lib/demiurge.rb
# This method 'subscribes' a block to various types of
# notifications. The block will be called with the notifications
# when they occur. A "specifier" for this method means either the
# special symbol +:all+ or an Array of Symbols or Strings to show
# what values a notification may have for the given field. For
# fields that might indicate Demiurge items such as "zone" or
# "actor" the value should be the Demiurge item *name*, not the
# item itself.
#
# When a notification occurs that matches the subscription, the
# given block will be called with a hash of data about that
# notification.
#
# The tracker is supplied to allow later unsubscribes. Pass a
# unique tracker object (usually a String or Symbol) when
# subscribing, then pass in the same one when unsubscribing.
#
# At a minimum, subscriptions should include a zone to avoid
# subscribing to all such notifications everywhere in the engine.
# Engine-wide subscriptions become very inefficient very quickly.
#
# Notifications only have a few mandatory fields - type, actor,
# zone and location. The location and/or actor can be nil in some
# cases, and the zone can be "admin" for engine-wide events. If
# you wish to subscribe based on other properties of the
# notification then you'll need to pass a custom predicate to
# check each notification. A "predicate" just means it's a proc
# that returns true or false, depending whether a notification
# matches.
#
# @example Subscribe to all notification types at a particular location
# subscribe_to_notifications(zone: "my zone name", location: "my location") { |h| puts "Got #{h.inspect}!" }
#
# @example Subscribe to all "say" notifications in my same zone
# subscribe_to_notifications(zone: "my zone", type: "say") { |h| puts "Somebody said something!" }
#
# @example Subscribe to all move_to notifications for a specific actor, with a tracker for future unsubscription
# subscribe_to_notifications(zone: ["one", "two", "three"], type: "move_to", actor: "bozo the clown", tracker: "bozo move tracker") { |h| bozo_move(h) }
#
# @example Subscribe to notifications matching a custom predicate
# subscribe_to_notifications(zone: "green field", type: "joyous dance", predicate: proc { |h| h["info"]["subtype"] == "butterfly wiggle" }) { |h| process(h) }
#
# @param type [:all, String, Array<Symbol>, Array<String>] A specifier for what Demiurge notification names to subscribe to
# @param zone [:all, String, Array<Symbol>, Array<String>] A specifier for what Zone names match this subscription
# @param location [:all, String, Array<Symbol>, Array<String>] A specifier for what location names match this subscription
# @param predicate [Proc, nil] Call this proc on each notification to see if it matches this subscription
# @param actor [:all, String, Array<Symbol>, Array<String>] A specifier for what Demiurge item name(s) must be the actor in a notification to match this subscription
# @param tracker [Object, nil] To unsubscribe from this notification later, pass in the same tracker to {#unsubscribe_from_notifications}, or another object that is +==+ to this tracker. A tracker is most often a String or Symbol. If the tracker is nil, you can't ever unsubscribe.
# @return [void]
# @since 0.0.1
This method 'subscribes' a block to various types of
notifications. The block will be called with the notifications
when they occur. A "specifier" for this method means either the
special symbol +:all+ or an Array of Symbols or Strings to show
what values a notification may have for the given field. For
fields that might indicate Demiurge items such as "zone" or
"actor" the value should be the Demiurge item *name*, not the
item itself.

When a notification occurs that matches the subscription, the
given block will be called with a hash of data about that
notification.

The tracker is supplied to allow later unsubscribes. Pass a
unique tracker object (usually a String or Symbol) when
subscribing, then pass in the same one when unsubscribing.

At a minimum, subscriptions should include a zone to avoid
subscribing to all such notifications everywhere in the engine.
Engine-wide subscriptions become very inefficient very quickly.

Notifications only have a few mandatory fields - type, actor,
zone and location. The location and/or actor can be nil in some
cases, and the zone can be "admin" for engine-wide events. If
you wish to subscribe based on other properties of the
notification then you'll need to pass a custom predicate to
check each notification. A "predicate" just means it's a proc
that returns true or false, depending whether a notification
matches.
This method ' subscribes ' a block to various types of notifications . The block will be called with the notifications when they occur . A " specifier " for this method means either the special symbol + : all + or an Array of Symbols or Strings to show what values a notification may have for the given field . For fields that might indicate Demiurge items such as " zone " or " actor " the value should be the Demiurge item * name * not the item itself . When a notification occurs that matches the subscription the given block will be called with a hash of data about that notification . The tracker is supplied to allow later unsubscribes . Pass a unique tracker object ( usually a String or Symbol ) when subscribing then pass in the same one when unsubscribing . At a minimum subscriptions should include a zone to avoid subscribing to all such notifications everywhere in the engine . Engine - wide subscriptions become very inefficient very quickly . Notifications only have a few mandatory fields - type actor zone and location . The location and / or actor can be nil in some cases and the zone can be " admin " for engine - wide events . If you wish to subscribe based on other properties of the notification then you ' ll need to pass a custom predicate to check each notification . A " predicate " just means it ' s a proc that returns true or false depending whether a notification matches .
def subscribe_to_notifications(type: :all, zone: :all, location: :all, predicate: nil, actor: :all, tracker: nil, &block)
      sub_structure = {
        type: notification_spec(type),
        zone: notification_spec(zone),
        location: notification_spec(location),
        actor: notification_spec(actor),
        predicate: predicate,
        tracker: tracker,
        block: block,
      }
      @subscriptions_by_tracker[tracker] ||= []
      @subscriptions_by_tracker[tracker].push(sub_structure)
      nil
    end
def subscribe_to_notifications ( type : :all , zone : :all , location : :all , predicate : nil , actor : :all , tracker : nil , & block ) sub_structure = { type : notification_spec ( type ) , zone : notification_spec ( zone ) , location : notification_spec ( location ) , actor : notification_spec ( actor ) , predicate : predicate , tracker : tracker , block : block , } @subscriptions_by_tracker [ tracker ] ||= [ ] @subscriptions_by_tracker [ tracker ] . push ( sub_structure ) nil end
This method 'subscribes' a block to various types of
notifications.
This method ' subscribes ' a block to various types of notifications .
None
void
type
A specifier for what Demiurge notification names to subscribe to
A specifier for what Demiurge notification names to subscribe to
zone
A specifier for what Zone names match this subscription
A specifier for what Zone names match this subscription
location
A specifier for what location names match this subscription
A specifier for what location names match this subscription
predicate
Call this proc on each notification to see if it matches this subscription
Call this proc on each notification to see if it matches this subscription
actor
A specifier for what Demiurge item name(s) must be the actor in a notification to match this subscription
A specifier for what Demiurge item name ( s ) must be the actor in a notification to match this subscription
tracker
To unsubscribe from this notification later, pass in the same tracker to {#unsubscribe_from_notifications}, or another object that is +==+ to this tracker. A tracker is most often a String or Symbol. If the tracker is nil, you can't ever unsubscribe.
To unsubscribe from this notification later pass in the same tracker to { #unsubscribe_from_notifications } or another object that is + == + to this tracker . A tracker is most often a String or Symbol . If the tracker is nil you can ' t ever unsubscribe .
block
example
Subscribe to all notification types at a particular location subscribe_to_notifications(zone: "my zone name", location: "my location") { |h| puts "Got #{h.inspect}!" }
Subscribe to all notification types at a particular location subscribe_to_notifications ( zone : " my zone name " location : " my location " ) { |h| puts " Got # { h . inspect } ! " }
example
Subscribe to all "say" notifications in my same zone subscribe_to_notifications(zone: "my zone", type: "say") { |h| puts "Somebody said something!" }
Subscribe to all " say " notifications in my same zone subscribe_to_notifications ( zone : " my zone " type : " say " ) { |h| puts " Somebody said something! " }
example
Subscribe to all move_to notifications for a specific actor, with a tracker for future unsubscription subscribe_to_notifications(zone: ["one", "two", "three"], type: "move_to", actor: "bozo the clown", tracker: "bozo move tracker") { |h| bozo_move(h) }
Subscribe to all move_to notifications for a specific actor with a tracker for future unsubscription subscribe_to_notifications ( zone : [ " one " " two " " three " ] type : " move_to " actor : " bozo the clown " tracker : " bozo move tracker " ) { |h| bozo_move ( h ) }
example
Subscribe to notifications matching a custom predicate subscribe_to_notifications(zone: "green field", type: "joyous dance", predicate: proc { |h| h["info"]["subtype"] == "butterfly wiggle" }) { |h| process(h) }
Subscribe to notifications matching a custom predicate subscribe_to_notifications ( zone : " green field " type : " joyous dance " predicate : proc { |h| h [ " info " ] [ " subtype " ] == " butterfly wiggle " } ) { |h| process ( h ) }
since
None