Class: Vedeu::Interfaces::DSL

Inherits:
Object
  • Object
show all
Extended by:
Common
Includes:
Common, DSL, DSL::Presentation, DSL::Shared, DSL::Text, DSL::Use
Defined in:
lib/vedeu/interfaces/dsl.rb

Overview

DSL for creating interfaces.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Vedeu::DSL

Instance Attribute Details

#client ⇒ Object (readonly, protected) Originally defined in module DSL

Returns The object instance where the DSL is being used.

Returns:

  • (Object) —

    The object instance where the DSL is being used.

#model ⇒ void (readonly, protected) Originally defined in module DSL

This method returns an undefined value.

Returns The new model object which the DSL is constructing.

Class Method Details

.absent?(variable) ⇒ Boolean Originally defined in module Common

Returns a boolean indicating whether a variable is nil or empty.

Parameters:

  • variable (String|Symbol|Array|Fixnum) —

    The variable to check.

Returns:

  • (Boolean)

.add_buffers!(name) ⇒ Vedeu::Buffers::Buffer (private)

Registers a set of buffers for the interface unless already registered, and also adds interface’s name to list of focussable interfaces.

Parameters:

  • name (String|Symbol)

Returns:

See Also:



60
61
62
 
# File 'lib/vedeu/interfaces/dsl.rb', line 60

def add_buffers!(name)
  Vedeu::Buffers::Buffer.new(name: name).store
end

.add_cursor!(name) ⇒ Vedeu::Cursors::Cursor (private)

Registers a new cursor for the interface unless already registered.

Parameters:

  • name (String|Symbol)

Returns:



69
70
71
 
# File 'lib/vedeu/interfaces/dsl.rb', line 69

def add_cursor!(name)
  Vedeu::Cursors::Cursor.store(name: name)
end

.add_focusable!(name) ⇒ void (private)

This method returns an undefined value.

Registers interface name in focus list unless already registered.

Parameters:

  • name (String|Symbol) 


78
79
80
 
# File 'lib/vedeu/interfaces/dsl.rb', line 78

def add_focusable!(name)
  Vedeu::Models::Focus.add(name)
end

.client(&block) ⇒ Object (private)

Returns the client object which called the DSL method.

Parameters:

  • block (Proc)

Returns:

  • (Object) 


86
87
88
 
# File 'lib/vedeu/interfaces/dsl.rb', line 86

def client(&block)
  eval('self', block.binding)
end

.demodulize(klass) ⇒ String Originally defined in module Common

Removes the module part from the expression in the string.

Examples:

demodulize('Vedeu::SomeModule::SomeClass') # => "SomeClass"

Parameters:

  • klass (Class|String)

Returns:

  • (String)

.interface(name, &block) ⇒ Vedeu::Interfaces::Interface

TODO:

More documentation required.

Register an interface by name which will display output from an event or a command. This provides the means for you to define your the views of your application without their content.

Vedeu.interface :my_interface do
  # ... some code
end

Parameters:

  • name (String|Symbol) —

    The name of the interface. Used to reference the interface throughout your application’s execution lifetime.

  • block (Proc) —

    A set of attributes which define the features of the interface.

Returns:

Raises:



37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/vedeu/interfaces/dsl.rb', line 37

def interface(name, &block)
  fail Vedeu::Error::RequiresBlock unless block_given?
  fail Vedeu::Error::MissingRequired,
       'name not given'.freeze unless present?(name)

  add_buffers!(name)
  add_cursor!(name)
  add_focusable!(name)

  attributes = { client: client(&block), name: name }

  Vedeu::Interfaces::Interface.build(attributes, &block).store
end

.present?(variable) ⇒ Boolean Originally defined in module Common

Returns a boolean indicating whether a variable has a useful value.

Parameters:

  • variable (String|Symbol|Array|Fixnum) —

    The variable to check.

Returns:

  • (Boolean)

.snake_case(name) ⇒ String Originally defined in module Common

Converts a class name to a lowercase snake case string.

Examples:

snake_case(MyClassName) # => "my_class_name"
snake_case(NameSpaced::ClassName)
# => "name_spaced/class_name"

Parameters:

  • name (String)

Returns:

  • (String)

Instance Method Details

#absent?(variable) ⇒ Boolean Originally defined in module Common

Returns a boolean indicating whether a variable is nil or empty.

Parameters:

  • variable (String|Symbol|Array|Fixnum) —

    The variable to check.

Returns:

  • (Boolean)

#attributes ⇒ Hash<Symbol => void> (private) Originally defined in module DSL

Note:

Specific DSL classes may be overriding this method.

Returns the default attributes for the new model.

Returns:

  • (Hash<Symbol => void>)

#background(value = '') ⇒ String Also known as: bg, bgcolor, background=, bg=, bgcolor= Originally defined in module DSL::Presentation

Note:

The last defined background colour for a particular interface, line or stream overrides previously defined entries in the same block.

Define the background colour for an interface, line, or a stream. When called with a block, will create a new stream with the background colour specified. When the block terminates, the background will return to that of the parent.

Examples:

interface 'my_interface' do
  background '#0022ff' # /or/ (blue)
  bgcolor    '#22ff00' # /or/ (blue is overridden to green)
  bg         '#ff0022' #      (green is overridden to red)
  # ...

  lines do
    background '#2200ff'
    # ...

    stream do
      background '#22ff00'
      # ...
    end
  end
end

Parameters:

  • value (String) (defaults to: '') —

    A HTML/CSS value.

Returns:

  • (String)

#border(name = nil, &block) ⇒ Vedeu::Borders::Border Originally defined in module DSL::Shared

Allows the setting of a border for the interface.

Examples:

Vedeu.interface :my_interface do
  border do
    # ... see Vedeu::Borders::DSL for DSL methods for
    #     borders.
  end
end

Parameters:

  • name (String|Symbol) (defaults to: nil) —

    The name of the interface; this is already provided when we define the interface or view, setting it here is just mirroring functionality of Borders::DSL.border.

  • block (Proc)

Returns:

Raises:

See Also:

#border! ⇒ Vedeu::Borders::Border Originally defined in module DSL::Shared

Applies the default border to the interface.

Examples:

Vedeu.interface :my_interface do
  border!

  # ... some code
end

Returns:

#colour(attrs = {}) ⇒ Vedeu::Colours::Colour Also known as: colour= Originally defined in module DSL::Presentation

Note:

Rejects invalid keys and empty/nil attributes. Also, the last defined colour for a particular interface, line or stream overrides previously defined entries in the same block.

Define either or both foreground and background colours for an interface, line or a stream. At least one attribute is required.

Examples:

interface 'my_interface' do
  colour background: '#ff00ff', foreground: '#ffff00'
  # ...

  lines do
    colour background: '#000000', foreground: '#ffffff'
    # ...

    stream do
      colour background: '#000000', foreground: '#ffffff'
      # ...
    end
  end
end

Parameters:

Returns:

#colour_attributes ⇒ Hash<Symbol => String> (private) Originally defined in module DSL::Presentation

Returns:

  • (Hash<Symbol => String>)

#cursor(value = true) ⇒ Vedeu::Cursors::Cursor

Set the cursor visibility on an interface.

Examples:

Vedeu.interface :my_interface do
  cursor  true  # => show the cursor for this interface
  # or...
  cursor  :show # => both of these are equivalent to line
                #    above
  # or...
  cursor!       #
  # ...
end

Vedeu.interface :my_interface do
  cursor false # => hide the cursor for this interface
  # or...
  cursor nil   # => as above
  # ...
end

Vedeu.view :my_interface do
  cursor true # => Specify the visibility of the cursor when
              #    the view is rendered.
  # ...
end

Parameters:

  • value (Boolean) (defaults to: true) —

    Any value other than nil or false will evaluate to true.

Returns:



123
124
125
126
127
 
# File 'lib/vedeu/interfaces/dsl.rb', line 123

def cursor(value = true)
  boolean = value ? true : false

  Vedeu::Cursors::Cursor.store(name: model.name, visible: boolean)
end

#cursor! ⇒ Vedeu::Cursors::Cursor

Set the cursor to visible for the interface.

Returns:



132
133
134
 
# File 'lib/vedeu/interfaces/dsl.rb', line 132

def cursor!
  cursor(true)
end

#delay(value) ⇒ Fixnum|Float

To maintain performance interfaces can be delayed from refreshing too often, the reduces artefacts particularly when resizing the terminal screen.

Examples:

Vedeu.interface :my_interface do
  delay 0.5 # interface will not update more often than
            # every 500ms.
  # ...
end

Parameters:

  • value (Fixnum|Float) —

    Time in seconds. (0.5 = 500ms).

Returns:

  • (Fixnum|Float) 


150
151
152
 
# File 'lib/vedeu/interfaces/dsl.rb', line 150

def delay(value)
  model.delay = value
end

#demodulize(klass) ⇒ String Originally defined in module Common

Removes the module part from the expression in the string.

Examples:

demodulize('Vedeu::SomeModule::SomeClass') # => "SomeClass"

Parameters:

  • klass (Class|String)

Returns:

  • (String)

#focus! ⇒ Array<String>

Note:

If multiple interfaces are defined, and this is included in each, then the last defined will be the interface in focus. However, this behaviour can be overridden:

“‘ruby Vedeu.focus_by_name :some_interface “`

When the above is specified (outside of a ‘Vedeu.interface` declaration), the named interface will be focussed instead.

Specify this interface as being in focus when the application starts.

Returns:

  • (Array<String>) —

    A list of focusable interfaces.



169
170
171
 
# File 'lib/vedeu/interfaces/dsl.rb', line 169

def focus!
  Vedeu::Models::Focus.add(model.name, true) if present?(model.name)
end

#foreground(value = '') ⇒ Object Also known as: fg, fgcolor, foreground=, fg=, fgcolor= Originally defined in module DSL::Presentation

See Also:

#geometry(name = nil, &block) ⇒ Vedeu::Geometry::Geometry Originally defined in module DSL::Shared

Define the geometry for an interface.

Examples:

Vedeu.interface :my_interface do
  geometry do
    # ... see Vedeu::Geometry::DSL for DSL methods for
    #     geometries.
  end
end

Parameters:

  • name (String|Symbol) (defaults to: nil) —

    The name of the interface; this is already provided when we define the interface or view, setting it here is just mirroring functionality of Geometry::DSL.geometry.

  • block (Proc)

Returns:

Raises:

See Also:

#group(name) ⇒ Vedeu::Groups::Group

Specify a group for an interface. Interfaces of the same group can be targetted together; for example you may want to refresh multiple interfaces at once.

Examples:

Vedeu.interface :my_interface do
  group :main_screen
  # ...
end

Parameters:

  • name (String|Symbol) —

    The name of the group to which this interface should belong.

Returns:



186
187
188
189
190
191
192
 
# File 'lib/vedeu/interfaces/dsl.rb', line 186

def group(name)
  return false unless present?(name)

  model.group = name

  Vedeu.groups.by_name(name).add(model.name)
end

#hide! ⇒ Boolean

Set the interface to invisible.

Examples:

Vedeu.interface :my_interface do
  # ... some code
end

Returns:

  • (Boolean) 


247
248
249
 
# File 'lib/vedeu/interfaces/dsl.rb', line 247

def hide!
  visible(false)
end

#initialize(model, client = nil) ⇒ void Originally defined in module DSL

Returns an instance of the DSL class including Vedeu::DSL.

Parameters:

  • model (void) —

    The model class which the DSL class is wrapping.

  • client (void) (defaults to: nil) —

    The class where the DSL methods are being used.

#keymap(name = model.name, &block) ⇒ Object Also known as: keys

Parameters:

  • name (String|Symbol) (defaults to: model.name) —

    The name of the interface to which this keymap should belong.

See Also:



197
198
199
 
# File 'lib/vedeu/interfaces/dsl.rb', line 197

def keymap(name = model.name, &block)
  Vedeu.keymap(name, &block)
end

#name(value) ⇒ String|Symbol

The name of the interface. Used to reference the interface throughout your application’s execution lifetime.

Examples:

Vedeu.interface do
  name :my_interface
  # ...
end

Parameters:

  • value (String|Symbol)

Returns:

  • (String|Symbol) 


214
215
216
 
# File 'lib/vedeu/interfaces/dsl.rb', line 214

def name(value)
  model.name = value
end

#no_cursor! ⇒ Vedeu::Cursors::Cursor

Set the cursor to invisible for the interface.

Returns:



221
222
223
 
# File 'lib/vedeu/interfaces/dsl.rb', line 221

def no_cursor!
  cursor(false)
end

#present?(variable) ⇒ Boolean Originally defined in module Common

Returns a boolean indicating whether a variable has a useful value.

Parameters:

  • variable (String|Symbol|Array|Fixnum) —

    The variable to check.

Returns:

  • (Boolean)

#show! ⇒ Boolean

Set the interface to visible.

Examples:

Vedeu.interface :my_interface do
  show!

  # ... some code
end

Returns:

  • (Boolean) 


235
236
237
 
# File 'lib/vedeu/interfaces/dsl.rb', line 235

def show!
  visible(true)
end

#snake_case(name) ⇒ String Originally defined in module Common

Converts a class name to a lowercase snake case string.

Examples:

snake_case(MyClassName) # => "my_class_name"
snake_case(NameSpaced::ClassName)
# => "name_spaced/class_name"

Parameters:

  • name (String)

Returns:

  • (String)

#style(value) ⇒ Vedeu::Presentation::Style Also known as: style=, styles, styles= Originally defined in module DSL::Presentation

Define a style or styles for an interface, line or a stream.

Examples:

interface 'my_interface' do
  style 'normal'
  # ...
end

lines do
  style ['bold', 'underline']
  # ...
end

stream do
  style 'blink'
  # ...
end

Parameters:

  • value (Array<Symbol>|Array<String>|Symbol|String)

Returns:

#text(value = '', options = {}) ⇒ String Also known as: text=, align, center, centre, left, right, align=, center=, centre=, left=, right= Originally defined in module DSL::Text

Note:

If using the convenience methods; left, centre, center or right, then a specified anchor will be ignored.

Specify the content for a view. Provides the means to align a string (or object responding to ‘to_s`), and add it as a Line or to the Stream.

Examples:

lines do
  centre '...'
end

line do
  right '...'
end

line do
  stream do
    text '...'
  end
end

left 'This will be left aligned.', width: 35
# => 'This will be left aligned.         '

centre 'This will be aligned centrally.', width: 35
# => '  This will be aligned centrally.  '
# centre is also aliased to center

right 'This will be right aligned.', width: 35
# => '        This will be right aligned.'

right 'This will be right aligned.', width: 35,
  anchor: centre

text 'This will be truncated here. More text here.',
  width: 28 # => 'This will be truncated here.'

text 'Padded with hyphens.', width: 25, pad: '-',
  anchor: :right # => '-----Padded with hyphens.'

Parameters:

  • value (String|Object) (defaults to: '') —

    A string or object that responds to ‘to_s`.

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

    Text options.

Options Hash (options):

  • :anchor (Symbol) —

    One of ‘:left`, `:centre`/`:center`, or `:right`.

  • :width (Integer|NilClass) —

    The width of the text stream to add. If the ‘string` provided is longer than this value, the string will be truncated. If no width is provided in the context of ’lines’, then the interface width is used. If no width is provided in the context of a ‘stream’, then no alignment will occur.

  • :pad (String) —

    The character to use to pad the width, by default uses an empty space (0x20). Only when the string is shorter than the specified width.

Returns:

  • (String)

#use(name) ⇒ Vedeu::Interfaces::Interface

Use a value from another model.

Parameters:

  • name (String|Symbol) —

    The name of the interface model you wish to use a value from.

Returns:



256
257
258
 
# File 'lib/vedeu/interfaces/dsl.rb', line 256

def use(name)
  model.repository.by_name(name)
end

#visible(value = true) ⇒ Boolean

Set the visibility of the interface.

Examples:

Vedeu.interface :my_interface do
  visible true  # => show the interface
  # or...
  show!         # => as above
  # ... some code
end

Vedeu.interface :my_interface do
  visible false # => hide the interface
  # or...
  hide!         # => as above
  # ... some code
end

Vedeu.view :my_interface do
  visible false
  # ... some code
end

Parameters:

  • value (Boolean) (defaults to: true) —

    Any value other than nil or false will evaluate to true.

Returns:

  • (Boolean) 


286
287
288
289
290
 
# File 'lib/vedeu/interfaces/dsl.rb', line 286

def visible(value = true)
  boolean = value ? true : false

  model.visible = boolean
end

#zindex(value) ⇒ Fixnum Also known as: z_index, z

Set the zindex of the interface. This controls the render order of interfaces. Interfaces with a lower zindex will render before those with a higher zindex.

Examples:

--4-- # rendered last
--3--
--2--
--1-- # rendered first

Vedeu.interface :my_interface do
  zindex 3
  # ...
end

Parameters:

  • value (Fixnum)

Returns:

  • (Fixnum) 


309
310
311
 
# File 'lib/vedeu/interfaces/dsl.rb', line 309

def zindex(value)
  model.zindex = value
end