vedeu 0.2.12 → 0.3.0

data/lib/vedeu/cursor/move_cursor.rb

@@ -0,0 +1,137 @@
+require 'vedeu/cursor/cursor'
+require 'vedeu/support/position_validator'
+
+module Vedeu
+
+  # Adjusts the position of the cursor.
+  #
+  class MoveCursor
+
+    extend Forwardable
+
+    def_delegators :@interface, :border,
+                                :border?,
+                                :geometry
+
+    def_delegators :geometry, :left,
+                              :top,
+                              :height,
+                              :width,
+                              :x,
+                              :y
+
+    # @param cursor    [Cursor]
+    # @param interface [Interface]
+    # @param dy        [Fixnum] Move up (-1), or down (1), or no action (0).
+    # @param dx        [Fixnum] Move left (-1), or right (1), or no action (0).
+    # @return [MoveCursor]
+    def initialize(cursor, interface, dy, dx)
+      @cursor    = cursor
+      @dy        = dy
+      @dx        = dx
+      @interface = interface
+    end
+
+    # Moves the cursor down by one row.
+    #
+    # @return [Cursor]
+    def self.down(cursor, interface)
+      new(cursor, interface, 1, 0).move
+    end
+
+    # Moves the cursor left by one column.
+    #
+    # @return [Cursor]
+    def self.left(cursor, interface)
+      return cursor unless cursor.ox > 0
+
+      new(cursor, interface, 0, -1).move
+    end
+
+    # Moves the cursor right by one column.
+    #
+    # @return [Cursor]
+    def self.right(cursor, interface)
+      new(cursor, interface, 0, 1).move
+    end
+
+    # Moves the cursor up by one row.
+    #
+    # @return [Cursor]
+    def self.up(cursor, interface)
+      return cursor unless cursor.oy > 0
+
+      new(cursor, interface, -1, 0).move
+    end
+
+    # Moves the cursor to the top left coordinate of the interface.
+    #
+    # @return [Cursor]
+    def self.origin(cursor, interface)
+      new(cursor, interface, (0 - cursor.y), (0 - cursor.x)).move
+    end
+
+    # Returns a newly positioned and stored Cursor.
+    #
+    # @return [Cursor]
+    def move
+      Cursor.new(cursor.attributes.merge(moved_attributes)).store
+    end
+
+    private
+
+    attr_reader :cursor, :dx, :dy, :interface
+
+    # @return [Hash]
+    def moved_attributes
+      {
+        x:  validator.x,
+        y:  validator.y,
+        ox: ox,
+        oy: oy,
+      }
+    end
+
+    # @return [PositionValidator]
+    def validator
+      @validator ||= Vedeu::PositionValidator.validate(interface,
+                                   coordinate.x_position(ox),
+                                   coordinate.y_position(oy))
+    end
+
+    # @return [Fixnum]
+    def ox
+      ox = cursor.ox + dx
+      ox = 0 if ox < 0
+      ox
+    end
+
+    # @return [Fixnum]
+    def oy
+      oy = cursor.oy + dy
+      oy = 0 if oy < 0
+      oy
+    end
+
+    # @return [Coordinate]
+    def coordinate
+      @coordinate ||= Coordinate.new(bordered_height, bordered_width, left, top)
+    end
+
+    # @return [Fixnum]
+    def bordered_height
+      return border.height if border?
+
+      height
+    end
+
+    # @return [Fixnum]
+    def bordered_width
+      return border.width if border?
+
+      width
+    end
+
+  end # MoveCursor
+
+end # Vedeu

data/lib/vedeu/cursor/toggle_cursor.rb

@@ -0,0 +1,53 @@
+module Vedeu
+
+  # Adjusts the visibility of the cursor.
+  #
+  class ToggleCursor
+
+    # @param cursor [Cursor]
+    # @return [ToggleCursor]
+    def initialize(cursor)
+      @cursor = cursor
+    end
+
+    # Hides the cursor.
+    #
+    # @param cursor [Cursor]
+    # @return [Cursor]
+    def self.hide(cursor)
+      return cursor if cursor.invisible?
+
+      new(cursor).hide
+    end
+
+    # Shows the cursor.
+    #
+    # @param cursor [Cursor]
+    # @return [Cursor]
+    def self.show(cursor)
+      return cursor if cursor.visible?
+
+      new(cursor).show
+    end
+
+    # Hides the cursor.
+    #
+    # @return [Cursor]
+    def hide
+      cursor.class.new(cursor.attributes.merge({ state: false })).store
+    end
+
+    # Shows the cursor.
+    #
+    # @return [Cursor]
+    def show
+      cursor.class.new(cursor.attributes.merge({ state: true })).store
+    end
+
+    private
+
+    attr_reader :cursor
+
+  end # ToggleCursor
+
+end # Vedeu

data/lib/vedeu/dsl/all.rb

@@ -0,0 +1,28 @@
+require 'vedeu/dsl/components/all'
+require 'vedeu/dsl/shared/all'
+
+require 'vedeu/dsl/composition'
+require 'vedeu/dsl/interface'
+require 'vedeu/dsl/line'
+require 'vedeu/dsl/stream'
+require 'vedeu/dsl/view'
+
+module Vedeu
+
+  module DSL
+
+    # Attempts to find the missing method on the client object.
+    #
+    # @param method [Symbol] The name of the method sought.
+    # @param args [Array] The arguments which the method was to be invoked with.
+    # @param block [Proc] The optional block provided to the method.
+    # @return []
+    def method_missing(method, *args, &block)
+      Vedeu.log("!!!method_missing '#{method}'")
+
+      client.send(method, *args, &block) if client
+    end
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/components/all.rb

@@ -0,0 +1,7 @@
+require 'vedeu/dsl/components/border'
+require 'vedeu/dsl/components/geometry'
+require 'vedeu/dsl/components/keymap'
+require 'vedeu/dsl/components/menu'
+
+module Vedeu
+end # Vedeu

data/lib/vedeu/dsl/components/border.rb

@@ -0,0 +1,104 @@
+require 'vedeu/dsl/shared/all'
+
+module Vedeu
+
+  module DSL
+
+    # DSL for creating borders for interfaces.
+    #
+    # Allows customisation for the border's sides and corners; a custom
+    # foreground and background, style, and whether a particular side should be
+    # drawn or not.
+    class Border
+
+      include Vedeu::DSL
+      include Vedeu::DSL::Colour
+      include Vedeu::DSL::Style
+
+      # Returns an instance of DSL::Border.
+      #
+      # @param model [Border]
+      def initialize(model, client = nil)
+        @model  = model
+        @client = client
+      end
+
+      # @param char [String] Character to be used as the bottom left border
+      #   character.
+      # @return [String]
+      def bottom_left(char)
+        model.attributes[:bottom_left] = char
+      end
+
+      # @param char [String] Character to be used as the bottom right border
+      #   character.
+      # @return [String]
+      def bottom_right(char)
+        model.attributes[:bottom_right] = char
+      end
+
+      # @param char [String] Character to be used as the horizontal border
+      #   character.
+      # @return [String]
+      def horizontal(char)
+        model.attributes[:horizontal] = char
+      end
+
+      # @param boolean [Boolean] All values evaluate as true except nil and
+      #   false.
+      # @return [Boolean]
+      def show_bottom(boolean)
+        model.attributes[:show_bottom] = !!boolean
+      end
+
+      # @param boolean [Boolean] All values evaluate as true except nil and
+      #   false.
+      # @return [Boolean]
+      def show_left(boolean)
+        model.attributes[:show_left] = !!boolean
+      end
+
+      # @param boolean [Boolean] All values evaluate as true except nil and
+      #   false.
+      # @return [Boolean]
+      def show_right(boolean)
+        model.attributes[:show_right] = !!boolean
+      end
+
+      # @param boolean [Boolean] All values evaluate as true except nil and
+      #   false.
+      # @return [Boolean]
+      def show_top(boolean)
+        model.attributes[:show_top] = !!boolean
+      end
+
+      # @param char [String] Character to be used as the top left border
+      #   character.
+      # @return [String]
+      def top_left(char)
+        model.attributes[:top_left] = char
+      end
+
+      # @param char [String] Character to be used as the top right border
+      #   character.
+      # @return [String]
+      def top_right(char)
+        model.attributes[:top_right] = char
+      end
+
+      # @param char [String] Character to be used as the vertical border
+      #   character.
+      # @return [String]
+      def vertical(char)
+        model.attributes[:vertical] = char
+      end
+
+      private
+
+      attr_reader :client, :model
+
+    end # Border
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/components/geometry.rb

@@ -0,0 +1,153 @@
+require 'vedeu/dsl/shared/use'
+
+module Vedeu
+
+  module DSL
+
+    # Provide DSL methods for configuring the geometry of an interface.
+    #
+    class Geometry
+
+      include Vedeu::DSL
+      include Vedeu::DSL::Use
+
+      class << self
+
+        def geometry(name, &block)
+          fail InvalidSyntax, 'block not given' unless block_given?
+
+          Vedeu::Geometry.build({ name: name }, &block).store
+        end
+
+      end
+
+      # Returns an instance of DSL::Geometry.
+      #
+      # @param model [Geometry]
+      def initialize(model, client = nil)
+        @model  = model
+        @client = client
+      end
+
+      # Instructs Vedeu to calculate x and y geometry automatically based on the
+      # centre character of the terminal, the width and the height.
+      #
+      # @param value [Boolean] Any value other than nil or false will evaluate
+      #   to true.
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     geometry do
+      #       centred!
+      #
+      #   interface 'my_interface' do
+      #     geometry do
+      #       centred false
+      #       ...
+      #
+      # @return [Boolean]
+      def centred(value = true)
+        model.centred = !!value
+      end
+      alias_method :centred!, :centred
+
+      # Specify the number of characters/rows/lines tall the interface will be.
+      #
+      # @param value [Fixnum]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     geometry do
+      #       height 8
+      #       ...
+      #
+      # @return [Fixnum]
+      def height(value)
+        model.height = value
+      end
+
+      # Specify the name of the interface for which the geometry belongs.
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     geometry do
+      #       name 'my_interface'
+      #       ...
+      #
+      # @param value [String]
+      # @return [String]
+      def name(value)
+        model.name = value
+      end
+
+      # Specify the number of characters/columns wide the interface will be.
+      #
+      # @param value [Fixnum]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     geometry do
+      #       width 25
+      #       ...
+      #
+      # @return [Fixnum]
+      def width(value)
+        model.width = value
+      end
+
+      # Specify the starting x position (column) of the interface.
+      #
+      # @param value [Fixnum]
+      # @param block [Proc]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     geometry do
+      #       x 7 # start on column 7.
+      #
+      #   interface 'other_interface' do
+      #     geometry do
+      #       x { use('my_interface').east } # start on column 8, if
+      #                                      # `my_interface` changes position,
+      #                                      # `other_interface` will too.
+      #
+      # @return [Fixnum]
+      def x(value = 0, &block)
+        return model.x = block if block_given?
+
+        model.x = value
+      end
+
+      # Specify the starting y position (row/line) of the interface.
+      #
+      # @param value [Fixnum]
+      # @param block [Proc]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     geometry do
+      #       y  4
+      #       ...
+      #
+      #   interface 'other_interface' do
+      #     geometry do
+      #       y  { use('my_interface').north } # start on row/line 3, if
+      #       ...                              # `my_interface` changes position,
+      #                                        # `other_interface` will too.
+      #
+      # @return [Fixnum]
+      def y(value = 0, &block)
+        return model.y = block if block_given?
+
+        model.y = value
+      end
+
+      private
+
+      attr_reader :client, :model
+
+    end # Geometry
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/components/keymap.rb

@@ -0,0 +1,93 @@
+require 'vedeu/exceptions'
+require 'vedeu/support/common'
+require 'vedeu/input/key'
+
+module Vedeu
+
+  module DSL
+
+    # Provides methods to be used to define keypress mapped to actions.
+    #
+    # @api public
+    class Keymap
+
+      include Vedeu::Common
+      include Vedeu::DSL
+
+      # Returns an instance of DSL::Keymap.
+      #
+      # @param model [Keymap]
+      def initialize(model, client = nil)
+        @model  = model
+        @client = client
+      end
+
+      # Define keypress(es) to perform an action.
+      #
+      # @param value_or_values [Array<String>|Array<Symbol>|String|Symbol]
+      #   The key(s) pressed. Special keys can be found in
+      #   {Vedeu::Input#specials}. When more than one key is defined, then the
+      #   extras are treated as aliases.
+      # @param block [Proc] The action to perform when this key is pressed. Can
+      #   be a method call or event triggered.
+      #
+      # @example
+      #   Vedeu.keymap do
+      #     key('s')        { Vedeu.trigger(:save) }
+      #     key('h', :left) { Vedeu.trigger(:left) }
+      #     key('j', :down) { Vedeu.trigger(:down) }
+      #     key('p') do
+      #       ...
+      #     end
+      #     ...
+      #
+      # @raise [InvalidSyntax] When the required block is not given, the
+      #   value_or_values parameter is undefined, or when processing the
+      #   collection, a member is undefined.
+      # @return [Array] A collection containing the keypress(es).
+      def key(*value_or_values, &block)
+        fail InvalidSyntax, 'No action defined for `key`.' unless block_given?
+
+        unless defined_value?(value_or_values)
+          fail InvalidSyntax, 'No keypress(es) defined for `key`.'
+        end
+
+        value_or_values.each do |value|
+          unless defined_value?(value)
+            fail InvalidSyntax, 'An invalid value for `key` was encountered.'
+          end
+
+          unless model.key_defined?(value)
+            model.add(Vedeu::Key.define(value, &block))
+          end
+        end
+      end
+
+      # Define the name of the keymap.
+      #
+      # To only allow certain keys to work with specific interfaces, use the
+      # same name as the interface.
+      #
+      # When the name '_global_' is used, all keys in the keymap block will be
+      # available to all interfaces. Once a key has been defined in the
+      # '_global_' keymap, it cannot be used for a specific interface.
+      #
+      # @note Using the name of a keymap that already exists will overwrite that
+      #   keymap. Do not use the name '_system_' as unexpected behaviour may
+      #   occur.
+      #
+      # @param value [String]
+      # @return [String]
+      def name(value)
+        model.name = value
+      end
+
+      private
+
+      attr_reader :client, :model
+
+    end # Keymap
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/components/menu.rb

@@ -0,0 +1,82 @@
+module Vedeu
+
+  module DSL
+
+    # Provides the mechanism to create menus within client applications and use
+    # events to drive them.
+    #
+    # @api public
+    class Menu
+
+      include Vedeu::DSL
+
+      # Return a new instance of DSL::Menu.
+      #
+      # @param model [Vedeu::Menu]
+      # @return      [DSL::Menu]
+      def initialize(model, client = nil)
+        @model  = model
+        @client = client
+      end
+
+      # Add an individual item to the menu.
+      #
+      # @param element [Object] An object you wish to add to the collection.
+      #
+      # @example
+      #   menu 'my_menu' do
+      #     item SomeClass.new
+      #     item SomeClass.new
+      #
+      # @return [Array]
+      def item(element)
+        model.collection << element
+      end
+
+      # Define the items for the menu. Most powerful when used with one of your
+      # model classes.
+      #
+      # In the 'my_playlist' example below, your `Track` model may return a
+      # collection of tracks to populate the menu.
+      #
+      # @param collection [Array<Object>] A collection of objects which make up
+      #   the menu items.
+      #
+      # @example
+      #   menu 'my_menu' do
+      #     items [:item_1, :item_2, :item_3]
+      #   end
+      #
+      #   menu 'my_playlist' do
+      #     items Track.all_my_favourites
+      #   end
+      #
+      # @return [Array]
+      def items(collection = [])
+        model.collection = collection
+      end
+
+      # The name of the menu. Used to reference the menu throughout your
+      # application's execution lifetime.
+      #
+      # @param value [String]
+      #
+      # @example
+      #   menu do
+      #     name 'my_menu'
+      #     ...
+      #
+      # @return [String]
+      def name(value)
+        model.name = value
+      end
+
+      private
+
+      attr_reader :client, :model
+
+    end # Menu
+
+  end # DSL
+
+end # Vedeu