vedeu 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c51db32c71781208264d0ea69bf433a5bde9bf75
-  data.tar.gz: bb5067249adad44b4788b4abcb0471c513d0ec9b
+  metadata.gz: 53b812fdf424dda850a0a008b824cb388a2329cb
+  data.tar.gz: 85d3208b47291886ed7dad1913fe29bb7806b2b8
 SHA512:
-  metadata.gz: 16bbad5b4ffb6b0748dbef756d4b5db9ef0abb562c842246a66aee21cbd3c3f1bcf7d0aeb43cf44171b958be9f8c821e199b61eea0439b571536238894341545
-  data.tar.gz: a29d38fd26002e43980502708196e9d3434a7a92f7b952feafc571e74dce7b27664c962bb0674a2607284824af145b6554f85616c256d48528b31c0288e986c3
+  metadata.gz: 6d2e44aebbefa2314e55ba466f262d9417ed6380872746d23f2b9e9fe940c70f9fbbc741ec756e1069211c54498d8da09de57702076814bf014f717bdb7908a5
+  data.tar.gz: 4cc8fd2986658da91d8d4b10d48da4514e9eaf588c11dc4941b2173471e85ccaf1adea8e5d19453f1f65532c5395e6234f5ffcca656743b7a9609e86dfb35adb

data/docs/api.md

@@ -59,7 +59,7 @@ Note: Nesting indicates where an API method is allowed/supposed to be used.
 #### Interfaces
 
 - interface
-  - centred
+  - centred (or centred!)
   - colour
   - delay
   - group

data/docs/events.md

@@ -15,10 +15,6 @@ Events described in this document assume that you have included Vedeu in your cl
 
 System events generally control the internal state of Vedeu with respects to your application. They are soft-namespaced using underscores.
 
-### `:_cleanup_`
-
-This event is fired by Vedeu when `:_exit_` is triggered. You can hook into this to perform a special action before the application terminates. Saving the user's work, session or preferences might be popular here.
-
 ### `:_clear_`
 
 Clears the whole terminal space.
@@ -67,10 +63,6 @@ When triggered will focus the next interface and restore the cursor position and
 
 When triggered will focus the previous interface and restore the cursor position and visibility.
 
-### `:_initialize_`
-
-Special event which Vedeu triggers when it is ready to enter the main loop. Client applications can listen for this event and perform some action(s), like render the first screen, interface or make a sound.
-
 ### `:_keypress_`
 
 Triggering this event will cause the triggering of the `:key` event; which you should define to 'do things'. If the `escape` key is pressed, then `key` is triggered with the argument `:escape`, also an internal event `_mode_switch_` is triggered.
@@ -153,6 +145,17 @@ System events can be handled or triggered by your application also, but overridi
 
 User events allow you to orchestrate behaviour within your application, ie. the user presses a specific key, you trigger an event to make something happen. Eg. pressing 'p' instructs the player to play.
 
+## Pre-defined User Events
+
+Vedeu pre-defines a few user events, which client applications can listen for, or trigger themselves.
+
+### `:_cleanup_`
+
+Vedeu triggers this event when `:_exit_` is triggered. You can hook into this to perform a special action before the application terminates. Saving the user's work, session or preferences might be popular here.
+
+### `:_initialize_`
+
+Vedeu triggers this event when it is ready to enter the main loop. Client applications can listen for this event and perform some action(s), like render the first screen, interface or make a sound.
 
 #### How to define user events
 

data/lib/vedeu/api/api.rb

@@ -1,16 +1,17 @@
 module Vedeu
 
-  # Vedeu::Trace.call({ trace: true })
-
   # Provides the API to Vedeu. Methods therein, and classes belonging to this
   # module expose Vedeu's core functionality.
+  #
+  # @api public
   module API
 
     # Configure Vedeu using a simple configuration DSL.
     #
-    # @api public
+    # @param block [Proc]
+    # @raise [InvalidSyntax] When the required block is not given.
+    # @return [Hash]
     # @see Vedeu::Configuration
-    # @return []
     def configure(&block)
       fail InvalidSyntax, '`configure` requires a block.' unless block_given?
 
@@ -20,9 +21,8 @@ module Vedeu
     # Returns information about various registered subsystems when used with
     # a defined method within {Vedeu::API::Defined}.
     #
-    # @api public
-    # @see Vedeu::API::Defined
     # @return [Vedeu::API::Defined]
+    # @see Vedeu::API::Defined
     def defined
       Vedeu::API::Defined
     end
@@ -30,7 +30,6 @@ module Vedeu
     # Register an event by name with optional delay (throttling) which when
     # triggered will execute the code contained within the passed block.
     #
-    # @api public
     # @param name  [Symbol] The name of the event which will be triggered later.
     # @param [Hash] opts The options to register the event with.
     # @option opts :delay [Fixnum|Float] Limits the execution of the
@@ -72,38 +71,21 @@ module Vedeu
     #
     # @return [Hash]
     def event(name, opts = {}, &block)
-      Vedeu.events.event(name, opts, &block)
-    end
-
-    # Initially accessed by Vedeu itself, this sets up some basic events needed
-    # by Vedeu to run. Afterwards, it is simply a gateway to the Events class
-    # used by other API methods.
-    #
-    # @api private
-    # @return [Events]
-    def events
-      @events ||= Vedeu::Events.new do
-        event(:_clear_)                   { Terminal.clear_screen     }
-        event(:_exit_)                    { Vedeu::Application.stop   }
-        event(:_keypress_)                { |key| Vedeu.keypress(key) }
-        event(:_log_)                     { |msg| Vedeu.log(msg)      }
-        event(:_mode_switch_)             { fail ModeSwitch           }
-        event(:_resize_, { delay: 0.25 }) { Vedeu.resize              }
-      end
+      Events.add(name, opts, &block)
     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 []
+    # @return [String] The name of the interface now in focus.
+    # @raise [InterfaceNotFound] When the interface cannot be found.
     def focus(name)
-      Vedeu.trigger(:_focus_by_name, name)
+      Vedeu.trigger(:_focus_by_name_, name)
     end
 
     # Find out how many lines the current terminal is able to display.
     #
-    # @api public
     # @example
     #   Vedeu.height
     #
@@ -117,7 +99,6 @@ module Vedeu
     # 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
@@ -136,7 +117,7 @@ module Vedeu
       API::Interface.define({ name: name }, &block)
     end
 
-    # @api public
+    # Simulate a keypress.
     #
     # @example
     #   Vedeu.keypress('s')
@@ -170,6 +151,7 @@ module Vedeu
     #     interface 'my_interface' # => will only function when 'my_interface'
     #     ...                      #    is in focus
     #
+    # @raise [InvalidSyntax] When the required block is not given.
     # @return [API::Keymap]
     def keys(*name_or_names, &block)
       fail InvalidSyntax, '`keys` requires a block.' unless block_given?
@@ -179,7 +161,6 @@ module Vedeu
 
     # Write a message to the Vedeu log file located at `$HOME/.vedeu/vedeu.log`
     #
-    # @api public
     # @param message [String] The message you wish to emit to the log
     #   file, useful for debugging.
     # @param force   [Boolean] When evaluates to true will
@@ -196,7 +177,6 @@ module Vedeu
     # Register a menu by name which will display a collection of items for your
     # users to select; and provide interactivity within your application.
     #
-    # @api public
     # @param name  [String] The name of the menu. Used to reference the
     #   menu throughout your application's execution lifetime.
     # @param block [Proc] A set of attributes which define the features of the
@@ -212,6 +192,7 @@ module Vedeu
     #     items Track.all_my_favourites
     #     ...
     #
+    # @raise [InvalidSyntax] When the required block is not given.
     # @return [API::Menu]
     def menu(name = '', &block)
       fail InvalidSyntax, '`menu` requires a block.' unless block_given?
@@ -223,7 +204,6 @@ module Vedeu
     # that the refresh event does not need to be triggered after creating the
     # view or views, though can be later triggered if needed.
     #
-    # @api public
     # @param block [Proc] The directives you wish to send to render. Must
     #                     include `view` or `views` with associated sub-
     #                     directives.
@@ -260,7 +240,6 @@ module Vedeu
     # Trigger a registered or system event by name with arguments. If the
     # event stored returns a value, that is returned.
     #
-    # @api public
     # @param name [Symbol] The name of the event you wish to trigger.
     #   The event does not have to exist.
     # @param args [Array] Any arguments the event needs to execute correctly.
@@ -270,23 +249,21 @@ module Vedeu
     #
     # @return [Array|undefined]
     def trigger(name, *args)
-      Vedeu.events.trigger(name, *args)
+      Events.use(name, *args)
     end
 
     # Unregisters the event by name, effectively deleting the associated events
     # bound with it also.
     #
-    # @api public
     # @param name [Symbol]
     # @return [Hash]
     def unevent(name)
-      Vedeu.events.unevent(name)
+      Events.remove(name)
     end
 
     # 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.
     #
@@ -304,7 +281,6 @@ module Vedeu
     # 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.
     # @param block [Proc] The directives you wish to send to this interface.
@@ -320,7 +296,6 @@ module Vedeu
 
     # Instruct Vedeu to treat contents of block as a single composition.
     #
-    # @api public
     # @param block [Proc] Instructs Vedeu to treat all of the 'view' directives
     #   therein as one instruction. Useful for redrawing multiple interfaces at
     #   once.
@@ -340,6 +315,7 @@ module Vedeu
     #       ...
     #   ...
     #
+    # @raise [InvalidSyntax] When the required block is not given.
     # @return [Hash]
     def views(&block)
       fail InvalidSyntax, '`views` requires a block.' unless block_given?
@@ -350,7 +326,6 @@ module Vedeu
 
     # Find out how many columns the current terminal is able to display.
     #
-    # @api public
     # @example
     #   Vedeu.width
     #
@@ -359,9 +334,10 @@ module Vedeu
       Terminal.width
     end
 
-  end
+  end # API
 
   extend API
 
   trap('SIGWINCH') { Vedeu.trigger(:_resize_) }
-end
+
+end # Vedeu

data/lib/vedeu/api/composition.rb

@@ -1,4 +1,5 @@
 module Vedeu
+
   module API
 
     # @see Vedeu::Composition
@@ -8,11 +9,11 @@ module Vedeu
 
       # Directly write a view buffer to the terminal.
       #
-      # @api public
       # @param block [Proc]
+      # @raise [InvalidSyntax] When the required block is not given.
       # @return [Array] A collection of strings, each defining containing the
-      #                 escape sequences and content. This data has already
-      #                 been sent to the terminal to be output.
+      #   escape sequences and content. This data has already been sent to the
+      #   terminal to be output.
       def self.render(&block)
         fail InvalidSyntax, '`render` requires a block.' unless block_given?
 
@@ -22,16 +23,20 @@ module Vedeu
           Buffers.add(interface.attributes)
 
           interface.name
-        end.map { |name| Compositor.render(name) }
+        end.map { |name| Vedeu::Refresh.by_name(name) }
       end
 
-      # @api public
+      # @param name [String]
+      # @param block [Proc]
+      # @return []
       # @see Vedeu::API#view
       def view(name, &block)
         attributes[:interfaces] << API::Interface
           .build({ name: name, parent: self.view_attributes }, &block)
       end
 
-    end
-  end
-end
+    end # Composition
+
+  end # API
+
+end # Vedeu

data/lib/vedeu/api/defined.rb

@@ -1,4 +1,5 @@
 module Vedeu
+
   module API
 
     # Provides a set of helpful API methods to return information about various
@@ -13,7 +14,7 @@ module Vedeu
       #
       # @return [Array]
       def events
-        Vedeu.events.registered
+        Vedeu::Events.registered
       end
 
       # Returns all groups currently registered with Vedeu.
@@ -30,6 +31,13 @@ module Vedeu
         Vedeu::Interfaces.registered
       end
 
+      # Returns the names of all keymaps currently registered with Vedeu.
+      #
+      # @return [Array]
+      def keymaps
+        Vedeu::Keymaps.registered
+      end
+
       # Returns all menus currently registered with Vedeu.
       #
       # @return [Array]
@@ -37,6 +45,8 @@ module Vedeu
         Vedeu::Menus.registered
       end
 
-    end
-  end
-end
+    end # Defined
+
+  end # API
+
+end # Vedeu

data/lib/vedeu/api/helpers.rb

@@ -1,4 +1,5 @@
 module Vedeu
+
   module API
 
     # Provides colour and style helpers for use in the {API::Interface},
@@ -10,7 +11,6 @@ module Vedeu
       # Define either or both foreground and background colours for an
       # interface, line or a stream.
       #
-      # @api public
       # @param values [Hash]
       #
       # @example
@@ -26,6 +26,8 @@ module Vedeu
       #     colour background: '#000000', foreground: '#ffffff'
       #     ...
       #
+      # @raise [InvalidSyntax] When the values parameter does not contain
+      #   required keys.
       # @return [Hash]
       def colour(values)
         unless values.key?(:foreground) || values.key?(:background)
@@ -38,7 +40,6 @@ module Vedeu
 
       # Define a style or styles for an interface, line or a stream.
       #
-      # @api public
       # @param values [Array|String]
       # @param block  [Proc]
       #
@@ -67,6 +68,8 @@ module Vedeu
         end
       end
 
-    end
-  end
-end
+    end # Helpers
+
+  end # API
+
+end # Vedeu

data/lib/vedeu/api/interface.rb

@@ -1,4 +1,5 @@
 module Vedeu
+
   module API
 
     # Provides methods to be used to define interfaces or views.
@@ -11,28 +12,27 @@ module Vedeu
       # Instructs Vedeu to calculate x and y geometry automatically based on the
       # centre character of the terminal, the width and the height.
       #
-      # @api public
-      # @param value [Boolean]
+      # @param value [Boolean] Any value other than nil or false will evaluate
+      #   to true.
       #
       # @example
       #   interface 'my_interface' do
-      #     centred true
+      #     centred!
+      #
+      #   interface 'my_interface' do
+      #     centred false
       #     ...
       #
       # @return [API::Interface]
-      def centred(value)
-        unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
-          fail InvalidSyntax, 'Argument must be `true` or `false` for centred.'
-        end
-
-        attributes[:geometry][:centred] = value
+      def centred(value = true)
+        attributes[:geometry][:centred] = !!(value)
       end
+      alias_method :centred!, :centred
 
       # To maintain performance interfaces can be delayed from refreshing too
       # often, the reduces artefacts particularly when resizing the terminal
       # screen.
       #
-      # @api public
       # @param value [Fixnum|Float]
       #
       # @return [API::Interface]
@@ -44,7 +44,6 @@ module Vedeu
       # targetted together; for example you may want to refresh multiple
       # interfaces at once.
       #
-      # @api public
       # @param value [String]
       #
       # @example
@@ -59,7 +58,6 @@ module Vedeu
 
       # Define the number of characters/rows/lines tall the interface will be.
       #
-      # @api public
       # @param value [Fixnum]
       #
       # @example
@@ -76,7 +74,6 @@ module Vedeu
 
       # Define a single line in a view.
       #
-      # @api public
       # @param value [String]
       # @param block [Proc]
       #
@@ -108,7 +105,6 @@ module Vedeu
       # The name of the interface. Used to reference the interface throughout
       # your application's execution lifetime.
       #
-      # @api public
       # @param value [String]
       #
       # @example
@@ -124,7 +120,6 @@ module Vedeu
       # Use the specified interface; useful for sharing attributes with other
       # interfaces.
       #
-      # @api public
       # @param value [String]
       # @see Vedeu::API#use
       def use(value)
@@ -133,7 +128,6 @@ module Vedeu
 
       # Define the number of characters/columns wide the interface will be.
       #
-      # @api public
       # @param value [Fixnum]
       #
       # @example
@@ -150,7 +144,6 @@ module Vedeu
 
       # Define the starting x position (column) of the interface.
       #
-      # @api public
       # @param value [Fixnum]
       # @param block [Proc]
       #
@@ -174,7 +167,6 @@ module Vedeu
 
       # Define the starting y position (row/line) of the interface.
       #
-      # @api public
       # @param value [Fixnum]
       # @param block [Proc]
       #
@@ -225,6 +217,8 @@ module Vedeu
         value < 1 || value > Terminal.width
       end
 
-    end
-  end
-end
+    end # Interface
+
+  end # API
+
+end # Vedeu

data/lib/vedeu/api/keymap.rb

@@ -1,4 +1,5 @@
 module Vedeu
+
   module API
 
     # Provides methods to be used to define keypress mapped to actions.
@@ -21,6 +22,9 @@ module Vedeu
       #     key('j', :down) { trigger(:down) }
       #     ...
       #
+      # @raise [InvalidSyntax] When the required block is not given, the
+      #   value_or_values parameter is undefined, or when processing the
+      #   collection, a member is undefined.
       # @return [Array] A collection containing the keypress(es).
       def key(*value_or_values, &block)
         fail InvalidSyntax,
@@ -29,8 +33,9 @@ module Vedeu
           defined_value?(value_or_values)
 
         value_or_values.each do |value|
-          fail InvalidSyntax, 'Key cannot be empty.' unless
-            defined_value?(value)
+          fail InvalidSyntax,
+            'An invalid value for `key` was encountered.' unless
+              defined_value?(value)
 
           attributes[:keys] << { key: value, action: block }
         end
@@ -58,7 +63,8 @@ module Vedeu
         attributes[:interfaces] = name_or_names
       end
 
-    end
+    end # Keymap
+
+  end # API
 
-  end
-end
+end # Vedeu

data/lib/vedeu/api/line.rb

@@ -1,4 +1,5 @@
 module Vedeu
+
   module API
 
     # Provides methods to be used to define views.
@@ -10,7 +11,6 @@ module Vedeu
 
       # Define a stream (a subset of a line).
       #
-      # @api public
       # @param block [Proc] Block contains directives relating to API::Stream.
       #
       # @example
@@ -19,6 +19,7 @@ module Vedeu
       #       stream do
       #         ...
       #
+      # @raise [InvalidSyntax] When the required block is not given.
       # @return [Array]
       def stream(&block)
         fail InvalidSyntax, '`stream` requires a block.' unless block_given?
@@ -31,7 +32,6 @@ module Vedeu
       # attributes for this line but is useful for adding lines straight into
       # the interface.
       #
-      # @api public
       # @param value [String]
       #
       # @example
@@ -48,7 +48,6 @@ module Vedeu
         attributes[:streams] << { text: value }
       end
 
-      # @api public
       # @param value [String]
       # @param block [Proc]
       #
@@ -66,7 +65,6 @@ module Vedeu
         attributes[:streams] << stream
       end
 
-      # @api public
       # @param value [String]
       # @param block [Proc]
       #
@@ -84,7 +82,8 @@ module Vedeu
         attributes[:streams] << stream
       end
 
-    end
+    end # Line
+
+  end # API
 
-  end
-end
+end # Vedeu

data/lib/vedeu/api/menu.rb

@@ -1,4 +1,5 @@
 module Vedeu
+
   module API
 
     # Provides the mechanism to create menus within client applications and use
@@ -27,6 +28,7 @@ module Vedeu
       end
 
       # @param block [Proc]
+      # @raise [InvalidSyntax] When the required block is not given.
       # @return [API::Menu]
       def define(&block)
         fail InvalidSyntax, '`menu` requires a block.' unless block_given?
@@ -35,8 +37,6 @@ module Vedeu
 
         instance_eval(&block)
 
-        validate_attributes!
-
         Vedeu::Menus.add(attributes)
 
         self
@@ -48,7 +48,6 @@ module Vedeu
       # In the 'my_playlist' example below, your `Track` model may return a
       # collection of tracks to populate the menu.
       #
-      # @api public
       # @param collection [Array]
       #
       # @example
@@ -68,7 +67,6 @@ module Vedeu
       # The name of the menu. Used to reference the menu throughout your
       # application's execution lifetime.
       #
-      # @api public
       # @param value [String]
       #
       # @example
@@ -94,22 +92,16 @@ module Vedeu
         }
       end
 
-      # At present, validates that a menu has a name attribute.
-      #
-      # @api private
-      # @return [Boolean]
-      def validate_attributes!
-        unless defined_value?(attributes[:name])
-          fail InvalidSyntax, 'Menus must have a `name`.'
-        end
-      end
-
       # @api private
       # @return []
       def method_missing(method, *args, &block)
+        Vedeu.log("API::Menu#method_missing '#{method.to_s}' (args: #{args.inspect})")
+
         @self_before_instance_eval.send(method, *args, &block)
       end
 
-    end
-  end
-end
+    end # Menu
+
+  end # API
+
+end # Vedeu