vedeu 0.2.12 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b2a6839a91cbe235601f64318bbeae95e5be439d
-  data.tar.gz: a3eb219aab24bf02d8cdf2280754c3a5a8375066
+  metadata.gz: 95a7c03c3ccd065d3c66d1c5a176e66f6e7d04f4
+  data.tar.gz: 2ddf794a56b73ddb0e2cd468ee8d4482baaa347c
 SHA512:
-  metadata.gz: d202139c56d5f1d12763ed282387d0c99059d820d2527940d6ae8805e0eb73bd58029aba5fc7ddb511f00ea628ff487dd3349bbf17bdb7a7670b7676b296cac4
-  data.tar.gz: c941ca66c0c66128ae4d1dd125fe02180d42b0bd28c6f23f8e5697409d4b4c17376ad7a2e801a13f242b00414b83c2c6e6e4dd02cd85e31156e9d37c832c3001
+  metadata.gz: 7fc84b1f48e9267a3f8fc5d282cc259764bc61a85dd77bee1f0bad19fb0b499e9e0102b7872d119405c4e25052afa50aa16c811ba72552615de827f69399d324
+  data.tar.gz: 391a08f45037963856371ebbcfb82ed17494d4f4b9e93f0df76068dd1c354e7796c5679d02246e643ac526bdf5d8fc577b26cab5de475b0f0634ccf3d3efb5d8

data/.ruby-version

@@ -1 +1 @@
-2.1
+2.2

data/Guardfile

@@ -1,3 +1,11 @@
+# guard 'cucumber' do
+#   watch(%r{^features/.+\.feature$})
+#   watch(%r{^features/support/.+$}) { 'features' }
+#   watch(%r{^features/step_definitions/(.+)_steps\.rb$}) do |m|
+#     Dir[File.join("**/#{m[1]}.feature")][0] || 'features'
+#   end
+# end
+
 guard :minitest, all_after_pass: true, focus_on_failed: true, env: { 'no_simplecov' => true } do
   watch(%r{^test/(.*)_test\.rb})
   watch(%r{^lib/(.+)\.rb}) do |m|
@@ -10,3 +18,8 @@ guard :bundler do
   watch('Gemfile')
   watch(/^.+\.gemspec/)
 end
+
+guard 'yard' do
+  watch(%r{docs/.+\.md})
+  watch(%r{lib/.+\.rb})
+end

data/README.md

@@ -45,20 +45,20 @@ class MyApp
   include Vedeu
 
   interface 'main' do
-    ...
+    # ...
   end
 
-  event :some_event do
+  bind :some_event do
     # ...
   end
 
-  event :other_event do |hash_args, array_args, args|
+  bind :other_event do |hash_args, array_args, args|
     # ...
   end
 
   keys do
-    key('a') { trigger(':apple') }
-    key('b') { trigger(':banana') }
+    key('a') { Vedeu.trigger(':apple') }
+    key('b') { Vedeu.trigger(':banana') }
   end
 end
 ```
@@ -87,10 +87,12 @@ Views with Vedeu are made up of simple building blocks. These blocks can be arra
 
 ```ruby
 interface 'main' do
-  y      1
-  x      1
-  width  10 # see notes below
-  height 10
+  geometry do
+    y      1
+    x      1
+    width  10 # see notes below
+    height 10
+  end
   colour foreground: '#ffffff', background: '#000000'
 end
 ```

data/Rakefile

@@ -1,10 +1,19 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'cucumber'
+require 'cucumber/rake/task'
 
-task :default => :test
+# Don't run cukes for the time being.
+# Cucumber::Rake::Task.new(:cucumber) do |t|
+#   t.cucumber_opts = "features --format progress"
+# end
+# Rake::Task['cucumber'].execute
 
 Rake::TestTask.new do |t|
   t.libs.push 'lib'
   t.libs.push 'test'
   t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
 end
+
+task :default => :test

data/bin/vedeu_test

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+lib_dir = File.dirname(__FILE__) + '/../lib'
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+
+require 'vedeu'
+
+class VedeuTestApp
+  def self.start(argv = ARGV)
+    Vedeu::Launcher.new(argv).execute!
+  end
+end
+
+VedeuTestApp.start(ARGV)

data/config/cucumber.yml

@@ -0,0 +1,8 @@
+<%
+rerun = File.file?('rerun.txt') ? IO.read('rerun.txt') : ""
+rerun_opts = rerun.to_s.strip.empty? ? "--format #{ENV['CUCUMBER_FORMAT'] || 'progress'} features" : "--format #{ENV['CUCUMBER_FORMAT'] || 'pretty'} #{rerun}"
+  std_opts = "--format #{ENV['CUCUMBER_FORMAT'] || 'rerun'} --strict --tags ~@wip --tags ~@ok --tags ~@pending --tags ~@failing"
+%>
+default: <%= std_opts %> features --format rerun
+wip: --tags @wip:99 --wip features --format pretty
+rerun: <%= rerun_opts %> --format rerun --out rerun.txt --strict --tags ~@wip

data/docs/api.md

@@ -15,7 +15,7 @@ Doing it this way will mean you can use any API method without the `Vedeu.` pref
 class SomeClassInYourApplication
   include Vedeu
 
-  ...
+  # ...
 ```
 
 
@@ -25,13 +25,13 @@ Doing it this way means you need to use the `Vedeu.` prefix.
 
 ```ruby
 class OtherClassInYourApplication
-  ...
+  # ...
 
   def some_method
     Vedeu.some_api_method
   end
 
-  ...
+  # ...
 ```
 
 ... TODO ...
@@ -43,16 +43,17 @@ Note: Nesting indicates where an API method is allowed/supposed to be used.
 
 #### Events
 
-- event
+- bind
 - trigger
-- unevent
+- unbind
 
 
 #### Input
 
 - keypress
-- keys
+- keymap
   - key
+  - name
   - interface
 
 
@@ -60,32 +61,40 @@ Note: Nesting indicates where an API method is allowed/supposed to be used.
 
 - interface
   - background
-  - centred (or centred!)
+  - border
   - cursor
   - colour
   - delay
   - focus!
   - foreground
+  - geometry
+    - centred (or centred!)
+    - height
+    - width
+    - x
+    - y
   - group
-  - height
-  - keys
+  - keymap
+    - key
+    - name
+    - interface
   - line
   - name
   - style
   - use
-  - width
-  - x
-  - y
 
 
 #### Views
 
-- render
-  - views
-    - view
+- renders
   - view
     - colour
     - cursor
+    - geometry
+      - height
+      - width
+      - x
+      - y
     - line
       - background
       - colour
@@ -98,10 +107,17 @@ Note: Nesting indicates where an API method is allowed/supposed to be used.
         - style
         - text
         - width
+      - streams
+        - stream
+      - text
       - style
+    - lines
+      - line
     - name
     - style
   - use
+- views
+  - ... as #renders
 
 
 #### Menus
@@ -113,10 +129,23 @@ Note: Nesting indicates where an API method is allowed/supposed to be used.
 
 #### Miscellany
 
-- defined
+- configure
 - focus
+- focus_by_name
+- focussed?
+- focus_next
+- focus_previous
+
 - height
+  Usage: Vedeu.height
+  Returns the height (in lines) for the current terminal.
+
 - log
 - resize
+  Usage: Vedeu.resize
+
+
 - width
+  Usage: Vedeu.width
+  Returns the width (in characters) for the current terminal.
 

data/docs/events.md

@@ -5,10 +5,10 @@ Vedeu provides an event mechanism to facilitate the functionality of your applic
 Events described in this document assume that you have included Vedeu in your class:
 
 ```ruby
-  class SomeClassInYourApplication
-    include Vedeu
+class SomeClassInYourApplication
+  include Vedeu
 
-    ...
+  # ...
 ```
 
 ## System Events
@@ -43,9 +43,21 @@ Hides the cursor for the focussed interface.
 
 Shows the cursor for the focussed interface.
 
+### `:_cursor_hide_by_name_`
+
+Hides the cursor for the named interface.
+
+### `:_cursor_show_by_name_`
+
+Shows the cursor for the named interface.
+
+### `:_cursor_origin_`
+
+Moves the cursor to the top left position of the focussed interface. If this interface has a border,then this is respected.
+
 ### `:_exit_`
 
-When triggered, Vedeu will trigger a `:_cleanup_` event which you can define (to save files, etc) and attempt to exit.
+When triggered, Vedeu will trigger a `:cleanup` event which you can define (to save files, etc) and attempt to exit.
 
 ### `:_focus_by_name_`
 
@@ -130,7 +142,7 @@ When triggered will cause Vedeu to trigger the `:_clear_` and `:_refresh_` event
 
 ##### 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.
+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?
 
@@ -145,7 +157,7 @@ User events allow you to orchestrate behaviour within your application, ie. the
 
 Vedeu pre-defines a few user events, which client applications can listen for, or trigger themselves.
 
-### `:_cleanup_`
+### `:cleanup`
 
 Vedeu triggers this event 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.
 
@@ -165,13 +177,13 @@ client application for timing amongst other things.
 #### How to define user events
 
 ```ruby
-event :event_name do |arg1, arg2|
-  ...
+bind :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
 ```
 

data/docs/getting_started.md

@@ -1,2 +1,18 @@
 ## Getting Started with Vedeu
 
+### Predefined Keys
+
+Vedeu automatically defines four keys for your client application:
+
+  - q = Quit. Internally triggers the :_exit_ system event which in turn
+    requests the application stops. This triggers the event :cleanup which
+    the client application can bind to and perform any tidying up it wishes
+    to perform before exiting.
+
+  - <esc> = Mode Switch. Toggle between cooked and raw terminal modes.
+
+  - <tab> = Focus Next. Focus the next interface in the focus list.
+
+  - <shift+tab> = Focus Previous. Focus the previous interface in the focus
+    list.
+

data/docs/views.md

@@ -0,0 +1,158 @@
+## Views with Vedeu
+
+There are two ways to construct views with Vedeu. You would like to draw the
+view to the screen immediately (immediate render) or you want to save a view to
+be drawn when you trigger a refresh event later (deferred view).
+
+** LINK Both of these approaches require that you have defined an interface (or
+'visible area') first. You can find out how to define an interface with Vedeu
+here. The examples in 'Immediate Render' and 'Deferred View' use these interface
+definitions: (Note: if you use these examples, ensure your terminal is at least
+70 characters in width and 5 lines in height.)
+
+```ruby
+  Vedeu.interface 'main' do
+    geometry do
+      centred!
+      height 4
+      width  50
+    end
+  end
+
+  Vedeu.interface 'title' do
+    geometry do
+      height 1
+      width  50
+      x      use('main').left
+      y      use('main').north
+    end
+  end
+```
+
+Both of these approaches use a concept of Buffers in Vedeu. There are three
+buffers for any defined interface. These are imaginatively called: 'back',
+'front' and 'previous'.
+
+The 'back' buffer is the content for an interface which will be shown next time
+a refresh event is fired globally or for that interface. So, 'back' becomes
+'front'.
+
+The 'front' buffer is the content for an interface which is currently showing.
+When a refresh event is fired, again, globally or for that interface
+specifically, the content of this 'front' buffer is first copied to the
+'previous' buffer, and then the current 'back' buffer overwrites this 'front'
+buffer.
+
+The 'previous' buffer contains what was shown on the 'front' before the current
+'front'.
+
+You can only write to either the 'front' (you want the content to be drawn
+immediately) or the 'back' (you would like the content to be drawn on the next
+refresh).
+
+### Immediate Render
+
+The immediate render DSL for Vedeu is accessed via `Vedeu.renders`. When this
+approach is used, the content defined is written directly to the 'front'
+buffer(s) for the interface(s) concerned. Take a glance at the example below:
+
+```ruby
+  Vedeu.renders do
+    view 'title' do
+      line do
+        stream do
+          left 'Title goes here', width: 35
+        end
+        stream do
+          right Time.now.strftime('%H:%m'), width: 7
+        end
+      end
+    end
+    view 'main' do
+      lines do
+        line 'This is content for the main interface.'
+        line ''
+        line 'Pretty easy eh?'
+      end
+    end
+  end
+```
+
+### Deferred View
+
+The deferred view DSL for Vedeu is accessed via `Vedeu.views`. This approach
+writes the content defined to the 'back' buffer(s) for the interface(s)
+concerned. It will become the front when your application triggers the refresh
+event for the interface(s).
+
+As you can see by comparing the examples above to these below, the immediate
+render simply wraps what is already here in the deferred view. Again, more
+specific information is available in the Rubydoc.
+
+```ruby
+  Vedeu.views do
+    view 'title' do
+      line do
+        stream do
+          left 'Title goes here', width: 35
+        end
+        stream do
+          right Time.now.strftime('%H:%m'), width: 7
+        end
+      end
+    end
+    view 'main' do
+      lines do
+        line 'This is content for the main interface.'
+        line ''
+        line 'Pretty easy eh?'
+      end
+    end
+  end
+```
+
+### Notes on Geometry
+
+... TODO
+
+### Notes on Refresh
+
+... TODO
+
+### Notes on Building Views
+
+The basic view DSL methods look like this:
+
+renders/views
+  |-- view
+        |-- lines
+        |     |-- line
+        |           |-- streams
+        |           |     |-- stream
+        |           |           |-- char
+        |           |
+        |           |-- stream
+        |                 |-- char
+        |
+        |-- line
+              |-- streams
+              |     |-- stream
+              |           |-- char
+              |
+              |-- stream
+                    |-- char
+
+renders/views
+  |-- view
+        |-- lines/line
+              |-- streams/stream
+                    |-- char
+
+#### Authors Notes
+
+The Rubydoc documentation has more specific information about the DSL methods
+demonstrated above; it can be accessed here.
+
+I've tried to write the DSL in a way which makes it read nice; believing that
+this will make it easier to use. I hope this is the case for you.
+