vedeu 0.2.0 → 0.2.1

data/lib/vedeu/repositories/keymaps.rb

@@ -0,0 +1,239 @@
+module Vedeu
+
+  # Repository for storing, retrieving and using defined keymaps.
+  #
+  # @api private
+  module Keymaps
+
+    include Vedeu::Common
+    extend self
+
+    # Stores the keymap attributes defined by the API.
+    #
+    # @param attributes [Hash]
+    # @return [TrueClass|KeyInUse|FalseClass]
+    def add(attributes)
+      return false unless defined_value?(attributes[:keys])
+
+      if defined_value?(attributes[:interfaces])
+        attributes[:interfaces].map do |interface|
+          storage.store(interface, {}) unless registered?(interface)
+
+          register(attributes, interface)
+        end
+
+      else
+        register(attributes)
+
+      end
+
+      true
+    end
+
+    # Return the whole repository of keymaps.
+    #
+    # @return [Hash]
+    def all
+      storage
+    end
+
+    # Find a keymap by interface name.
+    #
+    # @param name [String]
+    # @return [Hash]
+    def find(name)
+      storage.fetch(name, {})
+    end
+
+    # Return a boolean indicating whether the key is registered as a global key.
+    #
+    # @param key [String|Symbol]
+    # @return [Boolean]
+    def global_key?(key)
+      global_keys.include?(key)
+    end
+
+    # Return the collection of global keys.
+    #
+    # @return [Array]
+    def global_keys
+      storage.fetch('_global_keymap_', {}).keys
+    end
+
+    # Return a boolean indicating whether the key is registered as an interface
+    # key. When an interface argument is provided, only that interface is
+    # checked.
+    #
+    # @param key [String|Symbol]
+    # @param interface [String]
+    # @return [Boolean]
+    def interface_key?(key, interface = '')
+      if defined_value?(interface)
+        find(interface).keys.include?(key)
+
+      else
+        interface_keys.include?(key)
+
+      end
+    end
+
+    # Return a collection of interface keys.
+    #
+    # @return [Hash]
+    def interface_keys
+      storage.reject do |k, _|
+        k == '_global_keymap_'
+      end.map { |_, v| v.keys }.flatten.uniq
+    end
+
+    # Returns a collection of the interface names of all the registered keymaps.
+    #
+    # @return [Array]
+    def registered
+      storage.keys
+    end
+
+    # Returns a boolean indicating whether the named interface has a keymap
+    # registered.
+    #
+    # @param name [String]
+    # @return [Boolean]
+    def registered?(name)
+      storage.key?(name)
+    end
+
+    # Reset the keymaps repository; removing all registered keymaps. Only the
+    # system keymap will remain.
+    #
+    # @return [Hash]
+    def reset
+      @_storage = in_memory
+    end
+
+    # Return a boolean indicating whether the key is registered as a system key.
+    #
+    # @param key [String|Symbol]
+    # @return [Boolean]
+    def system_key?(key)
+      system_keys.include?(key)
+    end
+
+    # Return a collection of system keys.
+    #
+    # @return [Array]
+    def system_keys
+      Configuration.system_keys.invert.keys
+    end
+
+    # Handles the keypress in your application. Can also be used to simulate a
+    # keypress.
+    #
+    # 1) Log the keypress if debugging is enabled.
+    # 2) Trigger the client application's `:key` event (it may not exist).
+    # 3) Determine if the key pertains to the focussed interface and action it,
+    #    or check both global, then system keys to action it. Returns false if
+    #    nothing can deal with it.
+    #
+    # @param key [String|Symbol] The key which was pressed. Escape sequences
+    #   are also supported. Special keys like the F-keys are named as symbols;
+    #   i.e. `:f4`. A list of these translations can be found at {Vedeu::Input}.
+    #
+    # @example
+    #   Vedeu.keypress('s')
+    #
+    # @return [|FalseClass]
+    def use(key)
+      Vedeu.log("Key pressed: '#{key}'")
+
+      Vedeu.trigger(:key, key)
+
+      focussed_interface = Vedeu::Focus.current
+
+      if interface_key?(key, focussed_interface)
+        find(focussed_interface).fetch(key, noop).call
+
+      elsif global_key?(key)
+        find('_global_keymap_').fetch(key, noop).call
+
+      elsif system_key?(key)
+        system_key(key)
+
+      else
+        false
+
+      end
+    end
+
+    private
+
+    # Triggers the system event defined for this key.
+    #
+    # @param key [String|Symbol]
+    # @return []
+    def system_key(key)
+      action = Vedeu::Configuration.system_keys.key(key)
+      event  = ['_', action, '_'].join.to_sym
+
+      Vedeu.trigger(event)
+    end
+
+    # @param key [String|Symbol]
+    # @param interface [String]
+    # @return []
+    def validate(key, interface = '')
+      Vedeu::KeymapValidator.check(storage, key, interface)
+    end
+
+    # Registers the key.
+    #
+    # @api private
+    # @param attributes [Hash]
+    # @param interface [String]
+    # @return []
+    def register(attributes, interface = '')
+      attributes[:keys].map do |keymap|
+        valid, message = validate(keymap[:key], interface)
+
+        fail KeyInUse, message unless valid
+
+        Vedeu.log("Registering key '#{keymap[:key]}' with " \
+                  "'#{namespace(interface)}'")
+
+        storage[namespace(interface)]
+          .merge!({ keymap[:key] => keymap[:action] })
+      end
+    end
+
+    # Determine which interface to store the key with.
+    #
+    # @api private
+    # @param interface [String]
+    # @return [String]
+    def namespace(interface = '')
+      return defined_value?(interface) ? interface : '_global_keymap_'
+    end
+
+    # Returns a noop proc which when called returns :noop.
+    #
+    # @return [Proc]
+    def noop
+      proc { :noop }
+    end
+
+    # Access to the storage for this repository.
+    #
+    # @api private
+    # @return [Array]
+    def storage
+      @_storage ||= in_memory
+    end
+
+    # @api private
+    # @return [Array]
+    def in_memory
+      { '_global_keymap_' => {} }
+    end
+
+  end
+
+end

data/lib/vedeu/repositories/menus.rb

@@ -5,6 +5,7 @@ module Vedeu
   # @api private
   module Menus
 
+    include Common
     extend self
 
     # System events which when called with the appropriate menu name will
@@ -25,7 +26,9 @@ module Vedeu
     # @param attributes [Hash]
     # @return [Hash|FalseClass]
     def add(attributes)
-      return false if attributes[:name].empty?
+      return false unless defined_value?(attributes[:name])
+
+      Vedeu.log("Registering menu '#{attributes[:name]}'")
 
       storage.store(attributes[:name], attributes)
     end
@@ -57,7 +60,8 @@ module Vedeu
 
     # Returns a boolean indicating whether the named menu is registered.
     #
-    # @return [TrueClass|FalseClass]
+    # @param name [String]
+    # @return [Boolean]
     def registered?(name)
       storage.key?(name)
     end
@@ -65,7 +69,7 @@ module Vedeu
     # Removes the menu from the repository and associated events.
     #
     # @param name [String]
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def remove(name)
       return false unless registered?(name)
 
@@ -95,12 +99,17 @@ module Vedeu
 
     private
 
+    # Access to the storage for this repository.
+    #
     # @api private
     # @return [Hash]
     def storage
       @_storage ||= in_memory
     end
 
+    # Returns an empty collection ready for the storing of menus by name with
+    # associated menu instance.
+    #
     # @api private
     # @return [Hash]
     def in_memory

data/lib/vedeu/support/common.rb

@@ -7,8 +7,8 @@ module Vedeu
 
     # Returns a boolean indicating whether a variable has a useful value.
     #
-    # @param variable [String|Array] The variable to check.
-    # @return [TrueClass|FalseClass]
+    # @param variable [String|Symbol|Array] The variable to check.
+    # @return [Boolean]
     def defined_value?(variable)
       return true unless variable.nil? || variable.empty?
 

data/lib/vedeu/support/cursor.rb

@@ -5,6 +5,9 @@ module Vedeu
   # @api private
   class Cursor
 
+    # @return [Hash]
+    attr_reader :attributes
+
     # @return [Fixnum]
     attr_reader :top
 

data/lib/vedeu/support/event.rb

@@ -25,9 +25,9 @@ module Vedeu
     def trigger(*args)
       return execute(*args) unless debouncing? || throttling?
 
-      return execute(*args) if debouncing? && set_executed > deadline
+      return execute(*args) if debouncing? && debounce_expired?
 
-      return execute(*args) if throttling? && elapsed_time > delay
+      return execute(*args) if throttling? && throttle_expired?
     end
 
     private
@@ -63,19 +63,36 @@ module Vedeu
     # throttling.
     #
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def throttling?
       set_time
 
       options[:delay] > 0
     end
 
+    # Returns a boolean indicating whether the throttle has expired.
+    #
+    # @api private
+    # @return [Boolean]
+    def throttle_expired?
+      if elapsed_time > delay
+        Vedeu.log("Event throttle has expired for '#{event_name}', executing " \
+                  "event.")
+        true
+
+      else
+        Vedeu.log("Event throttle not yet expired for '#{event_name}'.")
+        false
+
+      end
+    end
+
     # Returns a boolean indicating whether debouncing is required for this
     # event. Setting the debounce option to any value greater than 0 will
     # enable debouncing.
     #
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def debouncing?
       set_time
 
@@ -84,6 +101,23 @@ module Vedeu
       options[:debounce] > 0
     end
 
+    # Returns a boolean indicating whether the debounce has expired.
+    #
+    # @api private
+    # @return [Boolean]
+    def debounce_expired?
+      if set_executed > deadline
+        Vedeu.log("Event debounce has expired for '#{event_name}', executing " \
+                  "event.")
+        true
+
+      else
+        Vedeu.log("Event debounce not yet expired for '#{event_name}'.")
+        false
+
+      end
+    end
+
     # @api private
     # @return [Float]
     def elapsed_time
@@ -109,7 +143,7 @@ module Vedeu
     end
 
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def has_deadline?
       @deadline > 0
     end
@@ -128,6 +162,12 @@ module Vedeu
       nil
     end
 
+    # @api private
+    # @return [String]
+    def event_name
+      options[:event_name].to_s
+    end
+
     # @api private
     # @return [Fixnum|Float]
     def debounce
@@ -150,8 +190,9 @@ module Vedeu
     # @return [Hash]
     def defaults
       {
-        delay:    0.0,
-        debounce: 0.0
+        delay:      0.0,
+        debounce:   0.0,
+        event_name: '',
       }
     end
 

data/lib/vedeu/support/grid.rb

@@ -63,7 +63,7 @@ module Vedeu
     end
 
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def out_of_range?
       value < 1 || value > 12
     end

data/lib/vedeu/support/registrar.rb

@@ -0,0 +1,66 @@
+module Vedeu
+
+  # When the client application has defined interfaces to be used, the Registrar
+  # stores these interfaces into various repositories for later use.
+  #
+  # @api private
+  class Registrar
+
+    include Common
+
+    # @param attributes [Hash]
+    # @return [TrueClass|]
+    def self.record(attributes = {})
+      new(attributes).record
+    end
+
+    # @param attributes [Hash]
+    # @return [Registrar]
+    def initialize(attributes = {})
+      @attributes = attributes
+    end
+
+    # Adds the attributes to a variety of repositories to use later.
+    #
+    # @return [TrueClass|MissingRequired]
+    def record
+      validate_attributes!
+
+      Vedeu::Buffers.add(attributes)
+
+      Vedeu::Interfaces.add(attributes)
+
+      Vedeu::Groups.add(attributes)
+
+      Vedeu::Focus.add(attributes)
+
+      true
+    end
+
+    private
+
+    # Client application defined settings for interfaces etc.
+    attr_reader :attributes
+
+    # At present, validates that attributes has a `:name` key that is not nil or
+    # empty.
+    #
+    # @api private
+    # @return [TrueClass|MissingRequired]
+    def validate_attributes!
+      return exception unless attributes.key?(:name)
+      return exception unless defined_value?(attributes[:name])
+
+      true
+    end
+
+    # Raises the MissingRequired exception.
+    #
+    # @see Vedeu::MissingRequired
+    def exception
+      fail MissingRequired, 'Cannot store data without a name attribute.'
+    end
+
+  end
+
+end