vedeu 0.3.4 → 0.3.5

data/lib/vedeu/dsl/line.rb

@@ -34,6 +34,7 @@ module Vedeu
     #   end
     #
     # @api public
+    #
     class Line
 
       include Vedeu::DSL
@@ -60,7 +61,8 @@ module Vedeu
       #       line do
       #         # ...
       #
-      # @return [Vedeu::Line]
+      # @raise [InvalidSyntax] When no block or value is provided.
+      # @return [Vedeu::Lines]
       def line(value = '', &block)
         content = if block_given?
           Vedeu::Line.build({ client: client,

data/lib/vedeu/dsl/shared/colour.rb

@@ -6,6 +6,7 @@ module Vedeu
     # {Vedeu::DSL::Line} and {Vedeu::DSL::Stream} classes.
     #
     # @api public
+    #
     module Colour
 
       # Define the background colour for an interface, line, or a stream. When

data/lib/vedeu/dsl/shared/style.rb

@@ -6,6 +6,7 @@ module Vedeu
     # {DSL::Stream} classes.
     #
     # @api public
+    #
     module Style
 
       # Define a style or styles for an interface, line or a stream.

data/lib/vedeu/dsl/shared/text.rb

@@ -4,6 +4,8 @@ module Vedeu
 
   module DSL
 
+    # Provides helper methods for building views.
+    #
     module Text
 
       # Specify the content for a view. Provides the means to align a string

data/lib/vedeu/dsl/shared/use.rb

@@ -2,6 +2,8 @@ module Vedeu
 
   module DSL
 
+    # Provides helper methods for building views.
+    #
     module Use
 
       extend self
@@ -29,6 +31,7 @@ module Vedeu
       #
       # @param value [String] The name of the interface you wish to use.
       #   Typically used when defining interfaces to share geometry.
+      # @raise [ModelNotFound] The interface has not yet been defined.
       # @return [Vedeu::Interface]
       def use(value)
         if Vedeu.interfaces.registered?(value) == false

data/lib/vedeu/dsl/stream.rb

@@ -7,6 +7,7 @@ module Vedeu
     # Provides methods to be used to define views.
     #
     # @api public
+    #
     class Stream
 
       include Vedeu::DSL
@@ -23,7 +24,8 @@ module Vedeu
       end
 
       # @param block [Proc]
-      # @return []
+      # @raise [InvalidSyntax] The required block was not given.
+      # @return [void]
       def stream(&block)
         fail InvalidSyntax, 'block not given' unless block_given?
 

data/lib/vedeu/dsl/view.rb

@@ -7,6 +7,7 @@ module Vedeu
     # DSL for creating views.
     #
     # @api public
+    #
     class View
 
       class << self

data/lib/vedeu/events/event.rb

@@ -7,6 +7,7 @@ module Vedeu
   # Contains all the logic of an event. Handles debouncing and throttling.
   #
   # @api private
+  #
   class Event
 
     include Vedeu::Model
@@ -57,7 +58,7 @@ module Vedeu
       #
       # @return [TrueClass]
       def bind(name, options = {}, &block)
-        Vedeu.log("Binding event: '#{name}'")
+        Vedeu.log(type: :event, message: "Binding: '#{name}'")
 
         new(name, options, block).bind
       end
@@ -76,7 +77,7 @@ module Vedeu
       def unbind(name)
         return false unless Vedeu.events.registered?(name)
 
-        Vedeu.log("Unbinding event: '#{name}")
+        Vedeu.log(type: :event, message: "Unbinding: '#{name}")
 
         Vedeu.events.remove(name)
         true
@@ -120,7 +121,7 @@ module Vedeu
     # Triggers the event based on debouncing and throttling conditions.
     #
     # @param args [Array]
-    # @return []
+    # @return [void]
     def trigger(*args)
       return execute(*args) unless debouncing? || throttling?
 
@@ -137,7 +138,7 @@ module Vedeu
     # Execute the code stored in the event closure.
     #
     # @param args []
-    # @return []
+    # @return [void]
     def execute(*args)
       reset_deadline
 
@@ -145,6 +146,8 @@ module Vedeu
 
       reset_time
 
+      Vedeu.log(type: :event, message: "Triggering: '#{name}'")
+
       closure.call(*args)
     end
 
@@ -165,7 +168,7 @@ module Vedeu
     def throttle_expired?
       return true if elapsed_time > delay
 
-      Vedeu.log("Throttling event '#{name}'")
+      Vedeu.log(type: :event, message: "Throttling: '#{name}'")
 
       false
     end
@@ -189,7 +192,7 @@ module Vedeu
     def debounce_expired?
       return true if set_executed > deadline
 
-      Vedeu.log("Debouncing event '#{name}'")
+      Vedeu.log(type: :event, message: "Debouncing: '#{name}'")
 
       false
     end

data/lib/vedeu/events/trigger.rb

@@ -9,6 +9,7 @@ module Vedeu
   #   Vedeu.trigger(:my_event, :oxidize, 'nitrogen')
   #
   # @api private
+  #
   class Trigger
 
     class << self
@@ -34,15 +35,13 @@ module Vedeu
     # @see Vedeu::Trigger.trigger
     # @return [Array]
     def trigger
-      return [] unless repository.registered?(name)
-
-      collection = repository.find(name)
+      if results.one?
+        results.first
 
-      results = collection.map { |event| event.trigger(*args) }
+      else
+        results
 
-      return results.first if results.one?
-
-      results
+      end
     end
 
     private
@@ -51,6 +50,18 @@ module Vedeu
       :args,
       :repository
 
+    # @return [Array<void>|void]
+    def results
+      @results ||= registered_events.map { |event| event.trigger(*args) }
+    end
+
+    # @return [Array|Array<Vedeu::Event>]
+    def registered_events
+      return [] unless repository.registered?(name)
+
+      repository.find(name)
+    end
+
   end # Trigger
 
 end # Vedeu

data/lib/vedeu/exceptions.rb

@@ -20,7 +20,9 @@ module Vedeu
   # OutOfRange: Raised when trying to access an interface column less than 1 or
   #   greater than 12. Vedeu is hard-wired to a 12-column layout for the time
   #   being.
-
+  #
+  # VedeuInterrupt: Raised when Vedeu wishes to exit.
+  #
   Exceptions = %w[
     ModelNotFound
     InvalidSyntax
@@ -28,6 +30,7 @@ module Vedeu
     ModeSwitch
     NotImplemented
     OutOfRange
+    VedeuInterrupt
   ]
   Exceptions.each { |e| const_set(e, Class.new(StandardError)) }
 

data/lib/vedeu/input/input.rb

@@ -4,6 +4,7 @@ module Vedeu
   # special characters into symbols.
   #
   # @api private
+  #
   class Input
 
     # Instantiate Input and capture keypress(es).

data/lib/vedeu/input/key.rb

@@ -1,6 +1,5 @@
 module Vedeu
 
-  #
   # A single keypress or combination of keypresses bound to a specific action.
   #
   class Key

data/lib/vedeu/input/keymap.rb

@@ -5,6 +5,7 @@ require 'vedeu/dsl/components/keymap'
 module Vedeu
 
   # A container class for keys associated with a particular interface.
+  #
   class Keymap
 
     include Vedeu::Model
@@ -22,6 +23,7 @@ module Vedeu
       # @option attributes keys []
       # @option attributes name [String]
       # @option attributes repository [Vedeu::Repository]
+      # @raise [InvalidSyntax] The required block was not given.
       # @return [Vedeu::Keymap]
       def build(attributes = {}, &block)
         fail InvalidSyntax, 'block not given' unless block_given?
@@ -61,7 +63,7 @@ module Vedeu
     end
 
     # @param key [Key]
-    # @return []
+    # @return [void]
     def add(key)
       return false unless valid?(key)
 
@@ -88,7 +90,7 @@ module Vedeu
     def use(input)
       return false unless key_defined?(input)
 
-      Vedeu.log("Key pressed: '#{input}'")
+      Vedeu.log(type: :input, message: "Key pressed: '#{input}'")
 
       Vedeu.trigger(:key, input)
 
@@ -104,7 +106,7 @@ module Vedeu
     def valid?(key)
       return true unless key_defined?(key.input)
 
-      Vedeu.log("Keymap '#{name}' already defines '#{key.input}'.")
+      Vedeu.log(type: :debug, message: "Keymap '#{name}' already defines '#{key.input}'.")
 
       false
     end

data/lib/vedeu/input/keys.rb

@@ -3,6 +3,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

@@ -1,6 +1,7 @@
 module Vedeu
 
   # Maps keys to keymaps.
+  #
   class Mapper
 
     # Takes a key as a keypress and sends it to registered keymaps. If found,

data/lib/vedeu/launcher.rb

@@ -6,6 +6,7 @@ module Vedeu
   # finally the exiting of the application with the correct exit code.
   #
   # @api public
+  #
   class Launcher
 
     attr_reader :exit_code
@@ -20,14 +21,14 @@ module Vedeu
           stdin  = STDIN,
           stdout = STDOUT,
           stderr = STDERR,
-          kernel = Kernel).execute!
+          kernel = Kernel).debug_execute!
     end
 
     # @param argv [Array]
-    # @param stdin []
-    # @param stdout []
-    # @param stderr []
-    # @param kernel []
+    # @param stdin [IO]
+    # @param stdout [IO]
+    # @param stderr [IO]
+    # @param kernel [Kernel]
     # @return [Launcher]
     def initialize(argv   = [],
                    stdin  = STDIN,
@@ -42,29 +43,51 @@ module Vedeu
       @exit_code = 1
     end
 
-    # @return []
+    # @return [void]
+    def debug_execute!
+      if configuration.debug?
+        Vedeu.debug { execute! }
+
+      else
+        execute!
+
+      end
+
+      terminate!
+    end
+
+    # @return [void]
     def execute!
       $stdin, $stdout, $stderr = @stdin, @stdout, @stderr
 
       Application.start(configuration)
 
       @exit_code = 0
+
     rescue StandardError => uncaught_exception
       puts uncaught_exception.message
       puts uncaught_exception.backtrace.join("\n") if configuration.debug?
 
-    ensure
-      Vedeu.log("Exiting gracefully.")
-
-      $stdin, $stdout, $stderr = STDIN, STDOUT, STDERR
-      @kernel.exit(exit_code)
     end
 
     private
 
+    # @!attribute [r] argv
+    # @return [Array<String>] The command line arguments provided.
     attr_reader :argv
 
-    # @return []
+    # Terminates the application after resetting $stdin, $stdout and $stderr.
+    #
+    # @return [void]
+    def terminate!
+      Vedeu.log(type: :info, message: "Exiting gracefully.")
+
+      $stdin, $stdout, $stderr = STDIN, STDOUT, STDERR
+
+      @kernel.exit(exit_code)
+    end
+
+    # @return [Vedeu::Configuration]
     def configuration
       Vedeu::Configuration.configure(argv)
 

data/lib/vedeu/main_loop.rb

@@ -0,0 +1,53 @@
+module Vedeu
+
+  # Provides the main loop for a Vedeu application.
+  #
+  class MainLoop
+
+    trap('SIGTERM') { stop! }
+    trap('TERM')    { stop! }
+    trap('INT')     { stop! }
+
+    # Start the main loop.
+    #
+    # @param block [Proc]
+    # @return [void]
+    def self.start!(&block)
+      @started = true
+      @loop    = true
+
+      while(@loop) do
+        Vedeu.trigger(:_tick_)
+
+        yield
+
+        safe_exit_point!
+      end
+    rescue VedeuInterrupt
+
+    end
+
+    # Signal that we wish to terminate the running application.
+    #
+    # @return [void]
+    def self.stop!
+      @loop = false
+    end
+
+    # Check the application has started and we wish to continue running.
+    #
+    # @raise [VedeuInterrupt] When we wish to terminate the running application.
+    # @return [void]
+    def self.safe_exit_point!
+      if @started && !@loop
+        fail VedeuInterrupt
+
+      else
+        Vedeu.trigger(:_tock_)
+
+      end
+    end
+
+  end # MainLoop
+
+end # Vedeu

data/lib/vedeu/models/collection.rb

@@ -6,26 +6,30 @@ module Vedeu
     # is being used.
     #
     # @private
+    #
     class Collection
 
       include Enumerable
 
       attr_accessor :parent, :name
 
+      # @param collection [Array|Vedeu::Model::Collection]
+      # @param parent []
+      # @param name [String|NilClass]
       # @return [Vedeu::Model::Collection]
       def self.coerce(collection = [], parent = nil, name = nil)
         if collection.kind_of?(Vedeu::Model::Collection)
           collection
 
-        elsif collection.is_a?(Array)
-          new(collection, parent, name)
-
         else
           new(Array(collection), parent, name)
 
         end
       end
 
+      # @param collection []
+      # @param parent []
+      # @param name []
       # @return [Vedeu::Model::Collection]
       def initialize(collection = [], parent = nil, name = nil)
         @collection = collection
@@ -33,10 +37,13 @@ module Vedeu
         @name       = name
       end
 
+      # @param value [Fixnum]
+      # @return [void]
       def [](value)
         @collection[value]
       end
 
+      # @param other [Vedeu::Model::Collection]
       # @return [Vedeu::Model::Collection]
       def add(*other)
         self.class.new(@collection += other, parent, name)
@@ -48,6 +55,7 @@ module Vedeu
         @collection
       end
 
+      # @param block [Proc]
       # @return [Enumerator]
       def each(&block)
         @collection.each(&block)

data/lib/vedeu/models/focus.rb

@@ -23,7 +23,7 @@ module Vedeu
         storage
 
       else
-        Vedeu.log("Storing focus entry: '#{name}'")
+        Vedeu.log(type: :store, message: "Storing focus entry: '#{name}'")
 
         if focus
           storage.unshift(name)
@@ -140,7 +140,7 @@ module Vedeu
     def update
       return false if empty?
 
-      Vedeu.log("Interface in focus: '#{current}'")
+      Vedeu.log(type: :info, message: "Interface in focus: '#{current}'")
 
       refresh
 
@@ -149,7 +149,7 @@ module Vedeu
 
     # Access to the storage for this repository.
     #
-    # @return [Hash]
+    # @return [Array]
     def storage
       @_storage ||= in_memory
     end

data/lib/vedeu/models/geometry.rb

@@ -26,6 +26,7 @@ module Vedeu
   #            south
   #
   # @api private
+  #
   class Geometry
 
     include Vedeu::Model
@@ -146,23 +147,14 @@ module Vedeu
       Vedeu::Limit.apply(y, @height, Terminal.height, Terminal.origin)
     end
 
-    # Returns an escape sequence to position the cursor at the top-left
-    # coordinate, relative to the interface's position.
-    #
-    # @param index [Fixnum]
-    # @param block [Proc]
-    # @return [String]
-    def origin(index = 0, &block)
-      Esc.set_position(*raw_origin(index), &block)
-    end
-
-    # Returns a tuple which positions the cursor at the top-left coordinate,
-    # relative to the interface's position.
+    # Returns the position of the cursor at the top-left coordinate, relative to
+    # the interface's position.
     #
-    # @param index [Fixnum]
-    # @return [Array<Fixnum>]
-    def raw_origin(index = 0)
-      [virtual_y[index], left]
+    # @param y_index [Fixnum]
+    # @param x_index [Fixnum]
+    # @return [Vedeu::Position]
+    def origin(y_index = 0, x_index = 0)
+      Vedeu::Position.new(virtual_y[y_index], virtual_x[x_index])
     end
 
     # Returns the top coordinate of the interface, a fixed or dynamic value

data/lib/vedeu/models/group.rb

@@ -4,6 +4,7 @@ module Vedeu
   # Group. A Group is a collection of interface names.
   #
   # @api private
+  #
   class Group
 
     include Vedeu::Model

data/lib/vedeu/models/menu.rb

@@ -6,6 +6,7 @@ module Vedeu
   # navigated using the instance methods or events provided.
   #
   # @api private
+  #
   class Menu
 
     include Vedeu::Model
@@ -74,7 +75,7 @@ module Vedeu
     # Returns the item from the collection which shares the same index as the
     # value of {Vedeu::Menu#current}.
     #
-    # @return []
+    # @return [void]
     def current_item
       @collection[@current]
     end

data/lib/vedeu/models/model.rb

@@ -4,10 +4,14 @@ module Vedeu
   # repository for later retrieval.
   #
   # @api private
+  #
   module Model
 
     attr_reader :repository
 
+    # When {Vedeu::Model} is included in a class, the methods within this module
+    # are included as class methods on that class.
+    #
     module ClassMethods
 
       # Build models using a simple DSL when a block is given, otherwise returns
@@ -29,7 +33,7 @@ module Vedeu
       #
       # @param klass [Class] The member (singular) or collection (multiple)
       #   class name for the respective model.
-      # @return []
+      # @return [void]
       def child(klass)
         send(:define_method, __callee__) { klass }
       end
@@ -54,6 +58,7 @@ module Vedeu
     # methods for the class.
     #
     # @param klass [Class]
+    # @return [void]
     def self.included(klass)
       klass.send :extend, ClassMethods
     end
@@ -84,6 +89,7 @@ module Vedeu
     #   demodulize('Vedeu::DSL::Interface') # => "Interface"
     #
     # @param klass [Class|String]
+    # @return [void]
     def demodulize(klass)
       klass = klass.to_s