vedeu 0.2.12 → 0.3.0

data/lib/vedeu/dsl/composition.rb

@@ -0,0 +1,72 @@
+module Vedeu
+
+  module DSL
+
+    # DSL for creating collections of interfaces.
+    #
+    class Composition
+
+      include Vedeu::DSL
+
+      # Returns an instance of DSL::Composition.
+      #
+      # @param model [Composition]
+      def initialize(model, client = nil)
+        @model  = model
+        @client = client
+      end
+
+      # Define a view.
+      #
+      # A view is just an Interface object.
+      #
+      # @todo More documentation required.
+      # @param name [String] The name of the interface you are targetting for
+      #   this view.
+      # @param block [Proc] The directives you wish to send to this interface.
+      #
+      # @example
+      #   view 'my_interface' do
+      #     ...
+      #
+      # @raise [InvalidSyntax] The required block was not given.
+      # @return [Vedeu::Model::Collection<Vedeu::Interface>]
+      def view(name = '', &block)
+        fail InvalidSyntax, 'block not given' unless block_given?
+
+        child_model = if Vedeu.interfaces.registered?(name)
+          interface = Vedeu.interfaces.find(name)
+          child.build(attributes.merge(interface.attributes), &block)
+
+        else
+          child.build(attributes.merge({ name: name }), &block)
+
+        end
+
+        model.add(child_model)
+      end
+
+      private
+
+      attr_reader :client, :model
+
+      # @return [Hash]
+      def attributes
+        {
+          client: client,
+          parent: model,
+        }
+      end
+
+      # Return the class name for the children on this model.
+      #
+      # @return [Class]
+      def child
+        Vedeu::Interface
+      end
+
+    end # Composition
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/interface.rb

@@ -0,0 +1,210 @@
+require 'vedeu/support/common'
+
+module Vedeu
+
+  module DSL
+
+    # DSL for creating interfaces.
+    class Interface
+
+      include Vedeu::Common
+      include Vedeu::DSL
+      include Vedeu::DSL::Colour
+      include Vedeu::DSL::Style
+      include Vedeu::DSL::Text
+      include Vedeu::DSL::Use
+
+      # Returns an instance of Vedeu::DSL::Interface.
+      #
+      # @param model [Vedeu::DSL::Interface]
+      # @param client [Object]
+      # @return [Vedeu::DSL::Interface]
+      def initialize(model, client = nil)
+        @model  = model
+        @client = client
+      end
+
+      # Allows the setting of a border for the interface.
+      #
+      # @param block [Proc]
+      # @raise [InvalidSyntax] The required block was not given.
+      # @return [Hash]
+      def border(&block)
+        fail InvalidSyntax, 'block not given' unless block_given?
+
+        border_attrs = attributes.merge({ enabled: true, interface: model })
+
+        model.border = Vedeu::Border.build(border_attrs, &block)
+      end
+
+      # Set the cursor visibility on an interface.
+      #
+      # @param value [Boolean] Any value other than nil or false will evaluate
+      #   to true.
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     cursor  true  # => show the cursor for this interface
+      #     cursor  :show # => both of these are equivalent to line above
+      #     cursor!       #
+      #     # ...
+      #
+      #     cursor false # => hide the cursor for this interface
+      #     cursor :hide # => both of these are equivalent to line above
+      #     cursor nil   #
+      #     # ...
+      #
+      #   view 'my_interface' do
+      #     cursor true
+      #     # ...
+      #
+      # @return [Cursor]
+      def cursor(value = true)
+        Vedeu::Cursor.new({ name: model.name, state: value }).store
+      end
+
+      def cursor!
+        cursor(true)
+      end
+
+      # To maintain performance interfaces can be delayed from refreshing too
+      # often, the reduces artefacts particularly when resizing the terminal
+      # screen.
+      #
+      # @param value [Fixnum|Float]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     delay 0.5 # interface will not update more often than every 500ms.
+      #     # ...
+      #
+      # @return [Fixnum|Float]
+      def delay(value)
+        model.delay = value
+      end
+
+      # Specify this interface as being in focus when the application starts.
+      #
+      # @note If multiple interfaces are defined, and this is included in each,
+      #   then the last defined will be the interface in focus.
+      #
+      # @return [String] The name of the interface in focus.
+      def focus!
+        Vedeu::Focus.add(model.name, true) if defined_value?(model.name)
+      end
+
+      # Define the geometry for an interface.
+      #
+      # @param block [Proc]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     geometry do
+      #       # ...
+      #
+      # @raise [InvalidSyntax] The required block was not given.
+      # @return [Geometry]
+      # @see Vedeu::DSL::Geometry
+      def geometry(&block)
+        fail InvalidSyntax, 'block not given' unless block_given?
+
+        model.geometry = Vedeu::Geometry.build(attributes, &block)
+      end
+
+      # Specify 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] The name for the group of interfaces.
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     group 'main_screen'
+      #     # ...
+      #
+      # @return [String]
+      def group(value)
+        if defined_value?(model.name)
+          if Vedeu.groups.registered?(value)
+            Vedeu.groups.find(value).add(model.name)
+
+          else
+            Vedeu::Group.new(value, model.name).store
+
+          end
+        end
+
+        model.group = value
+      end
+
+      # @see Vedeu::Keymap.keymap
+      def keymap(name = model.name, &block)
+        Vedeu.keymap(name, &block)
+      end
+      alias_method :keys, :keymap
+
+      # Specify multiple lines in a view.
+      #
+      # @param block [Proc]
+      #
+      # @example
+      #   view 'my_interface' do
+      #     lines do
+      #       # ... see {Vedeu::DSL::Line} and {Vedeu::DSL::Stream}
+      #     end
+      #   end
+      #
+      #   view 'my_interface' do
+      #     line do
+      #       # ... see {Vedeu::DSL::Line} and {Vedeu::DSL::Stream}
+      #     end
+      #   end
+      #
+      # @raise [InvalidSyntax] The required block was not given.
+      # @return [Line]
+      def lines(&block)
+        fail InvalidSyntax, 'block not given' unless block_given?
+
+        model.add(child.build(attributes, &block))
+      end
+      alias_method :line, :lines
+
+      # The name of the interface. Used to reference the interface throughout
+      # your application's execution lifetime.
+      #
+      # @param value [String]
+      #
+      # @example
+      #   interface do
+      #     name 'my_interface'
+      #     # ...
+      #
+      # @return [String]
+      def name(value)
+        model.name = value
+      end
+
+      private
+
+      attr_reader :client, :model
+
+      # @return [Hash]
+      def attributes
+        {
+          client: client,
+          parent: model,
+        }
+      end
+
+      # Return the class name for the children on this model.
+      #
+      # @return [Class]
+      def child
+        Vedeu::Line
+      end
+
+    end # Interface
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/line.rb

@@ -0,0 +1,135 @@
+require 'vedeu/dsl/shared/all'
+require 'vedeu/support/common'
+
+module Vedeu
+
+  module DSL
+
+    # Provides methods to be used to define views.
+    #
+    # @example
+    #   Vedeu.renders do
+    #     view 'my_interface' do
+    #       lines do
+    #         background '#000000'
+    #         foreground '#ffffff'
+    #         line 'This is white text on a black background.'
+    #         line 'Next is a blank line:'
+    #         line ''
+    #
+    #         streams { stream 'We can define ' }
+    #
+    #         streams do
+    #           foreground '#ff0000'
+    #           stream 'parts of a line '
+    #         end
+    #
+    #         streams { stream 'independently using ' }
+    #
+    #         streams do
+    #           foreground '#00ff00'
+    #           stream 'streams.'
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # @api public
+    class Line
+
+      include Vedeu::Common
+      include Vedeu::DSL
+      include Vedeu::DSL::Colour
+      include Vedeu::DSL::Style
+      include Vedeu::DSL::Text
+
+      # Returns an instance of DSL::Line.
+      #
+      # @param model [Vedeu::Line]
+      def initialize(model, client = nil)
+        @model  = model
+        @client = client
+      end
+
+      # Specify a single line in a view.
+      #
+      # @example
+      #   Vedeu.renders do
+      #     view 'my_interface' do
+      #       line 'some text...'
+      #       # ...
+      #
+      #       line do
+      #         # ...
+      #
+      # @return [Vedeu::Line]
+      def line(value = '', &block)
+        content = if block_given?
+          Vedeu::Line.build({ client: client,
+                              parent: model.parent }, &block)
+
+        elsif value
+          stream = Vedeu::Stream.build({ client: client,
+                                         parent: model,
+                                         value: value })
+          Vedeu::Line.build({ client:  client,
+                              parent:  model.parent,
+                              streams: [stream] })
+
+        else
+          fail InvalidSyntax, 'block not given'
+
+        end
+
+        model.parent.add(content)
+      end
+
+      # Define multiple streams (a stream is a subset of a line).
+      # Uses {Vedeu::DSL::Stream} for all directives within the required block.
+      #
+      # @param block [Proc]
+      #
+      # @example
+      #   Vedeu.renders do
+      #     view 'my_interface' do
+      #       line do
+      #         streams do
+      #           # ...
+      #
+      #         stream do
+      #           # ...
+      #
+      # @raise [InvalidSyntax] The required block was not given.
+      # @return [Vedeu::Streams<Vedeu::Stream>]
+      # @see Vedeu::DSL::Stream for subdirectives.
+      def streams(&block)
+        fail InvalidSyntax, 'block not given' unless block_given?
+
+        model.add(child.build(attributes, &block))
+      end
+      alias_method :stream, :streams
+
+      private
+
+      attr_reader :client, :model
+
+      # @return [Hash]
+      def attributes
+        {
+          client: client,
+          parent: model,
+        }
+      end
+
+      # Return the class name for the children on this model.
+      #
+      # @return [Class]
+      def child
+        Vedeu::Stream
+      end
+
+    end # Line
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/shared/all.rb

@@ -0,0 +1,7 @@
+require 'vedeu/dsl/shared/text'
+require 'vedeu/dsl/shared/colour'
+require 'vedeu/dsl/shared/style'
+require 'vedeu/dsl/shared/use'
+
+module Vedeu
+end # Vedeu

data/lib/vedeu/dsl/shared/colour.rb

@@ -0,0 +1,85 @@
+module Vedeu
+
+  module DSL
+
+    # Provides colour helpers for use in the {Vedeu::DSL::Interface},
+    # {Vedeu::DSL::Line} and {Vedeu::DSL::Stream} classes.
+    #
+    # @api public
+    module Colour
+
+      # Define the background colour for an interface, line, or a stream. When
+      # called with a block, will create a new stream with the background colour
+      # specified. When the block terminates, the background will return to that
+      # of the parent.
+      #
+      # @note The last defined background colour for a particular interface,
+      #   line or stream overrides previously defined entries in the same block.
+      #
+      # @param value [String]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     background '#0022ff' # /or/ (blue)
+      #     bgcolor    '#22ff00' # /or/ (blue is overridden to green)
+      #     bg         '#ff0022' #      (green is overridden to red)
+      #     # ...
+      #
+      #     lines do
+      #       background '#2200ff'
+      #       # ...
+      #
+      #       stream do
+      #         background '#22ff00'
+      #         # ...
+      #
+      # @return [String]
+      def background(value = '')
+        colour({ background: value })
+      end
+      alias_method :bg,      :background
+      alias_method :bgcolor, :background
+
+      # @see Vedeu::DSL::Colour#background
+      def foreground(value = '')
+        colour({ foreground: value })
+      end
+      alias_method :fg,      :foreground
+      alias_method :fgcolor, :foreground
+
+      # Define either or both foreground and background colours for an
+      # interface, line or a stream. At least one attribute is required.
+      #
+      # @note Rejects invalid keys and empty/nil attributes. Also, the last
+      #   defined colour for a particular interface, line or stream overrides
+      #   previously defined entries in the same block.
+      #
+      # @param attributes [Hash] See {Vedeu::Colour}
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     colour background: '#ff00ff', foreground: '#ffff00'
+      #     # ...
+      #
+      #     lines do
+      #       colour background: '#000000', foreground: '#ffffff'
+      #       # ...
+      #
+      #       stream do
+      #         colour background: '#000000', foreground: '#ffffff'
+      #         # ...
+      #
+      # @return [Hash]
+      def colour(attributes = {})
+        attributes.delete_if do |k, v|
+          [:background, :foreground].include?(k) == false || v.nil? || v.empty?
+        end
+
+        model.colour = Vedeu::Colour.new(attributes)
+      end
+
+    end # Colour
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/shared/style.rb

@@ -0,0 +1,38 @@
+module Vedeu
+
+  module DSL
+
+    # Provides a style helper for use in the {DSL::Interface}, {DSL::Line} and
+    # {DSL::Stream} classes.
+    #
+    # @api public
+    module Style
+
+      # Define a style or styles for an interface, line or a stream.
+      #
+      # @param value [Array|Symbol|String]
+      #
+      # @example
+      #   interface 'my_interface' do
+      #     style 'normal'
+      #     ...
+      #
+      #   lines do
+      #     style ['bold', 'underline']
+      #     ...
+      #
+      #   stream do
+      #     style 'blink'
+      #     ...
+      #
+      # @return [Vedeu::Style]
+      def style(value)
+        model.style = Vedeu::Style.coerce(value)
+      end
+      alias_method :styles, :style
+
+    end # Style
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/shared/text.rb

@@ -0,0 +1,102 @@
+require 'vedeu/support/text'
+
+module Vedeu
+
+  module DSL
+
+    module Text
+
+      # Specify the content for a view. Provides the means to align a string
+      # (or object responding to `to_s`), and add it as a Line or to the Stream.
+      #
+      # @note If using the convenience methods; {left}, {centre}, {center} or
+      #   {right}, then a specified anchor will be ignored.
+      #
+      # @example
+      #   lines do
+      #     centre '...'
+      #
+      #   line do
+      #     right '...'
+      #
+      #   left 'This will be left aligned.', width: 35
+      #   # => 'This will be left aligned.         '
+      #
+      #   centre 'This will be aligned centrally.', width: 35
+      #   # => '  This will be aligned centrally.  '
+      #   # centre is also aliased to center
+      #
+      #   right 'This will be right aligned.', width: 35
+      #   # => '        This will be right aligned.'
+
+      #   right 'This will be right aligned.', width: 35, anchor: centre
+      #   # => '        This will be right aligned.'
+      #
+      #   text 'This will be truncated here. More text here.', width: 28
+      #   # => 'This will be truncated here.'
+      #
+      #   text 'Padded with hyphens.', width: 25, pad: '-', anchor: :right
+      #   # => '-----Padded with hyphens.'
+      #
+      # @param value [String|Object] A string or object that responds to `to_s`.
+      # @param options [Hash] Text options.
+      # @option options :anchor [Symbol] One of `:left`, `:centre`/`:center`, or
+      #   `:right`.
+      # @option options :width [Integer|NilClass] The width of the text stream
+      #   to add. If the `string` provided is longer than this value, the string
+      #   will be truncated. If no width is provided in the context of 'lines',
+      #   then the interface width is used. If no width is provided in the
+      #   context of a 'stream', then no alignment will occur.
+      # @option options :pad [String] The character to use to pad the width, by
+      #   default uses an empty space (0x20). Only when the string is shorter
+      #   than the specified width.
+      # @return [String]
+      def text(value = '', options = {})
+        output = Vedeu::Text.with(value, options.merge({ anchor: __callee__ }))
+
+        content = if model.is_a?(Vedeu::Interface)
+          stream = stream_builder({ value: output })
+          Vedeu::Line.build({ streams: [stream], parent: model })
+
+        elsif model.is_a?(Vedeu::Line)
+          stream_builder({ value: output })
+
+        elsif model.is_a?(Vedeu::Stream)
+          stream_builder({ value: output, parent: model.parent })
+
+        else
+          # should never get here
+
+        end
+
+        model.add(content)
+      end
+      alias_method :align,  :text
+      alias_method :center, :text
+      alias_method :centre, :text
+      alias_method :left,   :text
+      alias_method :right,  :text
+
+      private
+
+      # @param attrs [Hash]
+      # @return [Vedeu::Stream]
+      def stream_builder(attrs)
+        Vedeu::Stream.build(stream_attributes(attrs))
+      end
+
+      # @param attrs [Hash]
+      # @return [Hash]
+      def stream_attributes(attrs)
+        {
+          colour: model.colour,
+          parent: model,
+          style:  model.style,
+        }.merge(attrs)
+      end
+
+    end # Text
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/shared/use.rb

@@ -0,0 +1,47 @@
+module Vedeu
+
+  module DSL
+
+    module Use
+
+      extend self
+
+      # Use the specified interface; useful for sharing attributes with other
+      # interfaces. Any public method of {Vedeu::Interface} is available.
+      #
+      # @example
+      #   Vedeu.interface 'my_interface' do
+      #     # use the delay of another interface
+      #     delay Vedeu.use('my_other_interface').delay
+      #     # ...
+      #   end
+      #
+      #   Vedeu.interface 'my_interface' do
+      #     geometry do
+      #       # use the width of another interface
+      #       width Vedeu.use('my_other_interface').width
+      #       # ...
+      #     end
+      #   end
+      #
+      #   Vedeu.use('my_other_interface').width # can be used in your code to
+      #                                         # get this value
+      #
+      # @param value [String] The name of the interface you wish to use.
+      #   Typically used when defining interfaces to share geometry.
+      # @return [Vedeu::Interface]
+      def use(value)
+        if Vedeu.interfaces.registered?(value) == false
+          fail ModelNotFound, "The properties of this interface (#{value}) " \
+                              "cannot be used, since the interface has not " \
+                              "been defined."
+        end
+
+        Vedeu.interfaces.find(value)
+      end
+
+    end # Use
+
+  end # DSL
+
+end # Vedeu