vedeu 0.6.35 → 0.6.36

data/lib/vedeu/geometry/alignment.rb

@@ -2,8 +2,13 @@ module Vedeu
 
   module Geometry
 
-    # Provides the mechanism to align an interface/view horizontally
-    # to the available terminal space.
+    # The subclasses of this class, HorizontalAlignment and
+    # VerticalAlignment provide the mechanism to align an interface or
+    # view horizontally or vertically within the available terminal
+    # space.
+    #
+    # @see Vedeu::Geometry::HorizontalAlignment
+    # @see Vedeu::Geometry::VerticalAlignment
     #
     class Alignment
 
@@ -19,33 +24,17 @@ module Vedeu
         @value = value
       end
 
-      # @raise [Vedeu::Error::InvalidSyntax] When the value is not one
-      #   of :centre, :left, :right
-      # @return [Symbol]
+      # @raise [Vedeu::Error::NotImplemented] Subclasses of this class
+      #   must implement this method.
       def align
-        return value if valid?
-
-        fail Vedeu::Error::InvalidSyntax,
-             'Cannot align as value is invalid or undefined.'.freeze
+        fail Vedeu::Error::NotImplemented, 'Subclasses implement this.'.freeze
       end
 
       private
 
-      # @return [Boolean]
-      def align_value?
-        @value.to_s.start_with?('align_')
-      end
-
-      # @return [Symbol]
-      def coerced_value
-        coerced = @value.to_s.gsub!('align_', '').to_sym
-
-        coerced == :center ? :centre : coerced
-      end
-
       # @return [Boolean]
       def none?
-        @value.nil? || !(@value.is_a?(Symbol)) || @value == :alignment
+        @value.nil? || !(@value.is_a?(Symbol))
       end
 
       # @return [Boolean]
@@ -61,9 +50,6 @@ module Vedeu
                     elsif @value == :center
                       :centre
 
-                    elsif align_value?
-                      coerced_value
-
                     else
                       @value.to_sym
 
@@ -73,10 +59,13 @@ module Vedeu
       # @return [Array<Symbol>]
       def values
         [
+          :bottom,
           :centre,
           :left,
+          :middle,
           :none,
           :right,
+          :top,
         ]
       end
 

data/lib/vedeu/geometry/all.rb

@@ -14,9 +14,13 @@ module Vedeu
 end # Vedeu
 
 require 'vedeu/geometry/alignment'
+require 'vedeu/geometry/horizontal_alignment'
+require 'vedeu/geometry/vertical_alignment'
 require 'vedeu/geometry/area'
 require 'vedeu/geometry/coordinate'
 require 'vedeu/geometry/dimension'
+require 'vedeu/geometry/x_dimension'
+require 'vedeu/geometry/y_dimension'
 require 'vedeu/geometry/dsl'
 require 'vedeu/geometry/coordinate'
 require 'vedeu/geometry/geometry'

data/lib/vedeu/geometry/area.rb

@@ -41,29 +41,30 @@ module Vedeu
       # @option attributes x_default [Fixnum]
       # @option attributes maximised [Boolean]
       # @option attributes centred [Boolean]
-      # @option attributes alignment [Symbol]
+      # @option attributes horizontal_alignment [Symbol]
+      # @option attributes vertical_alignment [Symbol]
       # @return [Vedeu::Geometry::Area]
       def self.from_attributes(attributes = {})
         y_attributes = {
-          d:         attributes[:y],
-          dn:        attributes[:yn],
-          d_dn:      attributes[:y_yn],
-          default:   Vedeu.height,
-          maximised: attributes[:maximised],
-          centred:   attributes[:centred],
-          # alignment: attributes[:alignment],
+          d:                  attributes[:y],
+          dn:                 attributes[:yn],
+          d_dn:               attributes[:y_yn],
+          default:            Vedeu.height,
+          maximised:          attributes[:maximised],
+          centred:            attributes[:centred],
+          vertical_alignment: attributes[:vertical_alignment],
         }
         x_attributes = {
-          d:         attributes[:x],
-          dn:        attributes[:xn],
-          d_dn:      attributes[:x_xn],
-          default:   Vedeu.width,
-          maximised: attributes[:maximised],
-          centred:   attributes[:centred],
-          alignment: attributes[:alignment],
+          d:                    attributes[:x],
+          dn:                   attributes[:xn],
+          d_dn:                 attributes[:x_xn],
+          default:              Vedeu.width,
+          maximised:            attributes[:maximised],
+          centred:              attributes[:centred],
+          horizontal_alignment: attributes[:horizontal_alignment],
         }
-        y_yn = Vedeu::Geometry::Dimension.pair(y_attributes)
-        x_xn = Vedeu::Geometry::Dimension.pair(x_attributes)
+        y_yn = Vedeu::Geometry::YDimension.pair(y_attributes)
+        x_xn = Vedeu::Geometry::XDimension.pair(x_attributes)
 
         new(y: y_yn[0], yn: y_yn[-1], x: x_xn[0], xn: x_xn[-1])
       end

data/lib/vedeu/geometry/dimension.rb

@@ -24,7 +24,8 @@ module Vedeu
       #   The terminal width or height.
       # @option attributes maximised [Boolean]
       # @option attributes centered [Boolean]
-      # @option attributes alignment [Symbol]
+      # @option attributes horizontal_alignment [Symbol]
+      # @option attributes vertical_alignment [Symbol]
       # @return [Vedeu::Geometry::Dimension]
       def initialize(attributes = {})
         defaults.merge!(attributes).each do |key, value|
@@ -32,20 +33,6 @@ module Vedeu
         end
       end
 
-      # Fetch the starting coordinate.
-      #
-      # @return [Fixnum]
-      def d1
-        dimension[0] < 1 ? 1 : dimension[0]
-      end
-
-      # Fetch the ending coordinate.
-      #
-      # @return [Fixnum]
-      def d2
-        dimension[-1]
-      end
-
       # Fetch the coordinates.
       #
       # @return [Array<Fixnum>]
@@ -81,12 +68,22 @@ module Vedeu
       attr_reader :centred
       alias_method :centred?, :centred
 
-      # @!attribute [r] alignment
+      # @!attribute [r] horizontal_alignment
       # @return [Symbol]
-      attr_reader :alignment
+      attr_reader :horizontal_alignment
+
+      # @!attribute [r] vertical_alignment
+      # @return [Symbol]
+      attr_reader :vertical_alignment
 
       private
 
+      # @raise [Vedeu::Error::NotImplemented] Subclasses of this class
+      #   must implement this method.
+      def alignment
+        fail Vedeu::Error::NotImplemented, 'Subclasses implement this.'.freeze
+      end
+
       # Return the dimension.
       #
       # 1) If maximised, it will be from the first row/line or column/
@@ -99,15 +96,24 @@ module Vedeu
         @dimension = if maximised?
                        [1, default]
 
+                     elsif bottom_aligned?
+                       [bottom_d, default]
+
                      elsif centre_aligned?
                        [centred_d, centred_dn]
 
                      elsif left_aligned?
                        [1, left_dn]
 
+                     elsif middle_aligned?
+                       [centred_d, centred_dn]
+
                      elsif right_aligned?
                        [right_d, default]
 
+                     elsif top_aligned?
+                       [1, top_dn]
+
                      elsif centred? && length?
                        [centred_d, centred_dn]
 
@@ -173,6 +179,13 @@ module Vedeu
         dn > default ? default : dn
       end
 
+      # Ascertains the ending coordinate for a left or top aligned
+      # interface/view.
+      #
+      # 1) Use the width or height (d_dn), or
+      # 2) Use the xn or yn (dn), or
+      # 3) Default to the terminal width or height.
+      #
       # @return [Fixnum]
       def left_dn
         if d_dn
@@ -186,7 +199,15 @@ module Vedeu
 
         end
       end
+      alias_method :top_dn, :left_dn
 
+      # Ascertains the starting coordinate for a right or bottom
+      # aligned interface/view.
+      #
+      # 1) Use the width or height (d_dn), or
+      # 2) Use the x or y (d), or
+      # 3) Default to 1.
+      #
       # @return [Fixnum]
       def right_d
         if d_dn
@@ -200,6 +221,7 @@ module Vedeu
 
         end
       end
+      alias_method :bottom_d, :right_d
 
       # Fetch the starting coordinate, or use 1 when not set.
       #
@@ -244,6 +266,20 @@ module Vedeu
         alignment == :left
       end
 
+      # Return a boolean indicating alignment was set to :middle.
+      #
+      # @return [Boolean]
+      def middle_aligned?
+        alignment == :middle
+      end
+
+      # Return a boolean indicating alignment was set to :bottom.
+      #
+      # @return [Boolean]
+      def bottom_aligned?
+        alignment == :bottom
+      end
+
       # Return a boolean indicating alignment was set to :centre.
       #
       # @return [Boolean]
@@ -258,9 +294,16 @@ module Vedeu
         alignment == :right
       end
 
+      # Return a boolean indicating alignment was set to :top.
+      #
+      # @return [Boolean]
+      def top_aligned?
+        alignment == :top
+      end
+
       # Returns the default options/attributes for this class.
       #
-      # @return [Hash<Symbol => NilClass,Boolean>]
+      # @return [Hash<Symbol => NilClass,Boolean,Symbol>]
       def defaults
         {
           d:         nil,
@@ -269,7 +312,6 @@ module Vedeu
           default:   nil,
           centred:   false,
           maximised: false,
-          alignment: Vedeu::Geometry::Alignment.align(:none),
         }
       end
 

data/lib/vedeu/geometry/dsl.rb

@@ -114,59 +114,204 @@ module Vedeu
       # @raise [Vedeu::Error::InvalidSyntax] When the value or width
       #   is not given.
       # @return [Vedeu::Geometry::Geometry]
-      def alignment(value, width)
+      # def alignment(value, width)
+      #   fail Vedeu::Error::InvalidSyntax,
+      #        'No alignment given. Valid values are :center, :centre, ' \
+      #        ':left, :none, :right.'.freeze unless present?(value)
+      #   fail Vedeu::Error::InvalidSyntax,
+      #        'No width given.'.freeze unless present?(width)
+
+      #   model.alignment = Vedeu::Geometry::Alignment.align(value)
+      #   model.width     = width
+      #   model
+      # end
+
+      # Align the interface/view horizontally or vertically within
+      # the terminal.
+      #
+      # @param vertical [Symbol] One of :bottom, :middle, :none, :top.
+      # @param horizontal [Symbol] One of :center, :centre, :left,
+      #   :none, :right.
+      # @param width [Fixnum] The number of characters/columns wide;
+      #   this is required when the given value for horizontal is any
+      #   value other than :none.
+      # @param height [Fixnum] The number of lines/rows tall; this is
+      #   required when the given value for vertical is any value
+      #   other than :none.
+      # @raise [Vedeu::Error::InvalidSyntax]
+      #   - When the vertical is not given.
+      #   - When the horizontal is not given.
+      #   - When the horizontal is given (and not :none) and the width
+      #     is not given.
+      #   - When the vertical is given (and not :none) and the height
+      #     is not given.
+      # @return [Vedeu::Geometry::Geometry]
+      def align(vertical, horizontal, width, height)
+        fail Vedeu::Error::InvalidSyntax,
+             'No vertical alignment given. Valid values are :bottom, ' \
+             ':middle, :none, :top.'.freeze unless present?(vertical)
+        fail Vedeu::Error::InvalidSyntax,
+             'No horizontal alignment given. Valid values are :center, ' \
+             ':centre, :left, :none, :right.'.freeze unless present?(horizontal)
+
+        unless vertical == :none
+          fail Vedeu::Error::InvalidSyntax,
+               'No height given.'.freeze if absent?(height)
+        end
+
+        unless horizontal == :none
+          fail Vedeu::Error::InvalidSyntax,
+               'No width given.'.freeze if absent?(width)
+        end
+
+        horizontal_alignment(horizontal, width)
+        vertical_alignment(vertical, height)
+      end
+
+      # @param value [Symbol] One of :center, :centre, :left, :none,
+      #   :right.
+      # @param width [Fixnum] The number of characters/columns.
+      # @return [Vedeu::Geometry::Geometry]
+      def horizontal_alignment(value, width)
         fail Vedeu::Error::InvalidSyntax,
-             'No alignment given. Valid values are :center, :centre, :left, ' \
-             ':none, :right.'.freeze unless present?(value)
+             'No horizontal alignment given. Valid values are :center, ' \
+             ':centre, :left, :none, :right.'.freeze unless present?(value)
         fail Vedeu::Error::InvalidSyntax,
              'No width given.'.freeze unless present?(width)
 
-        model.alignment = Vedeu::Geometry::Alignment.align(value)
-        model.width     = width
+        model.horizontal_alignment = Vedeu::Geometry::HorizontalAlignment
+          .align(value)
+        model.width = width
+        model
+      end
+
+      # @param value [Symbol] One of :bottom, :middle, :none, :top.
+      # @param height [Fixnum] The number of lines/rows.
+      # @return [Vedeu::Geometry::Geometry]
+      def vertical_alignment(value, height)
+        fail Vedeu::Error::InvalidSyntax,
+             'No vertical alignment given. Valid values are :bottom, ' \
+             ':middle, :none, :top.'.freeze unless present?(value)
+        fail Vedeu::Error::InvalidSyntax,
+             'No height given.'.freeze unless present?(height)
+
+        model.vertical_alignment = Vedeu::Geometry::VerticalAlignment
+          .align(value)
+        model.height = height
         model
       end
 
-      # Align the interface/view centrally.
+      # Vertically align the interface/view to the bottom of the
+      # terminal.
+      #
+      #   Vedeu.geometry :some_interface do
+      #     # `height` is a positive integer, e.g. 30
+      #     align_bottom 30
+      #
+      #     # this is the same as:
+      #     # vertical_alignment(:bottom, 30)
+      #
+      #     # or you can use: (see notes)
+      #     # align(:bottom, :none, Vedeu.width, 30)
+      #
+      #     # ... some code
+      #   end
+      #
+      # @note
+      #   Vedeu.width in the example above will set the width to the
+      #   default width of the terminal, this can be substituted for
+      #   your own positive integer.
+      # @param height [Fixnum] The number of lines/rows.
+      # @raise [Vedeu::Error::InvalidSyntax] When the height is not
+      #   given.
+      # @return [Vedeu::Geometry::Geometry]
+      def align_bottom(height)
+        vertical_alignment(:bottom, height)
+      end
+
+      # Horizontally align the interface/view centrally.
       #
       #   Vedeu.geometry :some_interface do
       #     # `width` is a positive integer, e.g. 30
       #     align_centre 30
       #
       #     # this is the same as:
-      #     # alignment(:centre, 30)
+      #     # horizontal_alignment(:centre, 30)
+      #
+      #     # or you can use: (see notes)
+      #     # align(:none, :centre, 30, Vedeu.height)
       #
       #     # ... some code
       #   end
       #
       #   # Also allows `align_center` if preferred.
       #
+      # @note
+      #   Vedeu.height in the example above will set the height to the
+      #   default height of the terminal, this can be substituted for
+      #   your own positive integer.
       # @param width [Fixnum] The number of characters/columns.
       # @raise [Vedeu::Error::InvalidSyntax] When the width is not
       #   given.
       # @return [Vedeu::Geometry::Geometry]
       def align_centre(width)
-        alignment(:centre, width)
+        horizontal_alignment(:centre, width)
       end
       alias_method :align_center, :align_centre
 
-      # Align the interface/view to the left.
+      # Horizontally align the interface/view to the left.
       #
       #   Vedeu.geometry :some_interface do
       #     # `width` is a positive integer, e.g. 30
       #     align_left 30
       #
       #     # this is the same as:
-      #     # alignment(:left, 30)
+      #     # horizontal_alignment(:left, 30)
+      #
+      #     # or you can use: (see notes)
+      #     # align(:none, :left, 30, Vedeu.height)
       #
       #     # ... some code
       #   end
       #
+      # @note
+      #   Vedeu.height in the example above will set the height to the
+      #   default height of the terminal, this can be substituted for
+      #   your own positive integer.
       # @param width [Fixnum] The number of characters/columns.
       # @raise [Vedeu::Error::InvalidSyntax] When the width is not
       #   given.
       # @return [Vedeu::Geometry::Geometry]
       def align_left(width)
-        alignment(:left, width)
+        horizontal_alignment(:left, width)
+      end
+
+      # Vertically align the interface/view to the middle of the
+      # terminal.
+      #
+      #   Vedeu.geometry :some_interface do
+      #     # `height` is a positive integer, e.g. 30
+      #     align_middle 30
+      #
+      #     # this is the same as:
+      #     # vertical_alignment(:middle, 30)
+      #
+      #     # or you can use: (see notes)
+      #     # align(:middle, :none, Vedeu.width, 30)
+      #
+      #     # ... some code
+      #   end
+      #
+      # @note
+      #   Vedeu.width in the example above will set the width to the
+      #   default width of the terminal, this can be substituted for
+      #   your own positive integer.
+      # @param height [Fixnum] The number of lines/rows.
+      # @raise [Vedeu::Error::InvalidSyntax] When the height is not
+      #   given.
+      # @return [Vedeu::Geometry::Geometry]
+      def align_middle(height)
+        vertical_alignment(:middle, height)
       end
 
       # Align the interface/view to the right.
@@ -176,17 +321,52 @@ module Vedeu
       #     align_right 30
       #
       #     # this is the same as:
-      #     # alignment(:right, 30)
+      #     # horizontal_alignment(:right, 30)
+      #
+      #     # or you can use: (see notes)
+      #     # align(:none, :right, 30, Vedeu.height)
       #
       #     # ... some code
       #   end
       #
+      # @note
+      #   Vedeu.height in the example above will set the height to the
+      #   default height of the terminal, this can be substituted for
+      #   your own positive integer.
       # @param width [Fixnum] The number of characters/columns.
       # @raise [Vedeu::Error::InvalidSyntax] When the width is not
       #   given.
       # @return [Vedeu::Geometry::Geometry]
       def align_right(width)
-        alignment(:right, width)
+        horizontal_alignment(:right, width)
+      end
+
+      # Vertically align the interface/view to the top of the
+      # terminal.
+      #
+      #   Vedeu.geometry :some_interface do
+      #     # `height` is a positive integer, e.g. 30
+      #     align_top 30
+      #
+      #     # this is the same as:
+      #     # vertical_alignment(:top, 30)
+      #
+      #     # or you can use: (see notes)
+      #     # align(:top, :none, Vedeu.width, 30)
+      #
+      #     # ... some code
+      #   end
+      #
+      # @note
+      #   Vedeu.width in the example above will set the width to the
+      #   default width of the terminal, this can be substituted for
+      #   your own positive integer.
+      # @param height [Fixnum] The number of lines/rows.
+      # @raise [Vedeu::Error::InvalidSyntax] When the height is not
+      #   given.
+      # @return [Vedeu::Geometry::Geometry]
+      def align_top(height)
+        vertical_alignment(:top, height)
       end
 
       # Instructs Vedeu to calculate x and y geometry automatically