vedeu 0.1.15 → 0.1.16

data/lib/vedeu/api/composition.rb

@@ -1,20 +1,8 @@
 module Vedeu
   module API
     class Composition < Vedeu::Composition
-      def self.build(&block)
-        new(&block).attributes
-      end
-
-      def initialize(&block)
-        super
-
-        if block_given?
-          @self_before_instance_eval = eval('self', block.binding)
-
-          instance_eval(&block)
-        end
-      end
 
+      # @see Vedeu::API#view
       def view(name, &block)
         attributes[:interfaces] << Interface.build({ name: name }, &block)
       end
@@ -24,6 +12,7 @@ module Vedeu
       def method_missing(method, *args, &block)
         @self_before_instance_eval.send(method, *args, &block)
       end
+
     end
   end
 end

data/lib/vedeu/api/helpers.rb

@@ -1,6 +1,26 @@
 module Vedeu
   module API
     module Helpers
+
+      # Define either or both foreground and background colours for an
+      # interface, line or a stream.
+      #
+      # @param values [Hash]
+      #
+      # @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)
@@ -8,6 +28,26 @@ module Vedeu
         attributes[:colour] = values
       end
 
+      # Define a style for an interface, line or a stream.
+      #
+      # @param values [Array|String]
+      # @param block  [Proc]
+      #
+      # @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 []
       def style(values = [], &block)
         if block_given?
           attributes[:streams] << API::Stream.build({ style: [values] }, &block)
@@ -17,6 +57,7 @@ module Vedeu
 
         end
       end
+
     end
   end
 end

data/lib/vedeu/api/interface.rb

@@ -1,97 +1,209 @@
 module Vedeu
-  InvalidHeight = Class.new(StandardError)
-  InvalidWidth  = Class.new(StandardError)
-  XOutOfBounds  = Class.new(StandardError)
-  YOutOfBounds  = Class.new(StandardError)
-
   module API
     class Interface < Vedeu::Interface
-      def self.build(attributes = {}, &block)
-        new(attributes, &block).attributes
-      end
+      include Helpers
 
+      # @param attributes [Hash]
+      # @param block [Proc]
+      # @return []
       def self.define(attributes = {}, &block)
         new(attributes).define(&block)
       end
 
-      def initialize(attributes = {}, &block)
-        @attributes = attributes
-
-        if block_given?
-          @self_before_instance_eval = eval('self', block.binding)
-
-          instance_eval(&block)
-        end
-      end
-
+      # @param block [Proc]
+      #
+      # @example
+      #   TODO
+      #
+      # @return []
       def define(&block)
         instance_eval(&block) if block_given?
 
-        Vedeu::Store.create(attributes)
-      end
+        Vedeu::Buffers.create(attributes)
 
+        Vedeu.event("_refresh_#{attributes[:name]}_".to_sym,
+                    { delay: attributes[:delay] }) do
+          Vedeu::Buffers.refresh(attributes[:name])
+        end
+
+        true
+      end
+
+      # Define a single line in a view.
+      #
+      # @param block [Proc]
+      #
+      # @example
+      #   view 'my_interface' do
+      #     line do
+      #       ... some line attributes ...
+      #     end
+      #   end
+      #
+      # @return []
       def line(&block)
         attributes[:lines] << Line.build(&block)
       end
 
+      # @see Vedeu::API#use
       def use(value)
         Vedeu.use(value)
       end
 
-      def colour(value)
-        attributes[:colour] = value
-      end
-
+      # Define the cursor visibility for an interface. A `true` value will show
+      # the cursor, whilst `false` will hide it.
+      #
+      # @param value [Boolean]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     cursor true
+      #     ... some interface attributes ...
+      #   end
+      #
+      # @return []
       def cursor(value)
         attributes[:cursor] = value
       end
 
+      # @param value [Fixnum|Float]
+      #
+      # @return []
       def delay(value)
         attributes[:delay] = value
       end
 
+      # Define a group for an interface. Interfaces of the same group can be
+      # targetted together; for example you may want to refresh multiple
+      # interfaces at once.
+      #
+      # @param value [String]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     group 'main_screen' do
+      #     ... some interface attributes ...
+      #   end
+      #
+      # @return []
       def group(value)
         attributes[:group] = value
       end
 
+      # The name of the interface. Used to reference the interface throughout
+      # your application's execution lifetime.
+      #
+      # @param value [String]
+      #
+      # @example
+      #   TODO
+      #
+      # @return []
       def name(value)
         attributes[:name] = value
       end
 
-      def x(value)
-        fail XOutOfBounds if x_out_of_bounds?(value)
+      # Define the starting x position (column) of the interface.
+      #
+      # @param value [Fixnum]
+      # @param block [Proc]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     x 7 # start on column 7.
+      #
+      #   interface 'other_interface' do
+      #     x { use('my_interface').east } # start on column 8, if
+      #                                    # `my_interface` changes position,
+      #                                    # `other_interface` will too.
+      #
+      # @return []
+      def x(value = 0, &block)
+        return attributes[:geometry][:x] = block if block_given?
+
+        Vedeu.log(out_of_bounds('x')) if x_out_of_bounds?(value)
 
         attributes[:geometry][:x] = value
       end
 
-      def y(value)
-        fail YOutOfBounds if y_out_of_bounds?(value)
+      # Define the starting y position (row/line) of the interface.
+      #
+      # @param value [Fixnum]
+      # @param block [Proc]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     y  4
+      #     ...
+      #
+      #   interface 'other_interface' do
+      #     y  { use('my_interface').north } # start on row/line 3, if
+      #     ...                              # `my_interface` changes position,
+      #                                      # `other_interface` will too.
+      #
+      # @return []
+      def y(value = 0, &block)
+        return attributes[:geometry][:y] = block if block_given?
+
+        Vedeu.log(out_of_bounds('y')) if y_out_of_bounds?(value)
 
         attributes[:geometry][:y] = value
       end
 
+      # Define the number of characters/columns wide the interface will be.
+      #
+      # @param value [Fixnum]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     width 25
+      #     ...
+      #
+      # @return []
       def width(value)
-        fail InvalidWidth if x_out_of_bounds?(value)
+        Vedeu.log(out_of_bounds('width')) if x_out_of_bounds?(value)
 
         attributes[:geometry][:width] = value
       end
 
+      # Define the number of characters/rows/lines tall the interface will be.
+      #
+      # @param value [Fixnum]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     height 8
+      #     ...
+      #
+      # @return []
       def height(value)
-        fail InvalidHeight if y_out_of_bounds?(value)
+        Vedeu.log(out_of_bounds('height')) if y_out_of_bounds?(value)
 
         attributes[:geometry][:height] = value
       end
 
+      # Instructs Vedeu to calculate x and y geometry automatically based on the
+      # centre character of the terminal, the width and the height.
+      #
+      # @param value [Boolean]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     centred true
+      #     ...
+      #
+      # @return []
       def centred(value)
         attributes[:geometry][:centred] = value
       end
 
-      def style(value)
-        attributes[:style] = value
-      end
-
       private
 
+      def out_of_bounds(name)
+        "Note: For this terminal, the value of '#{name}' may lead to content " \
+        "that is outside the viewable area."
+      end
+
       def y_out_of_bounds?(value)
         value < 1 || value > Terminal.height
       end
@@ -103,6 +215,7 @@ module Vedeu
       def method_missing(method, *args, &block)
         @self_before_instance_eval.send(method, *args, &block)
       end
+
     end
   end
 end

data/lib/vedeu/api/line.rb

@@ -3,25 +3,72 @@ module Vedeu
     class Line < Vedeu::Line
       include Helpers
 
+      # Define a stream (a subset of a line).
+      #
+      # @param block [Proc] Block contains directives relating to API::Stream.
+      #
+      # @example
+      #   ...
+      #     line do
+      #       stream do
+      #         ... other stream directives ...
+      #       end
+      #     end
+      #   ...
+      #
+      # @return [Array]
       def stream(&block)
         attributes[:streams] << API::Stream.build(&block)
       end
 
+      # Define text for a line. Using this directive will not allow stream
+      # attributes for this line but is useful for adding lines straight into
+      # the interface.
+      #
+      # @param value [String]
+      #
+      # @example
+      #   ...
+      #     line do
+      #       text 'Some text to display...'
+      #
+      # @return [Array]
       def text(value)
         attributes[:streams] << { text: value }
       end
 
+      # @param value [String]
+      # @param block [Proc]
+      #
+      # @example
+      #   ...
+      #     line do
+      #       foreground '#00ff00' do
+      #         ... other stream directives ...
+      #
+      # @return [Array]
       def foreground(value = '', &block)
         attributes[:streams] << API::Stream.build({
                                   colour: { foreground: value }
                                 }, &block)
       end
 
+      # @param value [String]
+      # @param block [Proc]
+      #
+      # @example
+      #   ...
+      #     line do
+      #       background '#0022ff' do
+      #         ... other stream directives ...
+      #
+      # @return [Array]
       def background(value = '', &block)
         attributes[:streams] << API::Stream.build({
                                   colour: { background: value }
                                 }, &block)
       end
+
     end
   end
 end

data/lib/vedeu/api/stream.rb

@@ -3,17 +3,58 @@ module Vedeu
     class Stream < Vedeu::Stream
       include Helpers
 
+      # Specify the alignment of the stream within the line. Useful in
+      # combination with #width to provide simple formatting effects.
+      #
+      # @param value [Symbol] `:left`, `:centre` and `right` are valid values
+      #   and will align accordingly. If not value is specified, the stream will
+      #   left align.
+      #
+      # @example
+      #   ...
+      #     stream do
+      #       align :right
+      #       ...
+      #
+      # @return [Symbol]
       def align(value)
         attributes[:align] = value
       end
 
+      # Add textual data to the stream via this method.
+      #
+      # @param value [String] The text to be added to the stream. If the length
+      #   of the text is greater than the interface's width, it will be
+      #   truncated and ellipsized.
+      #
+      # @example
+      #   ...
+      #     stream do
+      #       text 'Some text to display...'
+      #       ...
+      #
+      # @return [String]
       def text(value)
         attributes[:text] = value
       end
 
+      # Provides the ability to arbitrarily set the width of content for a
+      # stream. Useful in combination with #align to provide simple formatting
+      # effects.
+      #
+      # @param value [Fixnum] The width in characters.
+      #
+      # @example
+      #   ...
+      #     stream do
+      #       width 20
+      #       ...
+      #
+      # @return [Fixnum]
       def width(value)
         attributes[:width] = value
       end
+
     end
   end
 end