vedeu 0.8.5 → 0.8.6

data/lib/vedeu/dsl/view.rb

@@ -51,7 +51,7 @@ module Vedeu
       # @param block [Proc] The directives you wish to send to this
       #   view.
       # @macro raise_requires_block
-      # @raise [Vedeu::Error::MissingRequired]
+      # @macro raise_missing_required
       # @return [Vedeu::Views::Views<Vedeu::Views::View>]
       # @todo More documentation required.
       def view(name, &block)
@@ -82,8 +82,9 @@ module Vedeu
       #   use relative paths.
       # @param object [Object] The object for which the values of
       #   template's variables can be obtained.
-      # @param options [Hash<Symbol => void>] See {Vedeu::DSL::Wordwrap}
-      # @raise [Vedeu::Error::MissingRequired]
+      # @param options [Hash<Symbol => void>] See
+      #   {Vedeu::DSL::Wordwrap}
+      # @macro raise_missing_required
       # @return [Vedeu::Views::Views<Vedeu::Views::View>]
       def template_for(name, filename, object = nil, options = {})
         fail Vedeu::Error::MissingRequired,

data/lib/vedeu/error.rb

@@ -45,6 +45,12 @@ module Vedeu
     # Raised when Vedeu attempts to parse a view or interface and
     # encounters a problem.
     #
+    # @!macro [new] raise_invalid_syntax
+    #   @raise [Vedeu::Error::InvalidSyntax] When the value given for
+    #     an argument or parameter cannot be used because it is not
+    #     valid for the use case, unsupported or the method expects a
+    #     different type.
+    #
     class InvalidSyntax < StandardError
 
     end # InvalidSyntax
@@ -53,6 +59,11 @@ module Vedeu
     # For example, when a name is not provided for a model when
     # attempting to store it in a repository.
     #
+    # @!macro [new] raise_missing_required
+    #    @raise [Vedeu::Error::MissingRequired] When the required
+    #      argument or parameter was given but without a meaningful or
+    #      usable value (e.g. nil).
+    #
     class MissingRequired < StandardError
 
     end # MissingRequired
@@ -78,6 +89,12 @@ module Vedeu
     #
     # @see Vedeu::Colours::Translator
     #
+    # @!macro [new] raise_not_implemented
+    #    @raise [Vedeu::Error::NotImplemented] When a subclass of the
+    #      current class actually implements the method. Usually an
+    #      indicator that the subclass should be used instead of the
+    #      current class.
+    #
     class NotImplemented < StandardError
 
     end # NotImplemented

data/lib/vedeu/geometries/dsl/dsl.rb

@@ -83,6 +83,7 @@ module Vedeu
       # Align the interface/view horizontally or vertically within
       # the terminal.
       #
+      # {include:file:docs/dsl/by_method/geometry/align.md}
       # @param vertical [Symbol] One of :bottom, :middle, :none, :top.
       # @param horizontal [Symbol] One of :center, :centre, :left,
       #   :none, :right.
@@ -92,13 +93,7 @@ module Vedeu
       # @param height [Fixnum] The number of lines/rows tall; this is
       #   required when the given value for vertical is any value
       #   other than :none.
-      # @raise [Vedeu::Error::InvalidSyntax]
-      #   - When the vertical is not given.
-      #   - When the horizontal is not given.
-      #   - When the horizontal is given (and not :none) and the width
-      #     is not given.
-      #   - When the vertical is given (and not :none) and the height
-      #     is not given.
+      # @macro raise_invalid_syntax
       # @return [Vedeu::Geometries::Geometry]
       def align(vertical: :none, horizontal: :none, width: nil, height: nil)
         horizontal_alignment(horizontal, width)
@@ -149,8 +144,6 @@ module Vedeu
       #   default width of the terminal, this can be substituted for
       #   your own positive integer.
       # @param height [Fixnum] The number of lines/rows.
-      # @raise [Vedeu::Error::InvalidSyntax] When the height is not
-      #   given.
       # @return [Vedeu::Geometries::Geometry]
       def align_bottom(height = nil)
         vertical_alignment(:bottom, height)
@@ -178,8 +171,6 @@ module Vedeu
       #   default height of the terminal, this can be substituted for
       #   your own positive integer.
       # @param width [Fixnum] The number of characters/columns.
-      # @raise [Vedeu::Error::InvalidSyntax] When the width is not
-      #   given.
       # @return [Vedeu::Geometries::Geometry]
       def align_centre(width = nil)
         horizontal_alignment(:centre, width)
@@ -206,8 +197,6 @@ module Vedeu
       #   default height of the terminal, this can be substituted for
       #   your own positive integer.
       # @param width [Fixnum] The number of characters/columns.
-      # @raise [Vedeu::Error::InvalidSyntax] When the width is not
-      #   given.
       # @return [Vedeu::Geometries::Geometry]
       def align_left(width = nil)
         horizontal_alignment(:left, width)
@@ -234,8 +223,6 @@ module Vedeu
       #   default width of the terminal, this can be substituted for
       #   your own positive integer.
       # @param height [Fixnum] The number of lines/rows.
-      # @raise [Vedeu::Error::InvalidSyntax] When the height is not
-      #   given.
       # @return [Vedeu::Geometries::Geometry]
       def align_middle(height = nil)
         vertical_alignment(:middle, height)
@@ -261,8 +248,6 @@ module Vedeu
       #   default height of the terminal, this can be substituted for
       #   your own positive integer.
       # @param width [Fixnum] The number of characters/columns.
-      # @raise [Vedeu::Error::InvalidSyntax] When the width is not
-      #   given.
       # @return [Vedeu::Geometries::Geometry]
       def align_right(width = nil)
         horizontal_alignment(:right, width)
@@ -289,8 +274,6 @@ module Vedeu
       #   default width of the terminal, this can be substituted for
       #   your own positive integer.
       # @param height [Fixnum] The number of lines/rows.
-      # @raise [Vedeu::Error::InvalidSyntax] When the height is not
-      #   given.
       # @return [Vedeu::Geometries::Geometry]
       def align_top(height = nil)
         vertical_alignment(:top, height)

data/lib/vedeu/groups/refresh.rb

@@ -52,8 +52,7 @@ module Vedeu
 
       private
 
-      # @raise [Vedeu::Error::MissingRequired] When the name is empty
-      #   or nil.
+      # @macro raise_missing_required
       # @return [String]
       def group_name
         return name if present?(name)

data/lib/vedeu/input/dsl.rb

@@ -61,8 +61,7 @@ module Vedeu
       #   this keymap relates to.
       # @param block [Proc]
       # @macro raise_requires_block
-      # @raise [Vedeu::Error::MissingRequired] When the name is not
-      #   given.
+      # @macro raise_missing_required
       # @return [Vedeu::Input::Keymap]
       def self.keymap(name, &block)
         fail Vedeu::Error::MissingRequired unless name
@@ -83,10 +82,7 @@ module Vedeu
       #   defined, then the extras are treated as aliases.
       # @param block [Proc] The action to perform when this key is
       #   pressed. Can be a method call or event triggered.
-      # @raise [Vedeu::Error::InvalidSyntax]
-      #   When the required block is not given, the values parameter
-      #   is undefined, or when processing the collection, a member
-      #   is undefined.
+      # @macro raise_invalid_syntax
       # @return [Array] A collection containing the keypress(es).
       def key(*values, &block)
         fail Vedeu::Error::InvalidSyntax,

data/lib/vedeu/input/mapper.rb

@@ -27,8 +27,7 @@ module Vedeu
 
         # @param key [String|Symbol] The keypress.
         # @param name [String|Symbol] The keymap name.
-        # @raise [Vedeu::Error::MissingRequired] When the key or name
-        #   params are missing.
+        # @macro raise_missing_required
         # @return [Boolean]
         def registered?(key = nil, name = nil)
           fail Vedeu::Error::MissingRequired,

data/lib/vedeu/input/read.rb

@@ -116,6 +116,7 @@ module Vedeu
         present?(@input)
       end
 
+      # @macro raise_invalid_syntax
       # @return [Symbol]
       def mode
         unless valid_mode?

data/lib/vedeu/interfaces/dsl.rb

@@ -35,6 +35,7 @@ module Vedeu
         # @param block [Proc] A set of attributes which define the
         #   features of the interface.
         # @macro raise_requires_block
+        # @macro raise_missing_required
         # @return [Vedeu::Interfaces::Interface]
         # @todo More documentation required.
         def interface(name, &block)

data/lib/vedeu/menus/dsl.rb

@@ -35,8 +35,7 @@ module Vedeu
         #   end
         #
         # @macro raise_requires_block
-        # @raise [Vedeu::Error::MissingRequired] When a name is not
-        #   given.
+        # @macro raise_missing_required
         # @return [API::Menu]
         def menu(name, &block)
           fail Vedeu::Error::MissingRequired unless name

data/lib/vedeu/models/page.rb

@@ -16,6 +16,7 @@ module Vedeu
 
       # @param value
       #   [Vedeu::Models::Page|Vedeu::Models::Row|Array<void>|void]
+      # @macro raise_invalid_syntax
       # @return [Vedeu::Models::Page]
       def self.coerce(value)
         if value.is_a?(Vedeu::Models::Page)

data/lib/vedeu/output/output.rb

@@ -11,61 +11,59 @@ module Vedeu
     #
     class Output
 
-      # @param output (see #output)
-      # @return [Array]
-      def self.buffer_update(output)
-        return nil if output.nil?
+      include Vedeu::Common
 
-        new(output).buffer_update
-      end
-
-      # @param output (see #output)
-      # @return [Array]
-      def self.buffer_write(output)
-        return nil if output.nil?
+      class << self
 
-        new(output).buffer_write
-      end
+        # @param (see #output)
+        # @return (see #buffer_update)
+        def buffer_update(output)
+          new(output).buffer_update
+        end
 
-      # @param output (see #output)
-      # @return [Array<String>]
-      def self.direct_write(output)
-        return nil if output.nil?
+        # @param (see #output)
+        # @return (see #buffer_write)
+        def buffer_write(output)
+          new(output).buffer_write
+        end
 
-        new(output).direct_write
-      end
+        # @param (see #output)
+        # @return (see #direct_write)
+        def direct_write(output)
+          new(output).direct_write
+        end
 
-      # Writes output to the defined renderers.
-      #
-      # @param output (see #output)
-      # @return [Array|NilClass|String]
-      def self.render_output(output)
-        return nil if output.nil?
+        # Writes output to the defined renderers.
+        #
+        # @param (see #output)
+        # @return (see #render_output)
+        def render_output(output)
+          new(output).render_output
+        end
 
-        new(output).render_output
-      end
+      end # Eigenclass
 
       # Return a new instance of Vedeu::Output::Output.
       #
-      # @param output (see #output)
+      # @param (see #output)
       # @return [Vedeu::Output::Output]
       def initialize(output)
         @output = output
       end
 
-      # @return [Array]
+      # @return (see #render_output)
       def buffer_update
-        Vedeu::Buffers::Terminal.update(output)
+        Vedeu::Buffers::Terminal.update(output) if present?(output)
       end
 
-      # @return [Array]
+      # @return (see #render_output)
       def buffer_write
-        Vedeu::Buffers::Terminal.write(output)
+        Vedeu::Buffers::Terminal.write(output) if present?(output)
       end
 
-      # @return [Array<String>]
+      # @return (see #render_output)
       def direct_write
-        Vedeu::Terminal.output(output.to_s)
+        Vedeu::Terminal.output(output.to_s) if present?(output)
       end
 
       # Send the view to the renderers. If the output is a
@@ -75,9 +73,9 @@ module Vedeu
       # because escape sequences only make sense to the terminal and
       # not other renderers.
       #
-      # @return [Array|String|NilClass]
+      # @return [Array<String>|String|NilClass]
       def render_output
-        if escape_sequence?
+        if escape?(output)
           direct_write
 
         else
@@ -93,13 +91,6 @@ module Vedeu
       #   NilClass|Vedeu::Cells::Escape|Vedeu::Cells::Cursor]
       attr_reader :output
 
-      private
-
-      # @return [Boolean]
-      def escape_sequence?
-        output.is_a?(Vedeu::Cells::Escape) || output.is_a?(Vedeu::Cells::Cursor)
-      end
-
     end # Output
 
   end # Output
@@ -113,7 +104,7 @@ module Vedeu
   #   Vedeu.render_output(output)
   #
   # @!method render_output
-  # @return [Array|NilClass]
+  # @return (see Vedeu::Output::Output#render_output)
   def_delegators Vedeu::Output::Output,
                  :buffer_update,
                  :buffer_write,

data/lib/vedeu/renderers/html.rb

@@ -41,18 +41,9 @@ module Vedeu
         end
       end
 
-      # Returns a boolean indicating whether the output is a
-      # {Vedeu::Cells::Escape}. If it is, it won't be rendered in
-      # HTML.
-      #
-      # @return [Boolean]
-      def escape?
-        output.is_a?(Vedeu::Cells::Escape) || output.is_a?(Vedeu::Cells::Cursor)
-      end
-
       # @return [Boolean]
       def valid?
-        return false if string?(output) || escape?
+        return false if string?(output) || escape?(output)
 
         true
       end

data/lib/vedeu/renderers/options.rb

@@ -17,6 +17,20 @@ module Vedeu
       # Returns a new instance of the class including this module.
       #
       # @param opts [Hash]
+      # @option opts content [String] Defaults to an empty string.
+      # @option opts end_tag [String] Defaults to '</td>'.
+      # @option opts end_row_tag [String] Defaults to '</tr>'.
+      # @option opts filename [String] Provide a filename for the
+      #   output. Defaults to 'out'.
+      # @option opts start_tag [String] Defaults to '<td' (note the
+      #   end of the tag is missing, this is so that inline styles can
+      #   be added later).
+      # @option opts start_row_tag [String] Defaults to '<tr>'.
+      # @option opts template [String]
+      # @option opts timestamp [Boolean] Append a timestamp to the
+      #   filename.
+      # @option opts write_file [Boolean] Whether to write the file
+      #   to the given filename.
       # @return [void]
       def initialize(opts = {})
         @options = defaults.merge!(opts || {})
@@ -28,7 +42,6 @@ module Vedeu
       end
 
       # @param output [Vedeu::Models::Page]
-      # @param opts [Hash]
       # @return [void]
       def render(output = '')
         options.merge!(output: output)
@@ -36,9 +49,7 @@ module Vedeu
         write
       end
 
-      # @raise [Vedeu::Error::NotImplemented] Subclasses of this class
-      #   must implement this method.
-      # @return [Vedeu::Error::NotImplemented]
+      # @macro raise_not_implemented
       def write
         fail Vedeu::Error::NotImplemented, 'Including classes implement this.'
       end
@@ -66,29 +77,13 @@ module Vedeu
         end
       end
 
-      # @return [void]
+      # @macro raise_not_implemented
       def content
         fail Vedeu::Error::NotImplemented, 'Including classes implement this.'
       end
 
       # The default values for a new instance of this class.
       #
-      # @param options [Hash]
-      # @option options content [String] Defaults to an empty string.
-      # @option options end_tag [String] Defaults to '</td>'.
-      # @option options end_row_tag [String] Defaults to '</tr>'.
-      # @option options filename [String] Provide a filename for the
-      #   output. Defaults to 'out'.
-      # @option options start_tag [String] Defaults to '<td' (note the
-      #   end of the tag is missing, this is so that inline styles can
-      #   be added later).
-      # @option options start_row_tag [String] Defaults to '<tr>'.
-      # @option options template [String]
-      # @option options timestamp [Boolean] Append a timestamp to the
-      #   filename.
-      # @option options write_file [Boolean] Whether to write the file
-      #   to the given filename.
-      #
       # @return [Hash<Symbol => void>]
       def defaults
         {

data/lib/vedeu/renderers/terminal.rb

@@ -35,6 +35,10 @@ module Vedeu
 
       private
 
+      # Returns the output in a compressed form if the :compression
+      # option is true.
+      #
+      # @return [String]
       def content
         compression
       end

data/lib/vedeu/repositories/defaults.rb

@@ -38,8 +38,7 @@ module Vedeu
       end
 
       # @param attributes [Hash]
-      # @raise [Vedeu::Error::InvalidSyntax] When the :attributes
-      #   param is not a Hash.
+      # @macro raise_invalid_syntax
       # @return [Hash]
       def validate(attributes)
         fail Vedeu::Error::InvalidSyntax,