vedeu 0.2.12 → 0.3.0

data/lib/vedeu/api/api.rb

@@ -1,239 +0,0 @@
-require 'vedeu/support/terminal'
-
-module Vedeu
-
-  # Provides the API to Vedeu. Methods therein, and classes belonging to this
-  # module expose Vedeu's core functionality.
-  #
-  # @api public
-  module API
-
-    extend Forwardable
-
-    # @see Vedeu::Events#add
-    def_delegators Events,          :event
-    def_delegators Keymap,          :keys
-    def_delegators Keymaps,         :keypress
-    def_delegators Vedeu::Terminal, :height, :width
-
-    # Configure Vedeu using a simple configuration DSL.
-    #
-    # @param block [Proc]
-    # @raise [InvalidSyntax] When the required block is not given.
-    # @return [Hash]
-    # @see Vedeu::Configuration
-    def configure(&block)
-      fail InvalidSyntax, '`configure` requires a block.' unless block_given?
-
-      Vedeu::Configuration.configure(&block)
-    end
-
-    # Returns information about various registered subsystems when used with
-    # a defined method within {Vedeu::API::Defined}.
-    #
-    # @return [Vedeu::API::Defined]
-    # @see Vedeu::API::Defined
-    def defined
-      Vedeu::API::Defined
-    end
-
-    # Used after defining an interface or interfaces to set the initially
-    # focussed interface.
-    #
-    # @param name [String] The interface to focus; must be defined.
-    # @return [String] The name of the interface now in focus.
-    # @raise [ModelNotFound] When the interface cannot be found.
-    def focus(name)
-      Vedeu.trigger(:_focus_by_name_, name)
-    end
-
-
-    # Register an interface by name which will display output from a event or
-    # command. This provides the means for you to define your application's
-    # views without their content.
-    #
-    # @todo More documentation required.
-    # @param name  [String] The name of the interface. Used to reference the
-    #   interface throughout your application's execution lifetime.
-    # @param block [Proc] A set of attributes which define the features of the
-    #   interface.
-    #
-    # @example
-    #   Vedeu.interface 'my_interface' do
-    #     ...
-    #
-    #   Vedeu.interface do
-    #     name 'interfaces_must_have_a_name'
-    #     ...
-    #
-    # @return [TrueClass]
-    def interface(name = '', &block)
-      API::Interface.define({ name: name }, &block)
-    end
-
-    # Register a menu by name which will display a collection of items for your
-    # users to select; and provide interactivity within your application.
-    #
-    # @param name  [String] The name of the menu. Used to reference the
-    #   menu throughout your application's execution lifetime.
-    # @param block [Proc] A set of attributes which define the features of the
-    #   menu. See {Vedeu::API::Menu#items} and {Vedeu::API::Menu#name}.
-    #
-    # @example
-    #   Vedeu.menu 'my_interface' do
-    #     items [:item_1, :item_2, :item_3]
-    #     ...
-    #
-    #   Vedeu.menu do
-    #     name 'menus_must_have_a_name'
-    #     items Track.all_my_favourites
-    #     ...
-    #
-    # @raise [InvalidSyntax] When the required block is not given.
-    # @return [API::Menu]
-    def menu(name = '', &block)
-      fail InvalidSyntax, '`menu` requires a block.' unless block_given?
-
-      API::Menu.define({ name: name }, &block)
-    end
-
-    # Directly write a view buffer to the terminal. Using this method means
-    # that the refresh event does not need to be triggered after creating the
-    # view or views, though can be later triggered if needed.
-    #
-    # @param block [Proc] The directives you wish to send to render. Must
-    #                     include `view` or `views` with associated sub-
-    #                     directives.
-    #
-    # @example
-    #   Vedeu.render do
-    #     views do
-    #       view 'my_interface' do
-    #         ...
-    #
-    #   Vedeu.render do
-    #     view 'my_interface' do
-    #       ...
-    #
-    # @raise [InvalidSyntax] When the required block is not given.
-    # @return [Array] A collection of strings, each defining containing the
-    #   escape sequences and content. This data has already been sent to the
-    #   terminal to be output.
-    def render(&block)
-      API::Composition.render(&block)
-    end
-
-    # When the terminal emit the 'SIGWINCH' signal, Vedeu can intercept this
-    # and attempt to redraw the current interface with varying degrees of
-    # success. Can also be used to simulate a terminal resize.
-    #
-    # @return [TrueClass]
-    def resize
-      trigger(:_clear_)
-
-      trigger(:_refresh_)
-
-      true
-    end
-
-    # Trigger a registered or system event by name with arguments. If the
-    # event stored returns a value, that is returned. If multiple events are
-    # registered for a name, then the result of each event will be returned as
-    # part of a collection.
-    #
-    # @param name [Symbol] The name of the event you wish to trigger. The event
-    #   does not have to exist.
-    # @param args [Array] Any arguments the event needs to execute correctly.
-    #
-    # @example
-    #   Vedeu.trigger(:my_event, :oxidize, 'nitrogen')
-    #
-    # @return [Array|undefined]
-    def trigger(name, *args)
-      Events.use(name, *args)
-    end
-
-    # Unregisters the event by name, effectively deleting the associated events
-    # bound with it also.
-    #
-    # @param name [Symbol]
-    # @return [Hash]
-    def unevent(name)
-      Events.remove(name)
-    end
-
-    # Use attributes of another interface whilst defining one.
-    #
-    # @todo More documentation required.
-    # @param name [String] The name of the interface you wish to use. Typically
-    #   used when defining interfaces to share geometry.
-    #
-    # @example
-    #   Vedeu.interface 'main_screen' do
-    #     width use('my_interface').width
-    #     x     use('my_interface').east(1)
-    #     ...
-    #
-    # @return [Vedeu::Interface]
-    def use(name)
-      Vedeu::Interface.new(Vedeu::Interfaces.find(name))
-    end
-
-    # Define a view (content) for an interface.
-    #
-    # @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
-    #     ...
-    #
-    # @return [Hash]
-    def view(name, &block)
-      API::Composition.build { view(name, &block) }
-    end
-
-    # Instruct Vedeu to treat contents of block as a single composition.
-    #
-    # @note The views declared within this block are stored in their respective
-    #   interface back buffers until a refresh event occurs. When the refresh
-    #   event is triggered, the back buffers are swapped into the front buffers
-    #   and the content here will be rendered to {Terminal.output}.
-    #
-    # @param block [Proc] Instructs Vedeu to treat all of the 'view' directives
-    #   therein as one instruction. Useful for redrawing multiple interfaces at
-    #   once.
-    #
-    # @example
-    #   views do
-    #     view 'my_interface' do
-    #       ... some attributes ...
-    #     end
-    #     view 'my_other_interface' do
-    #       ... some other attributes ...
-    #     end
-    #     ...
-    #
-    #   composition do
-    #     view 'my_interface' do
-    #       ...
-    #   ...
-    #
-    # @raise [InvalidSyntax] When the required block is not given.
-    # @return [Array]
-    def views(&block)
-      fail InvalidSyntax, '`views` requires a block.' unless block_given?
-
-      API::Composition.build(&block)
-    end
-    alias_method :composition, :views
-
-  end # API
-
-  extend API
-
-  trap('SIGWINCH') { Vedeu.trigger(:_resize_) }
-
-end # Vedeu

data/lib/vedeu/api/composition.rb

@@ -1,38 +0,0 @@
-module Vedeu
-
-  module API
-
-    # @see Vedeu::Composition
-    #
-    # @api public
-    class Composition < Vedeu::Composition
-
-      # @param block [Proc]
-      # @return [Array]
-      # @see Vedeu::API#render
-      def self.render(&block)
-        fail InvalidSyntax, '`render` requires a block.' unless block_given?
-
-        attributes = API::Composition.build({}, &block)
-
-        Vedeu::Composition.new(attributes).interfaces.map do |interface|
-          Buffers.add(interface.attributes)
-
-          interface.name
-        end.map { |name| Vedeu::Refresh.by_name(name) }
-      end
-
-      # @param name [String]
-      # @param block [Proc]
-      # @return [Hash]
-      # @see Vedeu::API#view
-      def view(name, &block)
-        attributes[:interfaces] << API::Interface
-          .build({ name: name, parent: self.view_attributes }, &block)
-      end
-
-    end # Composition
-
-  end # API
-
-end # Vedeu

data/lib/vedeu/api/defined.rb

@@ -1,52 +0,0 @@
-module Vedeu
-
-  module API
-
-    # Provides a set of helpful API methods to return information about various
-    # registered subsystems.
-    #
-    # @api public
-    module Defined
-
-      extend self
-
-      # Returns all events currently registered with Vedeu.
-      #
-      # @return [Array]
-      def events
-        Vedeu::Events.registered
-      end
-
-      # Returns all groups currently registered with Vedeu.
-      #
-      # @return [Array]
-      def groups
-        Vedeu::Groups.registered
-      end
-
-      # Returns all interfaces currently registered with Vedeu.
-      #
-      # @return [Array]
-      def interfaces
-        Vedeu::Interfaces.registered
-      end
-
-      # Returns the names of all keymaps currently registered with Vedeu.
-      #
-      # @return [Array]
-      def keymaps
-        Vedeu::Keymaps.registered
-      end
-
-      # Returns all menus currently registered with Vedeu.
-      #
-      # @return [Array]
-      def menus
-        Vedeu::Menus.registered
-      end
-
-    end # Defined
-
-  end # API
-
-end # Vedeu

data/lib/vedeu/api/helpers.rb

@@ -1,161 +0,0 @@
-module Vedeu
-
-  module API
-
-    # Provides colour and style helpers for use in the {API::Interface},
-    # {API::Line} and {API::Stream} classes.
-    #
-    # @api public
-    module Helpers
-
-      include Common
-
-      # 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; see {Vedeu::API::Stream} for directives which are valid
-      # within the block. When the block terminates, the background will return
-      # to that of the parent.
-      #
-      # @param value [String]
-      # @param block [Proc]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     background '#0022ff'
-      #     ...
-      #
-      #   line do
-      #     background '#0022ff'
-      #     ...
-      #
-      #   stream do
-      #     background '#0022ff'
-      #     ...
-      #
-      #   foreground('#0022ff') { 'This will be blue.' }
-      #
-      # @raise [InvalidSyntax] When the value is not defined.
-      # @return [Hash]
-      def background(value = '', &block)
-        unless defined_value?(value)
-          fail InvalidSyntax, '`background` requires a value.'
-        end
-
-        if block_given?
-          attributes[:streams] << API::Stream
-            .build({ colour: { background: value },
-                     parent: self.view_attributes }, &block)
-
-        else
-          attributes[:colour].merge!({ background: value })
-
-        end
-      end
-
-      # 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'
-      #     ...
-      #
-      #   line do
-      #     colour background: '#000000', foreground: '#ffffff'
-      #     ...
-      #
-      #   stream do
-      #     colour background: '#000000', foreground: '#ffffff'
-      #     ...
-      #
-      # @raise [InvalidSyntax] When the values parameter does not contain
-      #   required keys.
-      # @return [Hash]
-      def colour(values)
-        unless values.key?(:foreground) || values.key?(:background)
-          fail InvalidSyntax, '#colour expects a Hash containing ' \
-            ':foreground or :background or both.'
-        end
-
-        attributes[:colour] = values
-      end
-
-      # Define the foreground colour for an interface, line, or a stream. When
-      # called with a block, will create a new stream with the foreground colour
-      # specified; see {Vedeu::API::Stream} for directives which are valid
-      # within the block. When the block terminates, the foreground will return
-      # to that of the parent.
-      #
-      # @param value [String]
-      # @param block [Proc]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     foreground '#0022ff'
-      #     ...
-      #
-      #   line do
-      #     foreground '#0022ff'
-      #     ...
-      #
-      #   stream do
-      #     foreground '#0022ff'
-      #     ...
-      #
-      #   foreground('#0022ff') { 'This will be blue.' }
-      #
-      # @raise [InvalidSyntax] When the value is not defined.
-      # @return [Hash]
-      def foreground(value = '', &block)
-        unless defined_value?(value)
-          fail InvalidSyntax, '`foreground` requires a value.'
-        end
-
-        if block_given?
-          attributes[:streams] << API::Stream
-            .build({ colour: { foreground: value },
-                     parent: self.view_attributes }, &block)
-
-        else
-          attributes[:colour].merge!({ foreground: value })
-
-        end
-      end
-
-      # Define a style or styles for an interface, line or a stream.
-      #
-      # @param values [Array|String]
-      # @param block  [Proc]
-      #
-      # @example
-      #   interface 'my_interface' do
-      #     style 'normal'
-      #     ...
-      #
-      #   line do
-      #     style ['bold', 'underline']
-      #     ...
-      #
-      #   stream do
-      #     style 'blink'
-      #     ...
-      #
-      # @return [Array]
-      def style(values = [], &block)
-        if block_given?
-          attributes[:streams] << API::Stream
-                                    .build({ style: Array(values) }, &block)
-
-        else
-          Array(values).each { |value| attributes[:style] << value }
-
-        end
-      end
-
-    end # Helpers
-
-  end # API
-
-end # Vedeu