openHAB

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

Inherits:
Object
  • Object
show all
Includes:
Core::EntityLookup
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

Methods included from Core::EntityLookup

#items, #method_missing, #things

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) 


317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
 
# File 'lib/openhab/dsl/items/builder.rb', line 317

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?

  if dimension
    raise ArgumentError, "`dimension` can only be specified with NumberItem" unless type == :number

    begin
      org.openhab.core.types.util.UnitUtils.parse_dimension(dimension.to_s)
    rescue java.lang.IllegalArgumentException
      raise ArgumentError, "Invalid dimension '#{dimension}'"
    end
  end

  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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class OpenHAB::Core::EntityLookup

Instance Attribute Details

#autoupdate ⇒ true, ...

Autoupdate setting

Returns:

  • (true, false, nil) 


236
237
238
 
# File 'lib/openhab/dsl/items/builder.rb', line 236

def autoupdate
  @autoupdate
end

#channels ⇒ String, ...

Channel to link the item to

Returns:



239
240
241
 
# File 'lib/openhab/dsl/items/builder.rb', line 239

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) 


211
212
213
 
# File 'lib/openhab/dsl/items/builder.rb', line 211

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) 


224
225
226
 
# File 'lib/openhab/dsl/items/builder.rb', line 224

def format
  @format
end

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

Groups to which this item should be added

Returns:



230
231
232
 
# File 'lib/openhab/dsl/items/builder.rb', line 230

def groups
  @groups
end

#icon ⇒ Symbol, ...

The icon to be associated with the item

Returns:



227
228
229
 
# File 'lib/openhab/dsl/items/builder.rb', line 227

def icon
  @icon
end

#label ⇒ String?

Item label

Returns:

  • (String, nil) 


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

def label
  @label
end

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

Returns:



241
242
243
 
# File 'lib/openhab/dsl/items/builder.rb', line 241

def metadata
  @metadata
end

#name ⇒ String

Item name

Returns:

  • (String) 


202
203
204
 
# File 'lib/openhab/dsl/items/builder.rb', line 202

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:



247
248
249
 
# File 'lib/openhab/dsl/items/builder.rb', line 247

def state
  @state
end

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

Tags to apply to this item

Returns:



233
234
235
 
# File 'lib/openhab/dsl/items/builder.rb', line 233

def tags
  @tags
end

#type ⇒ Symbol (readonly)

The type of this item

Examples:

type #=> :switch

Returns:



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

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) 


218
219
220
 
# File 'lib/openhab/dsl/items/builder.rb', line 218

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 426

#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

Relative channel name

items.build do
  switch_item Bedroom_Light, thing: "mqtt:topic:bedroom-light", channel: :power
end

Parameters:



486
487
488
489
490
 
# File 'lib/openhab/dsl/items/builder.rb', line 486

def channel(channel, config = {})
  channel = channel.to_s
  channel = "#{@thing}:#{channel}" if @thing && !channel.include?(":")
  @channels << [channel, config]
end

#expire(duration, command: nil, state: nil, ignore_state_updates: nil, ignore_commands: 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

Specify the duration and command in the same string

expire "5h,command=OFF"

Set the expire configuration

expire 5.minutes, ignore_state_updates: true

Parameters:

  • duration (String, Duration, nil) —

    Duration after which the command or state should be applied

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

    Command to send on expiration

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

    State to set on expiration

  • ignore_state_updates (true, false) (defaults to: nil) —

    When true, state updates will not reset the expire timer

  • ignore_commands (true, false) (defaults to: nil) —

    When true, commands will not reset the expire timer

Raises:

  • (ArgumentError) 


522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
 
# File 'lib/openhab/dsl/items/builder.rb', line 522

def expire(*args, command: nil, state: nil, ignore_state_updates: nil, ignore_commands: 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

  value = duration
  value += ",state=#{state}" if state
  value += ",command=#{command}" if command

  config = { ignoreStateUpdates: ignore_state_updates, ignoreCommands: ignore_commands }
  config.compact!
  @expire = [value, config]
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 437

#group(*groups) ⇒ void

This method returns an undefined value.

Add this item to a group

Parameters:



416
417
418
419
420
421
422
423
424
 
# File 'lib/openhab/dsl/items/builder.rb', line 416

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:



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

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


600
601
602
603
604
605
606
607
 
# File 'lib/openhab/dsl/items/builder.rb', line 600

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:



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

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) 


396
397
398
 
# File 'lib/openhab/dsl/items/builder.rb', line 396

def to_s
  label || name
end