vedeu 0.1.18 → 0.1.19

data/lib/vedeu/input/input.rb

@@ -0,0 +1,77 @@
+module Vedeu
+
+  # Captures input from the user via {Vedeu::Terminal#input} and translates
+  # special characters into symbols.
+  #
+  # @api private
+  class Input
+
+    # @return [String|Symbol]
+    def self.capture
+      new.capture
+    end
+
+    # Returns a new instance of Input.
+    #
+    # @return [Input]
+    def initialize; end
+
+    # @return []
+    def capture
+      Vedeu.trigger(:_keypress_, keypress)
+    end
+
+    private
+
+    # @api private
+    # @return [String]
+    def input
+      @_input ||= Terminal.input
+    end
+
+    # @api private
+    # @return [String|Symbol]
+    def keypress
+      key = input
+
+      specials.fetch(key, key)
+    end
+
+    # @api private
+    # @return [Hash]
+    def specials
+      {
+        "\r"      => :enter,
+        "\t"      => :tab,
+        "\e"      => :escape,
+        "\e[A"    => :up,
+        "\e[B"    => :down,
+        "\e[C"    => :right,
+        "\e[D"    => :left,
+        "\e[5~"   => :page_up,
+        "\e[6~"   => :page_down,
+        "\e[H"    => :home,
+        "\e[3~"   => :delete,
+        "\e[F"    => :end,
+        "\e[Z"    => :shift_tab,
+        "\eOP"    => :f1,
+        "\eOQ"    => :f2,
+        "\eOR"    => :f3,
+        "\eOS"    => :f4,
+        "\e[15~"  => :f5,
+        "\e[17~"  => :f6,
+        "\e[18~"  => :f7,
+        "\e[19~"  => :f8,
+        "\e[20~"  => :f9,
+        "\e[21~"  => :f10,
+        "\e[23~"  => :f11,
+        "\e[24~"  => :f12,
+        "\e[1;2P" => :print_screen,
+        "\e[1;2Q" => :scroll_lock,
+        "\e[1;2R" => :pause_break,
+        "\u007F"  => :backspace,
+      }
+    end
+
+  end
+end

data/lib/vedeu/launcher.rb

@@ -1,4 +1,11 @@
 module Vedeu
+
+  # This class ensures that STDIN, STDOUT and STDERR point to the correct
+  # places. It also handles the initial configuration of the application,
+  # the starting of the application, the handling of uncaught exceptions and
+  # finally the exiting of the application with the correct exit code.
+  #
+  # @api public
   class Launcher
 
     # :nocov:

data/lib/vedeu/models/attributes/background.rb

@@ -1,18 +1,28 @@
 module Vedeu
+
+  # The class represents one half (the other, can be found at
+  # {Vedeu::Foreground}) of a terminal colour escape sequence.
+  #
+  # @api private
   class Background < ColourTranslator
 
     private
 
+    # Returns an escape sequence for a named background colour.
+    #
+    # Valid names are: `:black`, `:red`, `:green`, `:yellow`, `:blue`,
+    # `:magenta`, `:cyan`, `:white` and `:default`.
+    #
     # @api private
     # @return [String]
     def named
-      ["\e[", background_codes[colour], "m"].join
+      ["\e[", background_codes[colour], 'm'].join
     end
 
     # @api private
     # @return [String]
     def numbered
-      ["\e[48;5;", css_to_numbered, "m"].join
+      ["\e[48;5;", css_to_numbered, 'm'].join
     end
 
     # @api private
@@ -27,6 +37,9 @@ module Vedeu
       end
     end
 
+    # Produces the background named colour escape sequence hash from the
+    # foreground escape sequence hash.
+    #
     # @api private
     # @return [Hash]
     def background_codes

data/lib/vedeu/models/attributes/coercions.rb

@@ -1,27 +1,42 @@
 module Vedeu
+
+  # Provides means to convert attributes into the correct model.
+  #
+  # @api private
   module Coercions
+
+    # Contains class methods which are accessible as such to classes and modules
+    # which include {Vedeu::Coercions}.
     module ClassMethods
 
+      include Vedeu::Common
+
       # Produces new objects of the correct class from attributes hashes,
       # ignores objects that have already been coerced.
+      # When provided with a parent argument, will allow the new object
+      # to know the colour and style of its parent.
       #
       # @param values [Array|Hash]
+      # @param parent [Hash|Nil]
       # @return [Array]
-      def coercer(values)
-        return [] if values.nil? || values.empty?
+      def coercer(values, parent = nil)
+        return [] unless defined_value?(values)
 
         [values].flatten.map do |value|
           if value.is_a?(self)
             value
 
           else
-            self.new(value)
+            self.new(value.merge!({ parent: parent }))
 
           end
         end
       end
     end
 
+    # Whenever this module {Vedeu::Coercions} is included in another class or
+    # module, make its methods into class methods, so they may be called
+    # directly.
     def self.included(receiver)
       receiver.extend(ClassMethods)
     end

data/lib/vedeu/models/attributes/colour_translator.rb

@@ -1,30 +1,36 @@
 module Vedeu
+
+  # Convert a CSS/HTML colour string into a terminal escape sequence.
+  #
+  # If provided with an empty value or a string it cannot convert, it will
+  # return an empty string.
+  #
+  # When provided with a named colour, uses the terminal's value for that
+  # colour. If a theme is being used with the terminal, which overrides the
+  # defaults, then the theme's colour will be used. The recognised names are:
+  # :black, :red, :green, :yellow, :blue, :magenta, :cyan, :white, :default.
+  #
+  # When a number between 0 and 255 is provided, Vedeu will use the terminal
+  # colour corresponding with that colour. TODO: Create chart.
+  #
+  # Finally, when provided a CSS/HTML colour string e.g. '#ff0000', Vedeu will
+  # translate that to the 8-bit escape sequence or if you have a capable
+  # terminal and the `VEDEU_TERM=xterm-truecolor` environment variable set,
+  # a 24-bit representation.
+  #
+  # @api private
   class ColourTranslator
 
     # Convert a CSS/HTML colour string into a terminal escape sequence.
     #
-    # If provided with an empty value or a string it cannot convert, it will
-    # return an empty string.
-    #
-    # When provided with a named colour, uses the terminal's value for that
-    # colour. If a theme is being used with the terminal, which overrides the
-    # defaults, then the theme's colour will be used. The recognised names are:
-    # :black, :red, :green, :yellow, :blue, :magenta, :cyan, :white, :default.
-    #
-    # When a number between 0 and 255 is provided, Vedeu will use the terminal
-    # colour corresponding with that colour. TODO: Create chart.
-    #
-    # Finally, when provided a CSS/HTML colour string e.g. '#ff0000', Vedeu will
-    # translate that to the 8-bit escape sequence or if you have a capable
-    # terminal and the `VEDEU_TERM=xterm-truecolor` environment variable set,
-    # a 24-bit representation.
-    #
     # @param colour [String]
     # @return [String]
     def self.escape_sequence(colour = '')
       new(colour).escape_sequence
     end
 
+    # Return a new instance of ColourTranslator.
+    #
     # @param colour [String]
     # @return [ColourTranslator]
     def initialize(colour = '')
@@ -32,7 +38,7 @@ module Vedeu
     end
 
     # @return [String]
-    # @see Vedeu::ColourTranslator.escape_sequence
+    # @see Vedeu::ColourTranslator
     def escape_sequence
       if no_colour?
         ''

data/lib/vedeu/models/attributes/foreground.rb

@@ -1,4 +1,9 @@
 module Vedeu
+
+  # The class represents one half (the other, can be found at
+  # {Vedeu::Background}) of a terminal colour escape sequence.
+  #
+  # @api private
   class Foreground < ColourTranslator
 
     private
@@ -6,13 +11,13 @@ module Vedeu
     # @api private
     # @return [String]
     def named
-      ["\e[", foreground_codes[colour], "m"].join
+      ["\e[", foreground_codes[colour], 'm'].join
     end
 
     # @api private
     # @return [String]
     def numbered
-      ["\e[38;5;", css_to_numbered, "m"].join
+      ["\e[38;5;", css_to_numbered, 'm'].join
     end
 
     # @api private
@@ -27,6 +32,9 @@ module Vedeu
       end
     end
 
+    # Produces the foreground named colour escape sequence hash from
+    # {Vedeu::ColourTranslator#codes}
+    #
     # @api private
     # @return [Hash]
     def foreground_codes

data/lib/vedeu/models/attributes/presentation.rb

@@ -1,15 +1,77 @@
 module Vedeu
+
+  # This module allows the sharing of presentation concerns between the models:
+  # Interface, Line and Stream.
+  #
+  # @api private
   module Presentation
 
+    # Returns the colour attributes of the receiving class.
+    #
+    # @return [Hash]
+    def view_attributes
+      {
+        colour: attributes[:colour],
+        style:  attributes[:style],
+      }
+    end
+
+    # Returns a new Colour instance.
+    #
     # @return [Colour]
     def colour
       @colour ||= Colour.new(attributes[:colour])
     end
 
+    # Returns a new Style instance.
+    #
     # @return [Style]
     def style
       @style ||= Style.new(attributes[:style])
     end
 
+    # Converts the colours and styles to escape sequences, and if the parent
+    # model has previously set the colour and style, reverts back to that for
+    # consistent formatting.
+    #
+    # @return [String]
+    def to_s
+      render_colour do
+        render_style do
+          data
+        end
+      end
+    end
+
+    private
+
+    # @api private
+    # @return [String]
+    def render_colour(&block)
+      [ colour.to_s, yield, parent_colour ].join
+    end
+
+    # @api private
+    # @return [String]
+    def render_style(&block)
+      [ style.to_s, yield, parent_style ].join
+    end
+
+    # @api private
+    # @return [String]
+    def parent_colour
+      return '' if parent.nil?
+
+      Colour.new(parent[:colour]).to_s
+    end
+
+    # @api private
+    # @return [String]
+    def parent_style
+      return '' if parent.nil?
+
+      Style.new(parent[:style]).to_s
+    end
+
   end
 end

data/lib/vedeu/models/colour.rb

@@ -1,11 +1,15 @@
 module Vedeu
+
+  # Provides a container for terminal escape sequences controlling the
+  # foreground and background colours of a character or collection of
+  # characters.
+  #
+  # @api private
   class Colour
 
     attr_reader :attributes
 
-    # Initialises a new Colour object which is a container terminal escape
-    # sequences controlling the foreground and background colour of a
-    # character or collection of characters.
+    # Returns a new instance of Colour.
     #
     # @param attributes [Hash]
     # @return [Colour]

data/lib/vedeu/models/composition.rb

@@ -1,10 +1,11 @@
 module Vedeu
+
+  # A composition is a collection of interfaces.
   class Composition
 
     attr_reader :attributes
 
-    # Builds a new composition, which is a collection of interfaces, ready to be
-    # rendered to the screen.
+    # Builds a new composition, ready to be rendered to the screen.
     #
     # @param attributes [Hash]
     # @param block [Proc]
@@ -13,6 +14,8 @@ module Vedeu
       new(attributes, &block).attributes
     end
 
+    # Returns a new instance of Composition.
+    #
     # @param attributes [Hash]
     # @param block [Proc]
     # @return [Composition]
@@ -26,30 +29,23 @@ module Vedeu
       end
     end
 
-    # Returns a collection of interface attributes associated with this
-    # composition.
+    # Returns a collection of interfaces associated with this composition.
     #
     # @return [Array]
     def interfaces
-      @interfaces ||= if attributes[:interfaces].nil? || attributes[:interfaces].empty?
-        []
-
-      else
-        [ attributes[:interfaces] ].flatten.map do |attrs|
-          stored = Buffers.retrieve_attributes(attrs[:name])
-
-          combined = stored.merge(attrs) do |key, s, a|
-            key == :lines && s.empty? ? a : s
-          end
-
-          Interface.new(combined)
-        end
+      @interfaces ||= Interface.coercer(attributes[:interfaces])
+    end
 
-      end
+    # Returns the view attributes for a Composition, which will always be none,
+    # as a composition is a merely a collection of interfaces.
+    #
+    # @return [Hash]
+    def view_attributes
+      {}
     end
 
     # Returns the complete escape sequence which this composition renders to.
-    # This is used by {Terminal.output} to draw the view.
+    # This is used by {Vedeu::Terminal.output} to draw the view.
     #
     # @return [String]
     def to_s
@@ -58,6 +54,8 @@ module Vedeu
 
     private
 
+    # The default values for a new instance of Composition.
+    #
     # @api private
     # @return [Hash]
     def defaults