vedeu 0.2.12 → 0.3.0

data/lib/vedeu/dsl/stream.rb

@@ -0,0 +1,49 @@
+require 'vedeu/dsl/shared/all'
+require 'vedeu/support/common'
+
+module Vedeu
+
+  module DSL
+
+    # Provides methods to be used to define views.
+    #
+    # @api public
+    class Stream
+
+      include Vedeu::Common
+      include Vedeu::DSL
+      include Vedeu::DSL::Colour
+      include Vedeu::DSL::Style
+      include Vedeu::DSL::Text
+
+      # Returns an instance of DSL::Stream.
+      #
+      # @param model [Vedeu::Stream]
+      def initialize(model, client = nil)
+        @model  = model
+        @client = client
+      end
+
+      def stream(&block)
+        fail InvalidSyntax, 'block not given' unless block_given?
+
+        model.add(model.class.build(attributes, &block))
+      end
+
+      private
+
+      attr_reader :client, :model
+
+      # @return [Hash]
+      def attributes
+        {
+          client: client,
+          parent: model.parent,
+        }
+      end
+
+    end # Stream
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/dsl/view.rb

@@ -0,0 +1,136 @@
+require 'vedeu/models/view/composition'
+
+module Vedeu
+
+  module DSL
+
+    # DSL for creating views.
+    #
+    # @api public
+    class View
+
+      class << self
+
+        # Register an interface by name which will display output from a event
+        # or command. This provides the means for you to define your the views
+        # of your application 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'
+        #     # ...
+        #
+        # @raise [InvalidSyntax] The required block was not given.
+        # @return [Interface]
+        def interface(name = '', &block)
+          fail InvalidSyntax, 'block not given' unless block_given?
+
+          attributes = { client: client(&block), name: name }
+
+          Vedeu::Interface.build(attributes, &block).store
+        end
+
+        # Immediate render
+        #
+        # 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 views, though can be later triggered if needed.
+        #
+        # @param block [Proc] The directives you wish to send to render.
+        #   Typically includes `view` with associated sub-directives.
+        #
+        # @example
+        #   Vedeu.renders do
+        #     view 'my_interface' do
+        #       # ...
+        #
+        # @raise [InvalidSyntax] The required block was not given.
+        # @return [Array<Interface>]
+        def renders(&block)
+          fail InvalidSyntax, 'block not given' unless block_given?
+
+          store(:store_immediate, &block)
+        end
+
+        # Deferred view
+        #
+        # Define a view (content) for an interface.
+        #
+        # @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
+        #   {Vedeu::Terminal.output}.
+        #
+        # @param block [Proc] The directives you wish to send to render. Typically
+        #   includes `view` with associated sub-directives.
+        #
+        # @example
+        #   Vedeu.views do
+        #     view 'my_interface' do
+        #       # ... some attributes ...
+        #     end
+        #     view 'my_other_interface' do
+        #       # ... some other attributes ...
+        #     end
+        #     ...
+        #
+        # @raise [InvalidSyntax] The required block was not given.
+        # @return [Array<Interface>]
+        def views(&block)
+          fail InvalidSyntax, 'block not given' unless block_given?
+
+          store(:store_deferred, &block)
+        end
+
+        private
+
+        # Returns the client object which called the DSL method.
+        #
+        # @param block [Proc]
+        # @return [Object]
+        def client(&block)
+          eval('self', block.binding)
+        end
+
+        # Creates a new Composition which may contain one or more views
+        # (Interface objects).
+        #
+        # @param client [Object]
+        # @param block [Proc]
+        # @return [Vedeu::Composition]
+        def composition(client, &block)
+          Vedeu::Composition.build({ client: client }, &block)
+        end
+
+        # Stores each of the views defined in their respective buffers ready to
+        # be rendered on next refresh.
+        #
+        # @param method [Symbol] An instruction; `:store_immediate` or
+        #   `:store_deferred` which determines whether the view will be shown
+        #   immediately or later respectively.
+        # @param block [Proc]
+        # @return [Array]
+        def store(method, &block)
+          composition(client(&block), &block).interfaces.map do |interface|
+            interface.public_send(method)
+          end
+        end
+
+      end
+
+    end # View
+
+  end # DSL
+
+end # Vedeu

data/lib/vedeu/events/all.rb

@@ -0,0 +1,10 @@
+require 'vedeu/events/event'
+require 'vedeu/events/trigger'
+
+module Vedeu
+
+  def self.events
+    @_events ||= Vedeu::Repository.new(Vedeu::Model::Collection)
+  end
+
+end # Vedeu

data/lib/vedeu/{repositories/models → events}/event.rb

@@ -1,3 +1,7 @@
+require 'vedeu/models/model'
+require 'vedeu/repositories/repository'
+require 'vedeu/events/trigger'
+
 module Vedeu
 
   # Contains all the logic of an event. Handles debouncing and throttling.
@@ -5,7 +9,81 @@ module Vedeu
   # @api private
   class Event
 
-    include Model
+    include Vedeu::Model
+
+    class << self
+
+      # Register an event by name with optional delay (throttling) which when
+      # triggered will execute the code contained within the passed block.
+      #
+      # @param name  [Symbol] The name of the event which will be triggered later.
+      # @param [Hash] options The options to register the event with.
+      # @option options :delay [Fixnum|Float] Limits the execution of the
+      #   triggered event to only execute when first triggered, with subsequent
+      #   triggering being ignored until the delay has expired.
+      # @option options :debounce [Fixnum|Float] Limits the execution of the
+      #   triggered event to only execute once the debounce has expired.
+      #   Subsequent triggers before debounce expiry are ignored.
+      # @param block [Proc] The event to be executed when triggered. This block
+      #   could be a method call, or the triggering of another event, or sequence
+      #   of either/both.
+      #
+      # @example
+      #   Vedeu.bind :my_event do |some, args|
+      #     ... some code here ...
+      #
+      #     Vedeu.trigger(:my_other_event)
+      #   end
+      #
+      #   T = Triggered, X = Executed, i = Ignored.
+      #
+      #   0.0.....0.2.....0.4.....0.6.....0.8.....1.0.....1.2.....1.4.....1.6...
+      #   .T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T
+      #   .X...i...i...i...i...X...i...i...i...i...X...i...i...i...i...i...i...i
+      #
+      #   Vedeu.bind(:my_delayed_event, { delay: 0.5 })
+      #     ... some code here ...
+      #   end
+      #
+      #   T = Triggered, X = Executed, i = Ignored.
+      #
+      #   0.0.....0.2.....0.4.....0.6.....0.8.....1.0.....1.2.....1.4.....1.6...
+      #   .T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T
+      #   .i...i...i...i...i...i...i...X...i...i...i...i...i...i...X...i...i...i
+      #
+      #   Vedeu.bind(:my_debounced_event, { debounce: 0.7 })
+      #     ... some code here ...
+      #   end
+      #
+      # @return [TrueClass]
+      def bind(name, options = {}, &block)
+        Vedeu.log("Binding event: '#{name}'")
+
+        new(name, options, block).bind
+      end
+      alias_method :event, :bind
+      alias_method :register, :bind
+
+      # @see Vedeu::Trigger.trigger
+      def trigger(name, *args)
+        Vedeu::Trigger.trigger(name, *args)
+      end
+
+      # Unbind events from a named handler.
+      #
+      # @param name [String]
+      # @return [Boolean]
+      def unbind(name)
+        return false unless Vedeu.events.registered?(name)
+
+        Vedeu.log("Unbinding event: '#{name}")
+
+        Vedeu.events.remove(name)
+        true
+      end
+      alias_method :unevent, :unbind
+
+    end
 
     # Returns a new instance of Event.
     #
@@ -20,10 +98,26 @@ module Vedeu
       @deadline     = 0
       @executed_at  = 0
       @now          = 0
+      @repository   = Vedeu.events
+    end
+
+    def bind
+      if repository.registered?(name)
+        collection     = repository.find(name)
+        new_collection = collection.add(self)
+
+      else
+        new_collection = Vedeu::Model::Collection.new([self], nil, name)
+
+      end
+
+      repository.store(new_collection)
+
+      true
     end
 
     # Triggers the event based on debouncing and throttling conditions.
-    #
+
     # @param args [Array]
     # @return []
     def trigger(*args)
@@ -39,11 +133,6 @@ module Vedeu
     attr_reader   :closure, :name
     attr_accessor :deadline, :executed_at, :now
 
-    # @return [Class] The repository class for this model.
-    def repository
-      Vedeu::Events
-    end
-
     # Execute the code stored in the event closure.
     #
     # @param args []
@@ -162,7 +251,7 @@ module Vedeu
       defaults.merge(@options)
     end
 
-    # The default values for a new instance of Event.
+    # The default values for a new instance of this class.
     #
     # @return [Hash]
     def defaults

data/lib/vedeu/events/trigger.rb

@@ -0,0 +1,58 @@
+module Vedeu
+
+  # 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.
+  #
+  # @example
+  #   Vedeu.trigger(:my_event, :oxidize, 'nitrogen')
+  #
+  # @api private
+  class Trigger
+
+    class << self
+
+      # @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.
+      # @return [Array]
+      def trigger(name, *args)
+        new(name, *args).trigger
+      end
+
+    end
+
+    # @see Vedeu::Trigger.trigger
+    # @return [Trigger]
+    def initialize(name, *args)
+      @name = name
+      @args = args
+      @repository = Vedeu.events
+    end
+
+    # @see Vedeu::Trigger.trigger
+    # @return [Array]
+    def trigger
+      return [] unless repository.registered?(name)
+
+      collection = repository.find(name)
+
+      results = collection.map do |event|
+        event.trigger(*args)
+      end
+
+      return results.first if results.one?
+
+      results
+    end
+
+    private
+
+    attr_reader :name,
+      :args,
+      :repository
+
+  end # Trigger
+
+end # Vedeu

data/lib/vedeu/exceptions.rb

@@ -0,0 +1,34 @@
+module Vedeu
+
+  # ModelNotFound: Raised with Vedeu attempts to access a named model that does
+  #   not exist.
+  #
+  # InvalidSyntax: Raised when Vedeu attempts to parse a {Vedeu.view} or
+  #   {Vedeu.interface} and encounters a problem.
+  #
+  # MissingRequired: Raised when a name is not provided for a model when
+  #   attempting to store it in a repository.
+  #
+  # ModeSwitch: Raised intentionally when the client application wishes to
+  #   switch between cooked and raw (or vice versa) terminal modes. Vedeu is
+  #   hard-wired to use the `Escape` key to trigger this change for the time
+  #   being.
+  #
+  # NotImplemented: Raised to remind me (or client application developers) that
+  #   the subclass implements the functionality sought.
+  #
+  # OutOfRange: Raised when trying to access an interface column less than 1 or
+  #   greater than 12. Vedeu is hard-wired to a 12-column layout for the time
+  #   being.
+
+  Exceptions = %w[
+    ModelNotFound
+    InvalidSyntax
+    MissingRequired
+    ModeSwitch
+    NotImplemented
+    OutOfRange
+  ]
+  Exceptions.each { |e| const_set(e, Class.new(StandardError)) }
+
+end # Vedeu

data/lib/vedeu/input/all.rb

@@ -0,0 +1,29 @@
+require 'vedeu/repositories/repository'
+require 'vedeu/input/mapper'
+require 'vedeu/input/keys'
+require 'vedeu/input/key'
+require 'vedeu/input/input'
+require 'vedeu/input/keymap'
+
+module Vedeu
+
+  extend self
+
+  def keymaps
+    @_keymaps ||= Vedeu::Repository.new(Vedeu::Keymap)
+  end
+
+  def_delegators Vedeu::Keymap, :keymap
+  def_delegators Vedeu::Keymap, :keypress
+
+  Vedeu.keymap('_system_') do |keymap|
+    Vedeu::Configuration.system_keys.each do |label, keypress|
+      keymap.key(keypress) { Vedeu.trigger(("_" + label.to_s + "_").to_sym) }
+    end
+  end
+
+  Vedeu.keymap('_global_') do
+
+  end
+
+end # Vedeu

data/lib/vedeu/input/input.rb

@@ -87,6 +87,32 @@ module Vedeu
         "\e[1;2Q" => :scroll_lock,
         "\e[1;2R" => :pause_break,
         "\u007F"  => :backspace,
+        "\u0001"  => :ctrl_a,
+        "\u0002"  => :ctrl_b,
+        "\u0003"  => :ctrl_c,
+        "\u0004"  => :ctrl_d,
+        "\u0005"  => :ctrl_e,
+        "\u0006"  => :ctrl_f,
+        "\u0007"  => :ctrl_g,
+        "\u0008"  => :ctrl_h,
+        # "\u0009"  => :ctrl_i, # duplicates tab
+        "\u0010"  => :ctrl_j,
+        "\u0011"  => :ctrl_k,
+        "\u0012"  => :ctrl_l,
+        "\u0013"  => :ctrl_m,
+        "\u0014"  => :ctrl_n,
+        "\u0015"  => :ctrl_o,
+        "\u0016"  => :ctrl_p,
+        "\u0017"  => :ctrl_q,
+        "\u0018"  => :ctrl_r,
+        "\u0019"  => :ctrl_s,
+        # "\u0020"  => :ctrl_t, # duplicates spacebar
+        "\u0021"  => :ctrl_u,
+        "\u0022"  => :ctrl_v,
+        "\u0023"  => :ctrl_w,
+        "\u0024"  => :ctrl_x,
+        "\u0025"  => :ctrl_y,
+        "\u0026"  => :ctrl_z,
       }
     end
 

data/lib/vedeu/{models → input}/key.rb

@@ -1,16 +1,30 @@
 module Vedeu
 
+  #
   # A single keypress or combination of keypresses bound to a specific action.
+  #
   class Key
 
+    # Creates a new instance of Key.
+    #
+    # @see Vedeu::Key#initialize
+    def self.define(input = nil, &block)
+      fail InvalidSyntax, 'block not given' unless block_given?
+
+      new(input, &block)
+    end
+
     # Returns a new instance of Key.
     #
     # @param input [String|Symbol]
-    # @param output [Proc]
+    # @param block [Proc]
+    # @raise [InvalidSyntax] The required block was not given.
     # @return [Key]
-    def initialize(input, output)
+    def initialize(input = nil, &block)
+      fail InvalidSyntax, 'block not given' unless block_given?
+
       @input  = input
-      @output = output
+      @output = block
     end
 
     # Returns the key defined.
@@ -21,18 +35,14 @@ module Vedeu
     end
     alias_method :key, :input
 
-    # The procedure to call when the key is pressed.
-    def output
-      @output
-    end
-    alias_method :action, :output
-
     # Pressing the key will call the procedure.
     #
     # @return [|Symbol]
-    def press
-      output.is_a?(Proc) ? output.call : :noop
+    def output
+      @output.call
     end
+    alias_method :action, :output
+    alias_method :press, :output
 
   end # Key
 

data/lib/vedeu/input/keymap.rb

@@ -0,0 +1,130 @@
+require 'vedeu/exceptions'
+require 'vedeu/support/common'
+require 'vedeu/models/model'
+require 'vedeu/dsl/components/keymap'
+
+module Vedeu
+
+  class Keymap
+
+    include Vedeu::Common
+    include Vedeu::Model
+
+    attr_accessor :name
+    attr_reader   :keys, :repository
+
+    class << self
+
+
+      # @option attributes client []
+      # @option attributes keys []
+      # @option attributes name []
+      # @option attributes repository []
+      def build(attributes = {}, &block)
+        fail InvalidSyntax, 'block not given' unless block_given?
+
+        attributes = defaults.merge(attributes)
+
+        model = new(attributes[:name],
+                    attributes[:keys],
+                    attributes[:repository])
+        model.deputy(attributes[:client]).instance_eval(&block)
+        model.store
+      end
+
+      # Define actions for keypresses for when specific interfaces are in focus.
+      # Unless an interface is specified, the key will be assumed to be global,
+      # meaning its action will happen regardless of the interface in focus.
+      #
+      # @note
+      #   When defining an interface, there is no need to provide a name since
+      #   this can be discerned from the interface itself, e.g:
+      #
+      #   Vedeu.interface 'my_interface' do
+      #     keymap do
+      #       ...
+      #
+      # @param name [String] The name of the interface which this keymap relates
+      #   to.
+      # @param block [Proc]
+      #
+      # @example
+      #   keymap 'my_interface' do
+      #     ...
+      #
+      # @raise [InvalidSyntax] The required block was not given.
+      # @return [Keymap]
+      def keymap(name, &block)
+        new(name).store
+
+        build({ name: name }, &block)
+      end
+
+      private
+
+      # The default values for a new instance of this class.
+      #
+      # @return [Hash]
+      def defaults
+        {
+          client:     nil,
+          keys:       [],
+          name:       '',
+          repository: Vedeu.keymaps,
+        }
+      end
+
+    end
+
+    # @param name [String] The name of the keymap.
+    # @param keys [Vedeu::Model::Collection|Array] A collection of keys.
+    # @return [Vedeu::Keymap]
+    def initialize(name = '', keys = [], repository = nil)
+      @name       = name
+      @keys       = Vedeu::Model::Collection.coerce(keys)
+      @repository = repository || Vedeu.keymaps
+    end
+
+    # @param key [Key]
+    def add(key)
+      return false unless valid?(key)
+
+      @keys << key
+
+      # immutable Keymap version:
+      # self.new(name, @keys += [key]).store if valid?(key)
+    end
+
+    # @param input [String|Symbol]
+    # @return [Boolean] A boolean indicating the input provided is already in
+    #   use for this keymap.
+    def key_defined?(input)
+      keys.any? { |key| key.input == input }
+    end
+
+    # @param input [String|Symbol]
+    # @return [Array|FalseClass]
+    def use(input)
+      return false unless key_defined?(input)
+
+      Vedeu.log("Key pressed: '#{input}'")
+
+      Vedeu.trigger(:key, input)
+
+      keys.select { |key| key.input == input }.map(&:press)
+    end
+
+    private
+
+    # @param key [Vedeu::Key]
+    def valid?(key)
+      return true unless key_defined?(key.input)
+
+      Vedeu.log("Keymap '#{name}' already defines '#{key.input}'.")
+
+      false
+    end
+
+  end # Keymap
+
+end # Vedeu

data/lib/vedeu/input/keys.rb

@@ -0,0 +1,8 @@
+require 'vedeu/models/collection'
+
+module Vedeu
+
+  class Keys < Vedeu::Model::Collection
+  end # Keys
+
+end # Vedeu