vedeu 0.1.18 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c988501e3c74334d3be70e231d973e75aeb1d3ec
-  data.tar.gz: e452c34986e00757580aab9e8adb6a2016d8c6b1
+  metadata.gz: f042b9de9119e64b521192d7d59b203d54f7cd0b
+  data.tar.gz: 1e1bd9c449e053e95d163dbfd8833515f21e9f8d
 SHA512:
-  metadata.gz: e03000d3934efdcf2597f9a0334f277c5a7779ae22939bc13419dee0986c9cf2013192a98b374335437605fd6b15447c7602814da7f0442ef4d5b2f185bef565
-  data.tar.gz: e4dfb2ae02ae58371a6d64fec619d4b9a17791a5e7b36b6597b0a16d594d06ada538184799457d806273c2fdc43e9e2b5dd6832645fdfd7fa902345caf66c6f0
+  metadata.gz: 8b6492e5404edf7622295e205fb8479537671b4dda4d9817a3b9ed2cf0c144b58ab13ec6e7cd786482995f33def8574c2c736ac8fff93a0d4f54cbae10d38083
+  data.tar.gz: 7709bce2742998b9e90c7f8521b4b3d131623ac3b0c35c3b91f98d9cd18f03952e7aba5d54cf2128ed35f1f3319f38adb3607f4511b03508e5d21a28e600bc39

data/.yardopts

@@ -1 +1,6 @@
 --private
+--protected
+--embed-mixin ClassMethods
+-
+docs/api.md
+docs/events.md

data/Dockerfile

@@ -0,0 +1,40 @@
+FROM stackbrew/ubuntu:trusty
+MAINTAINER Gavin Laking <gavinlaking@gmail.com>
+
+ENV DEBIAN_FRONTEND noninteractive
+
+RUN sudo apt-get update;\
+    sudo apt-get install -y --force-yes \
+                         software-properties-common \
+                         build-essential \
+                         openssl \
+                         ca-certificates \
+                         git-core \
+                         autoconf \
+                         gawk \
+                         libreadline6-dev \
+                         libyaml-dev \
+                         libgdbm-dev \
+                         libncurses5-dev \
+                         automake \
+                         libtool \
+                         bison \
+                         pkg-config \
+                         curl \
+                         libxslt-dev \
+                         libxml2-dev \
+                         make; \
+    sudo apt-get clean -y; \
+    sudo apt-get autoremove -y;
+
+RUN sudo add-apt-repository "deb http://ppa.launchpad.net/brightbox/ruby-ng/ubuntu  $(lsb_release -sc) main";\
+    sudo apt-get update; \
+    sudo apt-get install ruby2.1 ruby2.1-dev -y --force-yes; \
+    sudo apt-get clean -y; \
+    sudo apt-get autoremove -y;
+
+RUN echo "---\n:benchmark: false\n:bulk_threshold: 1000\n:backtrace: false\n:verbose: true\ngem: --no-ri --no-rdoc" > ~/.gemrc; \
+    /bin/bash -l -c "gem install bundler" ;
+
+RUN git clone https://github.com/gavinlaking/vedeu.git
+RUN cd vedeu; bundle install; rake

data/README.md

@@ -117,34 +117,9 @@ Note: not setting a width or height will set the values to the terminal's report
 - `cursor` is a Boolean specifying whether the cursor should show.
 
 
-### On Defining Events
+### Events
 
-```ruby
-event :event_name do |arg1, arg2|
-end
-```
-
-One can define events which perform work or trigger other events. Vedeu has built-in events which are namespaced with underscores:
-
-- `:_initialize_` Special event which Vedeu triggers when it is ready to enter the main loop. Client applications can listen for this event and perform some action(s), like render the first screen, interface or make a sound.
-
-- `:_cleanup_` This event is fired by Vedeu when `:_exit_` is triggered. You can hook into this to perform a special action before the application terminates. Saving the user's work, session or preferences might be popular here.
-
-- `:_clear_` Clears the whole terminal space.
-
-- `:_exit_` when triggered, Vedeu will trigger a `:_cleanup_` event which you can define (to save files, etc) and attempt to exit.
-
-- `:_keypress_` triggering this event will cause the triggering of the `:key` event; which you should define to 'do things'. If the `escape` key is pressed, then `key` is triggered with the argument `:escape`, also an internal event `_mode_switch_` is triggered.
-
-- `:_mode_switch_` when triggered (after the user presses `escape`), Vedeu switches from a "raw mode" terminal to a "cooked mode" terminal. The idea here being that the raw mode is for single keypress actions, whilst cooked mode allows the user to enter more elaborate commands- such as commands with arguments.
-
-- `:_refresh_` triggering this event will cause all interfaces to refresh.
-
-- `:_refresh_group_(group_name)_` will refresh all interfaces belonging to this group. E.g. `_refresh_group_home_` will refresh all interfaces with the group of `home`.
-
-- `:_refresh_(interface_name)_` will refresh the interface with this name. E.g. `_refresh_widget_` will refresh the interface `widget`.
-
-Note: Overriding or adding additional events to the Vedeu event namespace may cause unpredictable results. It is recommended to only to hook into events like :_cleanup_, :_initialize_ and :key if you need to do something respective to those events.
+More information about events can be found here: [Vedeu Events](http://www.rubydoc.info/github/gavinlaking/vedeu/file/docs/events.md)
 
 
 ### Geometry
@@ -212,10 +187,10 @@ Pull requests are very welcome! Please try to follow these simple rules if appli
 
 1. Fork it ([https://github.com/gavinlaking/vedeu/fork](https://github.com/gavinlaking/vedeu/fork))
 2. Clone it
-3. `bundle`
-4. `rake` (runs all tests and coverage report) or `bundle exec guard`
+3. Run `bundle`
+4. Run `rake` (runs all tests and coverage report) or `bundle exec guard`
 5. Create your feature branch (`git checkout -b my-new-feature`)
-6. Write some tests, write some code, have some fun!
+6. Write some tests, write some code, **have some fun!**
 7. Commit your changes (`git commit -am 'Add some feature'`)
 8. Push to the branch (`git push origin my-new-feature`)
 9. Create a new pull request.
@@ -223,6 +198,8 @@ Pull requests are very welcome! Please try to follow these simple rules if appli
 
 ## Author & Contributors
 
+### Author
+
 [Gavin Laking](https://github.com/gavinlaking) ([@gavinlaking](http://twitter.com/gavinlaking))
 
 

data/docs/api.md

@@ -0,0 +1,79 @@
+## Vedeu API
+
+Vedeu provides a simple DSL for the creation of terminal/console based
+applications.
+
+Below is a list of all the API methods. These can be accessed in your
+application by including Vedeu in your class or module or by calling them directly.
+
+
+### API 'include' example
+
+Doing it this way will mean you can use any API method without the `Vedeu.` prefix.
+
+```ruby
+class SomeClassInYourApplication
+  include Vedeu
+  
+  ...
+```
+
+
+### API direct example
+
+Doing it this way means you need to use the `Vedeu.` prefix.
+
+```ruby
+class OtherClassInYourApplication
+  ...
+   
+  def some_method
+    Vedeu.some_api_method   
+  end
+   
+  ...
+```
+
+... TODO ...
+
+
+### API DSL methods
+
+defined
+event
+events
+height
+interface
+keypress
+log
+resize
+trigger
+unevent
+use
+view
+views
+width
+
+colour
+style
+
+line
+use
+cursor
+delay
+group
+name
+x
+y
+width
+height
+centred
+
+stream
+text
+foreground
+background
+
+align
+text
+width

data/docs/events.md

@@ -0,0 +1,121 @@
+## Vedeu Events
+
+Vedeu provides an event mechanism to facilitate the functionality of your
+application. The events are either Vedeu defined, ie. system events or 
+user defined, ie. user events.
+
+Events described in this document assume that you have included Vedeu in your
+class:
+
+```ruby
+  class SomeClassInYourApplication
+    include Vedeu
+
+    ...
+```
+
+### System Events
+
+System events generally control the internal state of Vedeu with respects to
+your application. They are soft-namespaced using underscores.
+
+#### `:_cleanup_`
+
+This event is fired by Vedeu when `:_exit_` is triggered. You can hook into this to perform a special action before the application terminates. Saving the user's work, session or preferences might be popular here.
+
+#### `:_clear_`
+
+Clears the whole terminal space.
+
+#### `:_exit_` 
+
+When triggered, Vedeu will trigger a `:_cleanup_` event which you can define (to save files, etc) and attempt to exit.
+
+#### `:_focus_by_name_` 
+
+When triggered with an interface name will focus that interface.
+
+#### `:_focus_next_`
+
+When triggered will focus the next interface. 
+
+#### `:_focus_prev_`
+
+When triggered will focus the previous interface.
+
+#### `:_initialize_`
+
+Special event which Vedeu triggers when it is ready to enter the main loop. Client applications can listen for this event and perform some action(s), like render the first screen, interface or make a sound.
+
+#### `:_keypress_`
+
+Triggering this event will cause the triggering of the `:key` event; which you should define to 'do things'. If the `escape` key is pressed, then `key` is triggered with the argument `:escape`, also an internal event `_mode_switch_` is triggered.
+
+#### `:_log_` 
+
+When triggered with a message will cause Vedeu to log the message if logging is enabled in the configuration.
+
+#### `:_mode_switch_`
+
+When triggered (after the user presses `escape`), Vedeu switches from a "raw mode" terminal to a "cooked mode" terminal. The idea here being that the raw mode is for single keypress actions, whilst cooked mode allows the user to enter more elaborate commands- such as commands with arguments.
+
+#### `:_refresh_`
+
+Triggering this event will cause all interfaces to refresh.
+
+#### `:_refresh_group_(group_name)_`
+
+Will refresh all interfaces belonging to this group. E.g. `_refresh_group_home_` will refresh all interfaces with the group of `home`.
+
+#### `:_refresh_(interface_name)_`
+
+Will refresh the interface with this name. E.g. `_refresh_widget_` will refresh the interface `widget`.
+
+#### `:_resize_`
+
+When triggered will cause Vedeu to trigger the `:_clear_` and `:_refresh_`
+events. Please see those events for their behaviour.
+
+
+##### Notes:
+
+System events can be handled or triggered by your application also, but overriding or adding additional events to the Vedeu system event namespace may cause unpredictable results. It is recommended to only to hook into events like :_cleanup_, :_initialize_ and :key if you need to do something respective
+to those events.
+
+
+... TODO ... What about events in Vedeu::Menu?
+
+... TODO ... More information about system events.
+
+
+### User Events
+
+User events allow you to orchestrate behaviour within your application, ie. the user presses a specific key, you trigger an event to make something happen. Eg. pressing 'p' instructs the player to play.
+
+
+#### How to define user events
+
+```ruby
+event :event_name do |arg1, arg2|
+  ...
+
+  # Things that should happen when the event is triggered; these can be method
+  # calls or the triggering of another event or events.
+
+  ...
+end
+```
+
+... TODO ... How to define.
+
+
+#### How to trigger user events
+
+... TODO ... How to trigger.
+
+
+#### More information.
+
+... TODO ... More information about user events.
+
+

data/lib/vedeu.rb

@@ -1,14 +1,49 @@
+#
+#
+# Vedeu is a GUI framework for terminal/console applications written in Ruby.
+#
+#
 module Vedeu
 
-  EntityNotFound      = Class.new(StandardError)
-  GroupNotFound       = Class.new(StandardError)
-  InterfaceNotFound   = Class.new(StandardError)
-  InvalidSyntax       = Class.new(StandardError)
-  ModeSwitch          = Class.new(StandardError)
+  # Raised when Vedeu attempts to access a named buffer that does not exist.
+  BufferNotFound = Class.new(StandardError)
+
+  # Raised when trying to access a group of interfaces which do not exist by
+  # this name.
+  GroupNotFound = Class.new(StandardError)
+
+  # Raised when an interface cannot be found by name.
+  InterfaceNotFound = Class.new(StandardError)
+
+  # Raised when Vedeu attempts to parse a {Vedeu.view} or {Vedeu.interface} and
+  # encounters a problem.
+  InvalidSyntax = 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.
+  ModeSwitch = Class.new(StandardError)
+
+  # Raised when attempting to reach the currently in focus interface, when no
+  # interfaces have been defined yet.
   NoInterfacesDefined = Class.new(StandardError)
-  NotImplemented      = Class.new(StandardError)
-  OutOfRange          = Class.new(StandardError)
 
+  # Raised to remind me (or client application developers) that the subclass
+  # implements the functionality sought.
+  NotImplemented = Class.new(StandardError)
+
+  # 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.
+  OutOfRange = Class.new(StandardError)
+
+  # When Vedeu is included within one of your classes, you should have all
+  # API methods at your disposal.
+  #
+  # @example
+  #   class YourClassHere
+  #     include Vedeu
+  #     ...
+  #
   def self.included(receiver)
     receiver.send(:include, API)
     receiver.extend(API)
@@ -23,6 +58,7 @@ require 'logger'
 require 'optparse'
 require 'set'
 
+require 'vedeu/support/common'
 require 'vedeu/support/log'
 require 'vedeu/support/trace'
 require 'vedeu/configuration'
@@ -38,7 +74,6 @@ require 'vedeu/support/position'
 require 'vedeu/support/esc'
 require 'vedeu/support/terminal'
 require 'vedeu/support/event'
-require 'vedeu/support/events'
 
 require 'vedeu/models/geometry'
 require 'vedeu/models/colour'
@@ -47,6 +82,9 @@ require 'vedeu/models/interface'
 require 'vedeu/models/line'
 require 'vedeu/models/stream'
 
+require 'vedeu/repositories/events'
+
+require 'vedeu/api/defined'
 require 'vedeu/api/api'
 require 'vedeu/api/composition'
 require 'vedeu/api/helpers'
@@ -54,18 +92,23 @@ require 'vedeu/api/interface'
 require 'vedeu/api/line'
 require 'vedeu/api/stream'
 
-require 'vedeu/support/input'
+require 'vedeu/repositories/interfaces'
+require 'vedeu/repositories/groups'
+require 'vedeu/repositories/focus'
+require 'vedeu/repositories/events'
+require 'vedeu/repositories/buffers'
 
-require 'vedeu/application'
-require 'vedeu/launcher'
+require 'vedeu/output/clear'
+require 'vedeu/output/compositor'
+require 'vedeu/output/refresh'
+require 'vedeu/output/render'
+require 'vedeu/output/view'
 
-require 'vedeu/support/focus'
-require 'vedeu/support/groups'
-require 'vedeu/support/buffers'
-require 'vedeu/support/clear'
-require 'vedeu/support/render'
-require 'vedeu/support/view'
-require 'vedeu/support/buffer'
 require 'vedeu/support/grid'
 require 'vedeu/support/menu'
+require 'vedeu/support/cursor'
 
+require 'vedeu/input/input'
+
+require 'vedeu/application'
+require 'vedeu/launcher'

data/lib/vedeu/api/api.rb

@@ -1,6 +1,19 @@
 module Vedeu
+
+  # Provides the API to Vedeu. Methods therein, and classes belonging to this
+  # module expose Vedeu's core functionality.
   module API
 
+    # Returns information about various registered subsystems when used with
+    # a defined method within {Vedeu::API::Defined}.
+    #
+    # @api public
+    # @see Vedeu::API::Defined
+    # @return [Vedeu::API::Defined]
+    def defined
+      Vedeu::API::Defined
+    end
+
     # Register an event by name with optional delay (throttling) which when
     # triggered will execute the code contained within the passed block.
     #
@@ -49,19 +62,27 @@ module Vedeu
       Vedeu.events.event(name, opts = {}, &block)
     end
 
-    # Unregister an event by name.
+    # Initially accessed by Vedeu itself, this sets up some basic events needed
+    # by Vedeu to run. Afterwards, it is simply a gateway to the Events class
+    # used by other API methods.
     #
-    # @api public
-    # @param name [Symbol]
-    # @return [Hash]
-    def unevent(name)
-      Vedeu.events.unevent(name)
+    # @api private
+    # @return [Events]
+    def events
+      @events ||= Vedeu::Events.new do
+        event(:_clear_)                   { Terminal.clear_screen     }
+        event(:_exit_)                    { Vedeu::Application.stop   }
+        event(:_focus_by_name_)           { |name| Vedeu::Focus.by_name(name) }
+        event(:_focus_next_)              { Vedeu::Focus.next_item    }
+        event(:_focus_prev_)              { Vedeu::Focus.prev_item    }
+        event(:_keypress_)                { |key| Vedeu.keypress(key) }
+        event(:_log_)                     { |msg| Vedeu.log(msg)      }
+        event(:_mode_switch_)             { fail ModeSwitch           }
+        event(:_refresh_)                 { Vedeu::Refresh.all        }
+        event(:_resize_, { delay: 0.25 }) { Vedeu.resize              }
+      end
     end
 
-    # def focus(name)
-    #   Focus.by_name(name)
-    # end
-
     # Find out how many lines the current terminal is able to display.
     #
     # @api public
@@ -97,7 +118,12 @@ module Vedeu
     end
 
     # Handles the keypress in your application. Can also be used to simulate a
-    # keypress.
+    # 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
@@ -105,15 +131,15 @@ module Vedeu
     #   i.e. `:f4`. A list of these translations can be found at {Vedeu::Input}.
     #
     # @example
-    #   TODO
+    #   Vedeu.keypress('s')
     #
     # @return []
     def keypress(key)
-      Vedeu.events.trigger(:key, key)
-      Vedeu.events.trigger(:_log_, "Key: #{key}") if Configuration.debug?
-      Vedeu.events.trigger(:_mode_switch_) if key == :escape
-      Vedeu.events.trigger(:_focus_next_)  if key == :tab
-      Vedeu.events.trigger(:_focus_prev_)  if key == :shift_tab
+      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
     end
 
     # Write a message to the Vedeu log file located at `$HOME/.vedeu/vedeu.log`
@@ -121,14 +147,30 @@ 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
+    #   write to the log file regardless of the Configuration setting.
     #
     # @example
     #   Vedeu.log('A useful debugging message: Error!')
     #
     # @return [TrueClass]
-    def log(message)
-      Vedeu::Log.logger.debug(message) if Configuration.debug?
+    def log(message, force = false)
+      Vedeu::Log.logger.debug(message) if Configuration.debug? || force
+    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 []
+    # :nocov:
+    def resize
+      trigger(:_clear_)
+
+      trigger(:_refresh_)
     end
+    # :nocov:
 
     # Trigger a registered or system event by name with arguments.
     #
@@ -153,14 +195,13 @@ module Vedeu
     #
     # @example
     #   Vedeu.interface 'main_screen' do
-    #     ... some attributes ...
     #     width use('my_interface').width
     #     x     use('my_interface').east(1)
-    #   end
+    #     ...
     #
     # @return [Vedeu::Interface]
     def use(name)
-      Vedeu::Interface.new(Vedeu::Buffers.retrieve_attributes(name))
+      Vedeu::Interface.new(Vedeu::Interfaces.find(name))
     end
 
     # Define a view (content) for an interface. TODO: More help.
@@ -172,8 +213,7 @@ module Vedeu
     #
     # @example
     #   view 'my_interface' do
-    #     ... some view attributes ...
-    #   end
+    #     ...
     #
     # @return [Hash]
     def view(name, &block)
@@ -195,7 +235,7 @@ module Vedeu
     #     view 'my_other_interface' do
     #       ... some other attributes ...
     #     end
-    #   end
+    #     ...
     #
     #   composition do
     #     view 'my_interface' do
@@ -221,34 +261,14 @@ module Vedeu
       Terminal.width
     end
 
-    # @api private
-    # @return []
-    def events
-      @events ||= Vedeu::Events.new do
-        event(:_log_)                     { |msg| Vedeu.log(msg)      }
-        event(:_exit_)                    { Vedeu.shutdown            }
-        event(:_mode_switch_)             { fail ModeSwitch           }
-        event(:_clear_)                   { Terminal.clear_screen     }
-        event(:_refresh_)                 { Buffers.refresh_all       }
-        event(:_resize_, { delay: 0.25 }) { Vedeu.resize              }
-        event(:_keypress_)                { |key| Vedeu.keypress(key) }
-      end
-    end
-
-    # @api private
-    # @return []
-    def resize
-      trigger(:_clear_)
-
-      trigger(:_refresh_)
-    end
-
-    # @api private
-    # @return [Exception]
-    def shutdown
-      trigger(:_cleanup_)
-
-      fail StopIteration
+    # Unregisters the event by name, effectively deleting the associated events
+    # bound with it also.
+    #
+    # @api public
+    # @param name [Symbol]
+    # @return [Hash]
+    def unevent(name)
+      Vedeu.events.unevent(name)
     end
 
   end