Module: OpenHAB::DSL
- Includes:
- Core::Actions, Core::EntityLookup, Core::ScriptHandling, Rules::Terse
- Included in:
- Items::Builder, Rules::BuilderDSL
- Defined in:
- lib/openhab/dsl.rb,
lib/openhab/dsl/rules.rb,
lib/openhab/dsl/events.rb,
lib/openhab/dsl/version.rb,
lib/openhab/dsl/debouncer.rb,
lib/openhab/dsl/rules/guard.rb,
lib/openhab/dsl/rules/terse.rb,
lib/openhab/dsl/items/ensure.rb,
lib/openhab/dsl/thread_local.rb,
lib/openhab/dsl/items/builder.rb,
lib/openhab/dsl/rules/builder.rb,
lib/openhab/dsl/timer_manager.rb,
lib/openhab/dsl/rules/property.rb,
lib/openhab/dsl/rules/triggers.rb,
lib/openhab/dsl/things/builder.rb,
lib/openhab/dsl/events/watch_event.rb,
lib/openhab/dsl/items/timed_command.rb,
lib/openhab/dsl/rules/rule_triggers.rb,
lib/openhab/dsl/rules/name_inference.rb,
lib/openhab/dsl/rules/automation_rule.rb,
lib/openhab/dsl/rules/triggers/changed.rb,
lib/openhab/dsl/rules/triggers/channel.rb,
lib/openhab/dsl/rules/triggers/command.rb,
lib/openhab/dsl/rules/triggers/trigger.rb,
lib/openhab/dsl/rules/triggers/updated.rb,
lib/openhab/dsl/rules/triggers/cron/cron.rb,
lib/openhab/dsl/rules/triggers/conditions/proc.rb,
lib/openhab/dsl/rules/triggers/cron/cron_handler.rb,
lib/openhab/dsl/rules/triggers/conditions/duration.rb,
lib/openhab/dsl/rules/triggers/watch/watch_handler.rb
Overview
The main DSL available to rules.
Methods on this module are extended onto main
, the top level self
in
any file. You can also access them as class methods on the module for use
inside of other classes, or include the module.
Defined Under Namespace
Modules: Events, Items, Rules, Things Classes: Debouncer, TimerManager
Constant Summary collapse
- VERSION =
Version of openHAB helper libraries
"5.0.1"
Rule Creation collapse
-
.rule(name = nil, **kwargs) {|rule| ... } ⇒ Core::Rules::Rule?
Create a new rule.
-
.script(name = nil, id: nil, **kwargs) { ... } ⇒ Core::Rules::Rule
Create a new script.
Rule Support collapse
-
.profile(id) {|event, command: nil, state: nil, link:, item:, channel_uid:, configuration:, context:| ... } ⇒ void
Defines a new profile that can be applied to item channel links.
Object Access collapse
-
.items ⇒ Core::Items::Registry
Fetches all items from the item registry.
-
.rules ⇒ Core::Rules::Registry
Fetches all rules from the rule registry.
-
.shared_cache ⇒ Core::ValueCache
ValueCache is the interface used to access a shared cache available between scripts and/or rule executions.
-
.things ⇒ Core::Things::Registry
Get all things known to openHAB.
-
.timers ⇒ TimerManager
Provides access to timers created by after.
Utilities collapse
-
.after(duration, id: nil, reschedule: true) {|timer| ... } ⇒ Core::Timer
Create a timer and execute the supplied block after the specified duration.
-
.between(range) ⇒ Range
Convert a string based range into a range of LocalTime, LocalDate, MonthDay, or ZonedDateTime depending on the format of the string.
-
.debounce_for(debounce_time, id: nil, &block) ⇒ void
Waits until calls to this method have stopped firing for a period of time before executing the block.
-
.only_every(interval, id: nil, &block) ⇒ void
Limit how often the given block executes to the specified interval.
-
.store_states(*items) ⇒ Core::Items::StateStorage
Store states of supplied items.
-
.throttle_for(duration, id: nil, &block) ⇒ void
Rate-limits block executions by delaying calls and only executing the last call within the given duration.
-
.transform(type, function, value) ⇒ String
Applies a transformation of a given type with some function to a value.
Block Modifiers collapse
These methods allow certain operations to be grouped inside the given block to reduce repetitions
-
.ensure_states { ... } ⇒ Object
Global method that takes a block and for the duration of the block all commands sent will check if the item is in the command's state before sending the command.
- .holiday_file(*args) ⇒ Object
-
.holiday_file!(file = nil) ⇒ Symbol?
Sets a thread local variable to set the default holiday file.
-
.persistence(service) { ... } ⇒ Object
Sets a thread local variable to set the default persistence service for method calls inside the block.
-
.persistence!(service = nil) ⇒ Object?
Permanently sets the default persistence service for the current thread.
-
.provider(*args, **kwargs) { ... } ⇒ Object
Sets the implicit provider(s) for operations inside the block.
-
.provider!(things: nil, items: nil, metadata: nil, links: nil, **metadata_items) ⇒ void
Permanently set the implicit provider(s) for this thread.
-
.unit(*units) { ... } ⇒ Object
Sets the implicit unit(s) for operations inside the block.
-
.unit!(*units) ⇒ Hash<javax.measure.Dimension=>javax.measure.Unit>
Permanently sets the implicit unit(s) for this thread.
Methods included from Rules::Terse
#changed, #channel, #channel_linked, #channel_unlinked, #cron, #every, #item_added, #item_removed, #item_updated, #on_start, #received_command, #thing_added, #thing_removed, #thing_updated, #updated
Methods included from Core::ScriptHandling
script_loaded, script_unloaded
Methods included from Core::Actions
Methods included from Core::EntityLookup
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class OpenHAB::Core::EntityLookup
Class Method Details
.after(duration, id: nil, reschedule: true) {|timer| ... } ⇒ Core::Timer
Create a timer and execute the supplied block after the specified duration
#Reentrant Timers
Timers with an id are reentrant by id. Reentrant means that when the same id is encountered, the timer is rescheduled rather than creating a second new timer. Note that the timer will execute the block provided in the latest call.
This removes the need for the usual boilerplate code to manually keep track of timer objects.
Timers with id
can be managed with the built-in timers object.
When a timer is cancelled, it will be removed from the object.
Be sure that your ids are unique. For example, if you're using items as your
ids, you either need to be sure you don't use the same item for multiple logical contexts,
or you need to make your id more specific, by doing something like embedding the item in
array with a symbol of the timer's purpose, like [:vacancy, item]
. But also note that
assuming default settings, every Ruby file (for file-based rules) or UI rule gets its
own instance of the timers object, so you don't need to worry about collisions among
different files.
343 344 345 346 347 348 349 |
# File 'lib/openhab/dsl.rb', line 343 def after(duration, id: nil, reschedule: true, &block) raise ArgumentError, "Block is required" unless block # Carry rule name to timer thread_locals = ThreadLocal.persist timers.create(duration, id: id, reschedule: reschedule, thread_locals: thread_locals, block: block) end |
.between(range) ⇒ Range
Convert a string based range into a range of LocalTime, LocalDate, MonthDay, or ZonedDateTime depending on the format of the string.
373 374 375 376 377 378 379 |
# File 'lib/openhab/dsl.rb', line 373 def between(range) raise ArgumentError, "Supplied object must be a range" unless range.is_a?(Range) start = try_parse_time_like(range.begin) finish = try_parse_time_like(range.end) Range.new(start, finish, range.exclude_end?) end |
.debounce_for(debounce_time, id: nil, &block) ⇒ void
This method returns an undefined value.
Waits until calls to this method have stopped firing for a period of time before executing the block.
This method acts as a guard for the given block to ensure that it doesn't get executed
too frequently. The debounce_for method can be called as frequently as possible.
The given block, however, will only be executed once the debounce_time
has passed
since the last call to debounce_for.
This method can be used from within a UI rule as well as from a file-based rule.
445 446 447 448 |
# File 'lib/openhab/dsl.rb', line 445 def debounce_for(debounce_time, id: nil, &block) idle_time = debounce_time.is_a?(Range) ? debounce_time.begin : debounce_time debounce(for: debounce_time, idle_time: idle_time, id: id, &block) end |
.ensure_states { ... } ⇒ Object
Global method that takes a block and for the duration of the block all commands sent will check if the item is in the command's state before sending the command.
594 595 596 597 598 599 600 |
# File 'lib/openhab/dsl.rb', line 594 def ensure_states old = Thread.current[:openhab_ensure_states] Thread.current[:openhab_ensure_states] = true yield ensure Thread.current[:openhab_ensure_states] = old end |
.holiday_file(file) { ... } ⇒ Object .holiday_file ⇒ String?
925 926 927 928 929 930 931 932 933 934 935 |
# File 'lib/openhab/dsl.rb', line 925 def holiday_file(*args) raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 0..1)" if args.length > 1 old = Thread.current[:openhab_holiday_file] return old if args.empty? holiday_file!(args.first) yield ensure holiday_file!(old) end |
.holiday_file!(file = nil) ⇒ Symbol?
Sets a thread local variable to set the default holiday file.
950 951 952 |
# File 'lib/openhab/dsl.rb', line 950 def holiday_file!(file = nil) Thread.current[:openhab_holiday_file] = file end |
.items ⇒ Core::Items::Registry
Fetches all items from the item registry
The examples all assume the following items exist.
Dimmer DimmerTest "Test Dimmer"
Switch SwitchTest "Test Switch"
207 208 209 |
# File 'lib/openhab/dsl.rb', line 207 def items Core::Items::Registry.instance end |
.only_every(interval, id: nil, &block) ⇒ void
This method returns an undefined value.
Limit how often the given block executes to the specified interval.
only_every will execute the given block but prevents further executions until the given interval has passed. In contrast, throttle_for will not execute the block immediately, and will wait until the end of the interval.
508 509 510 511 |
# File 'lib/openhab/dsl.rb', line 508 def only_every(interval, id: nil, &block) interval = 1.send(interval) if %i[second minute hour day].include?(interval) debounce(for: interval, leading: true, id: id, &block) end |
.persistence(service) { ... } ⇒ Object
Sets a thread local variable to set the default persistence service for method calls inside the block
620 621 622 623 624 625 |
# File 'lib/openhab/dsl.rb', line 620 def persistence(service) old = persistence!(service) yield ensure persistence!(old) end |
.persistence!(service = nil) ⇒ Object?
This method is only intended for use at the top level of rule scripts. If it's used within library methods, or hap-hazardly within rules, things can get very confusing because the prior state won't be properly restored.
Permanently sets the default persistence service for the current thread
642 643 644 645 646 |
# File 'lib/openhab/dsl.rb', line 642 def persistence!(service = nil) old = Thread.current[:openhab_persistence_service] Thread.current[:openhab_persistence_service] = service old end |
.profile(id) {|event, command: nil, state: nil, link:, item:, channel_uid:, configuration:, context:| ... } ⇒ void
This method returns an undefined value.
Defines a new profile that can be applied to item channel links.
139 140 141 142 143 144 145 146 147 148 |
# File 'lib/openhab/dsl.rb', line 139 def profile(id, &block) raise ArgumentError, "Block is required" unless block id = id.to_s uid = org.openhab.core.thing.profiles.ProfileTypeUID.new("ruby", id) ThreadLocal.thread_local(openhab_rule_type: "profile", openhab_rule_uid: id) do Core::ProfileFactory.instance.register(uid, block) end end |
.provider(*args, **kwargs) { ... } ⇒ Object
Sets the implicit provider(s) for operations inside the block.
796 797 798 799 800 801 802 803 804 805 |
# File 'lib/openhab/dsl.rb', line 796 def provider(*args, **kwargs) raise ArgumentError, "You must give a block to set the provider for the duration of" unless block_given? begin old_providers = provider!(*args, **kwargs) yield ensure Thread.current[:openhab_providers] = old_providers end end |
.provider!(things: nil, items: nil, metadata: nil, links: nil, **metadata_items) ⇒ void
This method is only intended for use at the top level of rule scripts. If it's used within library methods, or hap-hazardly within rules, things can get very confusing because the prior state won't be properly restored.
This method returns an undefined value.
Permanently set the implicit provider(s) for this thread.
provider! calls are cumulative - additional calls will not erase the effects of previous calls unless they are for the same provider type.
838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 |
# File 'lib/openhab/dsl.rb', line 838 def provider!(*providers, **providers_by_type) thread_providers = Thread.current[:openhab_providers] ||= {} old_providers = thread_providers.dup providers.each do |provider| case provider when Core::Provider thread_providers[provider.class.type] = provider when org.openhab.core.common.registry.ManagedProvider type = provider.type unless type raise ArgumentError, "#{provider.inspect} is for objects which are not supported by openhab-scripting" end thread_providers[type] = provider when Proc, :transient, :persistent Core::Provider::KNOWN_TYPES.each do |known_type| thread_providers[known_type] = provider end when Hash # non-symbols can't be used as kwargs, so Item keys show up as a separate hash here # just merge it in, and allow it to be handled below providers_by_type.merge!(provider) else raise ArgumentError, "#{provider.inspect} is not a valid provider" end end providers_by_type.each do |type, provider| case provider when Proc, org.openhab.core.common.registry.ManagedProvider, :transient, :persistent, nil nil else raise ArgumentError, "#{provider.inspect} is not a valid provider" end case type when :items, :metadata, :things, :links if provider.is_a?(org.openhab.core.common.registry.ManagedProvider) && provider.type != type raise ArgumentError, "#{provider.inspect} is not a provider for #{type}" end thread_providers[type] = provider when Symbol, String (thread_providers[:metadata_namespaces] ||= {})[type.to_s] = provider when Item (thread_providers[:metadata_items] ||= {})[type.name] = provider else raise ArgumentError, "#{type.inspect} is not provider type" end end old_providers end |
.rule(name = nil, **kwargs) {|rule| ... } ⇒ Core::Rules::Rule?
Create a new rule
The rule must have at least one trigger and one execution block. To create a "script" without any triggers, use #script.
58 59 60 |
# File 'lib/openhab/dsl.rb', line 58 def rule(name = nil, **kwargs, &block) rules.build { rule(name, **kwargs, &block) } end |
.rules ⇒ Core::Rules::Registry
Fetches all rules from the rule registry.
170 171 172 |
# File 'lib/openhab/dsl.rb', line 170 def rules Core::Rules::Registry.instance end |
.script(name = nil, id: nil, **kwargs) { ... } ⇒ Core::Rules::Rule
Create a new script
A script is a rule with no triggers. It can be called by various other actions, such as the Run Rules action.
63 64 65 |
# File 'lib/openhab/dsl.rb', line 63 def script(name = nil, id: nil, **kwargs, &block) rules.build { script(name, id: id, **kwargs, &block) } end |
.shared_cache ⇒ Core::ValueCache
Only the sharedCache is exposed in Ruby. For a private cache, simply use an instance variable. See Instance Variables.
Because every script or UI rule gets it own JRuby engine instance, you cannot rely on being able to access Ruby objects between them. Only objects that implement a Java interface that's part of Java or openHAB Core (such as Hash implements java.util.Map, or other basic datatypes) can be reliably stored and accessed from the shared cache. Likewise, you can use the cache to access data from other scripting languages, but they'll be all but useless in Ruby. It's best to stick to simple data types. If you're having troubles, serializing to_json before storing may help.
ValueCache is the interface used to access a shared cache available between scripts and/or rule executions.
While ValueCache looks somewhat like a Hash, it does not support iteration of the contained elements. So it's limited to strictly storing, fetching, or removing known elements.
Shared caches are not persisted between openHAB restarts. And in fact, if all scripts are unloaded that reference a particular key, that key is removed.
161 162 163 |
# File 'lib/openhab/dsl.rb', line 161 def shared_cache $sharedCache end |
.store_states(*items) ⇒ Core::Items::StateStorage
Store states of supplied items
Takes one or more items and returns a map {Item => State}
with the
current state of each item. It is implemented by calling openHAB's
events.storeStates().
534 535 536 537 538 539 540 541 |
# File 'lib/openhab/dsl.rb', line 534 def store_states(*items) states = Core::Items::StateStorage.from_items(*items) if block_given? yield states.restore end states end |
.things ⇒ Core::Things::Registry
Get all things known to openHAB
225 226 227 |
# File 'lib/openhab/dsl.rb', line 225 def things Core::Things::Registry.instance end |
.throttle_for(duration, id: nil, &block) ⇒ void
This method returns an undefined value.
Rate-limits block executions by delaying calls and only executing the last call within the given duration.
When throttle_for is called, it will hold from executing the block and start a fixed timer for the given duration. Should more calls occur during this time, keep holding and once the wait time is over, execute the block.
throttle_for will execute the block after it had waited for the given duration,
regardless of how frequently throttle_for
was called.
In contrast, debounce_for will wait until there is a minimum interval
between two triggers.
throttle_for is ideal in situations where regular status updates need to be made for frequently changing values. It is also useful when a rule responds to triggers from multiple related items that are updated at around the same time. Instead of executing the rule multiple times, throttle_for will wait for a pre-set amount of time since the first group of triggers occurred before executing the rule.
478 479 480 |
# File 'lib/openhab/dsl.rb', line 478 def throttle_for(duration, id: nil, &block) debounce(for: duration, id: id, &block) end |
.timers ⇒ TimerManager
Provides access to timers created by after
233 234 235 |
# File 'lib/openhab/dsl.rb', line 233 def timers TimerManager.instance end |
.transform(type, function, value) ⇒ String
Applies a transformation of a given type with some function to a value.
483 484 485 |
# File 'lib/openhab/dsl.rb', line 483 def transform(type, function, value) Transformation.transform(type, function, value) end |
.unit(*units) { ... } ⇒ Object .unit(dimension) ⇒ javax.measure.Unit
Sets the implicit unit(s) for operations inside the block.
709 710 711 712 713 714 715 716 717 718 719 720 721 722 |
# File 'lib/openhab/dsl.rb', line 709 def unit(*units) if units.length == 1 && units.first.is_a?(javax.measure.Dimension) return Thread.current[:openhab_units]&.[](units.first) end raise ArgumentError, "You must give a block to set the unit for the duration of" unless block_given? begin old_units = unit!(*units) yield ensure Thread.current[:openhab_units] = old_units end end |
.unit!(*units) ⇒ Hash<javax.measure.Dimension=>javax.measure.Unit> .unit! ⇒ Hash<javax.measure.Dimension=>javax.measure.Unit>
This method is only intended for use at the top level of rule scripts. If it's used within library methods, or hap-hazardly within rules, things can get very confusing because the prior state won't be properly restored.
Permanently sets the implicit unit(s) for this thread
unit! calls are cumulative - additional calls will not erase the effects of previous calls unless they are for the same dimension.
765 766 767 768 769 770 771 772 773 774 |
# File 'lib/openhab/dsl.rb', line 765 def unit!(*units) units = units.each_with_object({}) do |unit, r| unit = org.openhab.core.types.util.UnitUtils.parse_unit(unit) if unit.is_a?(String) r[unit.dimension] = unit end old_units = Thread.current[:openhab_units] || {} Thread.current[:openhab_units] = units.empty? ? {} : old_units.merge(units) old_units end |