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, unit: nil, format: nil, icon: nil, group: nil, groups: nil, tag: nil, tags: nil, autoupdate: nil, thing: 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) 


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
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/openhab/dsl/items/builder.rb', line 273

def initialize(type,
               name = nil,
               label = nil,
               provider:,
               dimension: nil,
               unit: nil,
               format: nil,
               icon: nil,
               group: nil,
               groups: nil,
               tag: nil,
               tags: nil,
               autoupdate: nil,
               thing: 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
  self.unit = unit
  @icon = icon
  @groups = []
  @tags = []
  @metadata = Core::Items::Metadata::NamespaceHash.new
  @metadata.merge!(metadata) if metadata
  @autoupdate = autoupdate
  @channels = []
  @thing = thing
  @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
  self.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) 


194
195
196
 
# File 'lib/openhab/dsl/items/builder.rb', line 194

def autoupdate
  @autoupdate
end

#channels ⇒ String, ...

Channel to link the item to

Returns:



197
198
199
 
# File 'lib/openhab/dsl/items/builder.rb', line 197

def channels
  @channels
end

#dimension ⇒ String?

Unit dimension (for number items only)

If #unit is provided, and #dimension is not, it will be inferred.

Returns:

  • (String, nil) 


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

def dimension
  @dimension
end

#format ⇒ String?

The formatting pattern for the item's state

If #unit is provided, and #format is not, it will be inferred.

Returns:

  • (String, nil) 


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

def format
  @format
end

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

Groups to which this item should be added

Returns:



188
189
190
 
# File 'lib/openhab/dsl/items/builder.rb', line 188

def groups
  @groups
end

#icon ⇒ Symbol?

The icon to be associated with the item

Returns:



185
186
187
 
# File 'lib/openhab/dsl/items/builder.rb', line 185

def icon
  @icon
end

#label ⇒ String?

Item label

Returns:

  • (String, nil) 


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

def label
  @label
end

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

Returns:



199
200
201
 
# File 'lib/openhab/dsl/items/builder.rb', line 199

def metadata
  @metadata
end

#name ⇒ String

Item name

Returns:

  • (String) 


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

def name
  @name
end

#state ⇒ Core::Types::State

Initial state

If #state is set to a QuantityType, and #unit is not set, it will be inferred.

Returns:



205
206
207
 
# File 'lib/openhab/dsl/items/builder.rb', line 205

def state
  @state
end

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

Tags to apply to this item

Returns:



191
192
193
 
# File 'lib/openhab/dsl/items/builder.rb', line 191

def tags
  @tags
end

#type ⇒ Symbol (readonly)

The type of this item

Examples:

type #=> :switch

Returns:



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

def type
  @type
end

#unit ⇒ String?

Unit (for number items only)

Due to #format inference, setting the unit is cross-compatible with openHAB 3.4 and 4.0.

Returns:

  • (String, nil) 


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

def unit
  @unit
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 373

#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



426
427
428
429
 
# File 'lib/openhab/dsl/items/builder.rb', line 426

def channel(channel, config = {})
  channel = "#{@thing}:#{channel}" if @thing && !channel.include?(":")
  @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) 


451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/openhab/dsl/items/builder.rb', line 451

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 384

#group(*groups) ⇒ void

This method returns an undefined value.

Add this item to a group

Parameters:



363
364
365
366
367
368
369
370
371
 
# File 'lib/openhab/dsl/items/builder.rb', line 363

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:



406
407
408
409
410
411
 
# File 'lib/openhab/dsl/items/builder.rb', line 406

%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) 


526
527
528
529
530
531
532
533
 
# File 'lib/openhab/dsl/items/builder.rb', line 526

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:



353
354
355
 
# File 'lib/openhab/dsl/items/builder.rb', line 353

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) 


343
344
345
 
# File 'lib/openhab/dsl/items/builder.rb', line 343

def to_s
  label || name
end