automux 0.1.0 → 0.2.0

data/README.md

@@ -0,0 +1,322 @@
+Automux is a highly configurable Tmux automator inspired from similar projects like [Teamocil](https://github.com/remiprev/teamocil) & [Tmuxinator](https://github.com/aziz/tmuxinator).
+It provides more advanced configuration options like **getopts integration**, **custom indexes**  and **recipes** while keeping a strong focus on well designed, easily extendable code base.
+
+## Setup
+
+> Run these commands to get Automux started. Its easier to look at the different options later.
+
+```sh
+$ gem install automux
+$ automux setup
+$ automux
+```
+This should open 3 windows with 3 panes in the first window.
+
+## Blueprints & Recipes
+
+> The yaml configuration files are called **blueprints** while a logic to translate it into a shell script is called a **recipe**. Automux can be used with different combinations of blueprints and recipes.
+
+## Session, Windows and Panes
+
+> Automux stays true to tmux conventions for session, windows and panes. The first blueprint indentation level is for the `session`. Session can have many Windows all listed under the key `windows`.
+
+`windows` is an array of hashes. Just as in Tmux convention a window has atleast one pane, each hash should atleast have a blank `panes` key defined.
+
+```yaml
+name: test
+windows:
+  - name: blank
+  - panes:
+```
+The above blueprint will ask *automux* to create two shell windows with the first one named as blank.
+
+## Session Options
+
+__name__: helps to identify your session when `tmux ls` is run. Its the only field thats compulsory.
+
+__root__: automux will `cd` to this path before starting tmux.
+
+__windows__: an array of windows. A tmux session can be started with no windows defined.
+
+__flags__: session specific flags as given in the tmux man page.
+
+__options__: translates each key-value pair into `set-option`. See `man tmux` for the list of available options.
+
+__hooks__: is an hash with `pre` and `post` keys. The specified commands are run before starting and attaching session respectively.
+
+## Window Options
+
+__name__: optional name field.
+
+__layout__: layout can be one of the preset layouts(even-horizontal, even-vertical, main-horizontal, main-vertical, or tiled) or a custom defined value.
+
+__root__: automux will `cd` to this path before running the adding the pane.
+
+__panes__: is an array of commands for each pane in this window.
+
+__options__: translates each key-value pair into `set-window-option`. See `man tmux` for the list of available options.
+
+__hooks__: is an hash with `pre` and `post` keys. The specified commands are run before and after adding the panes respectively.
+
+__index__: index for the window.
+
+__opt__: makes the window optional. The window will not be created if the flag is not passed.
+
+## Default Blueprint
+
+> By default, `automux` uses the blueprint located at `$HOME/.automux/blueprints/default.yml`, which was copied during `automux setup`.
+
+```yaml
+name: test
+root: ~/
+flags: -u2
+options:
+  status-left: '#S>'
+hooks:
+  pre: echo 'Starting session'
+windows:
+  - name: panes
+    layout: tiled
+    panes:
+      - irb
+      - top
+      - ls
+  - name: vim
+    hooks:
+      pre:
+        - echo 'Starting vim'
+    panes: vim
+  - name: custom-indexed-window
+    index: 1
+    hooks:
+      post:
+        - echo 'Running <%= name %>'
+  - name: optional-window
+    opt: '-r'
+    panes:
+      - echo 'Created optional window'
+    options:
+      automatic-rename: off
+      window-status-bg: black
+```
+
+When an argument is passed, Automux will look for a blueprint with the specified name. For e.g., the following command will look for `custom.yml` under `$HOME/.automux/blueprints`
+```sh
+$ automux custom
+```
+The default blueprint can be changed to suit your needs. To get the original default blueprint back, run `automux setup` again.
+
+## Managing Blueprints
+
+> If __$EDITOR__ is undefined, `vi` will be used to open the blueprint.
+
+##### Create
+```sh
+$ automux blueprint create custom
+```
+This will clone the `default.yml` as `custom.yml` and open it in an editor.
+
+##### Edit
+```sh
+$ automux blueprint edit custom
+```
+
+##### Delete
+```sh
+$ automux blueprint delete custom
+```
+*aliased to __rm__*
+
+##### Copy
+```sh
+$ automux blueprint copy default custom
+```
+*aliased to __cp__*
+
+##### List
+```sh
+$ automux blueprint list
+```
+*aliased to __index__*
+
+## Command-line options
+
+> Automux can understand command-line options to make windows optional or provide input at runtime. Lets look at some examples.
+
+```yaml
+name: test
+root: '-r:'
+windows:
+  - name: top
+    opt: "-t"
+    panes: top
+```
+
+`automux test` will start Tmux with a window containing *shell*.
+
+`automux test -t` will start Tmux with a window containing *top*.
+
+`automux test -tr projects` will `cd` into the *projects* folder and then launch *top*.
+
+> The option can also be specified inside another command. This can be useful in cases like providing a branch name for a `git pull` at runtime:
+
+```yaml
+name: test
+windows:
+  - name: git
+    panes: git pull '-r:' master
+```
+
+* Note: The option needs to be surounded by quotes. It makes Automux's job easier.
+
+## Custom defined window indexes
+
+> Windows can have custom indexes which will be assigned to them at runtime. Lets look at an example.
+
+```yaml
+name: test
+windows:
+  - name: third
+    panes: ls
+  - name: fourth
+    panes: htop
+  - name: second
+    index: 1
+    panes: pwd
+  - name: first
+    index: 0
+    panes: [pwd, echo Hello]
+```
+
+Here the windows will be arranged in the order indicated by their names.
+
+#### Base Index
+
+As Automux tries to assign window indexes beforehand, it will overwrite any global **base-index** setting. To use a **base-index**, one would need to let Automux know about it like so:
+
+```yaml
+name: test
+options:
+  base-index: 2
+windows:
+  - panes: pwd
+  - panes: ls
+    index: 9
+```
+Here the indexing will start from 2 onwards.
+
+## The Automux Way
+
+> What would Tmux do?
+
+Automux is built on top of an ruby API for Tmux. Instead of providing a custom key for every possible Tmux option, its approach is to provide direct access to the session/window objects. This gives way for higher levels of customizations like allowing end users to add their own session/window methods and using them in the blueprints to letting them define their own recipes for logic. The following sections will look at some these approaches.
+
+### Hooks with ERB
+
+> Automux provides context specific ERB support for hooks.
+
+```yaml
+name: projects
+hooks:
+  pre: cd ~/<%= name %>
+windows:
+  - name: automux
+    hooks:
+      pre:
+       - cd <%= name %>
+       - pwd
+    panes: vim
+  - panes: pwd
+```
+
+This will execute the following steps
+
+* cd ~/projects
+* ... tmux startup stuff
+* ... create first window
+* cd automux
+* pwd   => ~/projects/automux
+* vim
+* ... create second window
+* pwd    => ~/projects
+
+The session/window hooks have access to session and window objects respectively.
+
+### Select/Focus Window
+
+To select a specific window when session is attached, Tmux provides the method `select-window`. Staying true to Tmux conventions, Automux's session object provides `select_window`.
+```yaml
+name: hooked
+hooks:
+  post:
+    - <%= select_window 'one' %>
+windows:
+  - name: one
+  - name: two
+```
+This selects the window named 'one' after all windows have been setup. Index number is also an acceptable parameter.
+
+### Link Window
+
+Tmux exposes the `link-window` method to link an existing window with current session.
+
+```yaml
+name: test
+hooks:
+  post:
+    - <%= link_window('primary', 'irb', 3)%>
+windows:
+  - panes: vim
+```
+
+This will link a window named *irb* from an existing session named *primary* as 3rd window in current session. The third parameter is optional just like Tmux would do.
+
+## Writing your own Recipe
+
+* `automux setup` copies a sample of the default recipe to `$HOME/recipes/default.sh.erb`. It looks like the following script:
+
+```
+cd <%= root %>
+
+= start_server
+= new_session
+
+- windows.each do |window|
+  = new_window(window)
+  = rename_window(window) if window.name
+
+  - if window.has_panes?
+    - window.panes.each do |pane|
+      = create_pane if pane.index > 0
+      = send_keys(window, pane.command)
+    - end
+  - end
+- end
+
+= attach_session
+```
+
+Its a simpler form of ERB much like [HAML](https://github.com/haml/haml) without indentation. The ERB is evaluated with session's context. Hence all methods defined for session are available here. The default recipe comes from the gem and cannot be overwritten. Custom recipes can be run like so:
+
+```sh
+$ automux default custom_recipe
+```
+_Here default is the default blueprint name._
+
+## Bash Autocompletion
+
+Currently blueprint names can be autocompleted. A dedicated autocompletion shell script is in the pipeline. For now add the following to your `~/.bashrc` to get autocompletion for blueprint names.
+
+```sh
+complete -W "$(automux blueprint list)" automux
+```
+
+## Coming Up
+
+* Bash Autocompletion for blueprint commands and recipe names.
+* Make Session and Window extendable on the client end.
+* Blueprint inheritance.
+
+## License
+
+MIT License. See LICENSE.txt for more details.

data/automux.gemspec

@@ -1,6 +1,7 @@
 # -*- encoding: utf-8 -*-
 $:.push File.expand_path("../lib", __FILE__)
 require 'automux/version'
+require 'automux/installation'
 
 Gem::Specification.new do |gem|
   gem.name          = 'automux'
@@ -10,9 +11,11 @@ Gem::Specification.new do |gem|
   gem.description   = %[Highly configurable Tmux Automator]
   gem.summary       = %[Automate tmux sessions stored in yaml files using custom recipes]
   gem.homepage      = %[https://github.com/notalex/automux]
+  gem.license       = %[MIT License]
 
   gem.files         = %x[git ls-files].split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = %w(lib)
+  gem.post_install_message = Automux::Installation::MESSAGE
 end

data/bin/automux

@@ -12,7 +12,7 @@ when 'setup'
   Automux::Controller::Setup.new.clone_defaults
 when 'blueprint'
   params = { blueprint_name: args[2], clone_name: args[3] }
-  Automux::Controller::Blueprints.new(params).send(args[1])
+  Automux::Controller::Blueprints.new(params).public_send(args[1])
 else
   params = {
     blueprint_name: args[0] || 'default',

data/data/automux/blueprints/default.yml

@@ -2,10 +2,12 @@ name: test
 root: ~/
 flags: -u2
 options:
-  status: off
+  status-left: '#S>'
+hooks:
+  pre: echo 'Starting session'
 windows:
   - name: panes
-    layout: main-vertical
+    layout: tiled
     panes:
       - irb
       - top
@@ -24,3 +26,6 @@ windows:
     opt: '-r'
     panes:
       - echo 'Created optional window'
+    options:
+      automatic-rename: off
+      window-status-bg: black

data/data/automux/recipes/default.sh.erb

@@ -39,8 +39,8 @@ cd <%= root %>
   - end
 - end
 
-= attach_session
-
 - post_hooks.each do |hook|
   = hook.command
 - end
+
+= attach_session

data/features/session_hooks.feature

@@ -8,7 +8,11 @@ Feature: Using pre and post hooks for session
         pre:
           - "echo Hello"
           - "rvm use automux"
-        post: "echo 'I will be back'"
+        post:
+          - <%= select_window 'one' %>
+      windows:
+        - name: one
+        - name: two
       """
     When I invoke Automux with the blueprint "test_sample"
     Then the rendered sequence of shell commands should be
@@ -21,9 +25,17 @@ Feature: Using pre and post hooks for session
       tmux start-server
       tmux new-session -d -s hooked
 
-      tmux attach-session -t hooked
+      tmux new-window -t hooked:0 2> /dev/null
+      tmux rename-window -t hooked:0 one
+      tmux send-keys -t hooked:0 "" C-m
 
-      echo 'I will be back'
+      tmux new-window -t hooked:1 2> /dev/null
+      tmux rename-window -t hooked:1 two
+      tmux send-keys -t hooked:1 "" C-m
+
+      tmux select-window -t hooked:0
+
+      tmux attach-session -t hooked
       """
 
   Scenario: Using window hooks

data/features/step_definitions/setup_windows_steps.rb

@@ -13,6 +13,6 @@ Then(/^the window with the name "(.+)" should have the following$/) do |name, ta
   window = @session.windows.find { |window| window.name == name }
   params = common_transformations(table.hashes).first
   params.each do |field, value|
-    window.send(field).must_equal value
+    window.public_send(field).must_equal value
   end
 end

data/features/step_definitions/shared_steps.rb

@@ -33,7 +33,7 @@ end
 
 def expected_array_for(string)
   expected_string = string.gsub(/\$HOME/, ENV['HOME'])
-  expected_array = expected_string.split("\n").reject { |text| text.split.empty? }
+  expected_array = expected_string.squeeze("\n").split("\n")
   expected_array.map { |text| text.strip }
 end
 

data/lib/automux/controller/blueprints.rb

@@ -36,6 +36,11 @@ module Automux
       end
       alias_method :rm, :delete
 
+      def index
+        render 'index'
+      end
+      alias_method :list, :index
+
       private ###
 
       def load_blueprint

data/lib/automux/controller/support/rendering.rb

@@ -41,7 +41,7 @@ module Automux
 
         # The recipe files can have empty lines for clarity. Remove them here.
         def remove_empty_lines(string)
-          string.split("\n").reject { |text| text.strip.empty? }.join("\n")
+          string.gsub(/\n\s+\n/, "\n")
         end
 
         # Remove all parent namespacing.

data/lib/automux/core/tmux/session.rb

@@ -47,6 +47,19 @@ module Automux
           %[tmux send-keys -t #{ name }:#{ window.index } "#{ command }" C-m]
         end
 
+        def select_window(identifier)
+          window = get_window(identifier)
+          %[tmux select-window -t #{ name }:#{ window.index }]
+        end
+
+        # Links window from source session to current session. Window name or index must be provided.
+        #
+        # E.g.: link_window(primary, finch, 3)
+        # This links a window named *finch* from an existing session named *primary* as 3rd window in current session.
+        def link_window(source_session_name, source_window_identifier, index = nil)
+          %[tmux link-window -s #{ source_session_name }:#{ source_window_identifier } -t #{ name }:#{ index }]
+        end
+
         def attach_session
           %[#{ tmux_with_flags } attach-session -t #{ name }]
         end

data/lib/automux/initializers/setup_editor.rb

@@ -1 +1 @@
-ENV['EDITOR'] ||= 'vim'
+ENV['EDITOR'] ||= 'vi'

data/lib/automux/installation.rb

@@ -0,0 +1,10 @@
+module Automux
+  module Installation
+    MESSAGE = <<-END
+********************************************************************************
+Please run the following the following command to setup default Automux folders:
+$ automux setup
+********************************************************************************
+    END
+  end
+end

data/lib/automux/version.rb

@@ -1,5 +1,5 @@
 module Automux
   module Version
-    STRING = '0.1.0'
+    STRING = '0.2.0'
   end
 end

data/lib/automux/views/blueprints/delete.sh.erb

@@ -0,0 +1,2 @@
+rm <%= path %>
+echo <%= File.basename(path) %> deleted

data/lib/automux/views/blueprints/index.sh.erb

@@ -0,0 +1,4 @@
+for filename in $(ls <%= Automux::Paths::blueprints_container %>)
+do
+  echo ${filename%.yml}
+done

data/lib/automux.rb

@@ -1,4 +1,5 @@
 require 'automux/version'
+require 'automux/installation'
 require 'automux/paths'
 require 'automux/library'
 require 'automux/core'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: automux
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-01 00:00:00.000000000 Z
+date: 2013-04-02 00:00:00.000000000 Z
 dependencies: []
 description: Highly configurable Tmux Automator
 email:
@@ -23,6 +23,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
+- README.md
 - automux.gemspec
 - bin/automux
 - data/automux/blueprints/default.yml
@@ -74,6 +75,7 @@ files:
 - lib/automux/initializers/custom_hooks.rb
 - lib/automux/initializers/setup_caches.rb
 - lib/automux/initializers/setup_editor.rb
+- lib/automux/installation.rb
 - lib/automux/library.rb
 - lib/automux/library/mini_erb.rb
 - lib/automux/library/yaml_parser.rb
@@ -81,7 +83,9 @@ files:
 - lib/automux/version.rb
 - lib/automux/views/blueprints/copy.sh.erb
 - lib/automux/views/blueprints/create.sh.erb
+- lib/automux/views/blueprints/delete.sh.erb
 - lib/automux/views/blueprints/edit.sh.erb
+- lib/automux/views/blueprints/index.sh.erb
 - lib/automux/views/messages/error.sh.erb
 - lib/automux/views/setup/clone_defaults.sh.erb
 - test/session_test.rb
@@ -90,8 +94,17 @@ files:
 - test/support/hash_factory.rb
 - test/support/test_helper.rb
 homepage: https://github.com/notalex/automux
-licenses: []
-post_install_message: 
+licenses:
+- MIT License
+post_install_message: ! '********************************************************************************
+
+  Please run the following the following command to setup default Automux folders:
+
+  $ automux setup
+
+  ********************************************************************************
+
+'
 rdoc_options: []
 require_paths:
 - lib