vedeu 0.2.12 → 0.3.0

data/lib/vedeu/api/interface.rb

@@ -1,287 +0,0 @@
-module Vedeu
-
-  module API
-
-    # Provides methods to be used to define interfaces or views.
-    #
-    # @api public
-    class Interface < Vedeu::Interface
-
-      include Helpers
-
-      # Allows the setting of a border for the interface. Via the `values`
-      # parameter, the various characters for the borders sides and corners can
-      # be set, a custom foreground and background, a custom style, and whether
-      # a particular side should be drawn or not. See {Border#initialize} for
-      # more details.
-      #
-      # @return [Hash]
-      def border(values = {})
-        auto_enable = { enabled: true }
-        attributes[:border] = auto_enable.merge(values)
-      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] Any value other than nil or false will evaluate
-      #   to true.
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     centred!
-      #
-      #   interface 'my_interface' do
-      #     centred false
-      #     ...
-      #
-      # @return [Boolean]
-      def centred(value = true)
-        attributes[:geometry][:centred] = !!(value)
-      end
-      alias_method :centred!, :centred
-
-      # 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
-      #     ...
-      #
-      #   view 'my_interface' do
-      #     cursor true
-      #     ...
-      #
-      # @return [Symbol]
-      def cursor(value = true)
-        attributes[:cursor] = if !!value
-          :show
-
-        else
-          :hide
-
-        end
-      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)
-        attributes[:delay] = value
-      end
-
-      # Specify this interface as being in focus when the application starts.
-      # 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!
-        attributes[:focus] = true
-      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]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     group 'main_screen'
-      #     ...
-      #
-      # @return [String]
-      def group(value)
-        attributes[:group] = value
-      end
-
-      # Specify the number of characters/rows/lines tall the interface will be.
-      #
-      # @param value [Fixnum]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     height 8
-      #     ...
-      #
-      # @return [Fixnum]
-      def height(value)
-        Vedeu.log(out_of_bounds('height')) if y_out_of_bounds?(value)
-
-        attributes[:geometry][:height] = value
-      end
-
-      # @see Vedeu::API#keys
-      def keys(&block)
-        Keymap.keys(attributes[:name], &block)
-      end
-
-      # Specify a single line in a view.
-      #
-      # @param value [String]
-      # @param block [Proc]
-      #
-      # @example
-      #   view 'my_interface' do
-      #     line 'This is a line of text...'
-      #     line 'and so is this...'
-      #     ...
-      #
-      #   view 'my_interface' do
-      #     line do
-      #       ... see {API::Line} and {API::Stream}
-      #     end
-      #   end
-      #
-      # @return [API::Line]
-      def line(value = '', &block)
-        if block_given?
-          attributes[:lines] << API::Line
-            .build({ parent: self.view_attributes }, &block)
-
-        else
-          attributes[:lines] << API::Line
-            .build({ streams: { text: value }, parent: self.view_attributes })
-
-        end
-      end
-
-      # 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)
-        attributes[:name] = value
-      end
-
-      # Use the specified interface; useful for sharing attributes with other
-      # interfaces. Any public method of #{Vedeu::Interface} is available.
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     use('my_other_interface').width # use the width of another interface
-      #     ...
-      #
-      #   Vedeu.use('my_other_interface').width # can be used in your code to
-      #                                         # get this value
-      #
-      # @param value [String]
-      # @see Vedeu::API#use
-      def use(value)
-        Vedeu.use(value)
-      end
-
-      # Specify the number of characters/columns wide the interface will be.
-      #
-      # @param value [Fixnum]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     width 25
-      #     ...
-      #
-      # @return [Fixnum]
-      def width(value)
-        Vedeu.log(out_of_bounds('width')) if x_out_of_bounds?(value)
-
-        attributes[:geometry][:width] = value
-      end
-
-      # Specify 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 [Fixnum]
-      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
-
-      # Specify 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 [Fixnum]
-      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
-
-      private
-
-      # Returns the out of bounds error message for the given named attribute.
-      #
-      # @param name [String]
-      # @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
-
-      # Checks the value is within the terminal's confines.
-      #
-      # @param value [Fixnum]
-      # @return [Boolean]
-      def y_out_of_bounds?(value)
-        value < 1 || value > Terminal.height
-      end
-
-      # Checks the value is within the terminal's confines.
-      #
-      # @param value [Fixnum]
-      # @return [Boolean]
-      def x_out_of_bounds?(value)
-        value < 1 || value > Terminal.width
-      end
-
-    end # Interface
-
-  end # API
-
-end # Vedeu

data/lib/vedeu/api/keymap.rb

@@ -1,75 +0,0 @@
-module Vedeu
-
-  module API
-
-    # Provides methods to be used to define keypress mapped to actions.
-    #
-    # @api public
-    class Keymap < Vedeu::Keymap
-
-      # Define keypress(es) to perform an action.
-      #
-      # @param value_or_values [String|Symbol] The key(s) pressed. Special keys
-      #   can be found in {Vedeu::Input#specials}. When more than one key is
-      #   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.
-      #
-      # @example
-      #   keys do
-      #     key('s')        { trigger(:save) }
-      #     key('h', :left) { trigger(:left) }
-      #     key('j', :down) { trigger(:down) }
-      #     ...
-      #
-      # @raise [InvalidSyntax] When the required block is not given, the
-      #   value_or_values parameter is undefined, or when processing the
-      #   collection, a member is undefined.
-      # @return [Array] A collection containing the keypress(es).
-      def key(*value_or_values, &block)
-        fail InvalidSyntax,
-          'No action defined for `key`.' unless block_given?
-        fail InvalidSyntax, 'No keypress(es) defined for `key`.' unless
-          defined_value?(value_or_values)
-
-        value_or_values.each do |value|
-          fail InvalidSyntax,
-            'An invalid value for `key` was encountered.' unless
-              defined_value?(value)
-
-          attributes[:keys] << { key: value, action: block }
-        end
-      end
-
-      # The interface(s) which will handle these keys.
-      #
-      # @param name_or_names [String] The name or names of the interface(s)
-      # which will handle these keys.
-      #
-      # @example
-      #   keys do
-      #     interface 'my_interface'
-      #     key('s')  { :something }
-      #     name      'my_keymap'
-      #     ...
-      #
-      #   keys do
-      #     interface('main', 'other')
-      #     key('s')  { :something }
-      #     ...
-      #
-      #   keys do
-      #     interfaces('main', 'other')
-      #     ...
-      #
-      # @return [Array]
-      def interface(*name_or_names)
-        attributes[:interfaces] = name_or_names
-      end
-      alias_method :interfaces, :interface
-
-    end # Keymap
-
-  end # API
-
-end # Vedeu

data/lib/vedeu/api/line.rb

@@ -1,107 +0,0 @@
-module Vedeu
-
-  module API
-
-    # Provides methods to be used to define views.
-    #
-    # @example
-    #   line do
-    #
-    #     background '#ffffff'
-    #
-    #     colour     background: '#222222', foreground: '#ff0000'
-    #
-    #     foreground '#000000'
-    #
-    #     stream do
-    #       # see {API::Stream} for directives
-    #     end
-    #
-    #     style 'normal' # or a collection: ['bold', 'underline']
-    #
-    #     text 'Some text...'
-    #
-    #
-    # @api public
-    class Line < Vedeu::Line
-
-      include Helpers
-
-      # @param value [String]
-      # @param block [Proc]
-      #
-      # @example
-      #   ...
-      #     line do
-      #       background '#0022ff' do
-      #         ... other stream directives ...
-      #
-      # @return [Array]
-      def background(value = '', &block)
-        stream = API::Stream.build({ colour: { background: value },
-                                     parent: self.view_attributes }, &block)
-
-        attributes[:streams] << stream
-      end
-
-      # @param value [String]
-      # @param block [Proc]
-      #
-      # @example
-      #   ...
-      #     line do
-      #       foreground '#00ff00' do
-      #         ... other stream directives ...
-      #
-      # @return [Array]
-      def foreground(value = '', &block)
-        stream = API::Stream.build({ colour: { foreground: value },
-                                     parent: self.view_attributes }, &block)
-
-        attributes[:streams] << stream
-      end
-
-      # Define a stream (a subset of a line).
-      #
-      # @param block [Proc] Block contains directives relating to API::Stream.
-      #
-      # @example
-      #   ...
-      #     line do
-      #       stream do
-      #         ...
-      #
-      # @raise [InvalidSyntax] When the required block is not given.
-      # @return [Array]
-      def stream(&block)
-        fail InvalidSyntax, '`stream` requires a block.' unless block_given?
-
-        attributes[:streams] << API::Stream
-          .build({ parent: self.view_attributes }, &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 goes here...'
-      #
-      #   ...
-      #     stream do
-      #       text 'Some text goes here...'
-      #
-      # @return [Array]
-      def text(value)
-        attributes[:streams] << { text: value }
-      end
-
-    end # Line
-
-  end # API
-
-end # Vedeu

data/lib/vedeu/api/menu.rb

@@ -1,111 +0,0 @@
-module Vedeu
-
-  module API
-
-    # Provides the mechanism to create menus within client applications and use
-    # events to drive them.
-    #
-    # @api public
-    class Menu
-
-      include Common
-
-      attr_reader :attributes
-
-      # Define a new Menu.
-      #
-      # @param attributes [Hash]
-      # @param block [Proc]
-      # @return [API::Menu]
-      def self.define(attributes = {}, &block)
-        new(attributes).define(&block)
-      end
-
-      # Return a new instance of Menu.
-      #
-      # @param  attributes [Hash]
-      # @return [API::Menu]
-      def initialize(attributes = {})
-        @attributes = defaults.merge(attributes)
-      end
-
-      # @param block [Proc]
-      # @raise [InvalidSyntax] When the required block is not given.
-      # @return [API::Menu]
-      def define(&block)
-        fail InvalidSyntax, '`menu` requires a block.' unless block_given?
-
-        @self_before_instance_eval = eval('self', block.binding)
-
-        instance_eval(&block)
-
-        Vedeu::Menus.add(attributes)
-
-        self
-      end
-
-      # Define the items for the menu. Most powerful when used with one of your
-      # model classes.
-      #
-      # In the 'my_playlist' example below, your `Track` model may return a
-      # collection of tracks to populate the menu.
-      #
-      # @param collection [Array]
-      #
-      # @example
-      #   menu 'my_menu' do
-      #     items [:item_1, :item_2, :item_3]
-      #   end
-      #
-      #   menu 'my_playlist' do
-      #     items Track.all_my_favourites
-      #   end
-      #
-      # @return [Vedeu::Menu]
-      def items(collection = [])
-        attributes[:items] = collection
-      end
-
-      # The name of the menu. Used to reference the menu throughout your
-      # application's execution lifetime.
-      #
-      # @param value [String]
-      #
-      # @example
-      #   menu do
-      #     name 'my_menu'
-      #     ...
-      #
-      # @return [String]
-      def name(value)
-        attributes[:name] = value
-      end
-
-      private
-
-      # The default values for a new instance of Menu.
-      #
-      # @return [Hash]
-      def defaults
-        {
-          name:  '',
-          items: []
-        }
-      end
-
-      # @param method [Symbol] The name of the method sought.
-      # @param args [Array] The arguments which the method was to be invoked
-      #   with.
-      # @param block [Proc] The optional block provided to the method.
-      # @return []
-      def method_missing(method, *args, &block)
-        Vedeu.log("API::Menu#method_missing '#{method}' (args: #{args.inspect})")
-
-        @self_before_instance_eval.send(method, *args, &block) if @self_before_instance_eval
-      end
-
-    end # Menu
-
-  end # API
-
-end # Vedeu

data/lib/vedeu/api/stream.rb

@@ -1,96 +0,0 @@
-module Vedeu
-
-  module API
-
-    # Provides methods to be used to define views.
-    #
-    # @api public
-    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
-      #       ...
-      #
-      # @raise [InvalidSyntax] When the value parameter is not one of +:left+,
-      #   +:right+ or +:centre+.
-      # @return [Symbol]
-      def align(value)
-        unless [:left, :right, :centre].include?(value.to_sym)
-          fail InvalidSyntax, '`align` requires a value of `left`, `right` ' \
-                              'or `centre`.'
-        end
-
-        attributes[:align] = value.to_sym
-      end
-
-      # Syntactic sugar used with {#align} to left align content.
-      #
-      # @return [Symbol]
-      def left
-        :left
-      end
-
-      # Syntactic sugar used with {#align} to right align content.
-      #
-      # @return [Symbol]
-      def right
-        :right
-      end
-
-      # Syntactic sugar used with {#align} to centre align content.
-      #
-      # @return [Symbol]
-      def centre
-        :centre
-      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 # Stream
-
-  end # API
-
-end # Vedeu