vedeu 0.2.0 → 0.2.1

data/lib/vedeu/api/composition.rb

@@ -4,6 +4,25 @@ module Vedeu
     # @see Vedeu::Composition
     class Composition < Vedeu::Composition
 
+      # Directly write a view buffer to the terminal.
+      #
+      # @api public
+      # @param block [Proc]
+      # @return [Array] A collection of strings, each defining containing the
+      #                 escape sequences and content. This data has already
+      #                 been sent to the terminal to be output.
+      def self.render(&block)
+        fail InvalidSyntax, '`render` requires a block.' unless block_given?
+
+        attributes = API::Composition.build({}, &block)
+
+        Vedeu::Composition.new(attributes).interfaces.map do |interface|
+          Buffers.add(interface.attributes)
+
+          interface.name
+        end.map { |name| Compositor.render(name) }
+      end
+
       # @api public
       # @see Vedeu::API#view
       def view(name, &block)

data/lib/vedeu/api/defined.rb

@@ -30,6 +30,13 @@ module Vedeu
         Vedeu::Interfaces.registered
       end
 
+      # Returns all menus currently registered with Vedeu.
+      #
+      # @return [Array]
+      def menus
+        Vedeu::Menus.registered
+      end
+
     end
   end
 end

data/lib/vedeu/api/interface.rb

@@ -6,45 +6,24 @@ module Vedeu
 
       include Helpers
 
-      # Define a single line in a view.
+      # Instructs Vedeu to calculate x and y geometry automatically based on the
+      # centre character of the terminal, the width and the height.
       #
       # @api public
-      # @param value [String]
-      # @param block [Proc]
+      # @param value [Boolean]
       #
       # @example
-      #   view 'my_interface' do
-      #     line 'This is a line of text...'
-      #     line 'and so is this...'
+      #   interface 'my_interface' do
+      #     centred true
       #     ...
       #
-      #   view 'my_interface' do
-      #     line do
-      #       ... some line attributes ...
-      #     end
-      #   end
-      #
       # @return [API::Interface]
-      def line(value = '', &block)
-        if block_given?
-          attributes[:lines] << API::Line
-            .build({ parent: self.view_attributes }, &block)
-
-        else
-          attributes[:lines] << API::Line
-            .build({ streams: { text: value }, parent: self.view_attributes })
-
+      def centred(value)
+        unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          fail InvalidSyntax, 'Argument must be `true` or `false` for centred.'
         end
-      end
 
-      # Use the specified interface; useful for sharing attributes with other
-      # interfaces.
-      #
-      # @api public
-      # @param value [String]
-      # @see Vedeu::API#use
-      def use(value)
-        Vedeu.use(value)
+        attributes[:geometry][:centred] = value
       end
 
       # Define the cursor visibility for an interface. A `true` value will show
@@ -96,6 +75,54 @@ module Vedeu
         attributes[:group] = value
       end
 
+      # Define the number of characters/rows/lines tall the interface will be.
+      #
+      # @api public
+      # @param value [Fixnum]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     height 8
+      #     ...
+      #
+      # @return [API::Interface]
+      def height(value)
+        Vedeu.log(out_of_bounds('height')) if y_out_of_bounds?(value)
+
+        attributes[:geometry][:height] = value
+      end
+
+      # Define a single line in a view.
+      #
+      # @api public
+      # @param value [String]
+      # @param block [Proc]
+      #
+      # @example
+      #   view 'my_interface' do
+      #     line 'This is a line of text...'
+      #     line 'and so is this...'
+      #     ...
+      #
+      #   view 'my_interface' do
+      #     line do
+      #       ... some line attributes ...
+      #     end
+      #   end
+      #
+      # @return [API::Interface]
+      def line(value = '', &block)
+        if block_given?
+          attributes[:lines] << API::Line
+            .build({ parent: self.view_attributes }, &block)
+
+        else
+          attributes[:lines] << API::Line
+            .build({ streams: { text: value }, parent: self.view_attributes })
+
+        end
+      end
+
       # The name of the interface. Used to reference the interface throughout
       # your application's execution lifetime.
       #
@@ -112,6 +139,33 @@ module Vedeu
         attributes[:name] = value
       end
 
+      # Use the specified interface; useful for sharing attributes with other
+      # interfaces.
+      #
+      # @api public
+      # @param value [String]
+      # @see Vedeu::API#use
+      def use(value)
+        Vedeu.use(value)
+      end
+
+      # Define the number of characters/columns wide the interface will be.
+      #
+      # @api public
+      # @param value [Fixnum]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     width 25
+      #     ...
+      #
+      # @return [API::Interface]
+      def width(value)
+        Vedeu.log(out_of_bounds('width')) if x_out_of_bounds?(value)
+
+        attributes[:geometry][:width] = value
+      end
+
       # Define the starting x position (column) of the interface.
       #
       # @api public
@@ -161,58 +215,32 @@ module Vedeu
         attributes[:geometry][:y] = value
       end
 
-      # Define the number of characters/columns wide the interface will be.
-      #
-      # @api public
-      # @param value [Fixnum]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     width 25
-      #     ...
-      #
-      # @return [API::Interface]
-      def width(value)
-        Vedeu.log(out_of_bounds('width')) if x_out_of_bounds?(value)
+      private
 
-        attributes[:geometry][:width] = value
+      # Returns the out of bounds error message for the given named attribute.
+      #
+      # @api private
+      # @param name [String]
+      # @return [String]
+      def out_of_bounds(name)
+        "Note: For this terminal, the value of '#{name}' may lead to content " \
+        "that is outside the viewable area."
       end
 
-      # Define the number of characters/rows/lines tall the interface will be.
+      # Checks the value is within the terminal's confines.
       #
-      # @api public
-      # @param value [Fixnum]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     height 8
-      #     ...
-      #
-      # @return [API::Interface]
-      def height(value)
-        Vedeu.log(out_of_bounds('height')) if y_out_of_bounds?(value)
-
-        attributes[:geometry][:height] = value
+      # @api private
+      # @return [Boolean]
+      def y_out_of_bounds?(value)
+        value < 1 || value > Terminal.height
       end
 
-      # Instructs Vedeu to calculate x and y geometry automatically based on the
-      # centre character of the terminal, the width and the height.
-      #
-      # @api public
-      # @param value [Boolean]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     centred true
-      #     ...
+      # Checks the value is within the terminal's confines.
       #
-      # @return [API::Interface]
-      def centred(value)
-        unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
-          fail InvalidSyntax, 'Argument must be `true` or `false` for centred.'
-        end
-
-        attributes[:geometry][:centred] = value
+      # @api private
+      # @return [Boolean]
+      def x_out_of_bounds?(value)
+        value < 1 || value > Terminal.width
       end
 
     end

data/lib/vedeu/api/keymap.rb

@@ -0,0 +1,62 @@
+module Vedeu
+  module API
+
+    # Provides methods to be used to define keypress mapped to actions.
+    class Keymap < Vedeu::Keymap
+
+      # Define keypress(es) to perform an action.
+      #
+      # @param value_or_values [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
+      #   keys do
+      #     key('s')        { trigger(:save) }
+      #     key('h', :left) { trigger(:left) }
+      #     key('j', :down) { trigger(:down) }
+      #     ...
+      #
+      # @return [Array] A collection containing the keypress(es).
+      def key(*value_or_values, &block)
+        fail InvalidSyntax,
+          'No action defined for `key`.' unless block_given?
+        fail InvalidSyntax, 'No keypress(es) defined for `key`.' unless
+          defined_value?(value_or_values)
+
+        value_or_values.each do |value|
+          fail InvalidSyntax, 'Key cannot be empty.' unless
+            defined_value?(value)
+
+          attributes[:keys] << { key: value, action: block }
+        end
+      end
+
+      # The interface(s) which will handle these keys.
+      #
+      # @param name_or_names [String] The name or names of the interface(s)
+      # which will handle these keys.
+      #
+      # @example
+      #   keys do
+      #     interface 'my_interface'
+      #     key('s')  { :something }
+      #     name      'my_keymap'
+      #     ...
+      #
+      #   keys do
+      #     interface('main', 'other')
+      #     key('s')  { :something }
+      #     ...
+      #
+      # @return [Array]
+      def interface(*name_or_names)
+        attributes[:interfaces] = name_or_names
+      end
+
+    end
+
+  end
+end

data/lib/vedeu/api/menu.rb

@@ -92,8 +92,10 @@ module Vedeu
         }
       end
 
+      # At present, validates that a menu has a name attribute.
+      #
       # @api private
-      # @return [TrueClass|FalseClass]
+      # @return [Boolean]
       def validate_attributes!
         unless defined_value?(attributes[:name])
           fail InvalidSyntax, 'Menus must have a `name`.'

data/lib/vedeu/configuration.rb

@@ -83,7 +83,7 @@ module Vedeu
     # Returns whether debugging is enabled or disabled. Default is false;
     # meaning nothing apart from warnings are written to the log file.
     #
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def debug?
       options[:debug]
     end
@@ -93,7 +93,7 @@ module Vedeu
     # standalone (will run until terminates of natural causes.) Default is true;
     # meaning the application will require user input.
     #
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def interactive?
       options[:interactive]
     end
@@ -103,12 +103,19 @@ module Vedeu
     # not. Default is false; meaning the application will loop forever or until
     # terminated by the user.
     #
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def once?
       options[:once]
     end
     alias_method :once, :once?
 
+    # Returns
+    #
+    # @return [Hash]
+    def system_keys
+      options[:system_keys]
+    end
+
     # Returns the terminal mode for the application. Default is `:raw`.
     #
     # @return [Symbol]
@@ -120,7 +127,7 @@ module Vedeu
     # the log file (logging method calls and events trigger). Default is false;
     # meaning tracing is disabled.
     #
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def trace?
       options[:trace]
     end
@@ -153,11 +160,22 @@ module Vedeu
         debug:         detect_debug_mode,
         interactive:   true,
         once:          false,
+        system_keys:   default_system_keys,
         terminal_mode: :raw,  #cooked
         trace:         detect_trace_mode,
       }
     end
 
+    # Vedeu's system keys.
+    def default_system_keys
+      {
+        exit:        'q',
+        focus_next:  :tab,
+        focus_prev:  :shift_tab,
+        mode_switch: :escape,
+      }
+    end
+
     # Determine the terminal colour mode via enviroment variables, or be
     # optimistic and settle for 256 colours.
     #
@@ -189,7 +207,7 @@ module Vedeu
     # Determine the debug mode via an enviroment variable.
     #
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     # :nocov:
     def detect_debug_mode
       if ENV['VEDEU_DEBUG']
@@ -209,7 +227,7 @@ module Vedeu
     # Determine the trace mode via an environment variable.
     #
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     # :nocov:
     def detect_trace_mode
       if ENV['VEDEU_TRACE']

data/lib/vedeu/models/attributes/coercions.rb

@@ -5,31 +5,23 @@ module Vedeu
   # @api private
   module Coercions
 
-    # Contains class methods which are accessible as such to classes and modules
-    # which include {Vedeu::Coercions}.
-    module ClassMethods
-
-      include Vedeu::Common
-
-      # Produces new objects of the correct class from attributes hashes,
-      # ignores objects that have already been coerced.
-      # When provided with a parent argument, will allow the new object
-      # to know the colour and style of its parent.
-      #
-      # @param values [Array|Hash]
-      # @param parent [Hash|Nil]
-      # @return [Array]
-      def coercer(values, parent = nil)
-        return [] unless defined_value?(values)
-
-        [values].flatten.map do |value|
-          if value.is_a?(self)
-            value
-
-          else
-            self.new(value.merge!({ parent: parent }))
-
-          end
+    include Vedeu::Common
+
+    # Produces new objects of the correct class from attributes hashes,
+    # ignores objects that have already been coerced.
+    #
+    # @param values [Array|Hash]
+    # @return [Array]
+    def coercer(values)
+      return [] unless defined_value?(values)
+
+      [values].flatten.map do |value|
+        if value.is_a?(self)
+          value
+
+        else
+          self.new(value)
+
         end
       end
     end
@@ -38,7 +30,7 @@ module Vedeu
     # module, make its methods into class methods, so they may be called
     # directly.
     def self.included(receiver)
-      receiver.extend(ClassMethods)
+      receiver.extend(self)
     end
 
   end