vedeu 0.6.7 → 0.6.8

data/lib/vedeu/logging/log.rb

@@ -0,0 +1,179 @@
+module Vedeu
+
+  module Logging
+
+    # Provides the ability to log anything to the Vedeu log file.
+    #
+    class Log
+
+      class << self
+
+        # Write a message to the Vedeu log file.
+        #
+        # @example
+        #   Vedeu.log(type:    :debug,
+        #             message: 'A useful debugging message: Error!')
+        #
+        # @param message [String] The message you wish to emit to the
+        #   log file, useful for debugging.
+        # @param force [Boolean] When evaluates to true will attempt
+        #   to write to the log file regardless of the Configuration
+        #   setting.
+        # @param type [Symbol] Colour code messages in the log file
+        #   depending on their source. See {message_types}
+        #
+        # @return [TrueClass]
+        def log(message:, force: false, type: :info)
+          output = log_entry(type, message)
+
+          if (enabled? || force) && (Vedeu::Configuration.log_only.empty? ||
+                     Vedeu::Configuration.log_only.include?(type))
+            logger.debug(output)
+          end
+
+          output
+        end
+
+        # Write a message to STDOUT.
+        #
+        # @example
+        #   Vedeu.log_stdout
+        #
+        # @return [TrueClass]
+        def log_stdout(type: :info, message:)
+          $stdout.puts log_entry(type, message)
+        end
+
+        # Write a message to STDERR.
+        #
+        # @example
+        #   Vedeu.log_stderr
+        #
+        # @return [TrueClass]
+        def log_stderr(type: :info, message:)
+          $stderr.puts log_entry(type, message)
+        end
+
+        private
+
+        # @return [TrueClass]
+        def logger
+          MonoLogger.new(log_file).tap do |log|
+            log.formatter = proc do |_, _, _, message|
+              formatted_message(message)
+            end
+          end
+        end
+
+        # Returns the message with timestamp.
+        #
+        #    [ 0.0987] [debug]  Something happened.
+        #
+        # @param message [String] The message type and message
+        #   coloured and combined.
+        # @return [String]
+        def formatted_message(message)
+          "#{timestamp}#{message}\n" if message
+        end
+
+        # Returns the message:
+        #
+        #     [type] message
+        #
+        # @param type [Symbol] The type of log message.
+        # @param message [String] The message you wish to emit to the
+        #   log file, useful for debugging.
+        # @return [String]
+        def log_entry(type, message)
+          "#{message_type(type)}#{message_body(type, message)}"
+        end
+
+        # Fetches the filename from the configuration.
+        #
+        # @return [String]
+        def log_file
+          Vedeu::Configuration.log
+        end
+        alias_method :enabled?, :log_file
+
+        # Displays the message body using the colour specified in the
+        # last element of {message_types}.
+        #
+        # @param type [Symbol] The type of log message.
+        # @param body [String] The log message itself.
+        # @return [String]
+        def message_body(type, body)
+          Vedeu::Esc.send(message_types.fetch(type, :default)[-1]) do
+            body
+          end
+        end
+
+        # Displays the message type using the colour specified in the
+        # first element of {message_types}.
+        #
+        # @param type [Symbol] The type of log message.
+        # @return [String]
+        def message_type(type)
+          Vedeu::Esc.send(message_types.fetch(type, :default)[0]) do
+            "[#{type}]".ljust(9)
+          end
+        end
+
+        # The defined message types for Vedeu with their respective
+        # colours. When used, produces a log entry of the format:
+        #
+        #     [type] message
+        #
+        # The 'type' will be shown as the first colour defined in the
+        # value array, whilst the 'message' will be shown using the
+        # last colour.
+        #
+        # Valid types available:
+        #
+        #     :config, :create, :debug, :error, :drb, :event, :info,
+        #     :input, :output, :reset, :store, :test, :timer, :update
+        #
+        # @return [Hash<Symbol => Array<Symbol>>]
+        def message_types
+          {
+            config: [:light_yellow,  :yellow],
+            create: [:light_green,   :green],
+            debug:  [:light_red,     :red],
+            error:  [:light_red,     :red],
+            drb:    [:light_blue,    :blue],
+            event:  [:light_magenta, :magenta],
+            info:   [:white,         :default],
+            input:  [:light_yellow,  :yellow],
+            output: [:light_green,   :green],
+            reset:  [:light_cyan,    :cyan],
+            store:  [:light_cyan,    :cyan],
+            test:   [:light_white,   :white],
+            timer:  [:light_yellow,  :yellow],
+            update: [:light_cyan,    :cyan],
+          }
+        end
+
+        # Returns a formatted timestamp.
+        # eg. [137.7824]
+        #
+        # @return [String]
+        def timestamp
+          @now  = Time.now.to_f
+          @time = 0.0  unless @time
+          @last = @now unless @last
+
+          unless @last == @time
+            @time += (@now - @last).round(4)
+            @last = @now
+          end
+
+          "[#{format('%7.4f', @time.to_s)}] ".rjust(7)
+        end
+
+      end # Eigenclass
+
+    end # Log
+
+  end # Logging
+
+end # Vedeu

data/lib/vedeu/logging/mono_logger.rb

@@ -0,0 +1,26 @@
+module Vedeu
+
+  module Logging
+
+    # Allows the creation of a lock-less log device.
+    #
+    class MonoLogger < ::Logger
+
+      # Create a trappable Logger instance.
+      #
+      # @param logdev [String|IO] The filename (String) or IO object
+      #   (typically STDOUT, STDERR or an open file).
+      # @return [Vedeu::Logging::MonoLogger]
+      def initialize(logdev)
+        @level             = Logger::DEBUG
+        @default_formatter = Logger::Formatter.new
+        @formatter         = nil
+
+        @logdev = Vedeu::Logging::LocklessLogDevice.new(logdev) if logdev
+      end
+
+    end # MonoLogger
+
+  end # Logging
+
+end # Vedeu

data/lib/vedeu/logging/timer.rb

@@ -0,0 +1,68 @@
+module Vedeu
+
+  module Logging
+
+    # Measure the duration. Used for debugging.
+    #
+    class Timer
+
+      class << self
+
+        # @example
+        #   Vedeu.timer 'message' do
+        #     # ... code to be measured
+        #   end
+        #
+        # @param message [String]
+        # @param block [Proc]
+        # @return [void] The return value of the executed block.
+        def timer(message = '', &block)
+          new(message).measure(&block)
+        end
+
+      end # Eigenclass
+
+      # Returns a new instance of Vedeu::Logging::Timer.
+      #
+      # @param message [String]
+      # @return [Vedeu::Logging::Timer]
+      def initialize(message = '')
+        @message = message
+        @started = Time.now.to_f
+      end
+
+      # Write an entry to the log file stating how long a section of
+      # code took in milliseconds. Useful for debugging performance.
+      #
+      # @return [void] The return value of the executed block.
+      def measure
+        work = yield
+
+        Vedeu.log(type: :timer, message: "#{message} took #{elapsed}ms.")
+
+        work
+      end
+
+      protected
+
+      # @!attribute [r] started
+      # @return [Time]
+      attr_reader :started
+
+      # @!attribute [r] message
+      # @return [String]
+      attr_reader :message
+
+      # Returns the elapsed time in milliseconds with 3 decimal
+      # places.
+      #
+      # @return [Float]
+      def elapsed
+        ((Time.now.to_f - started) * 1000).round(3)
+      end
+
+    end # Timer
+
+  end # Logging
+
+end # Vedeu

data/lib/vedeu/menus/all.rb

@@ -0,0 +1,12 @@
+module Vedeu
+
+  module Menus
+
+  end # Menus
+
+end # Vedeu
+
+require 'vedeu/menus/dsl'
+require 'vedeu/menus/menu'
+require 'vedeu/menus/null'
+require 'vedeu/menus/repository'

data/lib/vedeu/{dsl/menu.rb → menus/dsl.rb}

@@ -1,19 +1,19 @@
 module Vedeu
 
-  module DSL
+  module Menus
 
-    # Provides the mechanism to create menus within client applications and use
-    # events to drive them.
+    # Provides the mechanism to create menus within client
+    # applications and use events to drive them.
     #
-    class Menu
+    class DSL
 
       include Vedeu::DSL
 
-      # Return a new instance of DSL::Menu.
+      # Return a new instance of Vedeu::Menus::DSL.
       #
-      # @param model [Vedeu::Menu]
+      # @param model [Vedeu::Menus::Menu]
       # @param client [Object]
-      # @return [Vedeu::DSL::Menu]
+      # @return [Vedeu::Menus::DSL]
       def initialize(model, client = nil)
         @model  = model
         @client = client
@@ -21,7 +21,8 @@ module Vedeu
 
       # Add an individual item to the menu.
       #
-      # @param element [Object] An object you wish to add to the collection.
+      # @param element [Object] An object you wish to add to the
+      #   collection.
       #
       #   Vedeu.menu 'my_menu' do
       #     item SomeClass.new
@@ -34,11 +35,11 @@ module Vedeu
       end
       alias_method :item=, :item
 
-      # Define the items for the menu. Most powerful when used with one of your
-      # model classes.
+      # Define the items for the menu. Most powerful when used with
+      # one of your model classes.
       #
-      # In the 'my_playlist' example below, your `Track` model may return a
-      # collection of tracks to populate the menu.
+      # In the 'my_playlist' example below, your `Track` model may
+      # return a collection of tracks to populate the menu.
       #
       #   Vedeu.menu 'my_menu' do
       #     items [:item_1, :item_2, :item_3]
@@ -48,16 +49,16 @@ module Vedeu
       #     items Track.all_my_favourites
       #   end
       #
-      # @param collection [Array<Object>] A collection of objects which make up
-      #   the menu items.
+      # @param collection [Array<Object>] A collection of objects
+      #   which make up the menu items.
       # @return [Array]
       def items(collection = [])
         model.collection = collection
       end
       alias_method :items=, :items
 
-      # The name of the menu. Used to reference the menu throughout your
-      # application's execution lifetime.
+      # The name of the menu. Used to reference the menu throughout
+      # your application's execution lifetime.
       #
       #   Vedeu.menu do
       #     name 'my_menu'
@@ -71,8 +72,8 @@ module Vedeu
       end
       alias_method :name=, :name
 
-    end # Menu
+    end # DSL
 
-  end # DSL
+  end # Menus
 
 end # Vedeu

data/lib/vedeu/menus/menu.rb

@@ -0,0 +1,234 @@
+module Vedeu
+
+  module Menus
+
+    # Converts the collection passed into a list of menu items which
+    # can be navigated using the instance methods or events provided.
+    #
+    class Menu
+
+      include Vedeu::Model
+
+      # @!attribute [rw] collection
+      # @return [Array]
+      attr_accessor :collection
+
+      # Returns the index of the value in the collection which is
+      # current.
+      #
+      # @!attribute [rw] current
+      # @return [Fixnum]
+      attr_accessor :current
+
+      # The name of the menu. Used to reference the menu throughout
+      # the application's execution lifetime.
+      #
+      # @!attribute [rw] name
+      # @return [String]
+      attr_accessor :name
+
+      # Returns the index of the value in the collection which is
+      # selected.
+      #
+      # @!attribute [rw] selected
+      # @return [Fixnum]
+      attr_accessor :selected
+
+      # Register a menu by name which will display a collection of
+      # items for your users to select; and provide interactivity
+      # within your application.
+      #
+      # @param name [String]
+      # @param block [Proc] A set of attributes which define the
+      #   features of the menu. See {Vedeu::Menus::DSL#items} and
+      #   {Vedeu::Menus::DSL#name}.
+      #
+      # @example
+      #   Vedeu.menu 'my_interface' do
+      #     items [:item_1, :item_2, :item_3]
+      #     # ...
+      #   end
+      #
+      #   Vedeu.menu do
+      #     name 'menus_must_have_a_name'
+      #     items Track.all_my_favourites
+      #     # ...
+      #   end
+      #
+      # @raise [Vedeu::Error::InvalidSyntax] The required block was
+      #   not given.
+      # @return [API::Menu]
+      def self.menu(name = '', &block)
+        fail Vedeu::Error::InvalidSyntax, 'block not given' unless block_given?
+
+        build(name: name, &block).store
+      end
+
+      # Returns a new instance of Vedeu::Menus::Menu.
+      #
+      # @param attributes [Hash]
+      # @option attributes collection [Array]
+      # @option attributes name [String]
+      # @option attributes current [Fixnum]
+      # @option attributes selected [Fixnum|NilClass]
+      # @return [Vedeu::Menus::Menu]
+      def initialize(attributes = {})
+        @attributes = defaults.merge!(attributes)
+
+        @attributes.each do |key, value|
+          instance_variable_set("@#{key}", value)
+        end
+      end
+
+      # Returns the item from the collection which shares the same
+      # index as the value of {Vedeu::Menus::Menu#current}.
+      #
+      # @return [void]
+      def current_item
+        @collection[@current]
+      end
+
+      # Returns the item from the collection which shares the same
+      # index as the value of {Vedeu::Menus::Menu#selected}.
+      #
+      # @return [|NilClass]
+      def selected_item
+        return nil unless @selected
+
+        @collection[@selected]
+      end
+
+      # Returns a new collection of items.
+      # Each element of the collection is of the format:
+      #
+      #   [selected, current, item]
+      #
+      # `selected` is a boolean indicating whether the item is
+      # selected.
+      # `current`  is a boolean indicating whether the item is
+      # current.
+      # `item`     is the item itself.
+      #
+      # @return [Array]
+      def items
+        items = []
+        @collection.each_with_index do |item, index|
+          if index == @current && index == @selected
+            items << [true, true, item]
+
+          elsif index == @current
+            items << [false, true, item]
+
+          elsif index == @selected
+            items << [true, false, item]
+
+          else
+            items << [false, false, item]
+
+          end
+        end
+        items
+      end
+
+      # Returns a subset of all the items.
+      #
+      # @return [Array]
+      def view
+        items[@current, @collection.size]
+      end
+
+      # Sets the value of current to be the first item of the
+      # collection.
+      #
+      # @return [Array]
+      def top_item
+        @current = 0
+
+        items
+      end
+
+      # Sets the value of current to be the last item of the
+      # collection.
+      #
+      # @return [Array]
+      def bottom_item
+        @current = last
+
+        items
+      end
+
+      # 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
+
+      # 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
+
+      # Sets the selected item to be the same value as the current
+      # item.
+      #
+      # @return [Array]
+      def select_item
+        @selected = @current
+
+        items
+      end
+
+      # Removes the value of `selected`, meaning no items are
+      # selected.
+      #
+      # @return [Array]
+      def deselect_item
+        @selected = nil
+
+        items
+      end
+
+      # Returns the last index of the collection.
+      #
+      # @return [Fixnum]
+      def last
+        @collection.size - 1
+      end
+
+      # Returns the size of the collection.
+      #
+      # @return [Fixnum]
+      def size
+        @collection.size
+      end
+
+      private
+
+      # The default values for a new instance of this class.
+      #
+      # @return [Hash]
+      def defaults
+        {
+          client:     nil,
+          collection: [],
+          current:    0,
+          name:       '',
+          repository: Vedeu.menus,
+          selected:   nil,
+        }
+      end
+
+    end # Menu
+
+  end # Menus
+
+end # Vedeu

data/lib/vedeu/{null/menu.rb → menus/null.rb}

@@ -1,23 +1,23 @@
 module Vedeu
 
-  module Null
+  module Menus
 
     # Provides a non-existent model to swallow messages.
     #
-    class Menu < Vedeu::Null::Generic
+    class Null < Vedeu::Null::Generic
 
-      # Returns an instance of the Vedeu::Null::Menu class.
+      # Returns an instance of the Vedeu::Menus::Null class.
       #
       # @param attributes [Hash<Symbol => void>]
       # @option attributes name [String|NilClass]
-      # @return [Vedeu::Null::Menu]
+      # @return [Vedeu::Menus::Null]
       def initialize(attributes = {})
         @attributes = attributes
         @name       = @attributes[:name]
       end
 
-    end # Menu
+    end # Null
 
-  end # Null
+  end # Menus
 
 end # Vedeu

data/lib/vedeu/menus/repository.rb

@@ -0,0 +1,18 @@
+module Vedeu
+
+  module Menus
+
+    # Allows the storing of menus by name.
+    #
+    class Repository < Vedeu::Repository
+
+      singleton_class.send(:alias_method, :menus, :repository)
+
+      real Vedeu::Menus::Menu
+      null Vedeu::Menus::Null
+
+    end # Repository
+
+  end # Menus
+
+end # Vedeu