Class: Vedeu::Interfaces::DSL

Inherits:
Object
  • Object
show all
Extended by:
Common
Includes:
Common, Cursors::DSL, 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

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

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:



66
67
68
 
# File 'lib/vedeu/interfaces/dsl.rb', line 66

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:



75
76
77
 
# File 'lib/vedeu/interfaces/dsl.rb', line 75

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

.add_editor!(name) ⇒ Object (private)

Registers a new document with the interface.

Parameters:

  • name (String|Symbol) 


82
83
84
 
# File 'lib/vedeu/interfaces/dsl.rb', line 82

def add_editor!(name)
  Vedeu::Editor::Document.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) 


91
92
93
 
# File 'lib/vedeu/interfaces/dsl.rb', line 91

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) 


99
100
101
 
# File 'lib/vedeu/interfaces/dsl.rb', line 99

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

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

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

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:



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/vedeu/interfaces/dsl.rb', line 38

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

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

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

  add_buffers!(name)
  add_cursor!(name)
  add_editor!(name) if interface.editable?
  add_focusable!(name)

  interface
end

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

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

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

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

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

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

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 Originally defined in module Cursors::DSL

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:

#cursor! ⇒ Vedeu::Cursors::Cursor Also known as: show_cursor! Originally defined in module Cursors::DSL

Set the cursor to visible for the interface or view.

Returns:

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


119
120
121
 
# File 'lib/vedeu/interfaces/dsl.rb', line 119

def delay(value)
  model.delay = value
end

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

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

Removes the module part from the expression in the string.

Examples:

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

Parameters:

  • klass (Class|String)

Returns:

  • (String)

#editable(value = true) ⇒ Boolean

Note:

When an interface is made editable, then the cursor visibility will be set to visible.

Set whether the interface is editable.

Examples:

Vedeu.interface :my_interface do
  editable true # => The interface/view can be edited.

  # or...

  editable! # => Convenience method for above.

  # ...
end

Vedeu.interface :my_interface do
  editable false # => The interface/view cannot be edited.

  # or...

  editable # => as above
  # ...
end

Parameters:

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

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

Returns:

  • (Boolean) 


153
154
155
156
157
158
159
 
# File 'lib/vedeu/interfaces/dsl.rb', line 153

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

  cursor(true) if boolean

  model.editable = boolean
end

#editable! ⇒ Boolean

Set the interface to be editable.

Returns:

  • (Boolean) 


164
165
166
 
# File 'lib/vedeu/interfaces/dsl.rb', line 164

def editable!
  editable(true)
end

#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.



183
184
185
 
# File 'lib/vedeu/interfaces/dsl.rb', line 183

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:



200
201
202
203
204
205
206
 
# File 'lib/vedeu/interfaces/dsl.rb', line 200

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) 


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

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:



211
212
213
 
# File 'lib/vedeu/interfaces/dsl.rb', line 211

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) 


228
229
230
 
# File 'lib/vedeu/interfaces/dsl.rb', line 228

def name(value)
  model.name = value
end

#no_cursor! ⇒ Vedeu::Cursors::Cursor Also known as: hide_cursor! Originally defined in module Cursors::DSL

Set the cursor to invisible for the interface or view.

Returns:

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

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

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 Also known as: visible!

Set the interface to visible.

Examples:

Vedeu.interface :my_interface do
  show!

  # ... some code
end

Returns:

  • (Boolean) 


242
243
244
 
# File 'lib/vedeu/interfaces/dsl.rb', line 242

def show!
  visible(true)
end

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

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

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<Symbol => void>) (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:



264
265
266
 
# File 'lib/vedeu/interfaces/dsl.rb', line 264

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) 


294
295
296
297
298
 
# File 'lib/vedeu/interfaces/dsl.rb', line 294

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) 


317
318
319
 
# File 'lib/vedeu/interfaces/dsl.rb', line 317

def zindex(value)
  model.zindex = value
end