vedeu 0.1.17 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fd2666b59001c06c50ffd12741aff8bbf24eb926
-  data.tar.gz: c0198ab59c679313bc8faa58cb65438a8874e88f
+  metadata.gz: c988501e3c74334d3be70e231d973e75aeb1d3ec
+  data.tar.gz: e452c34986e00757580aab9e8adb6a2016d8c6b1
 SHA512:
-  metadata.gz: 6f561391d510a520f2846143e0def865aed71b737b42d9d1c76d310a1f12f96d619b4a8fe0b4cca4192c865b06b4eaf7911dc2321db2a0801d1b96ad8b1141fb
-  data.tar.gz: b1456ac646748bbd04cf397dc20286e9ff1408b9a098fed2cbb4722511e516ad8a212dd95c475b68ba900a374549ede282a4d3481af0b58b55b02eb1300ed38b
+  metadata.gz: e03000d3934efdcf2597f9a0334f277c5a7779ae22939bc13419dee0986c9cf2013192a98b374335437605fd6b15447c7602814da7f0442ef4d5b2f185bef565
+  data.tar.gz: e4dfb2ae02ae58371a6d64fec619d4b9a17791a5e7b36b6597b0a16d594d06ada538184799457d806273c2fdc43e9e2b5dd6832645fdfd7fa902345caf66c6f0

data/.yardopts

@@ -0,0 +1 @@
+--private

data/README.md

@@ -165,13 +165,13 @@ echo "export TERM=xterm-256color" >> ~/.bashrc
 or, if you wish not to tamper with `$TERM`:
 
 ```bash
-echo "export VEDEUTERM=xterm-256color" >> ~/.bashrc
+echo "export VEDEU_TERM=xterm-256color" >> ~/.bashrc
 ```
 
-If you know your terminal supports full 24-bit colour, set the `$VEDEUTERM` environment variable:
+If you know your terminal supports full 24-bit colour, set the `$VEDEU_TERM` environment variable:
 
 ```bash
-echo "export VEDEUTERM=xterm-truecolor" >> ~/.bashrc
+echo "export VEDEU_TERM=xterm-truecolor" >> ~/.bashrc
 ```
 
 
@@ -180,6 +180,20 @@ echo "export VEDEUTERM=xterm-truecolor" >> ~/.bashrc
 Vedeu has a range of symbol styles which are compatible with most terminals which are ANSI compatible. Like colours, they can be defined in either interfaces, for specific lines or within streams. Styles are applied as encountered.
 
 
+## Debugging & Environment Variables
+
+Vedeu has two types of debugging; `VEDEU_DEBUG` and `VEDEU_TRACE`. Both of these can be configured at run-time using the arguments you pass to your application. They can also be enabled/disabled globally by setting environment variables (see below). These messages are written to `~/.vedeu/vedeu.log`.
+
+To enable or disable, use true or false:
+
+```bash
+echo "export VEDEU_DEBUG=true" >> ~/.bashrc
+echo "export VEDEU_TRACE=true" >> ~/.bashrc
+```
+
+Debugging (`VEDEU_DEBUG`) provides helpful messages which inform you what is happening in the application. Tracing (`VEDEU_TRACE`) is a noisy, blow-by-blow account of what is happening, letting you know which methods were called and which events have been triggered. Both (more so with tracing) can impact the performance of your application.
+
+
 ## Development / Contributing
 
 * Documentation hosted at [RubyDoc](http://rubydoc.info/github/gavinlaking/vedeu/master/frames).

data/lib/vedeu.rb

@@ -3,6 +3,7 @@ module Vedeu
   EntityNotFound      = Class.new(StandardError)
   GroupNotFound       = Class.new(StandardError)
   InterfaceNotFound   = Class.new(StandardError)
+  InvalidSyntax       = Class.new(StandardError)
   ModeSwitch          = Class.new(StandardError)
   NoInterfacesDefined = Class.new(StandardError)
   NotImplemented      = Class.new(StandardError)
@@ -22,6 +23,8 @@ require 'logger'
 require 'optparse'
 require 'set'
 
+require 'vedeu/support/log'
+require 'vedeu/support/trace'
 require 'vedeu/configuration'
 
 require 'vedeu/models/attributes/coercions'
@@ -30,7 +33,13 @@ require 'vedeu/models/attributes/background'
 require 'vedeu/models/attributes/foreground'
 require 'vedeu/models/attributes/presentation'
 require 'vedeu/models/composition'
+
+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'
 require 'vedeu/models/style'
@@ -45,6 +54,8 @@ require 'vedeu/api/interface'
 require 'vedeu/api/line'
 require 'vedeu/api/stream'
 
+require 'vedeu/support/input'
+
 require 'vedeu/application'
 require 'vedeu/launcher'
 
@@ -55,12 +66,6 @@ require 'vedeu/support/clear'
 require 'vedeu/support/render'
 require 'vedeu/support/view'
 require 'vedeu/support/buffer'
-require 'vedeu/support/position'
-require 'vedeu/support/esc'
-require 'vedeu/support/event'
-require 'vedeu/support/events'
 require 'vedeu/support/grid'
-require 'vedeu/support/input'
-require 'vedeu/support/log'
 require 'vedeu/support/menu'
-require 'vedeu/support/trace'
+

data/lib/vedeu/api/api.rb

@@ -4,6 +4,7 @@ module Vedeu
     # Register an event by name with optional delay (throttling) which when
     # triggered will execute the code contained within the passed block.
     #
+    # @api public
     # @param name  [Symbol] The name of the event which will be triggered later.
     # @param [Hash] opts The options to register the event with.
     # @option opts :delay [Fixnum|Float] Limits the execution of the
@@ -23,19 +24,21 @@ module Vedeu
     #     Vedeu.trigger(:my_other_event)
     #   end
     #
-    #   T = Triggered, X = Executed, I = Ignored.
+    #   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
+    #   .X...i...i...i...i...X...i...i...i...i...X...i...i...i...i...i...i...i
     #
     #   Vedeu.event(:my_delayed_event, { delay: 0.5 })
     #     ... some code here ...
     #   end
     #
-    #   T = Triggered, X = Executed, I = Ignored.
+    #   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
+    #   .i...i...i...i...i...i...i...X...i...i...i...i...i...i...X...i...i...i
     #
     #   Vedeu.event(:my_debounced_event, { debounce: 0.7 })
     #     ... some code here ...
@@ -48,6 +51,7 @@ module Vedeu
 
     # Unregister an event by name.
     #
+    # @api public
     # @param name [Symbol]
     # @return [Hash]
     def unevent(name)
@@ -60,6 +64,7 @@ module Vedeu
 
     # Find out how many lines the current terminal is able to display.
     #
+    # @api public
     # @example
     #   Vedeu.height
     #
@@ -72,6 +77,7 @@ module Vedeu
     # command. This provides the means for you to define your application's
     # views without their content.
     #
+    # @api public
     # @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
@@ -79,18 +85,24 @@ module Vedeu
     #
     # @example
     #   Vedeu.interface 'my_interface' do
-    #      ... some interface attributes like width and height ...
-    #   end
+    #     ...
+    #
+    #   Vedeu.interface do
+    #     name 'interfaces_must_have_a_name'
+    #     ...
     #
     # @return [TrueClass]
-    def interface(name, &block)
+    def interface(name = '', &block)
       API::Interface.define({ name: name }, &block)
     end
 
-    # Simulate keypresses in your application. TODO: More help.
+    # Handles the keypress in your application. Can also be used to simulate a
+    # keypress.
     #
-    # @param key [String|Symbol] A simulated keypress. Escape sequences are also
-    #   supported. Special keys like the F-keys are named as symbols; i.e. `:f4`
+    # @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
     #   TODO
@@ -98,12 +110,15 @@ module Vedeu
     # @return []
     def keypress(key)
       Vedeu.events.trigger(:key, key)
-      Vedeu.events.trigger(:_log_, "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
     end
 
     # Write a message to the Vedeu log file located at `$HOME/.vedeu/vedeu.log`
     #
+    # @api public
     # @param message [String] The message you wish to emit to the log
     #   file, useful for debugging.
     #
@@ -112,11 +127,12 @@ module Vedeu
     #
     # @return [TrueClass]
     def log(message)
-      Vedeu::Log.logger.debug(message)
+      Vedeu::Log.logger.debug(message) if Configuration.debug?
     end
 
     # Trigger a registered or system event by name with arguments.
     #
+    # @api public
     # @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.
@@ -131,6 +147,7 @@ module Vedeu
 
     # Use attributes of another interface whilst defining one. TODO: More help.
     #
+    # @api public
     # @param name [String] The name of the interface you wish to use. Typically
     #   used when defining interfaces to share geometry.
     #
@@ -148,6 +165,7 @@ module Vedeu
 
     # Define a view (content) for an interface. TODO: More help.
     #
+    # @api public
     # @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.
@@ -163,8 +181,8 @@ module Vedeu
     end
 
     # Instruct Vedeu to treat contents of block as a single composition.
-    # TODO: More help.
     #
+    # @api public
     # @param block [Proc] Instructs Vedeu to treat all of the 'view' directives
     #   therein as one instruction. Useful for redrawing multiple interfaces at
     #   once.
@@ -186,12 +204,15 @@ module Vedeu
     #
     # @return [Hash]
     def views(&block)
+      fail InvalidSyntax, '`views` requires a block.' unless block_given?
+
       API::Composition.build(&block)
     end
     alias_method :composition, :views
 
     # Find out how many columns the current terminal is able to display.
     #
+    # @api public
     # @example
     #   Vedeu.width
     #
@@ -201,6 +222,7 @@ module Vedeu
     end
 
     # @api private
+    # @return []
     def events
       @events ||= Vedeu::Events.new do
         event(:_log_)                     { |msg| Vedeu.log(msg)      }
@@ -214,6 +236,7 @@ module Vedeu
     end
 
     # @api private
+    # @return []
     def resize
       trigger(:_clear_)
 
@@ -221,6 +244,7 @@ module Vedeu
     end
 
     # @api private
+    # @return [Exception]
     def shutdown
       trigger(:_cleanup_)
 

data/lib/vedeu/api/composition.rb

@@ -2,17 +2,12 @@ module Vedeu
   module API
     class Composition < Vedeu::Composition
 
+      # @api public
       # @see Vedeu::API#view
       def view(name, &block)
         attributes[:interfaces] << Interface.build({ name: name }, &block)
       end
 
-      private
-
-      def method_missing(method, *args, &block)
-        @self_before_instance_eval.send(method, *args, &block)
-      end
-
     end
   end
 end

data/lib/vedeu/api/helpers.rb

@@ -5,6 +5,7 @@ module Vedeu
       # Define either or both foreground and background colours for an
       # interface, line or a stream.
       #
+      # @api public
       # @param values [Hash]
       #
       # @example
@@ -30,6 +31,7 @@ module Vedeu
 
       # Define a style for an interface, line or a stream.
       #
+      # @api public
       # @param values [Array|String]
       # @param block  [Proc]
       #

data/lib/vedeu/api/interface.rb

@@ -3,50 +3,40 @@ module Vedeu
     class Interface < Vedeu::Interface
       include Helpers
 
-      # @see Vedeu::API#interface
-      # @param attributes [Hash]
-      # @param block [Proc]
-      # @return []
-      def self.define(attributes = {}, &block)
-        new(attributes).define(&block)
-      end
-
-      # @see Vedeu::API#interface
-      # @param block [Proc]
-      #
-      # @example
-      #   TODO
-      #
-      # @return []
-      def define(&block)
-        instance_eval(&block) if block_given?
-
-        Vedeu::Buffers.create(attributes)
-
-        Vedeu.event("_refresh_#{attributes[:name]}_".to_sym,
-                    { delay: attributes[:delay] }) do
-          Vedeu::Buffers.refresh(attributes[:name])
-        end
-
-        true
-      end
-
       # Define a single line in a view.
       #
+      # @api public
+      # @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
       #       ... some line attributes ...
       #     end
       #   end
       #
       # @return []
-      def line(&block)
-        attributes[:lines] << Line.build(&block)
+      def line(value = '', &block)
+        if block_given?
+          attributes[:lines] << Line.build(&block)
+
+        else
+          attributes[:lines] << Line.build({ streams: { text: value } })
+
+        end
       end
 
+      # Use the specified interface; useful for sharing attributes with other
+      # interfaces.
+      #
+      # @api public
+      # @param value [String]
       # @see Vedeu::API#use
       def use(value)
         Vedeu.use(value)
@@ -55,19 +45,28 @@ module Vedeu
       # Define the cursor visibility for an interface. A `true` value will show
       # the cursor, whilst `false` will hide it.
       #
+      # @api public
       # @param value [Boolean]
       #
       # @example
       #   interface 'my_interface' do
       #     cursor true
-      #     ... some interface attributes ...
-      #   end
+      #     ...
       #
       # @return []
       def cursor(value)
+        unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          fail InvalidSyntax, 'Argument must be `true` or `false` for cursor.'
+        end
+
         attributes[:cursor] = value
       end
 
+      # To maintain performance interfaces can be delayed from refreshing too
+      # often, the reduces artefacts particularly when resizing the terminal
+      # screen.
+      #
+      # @api public
       # @param value [Fixnum|Float]
       #
       # @return []
@@ -79,13 +78,13 @@ module Vedeu
       # targetted together; for example you may want to refresh multiple
       # interfaces at once.
       #
+      # @api public
       # @param value [String]
       #
       # @example
       #   interface 'my_interface' do
-      #     group 'main_screen' do
-      #     ... some interface attributes ...
-      #   end
+      #     group 'main_screen'
+      #     ...
       #
       # @return []
       def group(value)
@@ -95,10 +94,13 @@ module Vedeu
       # The name of the interface. Used to reference the interface throughout
       # your application's execution lifetime.
       #
+      # @api public
       # @param value [String]
       #
       # @example
-      #   TODO
+      #   interface do
+      #     name 'my_interface'
+      #     ...
       #
       # @return []
       def name(value)
@@ -107,6 +109,7 @@ module Vedeu
 
       # Define the starting x position (column) of the interface.
       #
+      # @api public
       # @param value [Fixnum]
       # @param block [Proc]
       #
@@ -130,6 +133,7 @@ module Vedeu
 
       # Define the starting y position (row/line) of the interface.
       #
+      # @api public
       # @param value [Fixnum]
       # @param block [Proc]
       #
@@ -154,6 +158,7 @@ module Vedeu
 
       # Define the number of characters/columns wide the interface will be.
       #
+      # @api public
       # @param value [Fixnum]
       #
       # @example
@@ -170,6 +175,7 @@ module Vedeu
 
       # Define the number of characters/rows/lines tall the interface will be.
       #
+      # @api public
       # @param value [Fixnum]
       #
       # @example
@@ -187,6 +193,7 @@ module Vedeu
       # Instructs Vedeu to calculate x and y geometry automatically based on the
       # centre character of the terminal, the width and the height.
       #
+      # @api public
       # @param value [Boolean]
       #
       # @example
@@ -196,26 +203,11 @@ module Vedeu
       #
       # @return []
       def centred(value)
-        attributes[:geometry][:centred] = value
-      end
-
-      private
-
-      def out_of_bounds(name)
-        "Note: For this terminal, the value of '#{name}' may lead to content " \
-        "that is outside the viewable area."
-      end
-
-      def y_out_of_bounds?(value)
-        value < 1 || value > Terminal.height
-      end
-
-      def x_out_of_bounds?(value)
-        value < 1 || value > Terminal.width
-      end
+        unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          fail InvalidSyntax, 'Argument must be `true` or `false` for centred.'
+        end
 
-      def method_missing(method, *args, &block)
-        @self_before_instance_eval.send(method, *args, &block)
+        attributes[:geometry][:centred] = value
       end
 
     end