vedeu 0.2.2 → 0.2.3

data/lib/vedeu/api/stream.rb

@@ -1,4 +1,5 @@
 module Vedeu
+
   module API
 
     # Provides methods to be used to define views.
@@ -11,7 +12,6 @@ module Vedeu
       # Specify the alignment of the stream within the line. Useful in
       # combination with {#width} to provide simple formatting effects.
       #
-      # @api public
       # @param value [Symbol] `:left`, `:centre` and `right` are valid values
       #   and will align accordingly. If not value is specified, the stream will
       #   left align.
@@ -22,6 +22,8 @@ module Vedeu
       #       align :right
       #       ...
       #
+      # @raise [InvalidSyntax] When the value parameter is not one of +:left+,
+      #   +:right+ or +:centre+.
       # @return [Symbol]
       def align(value)
         unless [:left, :right, :centre].include?(value.to_sym)
@@ -55,7 +57,6 @@ module Vedeu
 
       # Add textual data to the stream via this method.
       #
-      # @api public
       # @param value [String] The text to be added to the stream. If the length
       #   of the text is greater than the interface's width, it will be
       #   truncated and ellipsized.
@@ -75,7 +76,6 @@ module Vedeu
       # stream. Useful in combination with #align to provide simple formatting
       # effects.
       #
-      # @api public
       # @param value [Fixnum] The width in characters.
       #
       # @example
@@ -89,6 +89,8 @@ module Vedeu
         attributes[:width] = value
       end
 
-    end
-  end
-end
+    end # Stream
+
+  end # API
+
+end # Vedeu

data/lib/vedeu/application.rb

@@ -18,11 +18,11 @@ module Vedeu
       #   the client application may treat this event as Vedeu signalling that it
       #   is about to terminate. Client applications are encouraged to use this
       #   event to close any open buffers, save files, empty trash, etc.
-      # - A StopIteration exception is raised which will cause {#start} to exit
-      #   its looop and terminate the application.
       #
       # @api private
-      # @return [Exception]
+      # @raise [StopIteration] Will cause {#start} to exit its loop and
+      #   terminate the application.
+      # @return [StopIteration]
       def stop
         Vedeu.trigger(:_cleanup_)
 
@@ -73,10 +73,11 @@ module Vedeu
     end
 
     # For an interactive application we capture input, (usually from the user),
-    # and continue the main loop.
-    #
-    # @todo It appears for non-interactive applications, we do nothing. Must
-    #   investigate.
+    # and continue the main loop. If the client application does not require
+    # user input then Vedeu triggers the `:_standalone_` event for each run of
+    # the main loop. The client application is expected to respond to this event
+    # and 'do something useful'. When the client application has finished, it
+    # should trigger the `:_exit_` event.
     #
     # @api private
     # @return []
@@ -85,13 +86,14 @@ module Vedeu
         Input.capture
 
       else
-
+        Vedeu.trigger(:_standalone_)
 
       end
     end
 
-    # Runs the application in a continuous loop. This loop is stopped elsewhere
-    # with the raising of the StopIteration exception.
+    # Runs the application in a continuous loop. This loop is stopped when an
+    # uncaught exception occurs or when either the `:_mode_switch_` or `:_exit_`
+    # event is triggered.
     #
     # @api private
     # @return []
@@ -105,6 +107,6 @@ module Vedeu
 
     end
 
-  end
+  end # Application
   # :nocov:
-end
+end # Vedeu

data/lib/vedeu/configuration/api.rb

@@ -60,6 +60,8 @@ module Vedeu
       # @param value [Boolean]
       # @return [Boolean]
       def interactive!(value = true)
+        Vedeu.log("Configuration::API interactive: #{value.to_s}")
+
         options[:interactive] = value
       end
       alias_method :interactive, :interactive!
@@ -75,6 +77,8 @@ module Vedeu
       # @param value [Boolean]
       # @return [Boolean]
       def standalone!(value = true)
+        Vedeu.log("Configuration::API interactive: #{!value.to_s}")
+
         options[:interactive] = !value
       end
       alias_method :standalone, :standalone!
@@ -91,6 +95,8 @@ module Vedeu
       # @param value [Boolean]
       # @return [Boolean]
       def run_once!(value = true)
+        Vedeu.log("Configuration::API once: #{value.to_s}")
+
         options[:once] = value
       end
       alias_method :run_once, :run_once!
@@ -104,6 +110,8 @@ module Vedeu
       #
       # @return [Boolean]
       def cooked!
+        Vedeu.log("Configuration::API terminal_mode: :cooked")
+
         options[:terminal_mode] = :cooked
       end
       alias_method :cooked, :cooked!
@@ -117,6 +125,8 @@ module Vedeu
       #
       # @return [Boolean]
       def raw!
+        Vedeu.log("Configuration::API terminal_mode: :raw")
+
         options[:terminal_mode] = :raw
       end
       alias_method :raw, :raw!
@@ -139,9 +149,13 @@ module Vedeu
       # @return [Boolean]
       def debug!(value = true)
         if options.key?(:trace) && options[:trace] != false
+          Vedeu.log("Configuration::API debug: true")
+
           options[:debug] = true
 
         else
+          Vedeu.log("Configuration::API debug: #{value.to_s}")
+
           options[:debug] = value
 
         end
@@ -166,6 +180,8 @@ module Vedeu
       def trace!(value = true)
         options[:debug] = true if value === true
 
+        Vedeu.log("Configuration::API trace: #{value.to_s}")
+
         options[:trace] = value
       end
       alias_method :trace, :trace!
@@ -178,11 +194,15 @@ module Vedeu
       #     ...
       #
       # @param value [Fixnum]
+      # @raise [InvalidSyntax] When the value parameter is not one of +8+, +16+,
+      #   +256+ or +16777216+.
       # @return [Boolean]
       def colour_mode(value = nil)
         fail InvalidSyntax, '`colour_mode` must be `8`, `16`, `256`, ' \
                             '`16777216`.' unless valid_colour_mode?(value)
 
+        Vedeu.log("Configuration::API colour_mode: #{value.to_s}")
+
         options[:colour_mode] = value
       end
 
@@ -202,6 +222,8 @@ module Vedeu
       def exit_key(value)
         return invalid_key('exit_key') unless valid_key?(value)
 
+        Vedeu.log("Configuration::API exit_key: #{value.to_s}")
+
         system_key_options[:exit] = value
       end
 
@@ -222,6 +244,8 @@ module Vedeu
       def focus_next_key(value)
         return invalid_key('exit_key') unless valid_key?(value)
 
+        Vedeu.log("Configuration::API focus_next: #{value.to_s}")
+
         system_key_options[:focus_next] = value
       end
 
@@ -242,6 +266,8 @@ module Vedeu
       def focus_prev_key(value)
         return invalid_key('exit_key') unless valid_key?(value)
 
+        Vedeu.log("Configuration::API focus_prev: #{value.to_s}")
+
         system_key_options[:focus_prev] = value
       end
 
@@ -262,6 +288,8 @@ module Vedeu
       def mode_switch_key(value)
         return invalid_key('exit_key') unless valid_key?(value)
 
+        Vedeu.log("Configuration::API mode_switch: #{value.to_s}")
+
         system_key_options[:mode_switch] = value
       end
 
@@ -315,13 +343,15 @@ module Vedeu
       # @api private
       # @param system_key [String] The calling method wishing to raise an
       #   exception.
+      # @raise [InvalidSyntax] When the system_key parameter is not a String or
+      #   Symbol.
       # @return [InvalidSyntax]
       def invalid_key(system_key)
         fail InvalidSyntax, "`#{system_key}` must be a String or a Symbol."
       end
 
-    end
+    end # API
 
-  end
+  end # Configuration
 
-end
+end # Vedeu

data/lib/vedeu/configuration/cli.rb

@@ -36,39 +36,55 @@ module Vedeu
 
           opts.on('-i', '--interactive',
                   'Run the application in interactive mode (default).') do
+            Vedeu.log("Configuration::CLI interactive: true")
+
             options[:interactive] = true
           end
 
           opts.on('-I', '--noninteractive', '--standalone',
                   'Run the application non-interactively; i.e. not requiring ' \
                   'intervention from the user.') do
+            Vedeu.log("Configuration::CLI interactive: false")
+
             options[:interactive] = false
           end
 
           opts.on('-1', '--run-once',
                   'Run the application loop once.') do
+            Vedeu.log("Configuration::CLI once: true")
+
             options[:once] = true
           end
 
           opts.on('-n', '--run-many',
                   'Run the application loop continuously (default).') do
+            Vedeu.log("Configuration::CLI once: false")
+
             options[:once] = false
           end
 
           opts.on('-c', '--cooked', 'Run application in cooked mode.') do
+            Vedeu.log("Configuration::CLI terminal_mode: :cooked")
+
             options[:terminal_mode] = :cooked
           end
 
           opts.on('-r', '--raw', 'Run application in raw mode (default).') do
+            Vedeu.log("Configuration::CLI terminal_mode: :raw")
+
             options[:terminal_mode] = :raw
           end
 
           opts.on('-d', '--debug', 'Run application with debugging on.') do
+            Vedeu.log("Configuration::CLI debug: true")
+
             options[:debug] = true
           end
 
           opts.on('-D', '--trace', 'Run application with debugging on with ' \
                                    'method and event tracing (noisy!).') do
+            Vedeu.log("Configuration::CLI trace: true")
+
             options[:debug] = true
             options[:trace] = true
           end
@@ -77,9 +93,13 @@ module Vedeu
                   'Run application in either `8`, `16`, `256` or `16777216` ' \
                   'colour mode.') do |colours|
             if [8, 16, 256, 16777216].include?(colours)
+              Vedeu.log("Configuration::CLI colour_mode: #{colours.to_s}")
+
               options[:colour_mode] = colours
 
             else
+              Vedeu.log("Configuration::CLI colour_mode: 8 (defaulted)")
+
               options[:colour_mode] = 8
 
             end
@@ -103,8 +123,8 @@ module Vedeu
         @_options ||= {}
       end
 
-    end
+    end # CLI
 
-  end
+  end # Configuration
 
-end
+end # Vedeu

data/lib/vedeu/configuration/configuration.rb

@@ -194,5 +194,6 @@ module Vedeu
     end
     # :nocov:
 
-  end
-end
+  end # Configuration
+
+end # Vedeu

data/lib/vedeu/input/input.rb

@@ -37,6 +37,9 @@ module Vedeu
       specials.fetch(key, key)
     end
 
+    # Translates (if possible) entered escape sequences into symbols
+    # representing the key which was pressed.
+    #
     # @api private
     # @return [Hash]
     def specials
@@ -73,5 +76,6 @@ module Vedeu
       }
     end
 
-  end
-end
+  end # Input
+
+end # Vedeu

data/lib/vedeu/launcher.rb

@@ -41,6 +41,8 @@ module Vedeu
       puts uncaught_exception.backtrace.join("\n")
 
     ensure
+      Vedeu.log("Exiting gracefully.")
+
       $stdin, $stdout, $stderr = STDIN, STDOUT, STDERR
       @kernel.exit(@exit_code)
 
@@ -50,5 +52,6 @@ module Vedeu
 
     attr_reader :argv
 
-  end
-end
+  end # Launcher
+
+end # Vedeu

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

@@ -46,5 +46,6 @@ module Vedeu
       codes.inject({}){ |h, (k, v)| h.merge(k => v + 10) }
     end
 
-  end
-end
+  end # Background
+
+end # Vedeu

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

@@ -33,5 +33,6 @@ module Vedeu
       receiver.extend(self)
     end
 
-  end
-end
+  end # Coercions
+
+end # Vedeu

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

@@ -76,6 +76,8 @@ module Vedeu
     end
 
     # @api private
+    # @raise [NotImplemented] Subclasses of this class must implement this
+    #   method.
     # @return [Exception]
     def named
       fail NotImplemented, 'Subclasses implement this.'
@@ -94,7 +96,9 @@ module Vedeu
     end
 
     # @api private
-    # @return [Exception]
+    # @raise [NotImplemented] Subclasses of this class must implement this
+    #   method.
+    # @return [NotImplemented]
     def numbered
       fail NotImplemented, 'Subclasses implement this.'
     end
@@ -112,7 +116,9 @@ module Vedeu
     end
 
     # @api private
-    # @return [Exception]
+    # @raise [NotImplemented] Subclasses of this class must implement this
+    #   method.
+    # @return [NotImplemented]
     def rgb
       fail NotImplemented, 'Subclasses implement this.'
     end
@@ -179,5 +185,6 @@ module Vedeu
       }
     end
 
-  end
-end
+  end # ColourTranslator
+
+end # Vedeu

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

@@ -41,5 +41,6 @@ module Vedeu
       codes
     end
 
-  end
-end
+  end # Foreground
+
+end # Vedeu

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

@@ -84,5 +84,6 @@ module Vedeu
       Style.new(parent[:style]).to_s
     end
 
-  end
-end
+  end # Presentation
+
+end # Vedeu

data/lib/vedeu/models/colour.rb

@@ -50,5 +50,6 @@ module Vedeu
       }
     end
 
-  end
-end
+  end # Colour
+
+end # Vedeu

data/lib/vedeu/models/composition.rb

@@ -61,8 +61,11 @@ module Vedeu
     # @api private
     # @return []
     def method_missing(method, *args, &block)
+      Vedeu.log("Composition#method_missing '#{method.to_s}' (args: #{args.inspect})")
+
       @self_before_instance_eval.send(method, *args, &block)
     end
 
-  end
-end
+  end # Composition
+
+end # Vedeu

data/lib/vedeu/models/cursor.rb

@@ -256,6 +256,7 @@ module Vedeu
         state: :hide,
       }
     end
-  end
 
-end
+  end # Cursor
+
+end # Vedeu

data/lib/vedeu/models/geometry.rb

@@ -162,6 +162,9 @@ module Vedeu
     # Returns the bottom coordinate of the interface, a fixed or dynamic value
     # depending on the value of {#top}.
     #
+    # @todo I think `height` should be `viewport_height` because the terminal
+    #   may have resized, and viewport_height will properly handle this.
+    #
     # @return [Fixnum]
     def bottom
       top + height
@@ -185,6 +188,9 @@ module Vedeu
     # Returns the right coordinate of the interface, a fixed or dynamic value
     # depending on the value of {#left}.
     #
+    # @todo I think `width` should be `viewport_width` because the terminal may
+    #   have resized, and viewport_width will properly handle this.
+    #
     # @return [Fixnum]
     def right
       left + width
@@ -205,22 +211,57 @@ module Vedeu
       right + value
     end
 
-    private
-
     # Provides a virtual y position within the interface's dimensions.
     #
+    # @example
+    #   # top = 3
+    #   # bottom = 6
+    #   # virtual_y # => [3, 4, 5]
+    #
     # @return [Array]
     def virtual_y
-      (top..bottom).to_a
+      (top...bottom).to_a
     end
 
     # Provides a virtual x position within the interface's dimensions.
     #
+    # @example
+    #   # left = 9
+    #   # right = 13
+    #   # virtual_x # => [9, 10, 11, 12]
+    #
     # @return [Array]
     def virtual_x
-      (left..right).to_a
+      (left...right).to_a
     end
 
+    # Provides all the geometry in a convenient hash.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        centred:         centred,
+        height:          height,
+        width:           width,
+        x:               x,
+        y:               y,
+        viewport_height: viewport_height,
+        viewport_width:  viewport_width,
+        top:             top,
+        right:           right,
+        bottom:          bottom,
+        left:            left,
+        north:           north,
+        east:            east,
+        south:           south,
+        west:            west,
+        virtual_x:       virtual_x,
+        virtual_y:       virtual_y,
+      }
+    end
+
+    private
+
     # The default geometry of an interface- full screen.
     #
     # @return [Hash]
@@ -234,5 +275,6 @@ module Vedeu
       }
     end
 
-  end
-end
+  end # Geometry
+
+end # Vedeu

data/lib/vedeu/models/interface.rb

@@ -67,6 +67,13 @@ module Vedeu
       self
     end
 
+    # Returns a boolean indicating whether this interface is currently in focus.
+    #
+    # @return [Boolean]
+    def in_focus?
+      Focus.current?(name)
+    end
+
     # Returns a collection of lines associated with this interface.
     #
     # @return [Array]
@@ -103,8 +110,11 @@ module Vedeu
     # @api private
     # @return []
     def method_missing(method, *args, &block)
+      Vedeu.log("Interface#method_missing '#{method.to_s}' (args: #{args.inspect})")
+
       @self_before_instance_eval.send(method, *args, &block)
     end
 
-  end
-end
+  end # Interface
+
+end # Vedeu

data/lib/vedeu/models/keymap.rb

@@ -60,9 +60,11 @@ module Vedeu
     # @api private
     # @return []
     def method_missing(method, *args, &block)
+      Vedeu.log("Keymap#method_missing '#{method.to_s}' (args: #{args.inspect})")
+
       @self_before_instance_eval.send(method, *args, &block)
     end
 
-  end
+  end # Keymap
 
-end
+end # Vedeu

data/lib/vedeu/models/line.rb

@@ -70,8 +70,11 @@ module Vedeu
     # @api private
     # @return []
     def method_missing(method, *args, &block)
+      Vedeu.log("Line#method_missing '#{method.to_s}' (args: #{args.inspect})")
+
       @self_before_instance_eval.send(method, *args, &block)
     end
 
-  end
-end
+  end # Line
+
+end # Vedeu

data/lib/vedeu/models/stream.rb

@@ -40,6 +40,13 @@ module Vedeu
       end
     end
 
+    # Returns the content of this stream.
+    #
+    # @return [String]
+    def content
+      data
+    end
+
     private
 
     # Returns the text aligned if a width was set, otherwise just the text.
@@ -89,8 +96,11 @@ module Vedeu
     # @api private
     # @return []
     def method_missing(method, *args, &block)
+      Vedeu.log("Stream#method_missing '#{method.to_s}' (args: #{args.inspect})")
+
       @self_before_instance_eval.send(method, *args, &block)
     end
 
-  end
-end
+  end # Stream
+
+end # Vedeu

data/lib/vedeu/models/style.rb

@@ -48,5 +48,6 @@ module Vedeu
       end.join
     end
 
-  end
-end
+  end # Style
+
+end # Vedeu

data/lib/vedeu/output/clear.rb

@@ -29,6 +29,8 @@ module Vedeu
     #
     # @return [String]
     def clear
+      Vedeu.log("Clearing view: '#{interface.name}'")
+
       rows.inject([colours]) do |line, index|
         line << interface.origin(index) { ' ' * interface.viewport_width }
       end.join
@@ -50,5 +52,6 @@ module Vedeu
       interface.viewport_height.times
     end
 
-  end
-end
+  end # Clear
+
+end # Vedeu