vedeu 0.2.1 → 0.2.2

data/lib/vedeu/api/api.rb

@@ -6,6 +6,17 @@ module Vedeu
   # module expose Vedeu's core functionality.
   module API
 
+    # Configure Vedeu using a simple configuration DSL.
+    #
+    # @api public
+    # @see Vedeu::Configuration
+    # @return []
+    def configure(&block)
+      fail InvalidSyntax, '`configure` requires a block.' unless block_given?
+
+      Vedeu::Configuration.configure(&block)
+    end
+
     # Returns information about various registered subsystems when used with
     # a defined method within {Vedeu::API::Defined}.
     #
@@ -74,17 +85,22 @@ module Vedeu
       @events ||= Vedeu::Events.new do
         event(:_clear_)                   { Terminal.clear_screen     }
         event(:_exit_)                    { Vedeu::Application.stop   }
-        event(:_focus_by_name_)           { |name| Vedeu::Focus.by_name(name) }
-        event(:_focus_next_)              { Vedeu::Focus.next_item    }
-        event(:_focus_prev_)              { Vedeu::Focus.prev_item    }
         event(:_keypress_)                { |key| Vedeu.keypress(key) }
         event(:_log_)                     { |msg| Vedeu.log(msg)      }
         event(:_mode_switch_)             { fail ModeSwitch           }
-        event(:_refresh_)                 { Vedeu::Refresh.all        }
         event(:_resize_, { delay: 0.25 }) { Vedeu.resize              }
       end
     end
 
+    # Used after defining an interface or interfaces to set the initially
+    # focussed interface.
+    #
+    # @param name [String] The interface to focus; must be defined.
+    # @return []
+    def focus(name)
+      Vedeu.trigger(:_focus_by_name, name)
+    end
+
     # Find out how many lines the current terminal is able to display.
     #
     # @api public
@@ -100,11 +116,12 @@ module Vedeu
     # command. This provides the means for you to define your application's
     # views without their content.
     #
+    # @todo More documentation required.
     # @api public
     # @param name  [String] The name of the interface. Used to reference the
     #   interface throughout your application's execution lifetime.
     # @param block [Proc] A set of attributes which define the features of the
-    #   interface. TODO: More help.
+    #   interface.
     #
     # @example
     #   Vedeu.interface 'my_interface' do
@@ -234,6 +251,8 @@ module Vedeu
 
       trigger(:_refresh_)
 
+      trigger(:_cursor_refresh_)
+
       true
     end
     # :nocov:
@@ -264,8 +283,9 @@ module Vedeu
       Vedeu.events.unevent(name)
     end
 
-    # Use attributes of another interface whilst defining one. TODO: More help.
+    # Use attributes of another interface whilst defining one.
     #
+    # @todo More documentation required.
     # @api public
     # @param name [String] The name of the interface you wish to use. Typically
     #   used when defining interfaces to share geometry.
@@ -281,8 +301,9 @@ module Vedeu
       Vedeu::Interface.new(Vedeu::Interfaces.find(name))
     end
 
-    # Define a view (content) for an interface. TODO: More help.
+    # Define a view (content) for an interface.
     #
+    # @todo More documentation required.
     # @api public
     # @param name [String] The name of the interface you are targetting for this
     #   view.

data/lib/vedeu/api/composition.rb

@@ -2,6 +2,8 @@ module Vedeu
   module API
 
     # @see Vedeu::Composition
+    #
+    # @api public
     class Composition < Vedeu::Composition
 
       # Directly write a view buffer to the terminal.

data/lib/vedeu/api/helpers.rb

@@ -3,6 +3,8 @@ module Vedeu
 
     # Provides colour and style helpers for use in the {API::Interface},
     # {API::Line} and {API::Stream} classes.
+    #
+    # @api public
     module Helpers
 
       # Define either or both foreground and background colours for an

data/lib/vedeu/api/interface.rb

@@ -2,6 +2,8 @@ module Vedeu
   module API
 
     # Provides methods to be used to define interfaces or views.
+    #
+    # @api public
     class Interface < Vedeu::Interface
 
       include Helpers
@@ -26,26 +28,6 @@ module Vedeu
         attributes[:geometry][:centred] = value
       end
 
-      # Define the cursor visibility for an interface. A `true` value will show
-      # the cursor, whilst `false` will hide it.
-      #
-      # @api public
-      # @param value [Boolean]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     cursor true
-      #     ...
-      #
-      # @return [API::Interface]
-      def cursor(value)
-        unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
-          fail InvalidSyntax, 'Argument must be `true` or `false` for cursor.'
-        end
-
-        attributes[:cursor] = value
-      end
-
       # To maintain performance interfaces can be delayed from refreshing too
       # often, the reduces artefacts particularly when resizing the terminal
       # screen.

data/lib/vedeu/api/keymap.rb

@@ -2,6 +2,8 @@ module Vedeu
   module API
 
     # Provides methods to be used to define keypress mapped to actions.
+    #
+    # @api public
     class Keymap < Vedeu::Keymap
 
       # Define keypress(es) to perform an action.

data/lib/vedeu/api/line.rb

@@ -2,6 +2,8 @@ module Vedeu
   module API
 
     # Provides methods to be used to define views.
+    #
+    # @api public
     class Line < Vedeu::Line
 
       include Helpers

data/lib/vedeu/api/menu.rb

@@ -3,6 +3,8 @@ module Vedeu
 
     # Provides the mechanism to create menus within client applications and use
     # events to drive them.
+    #
+    # @api public
     class Menu
 
       include Common
@@ -60,7 +62,7 @@ module Vedeu
       #
       # @return [Vedeu::Menu]
       def items(collection = [])
-        attributes[:items] = Vedeu::Menu.new(collection)
+        attributes[:items] = collection
       end
 
       # The name of the menu. Used to reference the menu throughout your

data/lib/vedeu/api/stream.rb

@@ -2,12 +2,14 @@ module Vedeu
   module API
 
     # Provides methods to be used to define views.
+    #
+    # @api public
     class Stream < Vedeu::Stream
 
       include Helpers
 
       # Specify the alignment of the stream within the line. Useful in
-      # combination with #width to provide simple formatting effects.
+      # combination with {#width} to provide simple formatting effects.
       #
       # @api public
       # @param value [Symbol] `:left`, `:centre` and `right` are valid values
@@ -23,13 +25,34 @@ module Vedeu
       # @return [Symbol]
       def align(value)
         unless [:left, :right, :centre].include?(value.to_sym)
-          fail InvalidSyntax, '`align` requires a value of `:left`, `:right` ' \
+          fail InvalidSyntax, '`align` requires a value of `left`, `right` ' \
                               'or `centre`.'
         end
 
         attributes[:align] = value.to_sym
       end
 
+      # Syntactic sugar used with {#align} to left align content.
+      #
+      # @return [Symbol]
+      def left
+        :left
+      end
+
+      # Syntactic sugar used with {#align} to right align content.
+      #
+      # @return [Symbol]
+      def right
+        :right
+      end
+
+      # Syntactic sugar used with {#align} to centre align content.
+      #
+      # @return [Symbol]
+      def centre
+        :centre
+      end
+
       # Add textual data to the stream via this method.
       #
       # @api public

data/lib/vedeu/application.rb

@@ -2,7 +2,7 @@ module Vedeu
 
   # Orchestrates the running of the main application loop.
   #
-  # @api public
+  # @api private
   class Application
     # :nocov:
     class << self
@@ -75,8 +75,8 @@ module Vedeu
     # 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.
+    # @todo It appears for non-interactive applications, we do nothing. Must
+    #   investigate.
     #
     # @api private
     # @return []
@@ -85,7 +85,7 @@ module Vedeu
         Input.capture
 
       else
-        # TODO: What should happen here?
+
 
       end
     end

data/lib/vedeu/configuration/api.rb

@@ -0,0 +1,327 @@
+module Vedeu
+
+  module Configuration
+
+    # The Configuration::API class parses client application configuration into
+    # options used by Vedeu to affect certain behaviours.
+    #
+    # @api private
+    class API
+
+      include Vedeu::Common
+
+      # Configure Vedeu via a simple configuration API DSL. Options set here
+      # override the default Vedeu configuration set in
+      # {Vedeu::Configuration#defaults}.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     ...
+      #
+      # @param block [Proc]
+      # @return [Hash]
+      def self.configure(&block)
+        new(&block).configuration
+      end
+
+      # Returns an instance of Configuration::API.
+      #
+      # @param block [Proc]
+      # @return [Configuration::API]
+      def initialize(&block)
+        instance_eval(&block) if block_given?
+      end
+
+      # Returns the configuration options set up by the API DSL.
+      #
+      # @return [Hash]
+      def configuration
+        if system_key_options.any?
+          options.merge({ system_keys: system_key_options })
+
+        else
+          options
+
+        end
+      end
+
+      # Sets boolean to allow user input. The default behaviour of Vedeu is to
+      # be interactive.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     interactive!
+      #     ...
+      #
+      #   Vedeu.configure do
+      #     interactive false
+      #     ...
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      def interactive!(value = true)
+        options[:interactive] = value
+      end
+      alias_method :interactive, :interactive!
+
+      # Sets boolean to prevent user intervention. This is the same as setting
+      # {#interactive!} to false.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     standalone!
+      #     ...
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      def standalone!(value = true)
+        options[:interactive] = !value
+      end
+      alias_method :standalone, :standalone!
+
+      # Sets boolean to run the Vedeu main application loop once. In effect,
+      # using `run_once!` or setting `run_once` to true will allow Vedeu to
+      # initialize, run any client application code, cleanup, then terminate.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     run_once!
+      #     ...
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      def run_once!(value = true)
+        options[:once] = value
+      end
+      alias_method :run_once, :run_once!
+
+      # Sets the terminal mode to `cooked`. Default terminal mode is `raw`.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     cooked!
+      #     ...
+      #
+      # @return [Boolean]
+      def cooked!
+        options[:terminal_mode] = :cooked
+      end
+      alias_method :cooked, :cooked!
+
+      # Sets the terminal mode to `raw`. Default terminal mode is `raw`.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     raw!
+      #     ...
+      #
+      # @return [Boolean]
+      def raw!
+        options[:terminal_mode] = :raw
+      end
+      alias_method :raw, :raw!
+
+      # Sets boolean to enable/disable debugging. Vedeu's default setting is
+      # for debugging to be disabled. Using `debug!` or setting `debug` to true
+      # will enable debugging. If `trace!` is used, or `trace` is set to true,
+      # debugging will be enabled, overriding any setting here.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     debug!
+      #     ...
+      #
+      #   Vedeu.configure do
+      #     debug false
+      #     ...
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      def debug!(value = true)
+        if options.key?(:trace) && options[:trace] != false
+          options[:debug] = true
+
+        else
+          options[:debug] = value
+
+        end
+      end
+      alias_method :debug, :debug!
+
+      # Sets boolean to enable/disable tracing. Vedeu's default setting is for
+      # tracing to be disabled. Using `trace!` or setting `trace` to true will
+      # enable tracing and debugging.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     trace!
+      #     ...
+      #
+      #   Vedeu.configure do
+      #     trace false
+      #     ...
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      def trace!(value = true)
+        options[:debug] = true if value === true
+
+        options[:trace] = value
+      end
+      alias_method :trace, :trace!
+
+      # Sets the colour mode of the terminal.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     colour_mode 256
+      #     ...
+      #
+      # @param value [Fixnum]
+      # @return [Boolean]
+      def colour_mode(value = nil)
+        fail InvalidSyntax, '`colour_mode` must be `8`, `16`, `256`, ' \
+                            '`16777216`.' unless valid_colour_mode?(value)
+
+        options[:colour_mode] = value
+      end
+
+      # Sets the key used to exit the client application. The default is `q`.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     exit_key 'x'
+      #     ...
+      #
+      #   Vedeu.configure do
+      #     exit_key :f4
+      #     ...
+      #
+      # @param value [String|Symbol]
+      # @return [String|Symbol]
+      def exit_key(value)
+        return invalid_key('exit_key') unless valid_key?(value)
+
+        system_key_options[:exit] = value
+      end
+
+      # Sets the key used to switch focus to the next defined interface. The
+      # default is `:tab`.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     focus_next_key 'n'
+      #     ...
+      #
+      #   Vedeu.configure do
+      #     focus_next_key :right
+      #     ...
+      #
+      # @param value [String|Symbol]
+      # @return [String|Symbol]
+      def focus_next_key(value)
+        return invalid_key('exit_key') unless valid_key?(value)
+
+        system_key_options[:focus_next] = value
+      end
+
+      # Sets the key used to switch focus to the previous interface. The default
+      # is `:shift_tab`.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     focus_prev_key 'p'
+      #     ...
+      #
+      #   Vedeu.configure do
+      #     focus_prev_key :left
+      #     ...
+      #
+      # @param value [String|Symbol]
+      # @return [String|Symbol]
+      def focus_prev_key(value)
+        return invalid_key('exit_key') unless valid_key?(value)
+
+        system_key_options[:focus_prev] = value
+      end
+
+      # Sets the key used to switch between raw and cooked mode in Vedeu. The
+      # default is `:escape`.
+      #
+      # @example
+      #   Vedeu.configure do
+      #     mode_switch_key 'm'
+      #     ...
+      #
+      #   Vedeu.configure do
+      #     mode_switch_key :f1
+      #     ...
+      #
+      # @param value [String|Symbol]
+      # @return [String|Symbol]
+      def mode_switch_key(value)
+        return invalid_key('exit_key') unless valid_key?(value)
+
+        system_key_options[:mode_switch] = value
+      end
+
+      private
+
+      # Returns the options set via the configuration API DSL or an empty Hash
+      # if none were set.
+      #
+      # @api private
+      # @return [Hash]
+      def options
+        @_options ||= {}
+      end
+
+      # Returns the system keys set via the configuration API DSL or an empty
+      # hash if none were redefined.
+      #
+      # @api private
+      # @return [Hash]
+      def system_key_options
+        @_system_key_options ||= Configuration.default_system_keys
+      end
+
+      # Checks that the value provided to {#colour_mode} is valid.
+      #
+      # @api private
+      # @param value [Fixnum]
+      # @return [Boolean]
+      def valid_colour_mode?(value)
+        value.is_a?(Fixnum) && [8, 16, 256, 16777216].include?(value)
+      end
+
+      # Checks that the value provided to {#exit_key}, {#focus_next_key},
+      # {#focus_prev_key} and {#mode_switch_key} is valid. Must be a Symbol or a
+      # non-empty String.
+      #
+      # @api private
+      # @param value [String|Symbol]
+      # @return [Boolean]
+      def valid_key?(value)
+        return false unless value.is_a?(String) || value.is_a?(Symbol)
+
+        return false if value.is_a?(String) && value.size != 1
+
+        (value.is_a?(String) || value.is_a?(Symbol)) && defined_value?(value)
+      end
+
+      # Raises an exception on behalf of the calling method to report that the
+      # value provided is not valid.
+      #
+      # @api private
+      # @param system_key [String] The calling method wishing to raise an
+      #   exception.
+      # @return [InvalidSyntax]
+      def invalid_key(system_key)
+        fail InvalidSyntax, "`#{system_key}` must be a String or a Symbol."
+      end
+
+    end
+
+  end
+
+end