vedeu 0.1.18 → 0.1.19

data/lib/vedeu/api/composition.rb

@@ -1,11 +1,14 @@
 module Vedeu
   module API
+
+    # @see Vedeu::Composition
     class Composition < Vedeu::Composition
 
       # @api public
       # @see Vedeu::API#view
       def view(name, &block)
-        attributes[:interfaces] << Interface.build({ name: name }, &block)
+        attributes[:interfaces] << API::Interface
+          .build({ name: name, parent: self.view_attributes }, &block)
       end
 
     end

data/lib/vedeu/api/defined.rb

@@ -0,0 +1,35 @@
+module Vedeu
+  module API
+
+    # Provides a set of helpful API methods to return information about various
+    # registered subsystems.
+    #
+    # @api public
+    module Defined
+
+      extend self
+
+      # Returns all events currently registered with Vedeu.
+      #
+      # @return [Array]
+      def events
+        Vedeu.events.registered
+      end
+
+      # Returns all groups currently registered with Vedeu.
+      #
+      # @return [Array]
+      def groups
+        Vedeu::Groups.registered
+      end
+
+      # Returns all interfaces currently registered with Vedeu.
+      #
+      # @return [Array]
+      def interfaces
+        Vedeu::Interfaces.registered
+      end
+
+    end
+  end
+end

data/lib/vedeu/api/helpers.rb

@@ -1,5 +1,8 @@
 module Vedeu
   module API
+
+    # Provides colour and style helpers for use in the {API::Interface},
+    # {API::Line} and {API::Stream} classes.
     module Helpers
 
       # Define either or both foreground and background colours for an
@@ -11,25 +14,27 @@ module Vedeu
       # @example
       #   interface 'my_interface' do
       #     colour background: '#000000', foreground: '#ffffff'
-      #     ... some interface attributes ...
+      #     ...
       #
       #   line do
       #     colour background: '#000000', foreground: '#ffffff'
-      #     ... some line attributes ...
+      #     ...
       #
       #   stream do
       #     colour background: '#000000', foreground: '#ffffff'
-      #     ... some stream attributes ...
+      #     ...
       #
-      # @return []
-      def colour(values = {})
-        fail InvalidArgument, '#colour expects a Hash containing :foreground,' \
-                              ' :background or both.' unless values.is_a?(Hash)
+      # @return [Hash]
+      def colour(values)
+        unless values.key?(:foreground) || values.key?(:background)
+          fail InvalidSyntax, '#colour expects a Hash containing ' \
+            ':foreground or :background or both.'
+        end
 
         attributes[:colour] = values
       end
 
-      # Define a style for an interface, line or a stream.
+      # Define a style or styles for an interface, line or a stream.
       #
       # @api public
       # @param values [Array|String]
@@ -38,24 +43,24 @@ module Vedeu
       # @example
       #   interface 'my_interface' do
       #     style 'normal'
-      #     ... some interface attributes ...
-      #   end
+      #     ...
       #
       #   line do
       #     style ['bold', 'underline']
-      #     ... some line attributes ...
+      #     ...
       #
       #   stream do
       #     style 'blink'
-      #     ... some stream attributes ...
+      #     ...
       #
-      # @return []
+      # @return [Array]
       def style(values = [], &block)
         if block_given?
-          attributes[:streams] << API::Stream.build({ style: [values] }, &block)
+          attributes[:streams] << API::Stream
+                                    .build({ style: Array(values) }, &block)
 
         else
-          [values].flatten.each { |value| attributes[:style] << value }
+          Array(values).each { |value| attributes[:style] << value }
 
         end
       end

data/lib/vedeu/api/interface.rb

@@ -1,6 +1,9 @@
 module Vedeu
   module API
+
+    # Provides methods to be used to define interfaces or views.
     class Interface < Vedeu::Interface
+
       include Helpers
 
       # Define a single line in a view.
@@ -21,13 +24,15 @@ module Vedeu
       #     end
       #   end
       #
-      # @return []
+      # @return [API::Interface]
       def line(value = '', &block)
         if block_given?
-          attributes[:lines] << Line.build(&block)
+          attributes[:lines] << API::Line
+            .build({ parent: self.view_attributes }, &block)
 
         else
-          attributes[:lines] << Line.build({ streams: { text: value } })
+          attributes[:lines] << API::Line
+            .build({ streams: { text: value }, parent: self.view_attributes })
 
         end
       end
@@ -53,7 +58,7 @@ module Vedeu
       #     cursor true
       #     ...
       #
-      # @return []
+      # @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.'
@@ -69,7 +74,7 @@ module Vedeu
       # @api public
       # @param value [Fixnum|Float]
       #
-      # @return []
+      # @return [API::Interface]
       def delay(value)
         attributes[:delay] = value
       end
@@ -86,7 +91,7 @@ module Vedeu
       #     group 'main_screen'
       #     ...
       #
-      # @return []
+      # @return [API::Interface]
       def group(value)
         attributes[:group] = value
       end
@@ -102,7 +107,7 @@ module Vedeu
       #     name 'my_interface'
       #     ...
       #
-      # @return []
+      # @return [API::Interface]
       def name(value)
         attributes[:name] = value
       end
@@ -122,7 +127,7 @@ module Vedeu
       #                                    # `my_interface` changes position,
       #                                    # `other_interface` will too.
       #
-      # @return []
+      # @return [API::Interface]
       def x(value = 0, &block)
         return attributes[:geometry][:x] = block if block_given?
 
@@ -147,7 +152,7 @@ module Vedeu
       #     ...                              # `my_interface` changes position,
       #                                      # `other_interface` will too.
       #
-      # @return []
+      # @return [API::Interface]
       def y(value = 0, &block)
         return attributes[:geometry][:y] = block if block_given?
 
@@ -166,7 +171,7 @@ module Vedeu
       #     width 25
       #     ...
       #
-      # @return []
+      # @return [API::Interface]
       def width(value)
         Vedeu.log(out_of_bounds('width')) if x_out_of_bounds?(value)
 
@@ -183,7 +188,7 @@ module Vedeu
       #     height 8
       #     ...
       #
-      # @return []
+      # @return [API::Interface]
       def height(value)
         Vedeu.log(out_of_bounds('height')) if y_out_of_bounds?(value)
 
@@ -201,7 +206,7 @@ module Vedeu
       #     centred true
       #     ...
       #
-      # @return []
+      # @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.'

data/lib/vedeu/api/line.rb

@@ -1,6 +1,9 @@
 module Vedeu
   module API
+
+    # Provides methods to be used to define views.
     class Line < Vedeu::Line
+
       include Helpers
 
       # Define a stream (a subset of a line).
@@ -12,16 +15,14 @@ module Vedeu
       #   ...
       #     line do
       #       stream do
-      #         ... other stream directives ...
-      #       end
-      #     end
-      #   ...
+      #         ...
       #
       # @return [Array]
       def stream(&block)
         fail InvalidSyntax, '`stream` requires a block.' unless block_given?
 
-        attributes[:streams] << API::Stream.build(&block)
+        attributes[:streams] << API::Stream
+          .build({ parent: self.view_attributes }, &block)
       end
 
       # Define text for a line. Using this directive will not allow stream
@@ -34,7 +35,11 @@ module Vedeu
       # @example
       #   ...
       #     line do
-      #       text 'Some text to display...'
+      #       text 'Some text goes here...'
+      #
+      #   ...
+      #     stream do
+      #       text 'Some text goes here...'
       #
       # @return [Array]
       def text(value)
@@ -53,9 +58,10 @@ module Vedeu
       #
       # @return [Array]
       def foreground(value = '', &block)
-        attributes[:streams] << API::Stream.build({
-                                  colour: { foreground: value }
-                                }, &block)
+        stream = API::Stream.build({ colour: { foreground: value },
+                                     parent: self.view_attributes }, &block)
+
+        attributes[:streams] << stream
       end
 
       # @api public
@@ -70,11 +76,13 @@ module Vedeu
       #
       # @return [Array]
       def background(value = '', &block)
-        attributes[:streams] << API::Stream.build({
-                                  colour: { background: value }
-                                }, &block)
+        stream = API::Stream.build({ colour: { background: value },
+                                     parent: self.view_attributes }, &block)
+
+        attributes[:streams] << stream
       end
 
     end
+
   end
 end

data/lib/vedeu/api/stream.rb

@@ -1,6 +1,9 @@
 module Vedeu
   module API
+
+    # Provides methods to be used to define views.
     class Stream < Vedeu::Stream
+
       include Helpers
 
       # Specify the alignment of the stream within the line. Useful in

data/lib/vedeu/application.rb

@@ -1,5 +1,10 @@
 module Vedeu
+
+  # Orchestrates the running of the main application loop.
+  #
+  # @api public
   class Application
+    # :nocov:
     class << self
 
       # @return []
@@ -8,6 +13,21 @@ module Vedeu
       end
       alias_method :restart, :start
 
+      # Stops the application!
+      # - The `:_cleanup_` event is triggered. Vedeu does not handle this event;
+      #   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]
+      def stop
+        Vedeu.trigger(:_cleanup_)
+
+        fail StopIteration
+      end
     end
 
     # @return [Application]
@@ -29,7 +49,7 @@ module Vedeu
       Terminal.open do
         Terminal.set_cursor_mode
 
-        Vedeu.events.trigger(:_initialize_)
+        Vedeu.trigger(:_initialize_)
 
         runner { main_sequence }
       end
@@ -37,6 +57,9 @@ module Vedeu
 
     private
 
+    # Runs the application loop either once, or forever (exceptions and signals
+    # permitting).
+    #
     # @api private
     # @return []
     def runner
@@ -49,6 +72,12 @@ module Vedeu
       end
     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.
+    #
     # @api private
     # @return []
     def main_sequence
@@ -61,6 +90,9 @@ module Vedeu
       end
     end
 
+    # Runs the application in a continuous loop. This loop is stopped elsewhere
+    # with the raising of the StopIteration exception.
+    #
     # @api private
     # @return []
     def run_many
@@ -74,4 +106,5 @@ module Vedeu
     end
 
   end
+  # :nocov:
 end

data/lib/vedeu/configuration.rb

@@ -1,5 +1,11 @@
 module Vedeu
+
+  # Allows the customisation of Vedeu's behaviour through command-line
+  # arguments.
+  #
+  # @api public
   module Configuration
+
     extend self
 
     # Parses arguments passed on the command-line or via {Vedeu::Launcher} into
@@ -51,9 +57,9 @@ module Vedeu
         end
 
         opts.on('-C', '--colour-mode [COLOURS]', Integer,
-                'Run application in either `8`, `16` or `256` colour ' \
-                'mode.') do |colours|
-          if [8, 16, 256].include?(colours)
+                'Run application in either `8`, `16`, `256` or `16777216` ' \
+                'colour mode.') do |colours|
+          if [8, 16, 256, 16777216].include?(colours)
             options[:colour_mode] = colours
 
           else
@@ -157,6 +163,7 @@ module Vedeu
     #
     # @api private
     # @return [Fixnum]
+    # :nocov:
     def detect_colour_mode
       if ENV['VEDEU_TERM']
         case ENV['VEDEU_TERM']
@@ -177,11 +184,13 @@ module Vedeu
 
       end
     end
+    # :nocov:
 
     # Determine the debug mode via an enviroment variable.
     #
     # @api private
     # @return [TrueClass|FalseClass]
+    # :nocov:
     def detect_debug_mode
       if ENV['VEDEU_DEBUG']
         case ENV['VEDEU_DEBUG']
@@ -195,11 +204,13 @@ module Vedeu
 
       end
     end
+    # :nocov:
 
     # Determine the trace mode via an environment variable.
     #
     # @api private
     # @return [TrueClass|FalseClass]
+    # :nocov:
     def detect_trace_mode
       if ENV['VEDEU_TRACE']
         case ENV['VEDEU_TRACE']
@@ -213,6 +224,7 @@ module Vedeu
 
       end
     end
+    # :nocov:
 
   end
 end