vedeu 0.1.18 → 0.1.19

data/lib/vedeu/support/event.rb

@@ -1,6 +1,12 @@
 module Vedeu
+
+  # Contains all the logic of an event. Handles debouncing and throttling.
+  #
+  # @api private
   class Event
 
+    # Returns a new instance of Event.
+    #
     # @param closure [Proc]
     # @param options [Hash]
     # @return [Event]
@@ -12,6 +18,8 @@ module Vedeu
       @now          = 0
     end
 
+    # Triggers the event based on debouncing and throttling conditions.
+    #
     # @param args [Array]
     # @return []
     def trigger(*args)
@@ -27,6 +35,8 @@ module Vedeu
     attr_reader   :closure
     attr_accessor :deadline, :executed_at, :now
 
+    # Execute the code stored in the event closure.
+    #
     # @api private
     # @return []
     def execute(*args)
@@ -39,6 +49,10 @@ module Vedeu
       closure.call(*args)
     end
 
+    # Returns a boolean indicating whether throttling is required for this
+    # event. Setting the delay option to any value greater than 0 will enable
+    # throttling.
+    #
     # @api private
     # @return [TrueClass|FalseClass]
     def throttling?
@@ -47,6 +61,10 @@ module Vedeu
       options[:delay] > 0
     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]
     def debouncing?
@@ -104,13 +122,13 @@ module Vedeu
     # @api private
     # @return [Fixnum|Float]
     def debounce
-      options[:debounce]
+      options[:debounce] || defaults[:debounce]
     end
 
     # @api private
     # @return [Fixnum|Float]
     def delay
-      options[:delay]
+      options[:delay] || defaults[:delay]
     end
 
     # @api private
@@ -123,8 +141,8 @@ module Vedeu
     # @return [Hash]
     def defaults
       {
-        delay:    0,
-        debounce: 0
+        delay:    0.0,
+        debounce: 0.0
       }
     end
 

data/lib/vedeu/support/grid.rb

@@ -1,3 +1,5 @@
+# Monkey-patch Ruby's Fixnum to provide a columns method.
+# TODO: Don't monkey-patch because it is naughty.
 class Fixnum
 
   # Augment Fixnum to calculate column width in a grid-based layout.
@@ -12,15 +14,20 @@ class Fixnum
   #                     # Terminal is 92 characters wide, maximum value is
   #                     # therefore 84, meaning a column is 7 characters wide.
   def columns
-     Vedeu::Grid.columns(self)
+    Vedeu::Grid.columns(self)
   end
 end
 
 module Vedeu
+
+  # Divides horizontal terminal space into 12 equal columns, discarding
+  # the remainder.
+  #
+  # @api private
   class Grid
 
     # @param value [Fixnum]
-    # @return []
+    # @return [Fixnum]
     def self.columns(value)
       new(value).columns
     end
@@ -31,7 +38,7 @@ module Vedeu
       @value = value
     end
 
-    # @return []
+    # @return [Fixnum|OutOfRange]
     def columns
       fail OutOfRange, 'Valid range is 1..12.' if out_of_range?
 

data/lib/vedeu/support/log.rb

@@ -2,6 +2,7 @@ require 'fileutils'
 require 'time'
 
 module Vedeu
+  # :nocov:
   class MonoLogger < Logger
     # Create a trappable Logger instance.
     #
@@ -27,7 +28,11 @@ module Vedeu
       end
     end
 
+    # Ensures we can always write to the log file by creating a lock-less
+    # log device.
     class LocklessLogDevice < LogDevice
+
+      # @return []
       def initialize(log = nil)
         @dev = @filename = @shift_age = @shift_size = nil
         if log.respond_to?(:write) and log.respond_to?(:close)
@@ -39,18 +44,21 @@ module Vedeu
         end
       end
 
+      # @return []
       def write(message)
         @dev.write(message)
       rescue Exception => ignored
         warn("log writing failed. #{ignored}")
       end
 
+      # @return []
       def close
         @dev.close rescue nil
       end
 
-    private
+      private
 
+      # @return []
       def open_logfile(filename)
         if (FileTest.exist?(filename))
           open(filename, (File::WRONLY | File::APPEND))
@@ -59,6 +67,7 @@ module Vedeu
         end
       end
 
+      # @return []
       def create_logfile(filename)
         logdev = open(filename, (File::WRONLY | File::APPEND | File::CREAT))
         logdev.sync = true
@@ -66,6 +75,7 @@ module Vedeu
         logdev
       end
 
+      # @return []
       def add_log_header(file)
         file.write(
           "# Logfile created on %s by %s\n" % [Time.now.to_s, Logger::ProgName]
@@ -74,6 +84,8 @@ module Vedeu
     end
   end
 
+  # Provides the ability to Log anything to the Vedeu log file which is
+  # hard-coded to reside in `$HOME/.vedeu/vedeu.log`.
   class Log
 
     # @return [TrueClass]
@@ -108,4 +120,5 @@ module Vedeu
     end
 
   end
+  # :nocov:
 end

data/lib/vedeu/support/menu.rb

@@ -1,6 +1,12 @@
 module Vedeu
+
+  # Converts the collection passed into a list of menu items which can be
+  # navigated using the instance methods or events provided.
+  #
   class Menu
 
+    # Returns a new instance of Menu.
+    #
     # @param collection []
     # @return [Menu]
     def initialize(collection)
@@ -10,6 +16,8 @@ module Vedeu
       @events     = events
     end
 
+    # Creates events to manipulate this menu.
+    #
     # @return []
     def events
       @_events ||= Vedeu.events.add(self) do
@@ -26,28 +34,41 @@ module Vedeu
       end
     end
 
-    # @return []
+    # Returns the index of the value in the collection which is current.
+    #
+    # @return [Fixnum]
     def current
       @current
     end
 
-    # @return []
+    # Returns the index of the value in the collection which is selected.
+    #
+    # @return [Fixnum]
     def selected
       @selected
     end
 
+    # Returns the item from the collection which shares the same index as the
+    # value of {Vedeu::Menu#current}.
+    #
     # @return []
     def current_item
       @collection[@current]
     end
 
-    # @return []
+    # Returns the item from the collection which shares the same index as the
+    # value of {Vedeu::Menu#selected}.
+    #
+    # @return [|NilClass]
     def selected_item
       return nil unless @selected
 
       @collection[@selected]
     end
 
+    # Returns a new collection of items, which includes the `current` and
+    # `selected` states.
+    #
     # @return [Array]
     def items
       items = []
@@ -69,59 +90,77 @@ module Vedeu
       items
     end
 
-    # @return []
+    # @return [Array]
     def view
       items[@current, @collection.size]
     end
 
-    # @return []
+    # Sets the value of current to be the first item of the collection.
+    #
+    # @return [Array]
     def top_item
       @current = 0
 
       items
     end
 
-    # @return []
+    # Sets the value of current to be the last item of the collection.
+    #
+    # @return [Array]
     def bottom_item
       @current = last
 
       items
     end
 
-    # @return []
+    # Sets the value of current to be the next item in the collection until we
+    # reach the last.
+    #
+    # @return [Array]
     def next_item
       @current += 1 if @current < last
 
       items
     end
 
-    # @return []
+    # Sets the value of current to be the previous item in the collection until
+    # we reach the first.
+    #
+    # @return [Array]
     def prev_item
       @current -= 1 if @current > 0
 
       items
     end
 
-    # @return []
+    # Sets the selected item to be the same value as the current item.
+    #
+    # @return [Array]
     def select_item
       @selected = @current
 
       items
     end
 
-    # @return []
+    # Removes the value of `selected`, meaning no items are selected.
+    #
+    # @return [Array]
     def deselect_item
       @selected = nil
 
       items
     end
 
-    # @return []
+    # Returns the last index of the collection.
+    #
+    # @return [Fixnum]
     def last
       @collection.size - 1
     end
 
-    # @return []
+    # Returns the size of the collection.
+    #
+    # @return [Fixnum]
     def size
       @collection.size
     end

data/lib/vedeu/support/position.rb

@@ -1,6 +1,12 @@
 module Vedeu
+
+  # Change coordinates into an escape sequence to set the cursor position.
+  #
+  # @api private
   class Position
 
+    # Initializes a new instance of Position.
+    #
     # @param y [Fixnum]
     # @param x [Fixnum]
     # @return [Position]
@@ -8,6 +14,9 @@ module Vedeu
       @y, @x = y, x
     end
 
+    # Returns an escape sequence to position the cursor. When passed a block,
+    # will position the cursor, yield and return the original position.
+    #
     # @param block [Proc]
     # @return [String]
     def to_s(&block)

data/lib/vedeu/support/terminal.rb

@@ -1,10 +1,18 @@
 module Vedeu
+
+  # This module is the direct interface between Vedeu and your terminal/
+  # console, via Ruby's IO core library.
+  #
+  # @api private
   module Terminal
 
     extend self
 
+    # Opens a terminal screen in either `raw` or `cooked` mode. On exit,
+    # attempts to restore the screen. See {Vedeu::Terminal#restore_screen}.
+    #
     # @param block [Proc]
-    # @return []
+    # @return [Array]
     def open(&block)
       fail InvalidSyntax, '`open` requires a block.' unless block_given?
 
@@ -20,7 +28,11 @@ module Vedeu
 
     end
 
+    # Takes input from the user via the keyboard. Accepts special keys like
+    # the F-Keys etc, by capturing the entire sequence.
+    #
     # @return [String]
+    # :nocov:
     def input
       if raw_mode?
         keys = console.getch
@@ -35,13 +47,16 @@ module Vedeu
 
       end
     end
+    # :nocov:
 
-    # @param stream [String]
-    # @return [String]
-    def output(stream = '')
-      console.print(stream)
+    # Prints the streams to the screen and returns the streams.
+    #
+    # @param streams [String|Array]
+    # @return [Array]
+    def output(*streams)
+      streams.each { |stream| console.print(stream) }
 
-      stream
+      streams
     end
 
     # @param block [Proc]
@@ -52,42 +67,64 @@ module Vedeu
       yield
     end
 
+    # Clears the entire terminal space.
+    #
     # @return [String]
     def clear_screen
       output Esc.string 'clear'
     end
 
+    # Attempts to tidy up the screen just before the application terminates.
+    # The cursor is shown, colours are reset to terminal defaults, the
+    # terminal is told to reset, and finally we clear the last line ready for
+    # the prompt.
+    #
     # @return [String]
     def restore_screen
-      output Esc.string 'screen_exit'
-      output clear_last_line
+      output(Esc.string('screen_exit'), Esc.string('clear_last_line'))
     end
 
+    # Sets the cursor to be visible unless in raw mode, whereby it will be left
+    # hidden.
+    #
     # @return [String]
     def set_cursor_mode
       output Esc.string 'show_cursor' unless raw_mode?
     end
 
+    # Returns a boolean indicating whether the terminal is currently in `cooked`
+    # mode.
+    #
     # @return [Boolean]
     def cooked_mode?
       mode == :cooked
     end
 
+    # Sets the terminal in to `cooked` mode.
+    #
     # @return [Symbol]
     def cooked_mode!
       @_mode = :cooked
     end
 
+    # Returns a boolean indicating whether the terminal is currently in `raw`
+    # mode.
+    #
     # @return [Boolean]
     def raw_mode?
       mode == :raw
     end
 
+    # Sets the terminal in to `raw` mode.
+    #
     # @return [Symbol]
     def raw_mode!
       @_mode = :raw
     end
 
+    # Toggles the terminal's mode between `cooked` and `raw`, depending on its
+    # current mode.
+    #
     # @return [Symbol]
     def switch_mode!
       if raw_mode?
@@ -99,11 +136,6 @@ module Vedeu
       end
     end
 
-    # @return [String]
-    def clear_last_line
-      Esc.set_position((height - 1), 1) + Esc.string('clear_line')
-    end
-
     # Returns the mode of the terminal, either `:raw` or `:cooked`
     #
     # @return [Symbol]
@@ -120,7 +152,7 @@ module Vedeu
     end
 
     # Returns the `y` (row/line) component of the coordinate tuple provided by
-    # {Terminal.centre}
+    # {Vedeu::Terminal.centre}
     #
     # @return [Fixnum]
     def centre_y
@@ -128,7 +160,7 @@ module Vedeu
     end
 
     # Returns the `x` (column/character) component of the coodinate tuple
-    # provided by {Terminal.centre}
+    # provided by {Vedeu::Terminal.centre}
     #
     # @return [Fixnum]
     def centre_x
@@ -157,6 +189,8 @@ module Vedeu
       console.winsize
     end
 
+    # Provides our gateway into the wonderful rainbow-filled world of IO.
+    #
     # @return [File]
     def console
       IO.console