Module: Plushie::Extension::ClassMethods

Defined in:
lib/plushie/extension.rb

Overview

Methods added to classes that include Plushie::Extension.

Constant Summary collapse

VALID_KINDS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Valid extension kind values.

i[widget native_widget].freeze

Instance Method Summary collapse

Instance Method Details

#command(name, **params)

This method returns an undefined value.

Declares a command (for native extensions, informational in Ruby).

In pure Ruby extensions this is informational only. For native Rust-backed extensions, declared commands map to wire commands sent to the renderer.

Examples:

command :set_value, value: :number

Parameters:

  • name (Symbol) —

    command name

  • params (Hash{Symbol => Symbol}) —

    parameter names to types



184
185
186
 
# File 'lib/plushie/extension.rb', line 184

def command(name, **params)
  @_extension_commands << {name: name.to_sym, params: params}
end

#container? ⇒ Boolean

Whether this is a container widget.

Returns:

  • (Boolean) 


212
213
214
 
# File 'lib/plushie/extension.rb', line 212

def container?
  @_extension_container
end

#extension_props ⇒ Array<Hash{Symbol => Object}>

Returns the declared props metadata.

Returns:

  • (Array<Hash{Symbol => Object}>) —

    each hash has :name, :type, :default keys



205
206
207
 
# File 'lib/plushie/extension.rb', line 205

def extension_props
  @_extension_props
end

#finalize!

This method returns an undefined value.

Finalize the extension class by generating initialize, setters, and build.

Called automatically on first instantiation. Can also be called explicitly after all widget/prop/command declarations are complete.



222
223
224
225
226
227
228
229
230
 
# File 'lib/plushie/extension.rb', line 222

def finalize!
  return if @_finalized

  _validate!
  _generate_initialize!
  _generate_setters!
  _generate_build!
  @_finalized = true
end

#native? ⇒ Boolean

Whether this is a native (Rust-backed) extension.

Returns:

  • (Boolean) 


138
139
140
 
# File 'lib/plushie/extension.rb', line 138

def native?
  @_extension_kind == :native_widget
end

#native_crate ⇒ String?

Returns the native crate path declared via +rust_crate+.

Returns:

  • (String, nil) 


124
125
126
 
# File 'lib/plushie/extension.rb', line 124

def native_crate
  @_extension_native_crate
end

#prop(name, type, **opts)

This method returns an undefined value.

Declares a typed prop with optional default.

Examples:

prop :value, :number, default: 0
prop :label, :string

Parameters:

  • name (Symbol) —

    prop name (must not conflict with reserved names)

  • type (Symbol) —

    one of KNOWN_PROP_TYPES

  • opts (Hash) —

    options

Options Hash (**opts):

  • :default (Object) —

    default value for this prop

Raises:

  • (ArgumentError) —

    if type is unsupported or name is reserved



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/plushie/extension.rb', line 154

def prop(name, type, **opts)
  name = name.to_sym
  type = type.to_sym

  unless KNOWN_PROP_TYPES.include?(type)
    raise ArgumentError,
      "unsupported prop type #{type.inspect} for prop #{name.inspect}. " \
      "Supported: #{KNOWN_PROP_TYPES.inspect}"
  end

  if RESERVED_PROP_NAMES.include?(name)
    raise ArgumentError,
      "prop name #{name.inspect} is reserved. Reserved: #{RESERVED_PROP_NAMES.inspect}"
  end

  @_extension_props << {name: name, type: type, default: opts[:default]}
end

#prop_names ⇒ Array<Symbol>

Returns all declared prop names (including auto-added :a11y, :event_rate).

Returns:

  • (Array<Symbol>) 


198
199
200
 
# File 'lib/plushie/extension.rb', line 198

def prop_names
  @_extension_props.map { _1[:name] } + i[a11y event_rate]
end

#rust_constructor(expr)

This method returns an undefined value.

Declares the Rust constructor expression used in the generated main.rs. Required for +:native_widget+ extensions.

Examples:

rust_constructor "sparkline::SparklineExtension::new()"

Parameters:

  • expr (String) —

    a valid Rust expression (e.g. "MyExt::new()")



117
118
119
 
# File 'lib/plushie/extension.rb', line 117

def rust_constructor(expr)
  @_extension_rust_constructor = expr.to_s
end

#rust_constructor_expr ⇒ String?

Returns the Rust constructor expression declared via +rust_constructor+.

Returns:

  • (String, nil) 


131
132
133
 
# File 'lib/plushie/extension.rb', line 131

def rust_constructor_expr
  @_extension_rust_constructor
end

#rust_crate(path)

This method returns an undefined value.

Declares the relative path to the Rust crate directory. Required for +:native_widget+ extensions.

Examples:

rust_crate "native/sparkline"

Parameters:

  • path (String) —

    relative path from the project root to the crate



105
106
107
 
# File 'lib/plushie/extension.rb', line 105

def rust_crate(path)
  @_extension_native_crate = path.to_s
end

#type_names ⇒ Array<Symbol>

Returns the widget type names this extension handles.

Returns:

  • (Array<Symbol>) 


191
192
193
 
# File 'lib/plushie/extension.rb', line 191

def type_names
  [@_extension_widget]
end

#widget(type_name, **opts)

This method returns an undefined value.

Declares the widget type name.

Examples:

Pure Ruby widget

widget :gauge

Native Rust widget

widget :sparkline, kind: :native_widget

Parameters:

  • type_name (Symbol) —

    the wire type name for this widget

  • opts (Hash) —

    options

Options Hash (**opts):

  • :kind (Symbol) — default: :widget —

    either +:widget+ or +:native_widget+

  • :container (Boolean) — default: false —

    whether this widget accepts children



85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/plushie/extension.rb', line 85

def widget(type_name, **opts)
  kind = opts.fetch(:kind, :widget)
  unless VALID_KINDS.include?(kind)
    raise ArgumentError,
      "unsupported widget kind #{kind.inspect}. Supported: #{VALID_KINDS.inspect}"
  end

  @_extension_widget = type_name
  @_extension_kind = kind
  @_extension_container = opts.fetch(:container, false)
end