vedeu 0.3.1 → 0.3.2

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

@@ -1,5 +1,5 @@
 require 'vedeu/models/geometry'
-require 'vedeu/dsl/shared/use'
+require 'vedeu/dsl/shared/all'
 
 module Vedeu
 
@@ -14,6 +14,16 @@ module Vedeu
 
       class << self
 
+        # Specify the geometry of an interface or view with a simple DSL.
+        #
+        # @example
+        #   Vedeu.geometry 'some_interface' do
+        #     # ...
+        #
+        # @param name [String] The name of the interface or view to which this
+        #   geometry belongs.
+        # @param block [Proc]
+        # @return [Vedeu::Geometry]
         def geometry(name, &block)
           fail InvalidSyntax, 'block not given' unless block_given?
 
@@ -37,14 +47,13 @@ module Vedeu
       #   to true.
       #
       # @example
-      #   interface 'my_interface' do
-      #     geometry do
-      #       centred!
+      #   geometry 'some_interface' do
+      #     centred!
+      #     # ...
       #
-      #   interface 'my_interface' do
-      #     geometry do
-      #       centred false
-      #       ...
+      #   geometry 'some_interface' do
+      #     centred false
+      #     # ...
       #
       # @return [Boolean]
       def centred(value = true)
@@ -57,39 +66,23 @@ module Vedeu
       # @param value [Fixnum]
       #
       # @example
-      #   interface 'my_interface' do
-      #     geometry do
-      #       height 8
-      #       ...
+      #   geometry 'some_interface' 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
-      #       ...
+      #   geometry 'some_interface' do
+      #     width 25
+      #     # ...
       #
       # @return [Fixnum]
       def width(value)
@@ -102,15 +95,15 @@ module Vedeu
       # @param block [Proc]
       #
       # @example
-      #   interface 'my_interface' do
-      #     geometry do
-      #       x 7 # start on column 7.
+      #   geometry 'some_interface' 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.
+      #   geometry 'some_interface' do
+      #     x { use('other_interface').east } # start on column 8, if
+      #     # ...                             # `other_interface` changes
+      #                                       # position, `some_interface` will
+      #                                       # too.
       #
       # @return [Fixnum]
       def x(value = 0, &block)
@@ -125,16 +118,15 @@ module Vedeu
       # @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.
+      #   geometry 'some_interface' do
+      #     y  4
+      #     # ...
+      #
+      #   geometry 'some_interface' do
+      #     y  { use('other_interface').north } # start on row/line 3, if
+      #     # ...                               # `other_interface` changes
+      #                                         # position, `some_interface`
+      #                                         # will too.
       #
       # @return [Fixnum]
       def y(value = 0, &block)

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

@@ -14,6 +14,42 @@ module Vedeu
       include Vedeu::Common
       include Vedeu::DSL
 
+      class << self
+
+        # Define actions for keypresses for when specific interfaces are in focus.
+        # Unless an interface is specified, the key will be assumed to be global,
+        # meaning its action will happen regardless of the interface in focus.
+        #
+        # @note
+        #   When defining an interface, there is no need to provide a name since
+        #   this can be discerned from the interface itself, e.g:
+        #
+        #   Vedeu.interface 'my_interface' do
+        #     keymap do
+        #       ...
+        #
+        # @param name [String] The name of the interface which this keymap relates
+        #   to.
+        # @param block [Proc]
+        #
+        # @example
+        #   keymap 'my_interface' do
+        #     ...
+        #
+        # @raise [InvalidSyntax] The required block was not given.
+        # @return [Keymap]
+        def keymap(name, &block)
+          # fail InvalidSyntax, 'block not given' unless block_given?
+
+          # @todo Try to remember why we need to pre-create the keymap in the
+          #   repository.
+          Vedeu::Keymap.new(name).store
+
+          Vedeu::Keymap.build({ name: name }, &block).store
+        end
+
+      end
+
       # Returns an instance of DSL::Keymap.
       #
       # @param model [Keymap]

data/lib/vedeu/dsl/interface.rb

@@ -34,13 +34,23 @@ module Vedeu
       #
       # @param block [Proc]
       # @raise [InvalidSyntax] The required block was not given.
-      # @return [Hash]
+      # @return [Vedeu::Border]
       def border(&block)
         fail InvalidSyntax, 'block not given' unless block_given?
 
-        border_attrs = attributes.merge({ enabled: true, interface: model })
+        border_attrs = attributes.merge({ enabled: true,
+                                          name:    model.name })
 
-        model.border = Vedeu::Border.build(border_attrs, &block)
+        Vedeu::Border.build(border_attrs, &block).store
+      end
+
+      # Applies the default border to the interface.
+      #
+      # @return [Vedeu::Border]
+      def border!
+        border do
+          # adds default border
+        end
       end
 
       # Set the cursor visibility on an interface.
@@ -69,6 +79,9 @@ module Vedeu
         Vedeu::Cursor.new({ name: model.name, state: value }).store
       end
 
+      # Set the cursor to visible for the interface.
+      #
+      # @return [Vedeu::Cursor]
       def cursor!
         cursor(true)
       end
@@ -114,7 +127,7 @@ module Vedeu
       def geometry(&block)
         fail InvalidSyntax, 'block not given' unless block_given?
 
-        model.geometry = Vedeu::Geometry.build(attributes, &block)
+        Vedeu::Geometry.build({ name: model.name }, &block).store
       end
 
       # Specify a group for an interface. Interfaces of the same group can be
@@ -130,6 +143,8 @@ module Vedeu
       #
       # @return [String]
       def group(value)
+        return false unless defined_value?(value)
+
         if defined_value?(model.name)
           if Vedeu.groups.registered?(value)
             Vedeu.groups.find(value).add(model.name)
@@ -143,7 +158,7 @@ module Vedeu
         model.group = value
       end
 
-      # @see Vedeu::Keymap.keymap
+      # @see Vedeu::DSL::Keymap.keymap
       def keymap(name = model.name, &block)
         Vedeu.keymap(name, &block)
       end

data/lib/vedeu/dsl/stream.rb

@@ -22,6 +22,8 @@ module Vedeu
         @client = client
       end
 
+      # @param block [Proc]
+      # @return []
       def stream(&block)
         fail InvalidSyntax, 'block not given' unless block_given?
 

data/lib/vedeu/events/all.rb

@@ -2,9 +2,4 @@ require 'vedeu/events/event'
 require 'vedeu/events/trigger'
 
 module Vedeu
-
-  def self.events
-    @_events ||= Vedeu::Repository.new(Vedeu::Model::Collection)
-  end
-
 end # Vedeu

data/lib/vedeu/events/event.rb

@@ -101,6 +101,7 @@ module Vedeu
       @repository   = Vedeu.events
     end
 
+    # @see Vedeu::Event.bind
     def bind
       if repository.registered?(name)
         collection     = repository.find(name)
@@ -117,7 +118,7 @@ module Vedeu
     end
 
     # Triggers the event based on debouncing and throttling conditions.
-
+    #
     # @param args [Array]
     # @return []
     def trigger(*args)

data/lib/vedeu/events/trigger.rb

@@ -38,9 +38,7 @@ module Vedeu
 
       collection = repository.find(name)
 
-      results = collection.map do |event|
-        event.trigger(*args)
-      end
+      results = collection.map { |event| event.trigger(*args) }
 
       return results.first if results.one?
 

data/lib/vedeu/input/all.rb

@@ -1,4 +1,4 @@
-require 'vedeu/repositories/repository'
+require 'vedeu/repositories/all'
 require 'vedeu/input/mapper'
 require 'vedeu/input/keys'
 require 'vedeu/input/key'
@@ -7,22 +7,17 @@ require 'vedeu/input/keymap'
 
 module Vedeu
 
-  extend self
-
-  def keymaps
-    @_keymaps ||= Vedeu::Repository.new(Vedeu::Keymap)
-  end
-
-  def_delegators Vedeu::Keymap, :keymap
-  def_delegators Vedeu::Keymap, :keypress
-
-  Vedeu.keymap('_system_') do |keymap|
+  # Define a keymap called '_system_' which will hold some vital keys needed by
+  # Vedeu to run effectively.
+  Vedeu::DSL::Keymap.keymap('_system_') do |keymap|
     Vedeu::Configuration.system_keys.each do |label, keypress|
       keymap.key(keypress) { Vedeu.trigger(("_" + label.to_s + "_").to_sym) }
     end
   end
 
-  Vedeu.keymap('_global_') do
+  # Define a keymap called '_global_' which will respond no matter which
+  # interface is in focus.
+  Vedeu::DSL::Keymap.keymap('_global_') do
 
   end
 

data/lib/vedeu/input/keymap.rb

@@ -12,14 +12,16 @@ module Vedeu
     member     Vedeu::Key
 
     attr_accessor :name
-    attr_reader   :repository
 
     class << self
 
+      # @param attributes [Hash]
+      # @param block [Proc]
       # @option attributes client []
       # @option attributes keys []
-      # @option attributes name []
-      # @option attributes repository []
+      # @option attributes name [String]
+      # @option attributes repository [Vedeu::Repository]
+      # @return [Vedeu::Keymap]
       def build(attributes = {}, &block)
         fail InvalidSyntax, 'block not given' unless block_given?
 
@@ -32,34 +34,6 @@ module Vedeu
         model.store
       end
 
-      # Define actions for keypresses for when specific interfaces are in focus.
-      # Unless an interface is specified, the key will be assumed to be global,
-      # meaning its action will happen regardless of the interface in focus.
-      #
-      # @note
-      #   When defining an interface, there is no need to provide a name since
-      #   this can be discerned from the interface itself, e.g:
-      #
-      #   Vedeu.interface 'my_interface' do
-      #     keymap do
-      #       ...
-      #
-      # @param name [String] The name of the interface which this keymap relates
-      #   to.
-      # @param block [Proc]
-      #
-      # @example
-      #   keymap 'my_interface' do
-      #     ...
-      #
-      # @raise [InvalidSyntax] The required block was not given.
-      # @return [Keymap]
-      def keymap(name, &block)
-        new(name).store
-
-        build({ name: name }, &block)
-      end
-
       private
 
       # The default values for a new instance of this class.
@@ -70,7 +44,7 @@ module Vedeu
           client:     nil,
           keys:       [],
           name:       '',
-          repository: Vedeu.keymaps,
+          repository: Vedeu::Keymaps.keymaps,
         }
       end
 
@@ -82,10 +56,11 @@ module Vedeu
     def initialize(name = '', keys = [], repository = nil)
       @name       = name
       @keys       = keys
-      @repository = repository || Vedeu.keymaps
+      @repository = repository || Vedeu::Keymaps.keymaps
     end
 
     # @param key [Key]
+    # @return []
     def add(key)
       return false unless valid?(key)
 
@@ -94,7 +69,7 @@ module Vedeu
 
     # @return [Vedeu::Keys]
     def keys
-      collection.coerce(@keys,  self)
+      collection.coerce(@keys, self)
     end
 
     # @param input [String|Symbol]
@@ -119,6 +94,7 @@ module Vedeu
     private
 
     # @param key [Vedeu::Key]
+    # @return [Boolean]
     def valid?(key)
       return true unless key_defined?(key.input)
 

data/lib/vedeu/input/keys.rb

@@ -2,6 +2,7 @@ require 'vedeu/models/collection'
 
 module Vedeu
 
+  # A collection of {Vedeu::Key} instances.
   class Keys < Vedeu::Model::Collection
   end # Keys
 

data/lib/vedeu/input/mapper.rb

@@ -47,11 +47,7 @@ module Vedeu
     def valid?
       return false unless key
 
-      return false if key_defined?
-
-      return false if global_key?
-
-      return false if system_key?
+      return false if key_defined? || global_key? || system_key?
 
       true
     end

data/lib/vedeu/models/collection.rb

@@ -12,6 +12,7 @@ module Vedeu
 
       attr_accessor :parent, :name
 
+      # @return [Vedeu::Model::Collection]
       def self.coerce(collection = [], parent = nil, name = nil)
         if collection.kind_of?(Vedeu::Model::Collection)
           collection
@@ -25,6 +26,7 @@ module Vedeu
         end
       end
 
+      # @return [Vedeu::Model::Collection]
       def initialize(collection = [], parent = nil, name = nil)
         @collection = collection
         @parent     = parent
@@ -41,10 +43,12 @@ module Vedeu
       end
       alias_method :<<, :add
 
+      # @return [Array]
       def all
         @collection
       end
 
+      # @return [Enumerator]
       def each(&block)
         @collection.each(&block)
       end