vedeu 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa08f6802848478327fb38d44b28b19ffbb78d75
-  data.tar.gz: 8e30625c919e7d3c678c7301c707904e5ac70328
+  metadata.gz: dec7d96b1f14de41e305192ec084b5f16ea39779
+  data.tar.gz: afd4cc9b1eea2d7eb9c781abbdf71feab39514ed
 SHA512:
-  metadata.gz: 50aaa91ab6b23ce968ab31fa9100959c8a05f21d9accffd2f3444a53474fa16c6b30527aa4aca79e4ce35fd5dece0799ed101b6e5c9ad171bddc44734ad94bb7
-  data.tar.gz: 7dafc1f4a3f8fa836e05f665ef005c30550632bce5e92eb1ba69abe435e48b159b94268448c7465392816692e625e48f5b129bb573eedc86564eeef64c58af07
+  metadata.gz: c008ae703f26a202bb20b3c0909dc1779a4d30606365f96342637e5c3715018fa75d16ddf12f7087599a99aa24785830ca55683b286246e77e2ad444101f2fbe
+  data.tar.gz: f587307ac3e309e74b018770048f90dae43cae84b8805f041df8d29c0231c42191d5d92337a5625ceb11c71fc24aca8cb072170227bc7cde177082f299d42833

data/README.md

@@ -56,15 +56,9 @@ class MyApp
     # ...
   end
 
-  event :key do |key|
-    case key
-    when 'a' then puts "Apple"
-    when 'b' then puts "Banana"
-    # ...
-    when :f1 then trigger(:some_event)
-    when :f2 then
-      trigger(:other_event, { args: here }, [:or, :here], :etc)
-    end
+  keys do
+    key('a') { trigger(':apple') }
+    key('b') { trigger(':banana') }
   end
 end
 ```

data/docs/api.md

@@ -39,45 +39,73 @@ class OtherClassInYourApplication
 
 ### API DSL methods
 
-defined
-event
-events
-height
-interface
-keypress
-log
-menu
-resize
-trigger
-unevent
-use
-view
-views
-width
-
-colour
-style
-
-line
-use
-cursor
-delay
-group
-name
-x
-y
-width
-height
-centred
-
-items
-name
-
-stream
-text
-foreground
-background
-
-align
-text
-width
+#### Events
+
+- event
+- trigger
+- unevent
+
+
+#### Input
+
+- keypress
+- keys
+  - key
+  - interface
+
+
+#### Interfaces
+
+- interface
+  - centred
+  - colour
+  - cursor
+  - delay
+  - group
+  - height
+  - name
+  - style
+  - use
+  - width
+  - x
+  - y
+
+
+#### Views
+
+- render
+  - views
+    - view
+  - view
+    - colour
+    - line
+      - background
+      - colour
+      - foreground
+      - stream
+        - align
+        - colour
+        - style
+        - text
+        - width
+      - style
+    - name
+    - style
+  - use
+
+
+#### Menus
+
+- menu
+  - items
+  - name
+
+
+#### Miscellany
+
+- defined
+- height
+- log
+- resize
+- width
+

data/elements.txt

@@ -0,0 +1,118 @@
+holmium
+neon
+mercury
+protactinium
+- calcium
+- fermium
+- nitrogen
+- palladium
+- silicon
+- oxygen
+- americium
+- bismuth
+ununpentium
+- chlorine
+neptunium
+plutonium
+- carbon
+- zinc
+polonium
+roentgenium
+darmstadtium
+mendelevium
+copernicium
+molybdenum
+aluminium
+iridium
+lanthanum
+neodymium
+ruthenium
+bohrium
+thorium
+indium
+uranium
+strontium
+rubidium
+helium
+berkelium
+gallium
+thallium
+livermorium
+lithium
+fluorine
+chromium
+europium
+selenium
+- cadmium
+xenon
+hassium
+tantalum
+radium
+scandium
+yttrium
+potassium
+promethium
+astatine
+niobium
+seaborgium
+cerium
+lead
+caesium
+gold
+phosphorus
+antimony
+sodium
+rhodium
+magnesium
+hafnium
+rhenium
+cobalt
+francium
+ununtrium
+rutherfordium
+manganese
+lutetium
+thulium
+samarium
+ytterbium
+argon
+technetium
+actinium
+iron
+sulfur
+tungsten
+tin
+hydrogen
+- vanadium
+germanium
+platinum
+- meitnerium
+erbium
+flerovium
+tellurium
+zirconium
+iodine
+titanium
+einsteinium
+dysprosium
+copper
+silver
+arsenic
+dubnium
+nobelium
+radon
+gadolinium
+terbium
+boron
+ununoctium
+nickel
+ununseptium
+bromine
+krypton
+lawrencium
+beryllium
+osmium
+praseodymium
+barium
+curium
+californium

data/lib/vedeu.rb

@@ -1,8 +1,5 @@
-#
-#
 # Vedeu is a GUI framework for terminal/console applications written in Ruby.
 #
-#
 module Vedeu
 
   # Raised when Vedeu attempts to access a named buffer that does not exist.
@@ -19,9 +16,16 @@ module Vedeu
   # encounters a problem.
   InvalidSyntax = Class.new(StandardError)
 
+  # Raised when attempting to assign a key which is already in use.
+  KeyInUse = Class.new(StandardError)
+
   # Raised when a menu cannot be found by name.
   MenuNotFound = Class.new(StandardError)
 
+  # Raised when the attributes argument to {Vedeu::Registrar} does not contain
+  # a required key or the value to that key is nil or empty.
+  MissingRequired = Class.new(StandardError)
+
   # 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.
@@ -61,10 +65,10 @@ require 'logger'
 require 'optparse'
 require 'set'
 
+require 'vedeu/configuration'
 require 'vedeu/support/common'
 require 'vedeu/support/log'
 require 'vedeu/support/trace'
-require 'vedeu/configuration'
 
 require 'vedeu/models/attributes/coercions'
 require 'vedeu/models/attributes/colour_translator'
@@ -82,6 +86,7 @@ require 'vedeu/models/geometry'
 require 'vedeu/models/colour'
 require 'vedeu/models/style'
 require 'vedeu/models/interface'
+require 'vedeu/models/keymap'
 require 'vedeu/models/line'
 require 'vedeu/models/stream'
 
@@ -92,17 +97,22 @@ require 'vedeu/api/api'
 require 'vedeu/api/composition'
 require 'vedeu/api/helpers'
 require 'vedeu/api/interface'
+require 'vedeu/api/keymap'
 require 'vedeu/api/line'
 require 'vedeu/api/menu'
 require 'vedeu/api/stream'
 
 require 'vedeu/repositories/menus'
+require 'vedeu/repositories/keymap_validator'
+require 'vedeu/repositories/keymaps'
 require 'vedeu/repositories/interfaces'
 require 'vedeu/repositories/groups'
 require 'vedeu/repositories/focus'
 require 'vedeu/repositories/events'
 require 'vedeu/repositories/buffers'
 
+require 'vedeu/support/registrar'
+
 require 'vedeu/output/clear'
 require 'vedeu/output/compositor'
 require 'vedeu/output/refresh'

data/lib/vedeu/api/api.rb

@@ -1,5 +1,7 @@
 module Vedeu
 
+  # Vedeu::Trace.call({ trace: true })
+
   # Provides the API to Vedeu. Methods therein, and classes belonging to this
   # module expose Vedeu's core functionality.
   module API
@@ -59,7 +61,7 @@ module Vedeu
     #
     # @return [Hash]
     def event(name, opts = {}, &block)
-      Vedeu.events.event(name, opts = {}, &block)
+      Vedeu.events.event(name, opts, &block)
     end
 
     # Initially accessed by Vedeu itself, this sets up some basic events needed
@@ -117,29 +119,45 @@ module Vedeu
       API::Interface.define({ name: name }, &block)
     end
 
-    # Handles the keypress in your application. Can also be used to simulate a
-    # keypress. The example below will have the following workflow:
-    #
-    # 1) Trigger the event `:key` in your application, which you will handle
-    #    and perform the appropriate action- maybe nothing.
-    # 2) If debugging is enabled in Vedeu, then the key is logged to the log
-    #    file.
-    #
     # @api public
-    # @param key [String|Symbol] The key which was pressed. Escape sequences
-    #   are also supported. Special keys like the F-keys are named as symbols;
-    #   i.e. `:f4`. A list of these translations can be found at {Vedeu::Input}.
     #
     # @example
     #   Vedeu.keypress('s')
     #
-    # @return []
+    # @see Vedeu::Keymaps.use
     def keypress(key)
-      Vedeu.trigger(:key, key)
-      Vedeu.trigger(:_log_, "Key: #{key}") if Configuration.debug?
-      Vedeu.trigger(:_mode_switch_) if key == :escape
-      Vedeu.trigger(:_focus_next_)  if key == :tab
-      Vedeu.trigger(:_focus_prev_)  if key == :shift_tab
+      Vedeu::Keymaps.use(key)
+    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.
+    #
+    # @api public
+    # @param name_or_names [String] The name or names of the interface(s) which
+    #   will handle these keys.
+    # @param block [Proc]
+    #
+    # @example
+    #   keys do                    # => will be global
+    #     key('s') { :something }
+    #     ...
+    #
+    #   keys 'my_interface' do     # => will only function when 'my_interface'
+    #     ...                      #    is in focus
+    #
+    #   keys('main', 'other') do   # => will function for both 'main' and
+    #     ...                      #    'other' interfaces
+    #
+    #   keys do
+    #     interface 'my_interface' # => will only function when 'my_interface'
+    #     ...                      #    is in focus
+    #
+    # @return [API::Keymap]
+    def keys(*name_or_names, &block)
+      fail InvalidSyntax, '`keys` requires a block.' unless block_given?
+
+      API::Keymap.define({ interfaces: name_or_names }, &block)
     end
 
     # Write a message to the Vedeu log file located at `$HOME/.vedeu/vedeu.log`
@@ -147,7 +165,7 @@ module Vedeu
     # @api public
     # @param message [String] The message you wish to emit to the log
     #   file, useful for debugging.
-    # @param force   [TrueClass|FalseClass] When evaluates to true will
+    # @param force   [Boolean] When evaluates to true will
     #   write to the log file regardless of the Configuration setting.
     #
     # @example
@@ -158,40 +176,65 @@ module Vedeu
       Vedeu::Log.logger.debug(message) if Configuration.debug? || force
     end
 
-    # Register a menu 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.
+    # Register a menu by name which will display a collection of items for your
+    # users to select; and provide interactivity within your application.
     #
     # @api public
     # @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. TODO: More help.
+    #   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
     #     ...
     #
     # @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.
+    #
+    # @api public
+    # @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
+    #         ...
+    #
+    # @return [Array]
+    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.
     #
     # @api private
-    # @return []
+    # @return [TrueClass]
     # :nocov:
     def resize
       trigger(:_clear_)
 
       trigger(:_refresh_)
+
+      true
     end
     # :nocov: