openHAB

Class: OpenHAB::DSL::Items::ItemBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/openhab/dsl/items/builder.rb

Overview

The ItemBuilder DSL allows you to customize an Item

Direct Known Subclasses

GroupItemBuilder

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(type, name = nil, label = nil, provider:, dimension: nil, format: nil, icon: nil, group: nil, groups: nil, tag: nil, tags: nil, autoupdate: nil, channel: nil, expire: nil, alexa: nil, ga: nil, homekit: nil, metadata: nil, state: nil) ⇒ ItemBuilder

Returns a new instance of ItemBuilder.

Parameters:

Raises:

  • (ArgumentError) 


246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/openhab/dsl/items/builder.rb', line 246

def initialize(type, name = nil, label = nil,
               provider:,
               dimension: nil,
               format: nil,
               icon: nil,
               group: nil,
               groups: nil,
               tag: nil,
               tags: nil,
               autoupdate: nil,
               channel: nil,
               expire: nil,
               alexa: nil,
               ga: nil, # rubocop:disable Naming/MethodParameterName
               homekit: nil,
               metadata: nil,
               state: nil)
  raise ArgumentError, "`name` cannot be nil" if name.nil?
  raise ArgumentError, "`dimension` can only be specified with NumberItem" if dimension && type != :number

  name = name.name if name.respond_to?(:name)
  if provider.is_a?(GroupItemBuilder)
    name = "#{provider.name_base}#{name}"
    label = "#{provider.label_base}#{label}".strip if label
  end
  @provider = provider
  @type = type
  @name = name.to_s
  @label = label
  @dimension = dimension
  @format = format
  @icon = icon
  @groups = []
  @tags = []
  @metadata = Core::Items::Metadata::NamespaceHash.new
  @metadata.merge!(metadata) if metadata
  @autoupdate = autoupdate
  @channels = []
  @expire = nil
  if expire
    expire = Array(expire)
    expire_config = expire.pop if expire.last.is_a?(Hash)
    expire_config ||= {}
    self.expire(*expire, **expire_config)
  end
  self.alexa(alexa) if alexa
  self.ga(ga) if ga
  self.homekit(homekit) if homekit
  @state = state

  self.group(*group)
  self.group(*groups)

  self.tag(*tag)
  self.tag(*tags)

  self.channel(*channel) if channel
end

Instance Attribute Details

#autoupdate ⇒ true, ...

Autoupdate setting

Returns:

  • (true, false, nil) 


175
176
177
 
# File 'lib/openhab/dsl/items/builder.rb', line 175

def autoupdate
  @autoupdate
end

#channels ⇒ String, ...

Channel to link the item to

Returns:



178
179
180
 
# File 'lib/openhab/dsl/items/builder.rb', line 178

def channels
  @channels
end

#dimension ⇒ String?

Unit dimension (for number items only)

Returns:

  • (String, nil) 


160
161
162
 
# File 'lib/openhab/dsl/items/builder.rb', line 160

def dimension
  @dimension
end

#format ⇒ String?

The formatting pattern for the item's state

Returns:

  • (String, nil) 


163
164
165
 
# File 'lib/openhab/dsl/items/builder.rb', line 163

def format
  @format
end

#groups ⇒ Array<String, GroupItem> (readonly)

Groups to which this item should be added

Returns:



169
170
171
 
# File 'lib/openhab/dsl/items/builder.rb', line 169

def groups
  @groups
end

#icon ⇒ Symbol?

The icon to be associated with the item

Returns:



166
167
168
 
# File 'lib/openhab/dsl/items/builder.rb', line 166

def icon
  @icon
end

#label ⇒ String?

Item label

Returns:

  • (String, nil) 


157
158
159
 
# File 'lib/openhab/dsl/items/builder.rb', line 157

def label
  @label
end

#metadata ⇒ Core::Items::Metadata::NamespaceHash (readonly)

Returns:



180
181
182
 
# File 'lib/openhab/dsl/items/builder.rb', line 180

def metadata
  @metadata
end

#name ⇒ String

Item name

Returns:

  • (String) 


154
155
156
 
# File 'lib/openhab/dsl/items/builder.rb', line 154

def name
  @name
end

#state ⇒ Core::Types::State

Initial state

Returns:



183
184
185
 
# File 'lib/openhab/dsl/items/builder.rb', line 183

def state
  @state
end

#tags ⇒ Array<String, Semantics::Tag> (readonly)

Tags to apply to this item

Returns:



172
173
174
 
# File 'lib/openhab/dsl/items/builder.rb', line 172

def tags
  @tags
end

#type ⇒ Symbol (readonly)

The type of this item

Examples:

type #=> :switch

Returns:



151
152
153
 
# File 'lib/openhab/dsl/items/builder.rb', line 151

def type
  @type
end

Instance Method Details

#alexa(value, config = nil) ⇒ void

This method returns an undefined value.

Shortcut for adding Alexa metadata

Parameters:

  • value (String, Symbol) —

    Type of Alexa endpoint

  • config (Hash, nil) (defaults to: nil) —

    Additional Alexa configuration

See Also:




# File 'lib/openhab/dsl/items/builder.rb', line 340

#channel(channel, config = {}) ⇒ void

This method returns an undefined value.

Add a channel link to this item.

Examples:

items.build do
  date_time_item Bedroom_Light_Updated do
    channel "hue:0210:1:bulb1:color", profile: "system:timestamp-update"
  end
end

Parameters:

  • config (Hash) (defaults to: {}) —

    Additional configuration, such as profile



393
394
395
 
# File 'lib/openhab/dsl/items/builder.rb', line 393

def channel(channel, config = {})
  @channels << [channel, config]
end

#expire(command: nil, state: nil) ⇒ void

This method returns an undefined value.

Configure item expiration

Examples:

Get the current expire setting

expire

Clear any expire setting

expire nil

Use a duration

expire 5.hours

Use a string duration

expire "5h"

Set a specific state on expiration

expire 5.minutes, NULL
expire 5.minutes, state: NULL

Send a command on expiration

expire 5.minutes, command: OFF

Raises:

  • (ArgumentError) 


417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
 
# File 'lib/openhab/dsl/items/builder.rb', line 417

def expire(*args, command: nil, state: nil)
  unless (0..2).cover?(args.length)
    raise ArgumentError,
          "wrong number of arguments (given #{args.length}, expected 0..2)"
  end
  return @expire if args.empty?

  state = args.last if args.length == 2
  raise ArgumentError, "cannot provide both command and state" if command && state

  duration = args.first
  return @expire = nil if duration.nil?

  duration = duration.to_s[2..].downcase if duration.is_a?(Duration)
  state = "'#{state}'" if state.respond_to?(:to_str) && type == :string
  @expire = duration
  @expire += ",state=#{state}" if state
  @expire += ",command=#{command}" if command
end

#ga(value, config = nil) ⇒ void

This method returns an undefined value.

Shortcut for adding Google Assistant metadata

Parameters:

  • value (String, Symbol) —

    Type of Google Assistant endpoint

  • config (Hash, nil) (defaults to: nil) —

    Additional Google Assistant configuration

See Also:




# File 'lib/openhab/dsl/items/builder.rb', line 351

#group(*groups) ⇒ void

This method returns an undefined value.

Add this item to a group

Parameters:



330
331
332
333
334
335
336
337
338
 
# File 'lib/openhab/dsl/items/builder.rb', line 330

def group(*groups)
  unless groups.all? do |group|
           group.is_a?(String) || group.is_a?(Core::Items::GroupItem) || group.is_a?(GroupItemBuilder)
         end
    raise ArgumentError, "`group` must be a `GroupItem`, `GroupItemBuilder`, or a `String`"
  end

  @groups.concat(groups)
end

#homekit(value, config = nil) ⇒ void

This method returns an undefined value.

Shortcut for adding Homekit metadata

Parameters:

  • value (String, Symbol) —

    Type of Homekit accessory or characteristic

  • config (Hash, nil) (defaults to: nil) —

    Additional Homekit configuration

See Also:



373
374
375
376
377
378
 
# File 'lib/openhab/dsl/items/builder.rb', line 373

%i[alexa ga homekit].each do |shortcut|
  define_method(shortcut) do |value = nil, config = nil|
    value, config = value if value.is_a?(Array)
    metadata[shortcut] = [value, config]
  end
end

#inspect ⇒ String

Returns:

  • (String) 


458
459
460
461
462
463
464
465
 
# File 'lib/openhab/dsl/items/builder.rb', line 458

def inspect
  s = "#<OpenHAB::Core::Items::#{inspect_type}ItemBuilder#{type_details} #{name} #{label.inspect}"
  s += " category=#{icon.inspect}" if icon
  s += " tags=#{tags.inspect}" unless tags.empty?
  s += " groups=#{groups.map { |g| g.respond_to?(:name) ? g.name : g }.inspect}" unless groups.empty?
  s += " metadata=#{metadata.to_h.inspect}" unless metadata.empty?
  "#{s}>"
end

#tag(*tags) ⇒ void

This method returns an undefined value.

Tag item

Parameters:



320
321
322
 
# File 'lib/openhab/dsl/items/builder.rb', line 320

def tag(*tags)
  @tags += self.class.normalize_tags(*tags)
end

#to_s ⇒ String

The item's label if one is defined, otherwise its name.

Returns:

  • (String) 


310
311
312
 
# File 'lib/openhab/dsl/items/builder.rb', line 310

def to_s
  label || name
end