vedeu 0.2.12 → 0.3.0

data/lib/vedeu/models/geometry.rb

@@ -1,37 +1,116 @@
+require 'vedeu/dsl/components/geometry'
+require 'vedeu/models/model'
+require 'vedeu/support/esc'
+require 'vedeu/support/terminal'
+
 module Vedeu
 
+  # @todo Consider storing the Terminal size at the time of first creation,
+  # this allows us to return the interface to its original dimensions if
+  # the terminal resizes back to normal size.
+
   # Calculates and provides interface geometry determined by both the client's
   # requirements and the terminal's current viewing area.
   #
   # Geometry for Vedeu, as the same for ANSI terminals, has the origin at
   # top-left, y = 1, x = 1. The 'y' coordinate is deliberately first.
   #
+  #       x    north    xn           # north:  y - 1
+  #     y +--------------+           # top:    y
+  #       |     top      |           # west:   x - 1
+  #       |              |           # left:   x
+  #  west | left   right | east      # right:  xn
+  #       |              |           # east:   xn + 1
+  #       |    bottom    |           # bottom: yn
+  #    yn +--------------+           # south:  yn + 1
+  #            south
+  #
   # @api private
   class Geometry
 
-    attr_reader :attributes, :centred
+    include Vedeu::Model
+
+    attr_accessor :centred, :height, :name, :width
+    attr_reader   :attributes
+    attr_writer   :x, :y
+
+    class << self
+
+      # Build models using a simple DSL when a block is given, otherwise returns
+      # a new instance of the class including this module.
+      #
+      # @see Vedeu::Geometry#initialize
+      def build(attributes = {}, &block)
+        attributes = defaults.merge(attributes)
+
+        model = new(attributes)
+        model.deputy(attributes[:client]).instance_eval(&block) if block_given?
+        model
+      end
+
+      private
+
+      # The default values for a new instance of this class.
+      #
+      # @return [Hash]
+      def defaults
+        {
+          client: nil
+        }
+      end
+
+    end
 
     # Returns a new instance of Geometry.
     #
     # @param attributes [Hash]
+    # @option attributes centred [Boolean]
+    # @option attributes height [Fixnum]
+    # @option attributes name [String]
+    # @option attributes width [Fixnum]
+    # @option attributes x [Fixnum]
+    # @option attributes xn [Fixnum]
+    # @option attributes y [Fixnum]
+    # @option attributes yn [Fixnum]
     # @return [Geometry]
     def initialize(attributes = {})
       @attributes = defaults.merge(attributes)
 
       @centred = @attributes[:centred]
       @height  = @attributes[:height]
+      @name    = @attributes[:name]
       @width   = @attributes[:width]
+      @x       = @attributes[:x]
+      @xn      = @attributes[:xn]
+      @y       = @attributes[:y]
+      @yn      = @attributes[:yn]
+      @repository = Vedeu.geometries
+    end
+
+    # Returns log friendly output.
+    #
+    # @note
+    #   The attribute format is (specified/calculated).
+    #
+    # @return [String]
+    def inspect
+      "<#{self.class.name} (height:(#{@height}/#{height}) " \
+                           "width:(#{@width}/#{width}) " \
+                           "top:#{top} " \
+                           "bottom:#{bottom} " \
+                           "left:#{left} " \
+                           "right:#{right})>"
     end
 
     # Returns the row/line start position for the interface.
     #
     # @return [Fixnum]
     def y
-      if attributes[:y].is_a?(Proc)
-        attributes[:y].call
+      if @y.is_a?(Proc)
+        @y.call
 
       else
-        attributes[:y]
+        @y
 
       end
     end
@@ -40,11 +119,11 @@ module Vedeu
     #
     # @return [Fixnum]
     def yn
-      if attributes[:yn].is_a?(Proc)
-        attributes[:yn].call
+      if @yn.is_a?(Proc)
+        @yn.call
 
       else
-        attributes[:yn]
+        @yn
 
       end
     end
@@ -53,11 +132,11 @@ module Vedeu
     #
     # @return [Fixnum]
     def x
-      if attributes[:x].is_a?(Proc)
-        attributes[:x].call
+      if @x.is_a?(Proc)
+        @x.call
 
       else
-        attributes[:x]
+        @x
 
       end
     end
@@ -66,11 +145,11 @@ module Vedeu
     #
     # @return [Fixnum]
     def xn
-      if attributes[:xn].is_a?(Proc)
-        attributes[:xn].call
+      if @xn.is_a?(Proc)
+        @xn.call
 
       else
-        attributes[:xn]
+        @xn
 
       end
     end
@@ -141,7 +220,6 @@ module Vedeu
 
       end
     end
-    alias_method :y_min, :top
 
     # Returns the row above the top by default.
     #
@@ -171,7 +249,6 @@ module Vedeu
 
       end
     end
-    alias_method :x_min, :left
 
     # Returns the column before left by default.
     #
@@ -258,257 +335,21 @@ module Vedeu
       (left...right).to_a
     end
 
-    # Returns the actual position of y for a given index. Crudely corrects out
-    # of range values.
-    #
-    # @example
-    #   # y_range = [7, 8, 9, 10, 11]
-    #   y_position     # => 7
-    #   y_position(-2) # => 7
-    #   y_position(2)  # => 9
-    #   y_position(7)  # => 11
-    #
-    # @param index [Fixnum]
-    # @return [Fixnum]
-    def y_position(index = 0)
-      if index <= 0
-        y_min
-
-      elsif index >= y_max_index
-        y_max
-
-      else
-        y_range[index]
-
-      end
-    end
-
-    # Returns the actual position of x for a given index. Crudely corrects out
-    # of range values.
-    #
-    # @example
-    #   # x_range = [4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
-    #   x_position     # => 4
-    #   x_position(-2) # => 4
-    #   x_position(2)  # => 6
-    #   x_position(15) # => 13
-    #
-    # @param index [Fixnum]
-    # @return [Fixnum]
-    def x_position(index = 0)
-      if index <= 0
-        x_min
-
-      elsif index >= x_max_index
-        x_max
-
-      else
-        x_range[index]
-
-      end
-    end
-
-    # Provides all the geometry in a convenient hash.
-    #
-    # @return [Hash]
-    def to_h
-      {
-        centred:         centred,
-        height:          height,
-        width:           width,
-        x:               x,
-        y:               y,
-        top:             top,
-        right:           right,
-        bottom:          bottom,
-        left:            left,
-        north:           north,
-        east:            east,
-        south:           south,
-        west:            west,
-        virtual_x:       virtual_x,
-        virtual_y:       virtual_y,
-      }
-    end
-
     private
 
-    # Returns the y coordinate as an offset index in the area's y range. When a
-    # value is provided, the y coordinate is overridden. Crudely corrects out of
-    # range values.
-    #
-    # @example
-    #   # y_range  = [7, 8, 9, 10]
-    #   # y = 8
-    #   y_index     # => 1
-    #   y_index(10) # => 3
-    #   y_index(5)  # => 0
-    #   y_index(15) # => 3
-    #
-    # @param value [Fixnum]
-    # @return [Fixnum]
-    def y_index(value = y)
-      if height <= 0 || value <= y_min
-        0
-
-      elsif value >= y_max
-        y_max_index
-
-      else
-        y_range.index(value)
-
-      end
-    end
-
-    # Returns the x coordinate as an offset index in the area's x range. When a
-    # value is provided, the x coordinate is overridden. Crudely corrects out of
-    # range values.
-    #
-    # @example
-    #   # x_range = [4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
-    #   # x = 8
-    #   x_index     # => 4
-    #   x_index(11) # => 7
-    #   x_index(2)  # => 0
-    #   x_index(15) # => 9
-    #
-    # @param value [Fixnum]
-    # @return [Fixnum]
-    def x_index(value = x)
-      if width <= 0 || value <= x_min
-        0
-
-      elsif value >= x_max
-        x_max_index
-
-      else
-        x_range.index(value)
-
-      end
-    end
-
-    # Returns the maximum y index for an area.
-    #
-    # @example
-    #   # height = 3
-    #   y_max_index # => 2
-    #
-    # @return [Fixnum]
-    def y_max_index
-      return 0 if y_indices.empty?
-
-      y_indices.last
-    end
-
-    # Returns the maximum x index for an area.
-    #
-    # @example
-    #   # width = 6
-    #   x_max_index # => 5
-    #
-    # @return [Fixnum]
-    def x_max_index
-      return 0 if x_indices.empty?
-
-      x_indices.last
-    end
-
-    # Returns the same as #y_range, except as indices of an array.
-    #
-    # @example
-    #   # height = 4
-    #   y_indices # => [0, 1, 2, 3]
-    #
-    # @return [Array]
-    def y_indices
-      (0...height).to_a
-    end
-
-    # Returns the same as #x_range, except as indices of an array.
-    #
-    # @example
-    #   # width = 10
-    #   x_indices # => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
-    #
-    # @return [Array]
-    def x_indices
-      (0...width).to_a
-    end
-
-    # Returns an array with all coordinates from x to x_max.
-    #
-    # @example
-    #   # width = 10
-    #   # x_min = 4
-    #   # x_max = 14
-    #   x_range # => [4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
-    #
-    # @return [Array]
-    def x_range
-      (x_min...x_max).to_a
-    end
-
-    # Returns an array with all coordinates from y to y_max.
-    #
-    # @example
-    #   # height = 4
-    #   # y_min  = 7
-    #   # y_max  = 11
-    #   y_range # => [7, 8, 9, 10]
-    #
-    # @return [Array]
-    def y_range
-      (y_min...y_max).to_a
-    end
-
-    # Returns the maximum y coordinate for an area.
-    #
-    # @example
-    #   # y_min = 2
-    #   # height = 4
-    #   y_max # => 6
-    #
-    # @return [Fixnum]
-    def y_max
-      if height <= 0
-        0
-
-      else
-        y_min + height
-
-      end
-    end
-
-    # Returns the maximum x coordinate for an area.
-    #
-    # @example
-    #   # x_min = 5
-    #   # width = 20
-    #   x_max # => 25
-    #
-    # @return [Fixnum]
-    def x_max
-      if width <= 0
-        0
-
-      else
-        x_min + width
-
-      end
-    end
-
-    # The default geometry of an interface- full screen.
+    # The default values for a new instance of this class.
     #
     # @return [Hash]
     def defaults
       {
-        y:       1,
-        x:       1,
-        width:   Terminal.width,
-        height:  Terminal.height,
         centred: false,
-        yn:      nil,
-        xn:      nil,
+        height:  Terminal.height,
+        name:    '',
+        width:   Terminal.width,
+        x:       1,
+        xn:      Terminal.width,
+        y:       1,
+        yn:      Terminal.height,
       }
     end
 

data/lib/vedeu/{repositories/models → models}/group.rb

@@ -3,18 +3,22 @@ module Vedeu
   # Interfaces can be associated with one another by being members of the same
   # Group. A Group is a collection of interface names.
   #
+  # @api private
   class Group
 
+    include Vedeu::Model
+
     attr_reader :name
 
     # Return a new instance of Group.
     #
     # @param name [String] The name of the group.
-    # @param members [String]
+    # @param members [Array]
     # @return [Group]
-    def initialize(name, *members)
-      @name    = name
-      @members = members.to_set
+    def initialize(name, members = [])
+      @name       = name
+      @members    = Array(members)
+      @repository = Vedeu.groups
     end
 
     # Add a member to the group by name.
@@ -22,16 +26,14 @@ module Vedeu
     # @param member [String]
     # @return [Group]
     def add(member)
-      new_members = @members.add(member)
-
-      Group.new(name, *new_members)
+      Group.new(name, members.add(member)).store
     end
 
-    # Returns the members as a collection.
+    # Return the members as a Set.
     #
-    # @return [Array]
+    # @return [Set]
     def members
-      @members.to_a
+      @members.to_set
     end
 
     # Remove a member from the group by name.
@@ -39,18 +41,18 @@ module Vedeu
     # @param member [String]
     # @return [Group]
     def remove(member)
-      new_members = @members.delete(member)
-
-      Group.new(name, *new_members)
+      Group.new(name, members.delete(member)).store
     end
 
     # Remove all members from the group.
     #
     # @return [Group]
     def reset
-      Group.new(name)
+      Group.new(name).store
     end
 
+    private
+
   end # Group
 
 end # Vedeu

data/lib/vedeu/{repositories/models → models}/menu.rb

@@ -1,3 +1,6 @@
+require 'vedeu/models/model'
+require 'vedeu/support/common'
+
 module Vedeu
 
   # Converts the collection passed into a list of menu items which can be
@@ -6,32 +9,97 @@ module Vedeu
   # @api private
   class Menu
 
-    include Model
+    include Vedeu::Common
+    include Vedeu::Model
 
-    # Returns a new instance of Menu.
-    #
-    # @param collection [Array]
-    # @param name [String]
-    # @return [Menu]
-    def initialize(collection, name = '')
-      @collection = collection
-      @name       = name
-      @current    = 0
-      @selected   = nil
-    end
+    attr_accessor :collection
 
     # Returns the index of the value in the collection which is current.
     #
     # @return [Fixnum]
-    def current
-      @current
-    end
+    attr_accessor :current
+
+    attr_accessor :name
 
     # Returns the index of the value in the collection which is selected.
     #
     # @return [Fixnum]
-    def selected
-      @selected
+    attr_accessor :selected
+
+    class << self
+
+      # @option attributes collection []
+      # @option attributes client []
+      # @option attributes name []
+      # @option attributes current []
+      # @option attributes selected []
+      def build(attributes = {}, &block)
+        attributes = defaults.merge(attributes)
+
+        model = new(attributes[:collection],
+                    attributes[:name],
+                    attributes[:current],
+                    attributes[:selected])
+        model.deputy(attributes[:client]).instance_eval(&block) if block_given?
+        model
+      end
+
+      # Register a menu by name which will display a collection of items for
+      # your users to select; and provide interactivity within your application.
+      #
+      # @param name  [String] The name of the menu. Used to reference the
+      #   menu throughout your application's execution lifetime.
+      # @param block [Proc] A set of attributes which define the features of the
+      #   menu. See {Vedeu::DSL::Menu#items} and {Vedeu::DSL::Menu#name}.
+      #
+      # @example
+      #   Vedeu.menu 'my_interface' do
+      #     items [:item_1, :item_2, :item_3]
+      #     ...
+      #
+      #   Vedeu.menu do
+      #     name 'menus_must_have_a_name'
+      #     items Track.all_my_favourites
+      #     ...
+      #
+      # @raise [InvalidSyntax] The required block was not given.
+      # @return [API::Menu]
+      def menu(name = '', &block)
+        fail InvalidSyntax, 'block not given' unless block_given?
+
+        build({ name: name }, &block).store
+      end
+
+      private
+
+      # The default values for a new instance of this class.
+      #
+      # @return [Hash]
+      def defaults
+        {
+          client:     nil,
+          collection: [],
+          current:    0,
+          name:       '',
+          selected:   nil,
+        }
+      end
+
+    end
+
+    # Returns a new instance of Menu.
+    #
+    # @param collection [Array]
+    # @param name [String]
+    # @param current [Fixnum]
+    # @param selected [Fixnum|NilClass]
+    # @return [Menu]
+    def initialize(collection = [], name = '', current = 0, selected = nil)
+      @collection = collection
+      @name       = name
+      @current    = current
+      @selected   = selected
+      @repository = Vedeu.menus
     end
 
     # Returns the item from the collection which shares the same index as the
@@ -161,11 +229,6 @@ module Vedeu
 
     private
 
-    # @return [Class] The repository class for this model.
-    def repository
-      Vedeu::Menus
-    end
-
   end # Menu
 
 end # Vedeu

data/lib/vedeu/models/model.rb

@@ -0,0 +1,51 @@
+module Vedeu
+
+  # When included into a class, provides the mechanism to store the class in a
+  # repository for later retrieval.
+  #
+  # @api private
+  module Model
+
+    attr_reader :repository
+
+    # Returns a DSL instance responsible for defining the DSL methods of this
+    # model.
+    #
+    # @param client [Object|NilClass] The client binding represents
+    #   the client application object that is currently invoking a DSL method.
+    #   It is required so that we can send messages to the client application
+    #   object should we need to.
+    # @return [void] The DSL instance for this model.
+    def deputy(client = nil)
+      Object.const_get(dsl_class).new(self, client)
+    end
+
+    # @return [void] The model instance stored in the repository.
+    def store
+      repository.store(self) # if valid?
+    end
+
+    private
+
+    # Removes the module part from the expression in the string.
+    #
+    # @example
+    #   demodulize('Vedeu::DSL::Interface') # => "Interface"
+    #
+    # @param klass [Class|String]
+    def demodulize(klass)
+      klass = klass.to_s
+
+      klass[(klass.rindex('::') + 2)..-1]
+    end
+
+    # Returns the DSL class name responsible for this model.
+    #
+    # @return [String]
+    def dsl_class
+      'Vedeu::DSL::' + demodulize(self.class.name)
+    end
+
+  end # Model
+
+end # Vedeu

data/lib/vedeu/models/view/all.rb

@@ -0,0 +1,12 @@
+require 'vedeu/models/view/chars'
+require 'vedeu/models/view/char'
+require 'vedeu/models/view/composition'
+require 'vedeu/models/view/interfaces'
+require 'vedeu/models/view/interface'
+require 'vedeu/models/view/lines'
+require 'vedeu/models/view/line'
+require 'vedeu/models/view/streams'
+require 'vedeu/models/view/stream'
+
+module Vedeu
+end # Vedeu