vedeu 0.1.17 → 0.1.18

data/lib/vedeu/launcher.rb

@@ -24,7 +24,9 @@ module Vedeu
     def execute!
       $stdin, $stdout, $stderr = @stdin, @stdout, @stderr
 
-      Application.start(configuration)
+      Configuration.configure(argv)
+
+      Application.start
 
       @exit_code = 0
     rescue StandardError => uncaught_exception
@@ -41,10 +43,5 @@ module Vedeu
 
     attr_reader :argv
 
-    def configuration
-      Configuration.configure(argv)
-    end
-    # :nocov:
-
   end
 end

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

@@ -3,16 +3,22 @@ module Vedeu
 
     private
 
+    # @api private
+    # @return [String]
     def named
       ["\e[", background_codes[colour], "m"].join
     end
 
+    # @api private
+    # @return [String]
     def numbered
       ["\e[48;5;", css_to_numbered, "m"].join
     end
 
+    # @api private
+    # @return [String]
     def rgb
-      if Terminal.colour_mode == 16777216
+      if Configuration.colour_mode == 16777216
         sprintf("\e[48;2;%s;%s;%sm", *css_to_rgb)
 
       else
@@ -21,6 +27,8 @@ module Vedeu
       end
     end
 
+    # @api private
+    # @return [Hash]
     def background_codes
       codes.inject({}){ |h, (k, v)| h.merge(k => v + 10) }
     end

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

@@ -11,7 +11,13 @@ module Vedeu
     # defaults, then the theme's colour will be used. The recognised names are:
     # :black, :red, :green, :yellow, :blue, :magenta, :cyan, :white, :default.
     #
-    # TODO: add more documentation
+    # 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]
@@ -50,46 +56,68 @@ module Vedeu
 
     attr_reader :colour
 
+    # @api private
+    # @return [TrueClass|FalseClass]
     def no_colour?
       colour.nil? || colour.to_s.empty?
     end
 
+    # @api private
+    # @return [TrueClass|FalseClass]
     def named?
       colour.is_a?(Symbol) && valid_name?
     end
 
+    # @api private
+    # @return [Exception]
     def named
       fail NotImplemented, 'Subclasses implement this.'
     end
 
+    # @api private
+    # @return [TrueClass|FalseClass]
     def valid_name?
       codes.keys.include?(colour)
     end
 
+    # @api private
+    # @return [TrueClass|FalseClass]
     def numbered?
       colour.is_a?(Fixnum) && valid_range?
     end
 
+    # @api private
+    # @return [Exception]
     def numbered
       fail NotImplemented, 'Subclasses implement this.'
     end
 
+    # @api private
+    # @return [TrueClass|FalseClass]
     def valid_range?
       colour >= 0 && colour <= 255
     end
 
+    # @api private
+    # @return [TrueClass|FalseClass]
     def rgb?
       colour.is_a?(String) && valid_rgb?
     end
 
+    # @api private
+    # @return [Exception]
     def rgb
       fail NotImplemented, 'Subclasses implement this.'
     end
 
+    # @api private
+    # @return [TrueClass|FalseClass]
     def valid_rgb?
-      colour =~ /^#([A-Fa-f0-9]{6})$/
+      !!(colour =~ /^#([A-Fa-f0-9]{6})$/)
     end
 
+    # @api private
+    # @return [Array]
     def css_to_rgb
       [
         colour[1..2].to_i(16),
@@ -98,6 +126,8 @@ module Vedeu
       ]
     end
 
+    # @api private
+    # @return [Fixnum]
     def css_to_numbered
       if rgb?
         [16, red, green, blue].inject(:+)
@@ -108,18 +138,26 @@ module Vedeu
       end
     end
 
+    # @api private
+    # @return [Fixnum]
     def red
       (css_to_rgb[0] / 51) * 36
     end
 
+    # @api private
+    # @return [Fixnum]
     def green
       (css_to_rgb[1] / 51) * 6
     end
 
+    # @api private
+    # @return [Fixnum]
     def blue
       (css_to_rgb[2] / 51) * 1
     end
 
+    # @api private
+    # @return [Hash]
     def codes
       {
         black:   30,

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

@@ -3,16 +3,22 @@ module Vedeu
 
     private
 
+    # @api private
+    # @return [String]
     def named
       ["\e[", foreground_codes[colour], "m"].join
     end
 
+    # @api private
+    # @return [String]
     def numbered
       ["\e[38;5;", css_to_numbered, "m"].join
     end
 
+    # @api private
+    # @return [String]
     def rgb
-      if Terminal.colour_mode == 16777216
+      if Configuration.colour_mode == 16777216
         sprintf("\e[38;2;%s;%s;%sm", *css_to_rgb)
 
       else
@@ -21,6 +27,8 @@ module Vedeu
       end
     end
 
+    # @api private
+    # @return [Hash]
     def foreground_codes
       codes
     end

data/lib/vedeu/models/colour.rb

@@ -3,6 +3,10 @@ module Vedeu
 
     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.
+    #
     # @param attributes [Hash]
     # @return [Colour]
     def initialize(attributes = {})
@@ -33,6 +37,8 @@ module Vedeu
 
     private
 
+    # @api private
+    # @return [Hash]
     def defaults
       {
         foreground: '',

data/lib/vedeu/models/composition.rb

@@ -49,7 +49,7 @@ module Vedeu
     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 {Terminal.output} to draw the view.
     #
     # @return [String]
     def to_s
@@ -58,11 +58,18 @@ module Vedeu
 
     private
 
+    # @api private
+    # @return [Hash]
     def defaults
       {
         interfaces: []
       }
     end
 
+    # @api private
+    def method_missing(method, *args, &block)
+      @self_before_instance_eval.send(method, *args, &block)
+    end
+
   end
 end

data/lib/vedeu/models/geometry.rb

@@ -3,6 +3,9 @@ module Vedeu
 
     attr_reader :attributes, :centred, :height, :width
 
+    # Calculate and provide interface geometry determined by both the client's
+    # requirements and the terminal's current viewing area.
+    #
     # @param attributes [Hash]
     # @return [Geometry]
     def initialize(attributes = {})
@@ -80,6 +83,8 @@ module Vedeu
       end
     end
 
+    # Returns the top-left coordinate, relative to the interface's position.
+    #
     # @param index [Fixnum]
     # @param block [Proc]
     # @return [String]
@@ -87,10 +92,13 @@ module Vedeu
       Esc.set_position(virtual_y[index], left, &block)
     end
 
+    # Returns a fixed or dynamic value depending on whether the interface is
+    # centred or not.
+    # 
     # @return [Fixnum]
     def top
       if centred
-        centre_y - (viewport_height / 2)
+        Terminal.centre_y - (viewport_height / 2)
 
       else
         y
@@ -113,10 +121,13 @@ module Vedeu
       top - value
     end
 
+    # Returns a fixed or dynamic value depending on whether the interface is
+    # centred or not.
+    #
     # @return [Fixnum]
     def left
       if centred
-        centre_x - (viewport_width / 2)
+        Terminal.centre_x - (viewport_width / 2)
 
       else
         x
@@ -159,6 +170,9 @@ module Vedeu
       bottom + value
     end
 
+    # Returns a fixed or dynamic value depending on whether the interface is
+    # centred or not.
+    #
     # @return [Fixnum]
     def right
       left + width
@@ -181,22 +195,21 @@ module Vedeu
 
     private
 
-    def centre
-      Terminal.centre
-    end
-
-    def centre_y
-      centre.first
-    end
-
-    def centre_x
-      centre.last
+    # Provides a virtual y position within the interface's dimensions.
+    #
+    # @return [Array]
+    def virtual_y
+      (top..bottom).to_a
     end
 
-    def virtual_y
-      @_virtual_y ||= (top..bottom).to_a
+    # Provides a virtual x position within the interface's dimensions.
+    #
+    # @return [Array]
+    def virtual_x
+      (left..right).to_a
     end
 
+    # @return [Hash]
     def defaults
       {
         y:       1,

data/lib/vedeu/models/interface.rb

@@ -19,6 +19,14 @@ module Vedeu
       new(attributes, &block).attributes
     end
 
+    # @see Vedeu::API#interface
+    # @param attributes [Hash]
+    # @param block [Proc]
+    # @return []
+    def self.define(attributes = {}, &block)
+      new(attributes).define(&block)
+    end
+
     # @param  attributes [Hash]
     # @param  block [Proc]
     # @return [Interface]
@@ -36,6 +44,30 @@ module Vedeu
       end
     end
 
+    # @see Vedeu::API#interface
+    # @param block [Proc]
+    #
+    # @example
+    #   TODO
+    #
+    # @return []
+    def define(&block)
+      instance_eval(&block) if block_given?
+
+      if attributes[:name].nil? || attributes[:name].empty?
+        fail InvalidSyntax, 'Interfaces and views must have a `name`.'
+      end
+
+      Vedeu::Buffers.create(attributes)
+
+      Vedeu.event("_refresh_#{attributes[:name]}_".to_sym,
+                  { delay: attributes[:delay] }) do
+        Vedeu::Buffers.refresh(attributes[:name])
+      end
+
+      self
+    end
+
     # @return [Array]
     def lines
       @lines ||= Line.coercer(attributes[:lines])
@@ -69,6 +101,8 @@ module Vedeu
 
     private
 
+    # @api private
+    # @return [Hash]
     def defaults
       {
         name:     '',
@@ -82,5 +116,30 @@ module Vedeu
       }
     end
 
+    # @api private
+    # @return [String]
+    def out_of_bounds(name)
+      "Note: For this terminal, the value of '#{name}' may lead to content " \
+      "that is outside the viewable area."
+    end
+
+    # @api private
+    # @return [TrueClass|FalseClass]
+    def y_out_of_bounds?(value)
+      value < 1 || value > Terminal.height
+    end
+
+    # @api private
+    # @return [TrueClass|FalseClass]
+    def x_out_of_bounds?(value)
+      value < 1 || value > Terminal.width
+    end
+
+    # @api private
+    # @return []
+    def method_missing(method, *args, &block)
+      @self_before_instance_eval.send(method, *args, &block)
+    end
+
   end
 end

data/lib/vedeu/models/line.rb

@@ -37,6 +37,8 @@ module Vedeu
 
     private
 
+    # @api private
+    # @return [Hash]
     def defaults
       {
         colour:  {},
@@ -45,6 +47,8 @@ module Vedeu
       }
     end
 
+    # @api private
+    # @return []
     def method_missing(method, *args, &block)
       @self_before_instance_eval.send(method, *args, &block)
     end