cmds 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5caaa2f3116bf7e3a3d0d177334117a3877a0c30
+  data.tar.gz: a9c58cb91f4f58eec0317d6dadf19d5b645d9d74
+SHA512:
+  metadata.gz: d1386ff56087d5031e83ec65e26e0582c551f0df1a7df48661448a046a4b04d5e1391f4133804762a17783b3daa982594227d48702a73e28567ac42c91fd7901
+  data.tar.gz: d8f87632411dca1a6195eafaf66f45ab0636190e4771a19a2e30bb6859a5d2725c860dd2c44be9867404efc0df0f9c5e808877eac019f3f43a0b6eae61846052

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+ref/repos

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# use local
+gem 'nrser', '~> 0.0', :path => '../nrser-ruby'
+
+# Specify your gem's dependencies in cmds.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 nrser
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,333 @@
+# cmds
+
+cmds tries to make it easier to read, write and remember using shell commands in Ruby.
+
+it treats generating shell the in a similar fashion to generating SQL or HTML.
+
+
+## status
+
+eh, it's kinda starting to work... i'll be using it for stuff and seeing how it goes, but no promises until `1.0` of course.
+
+
+## installation
+
+Add this line to your application's Gemfile:
+
+```
+gem 'cmds'
+```
+
+
+And then execute:
+
+```
+$ bundle
+```
+
+
+Or install it yourself as:
+
+```
+$ gem install cmds
+```
+
+
+
+## real-world examples
+
+instead of
+
+```
+`psql -U #{ db_config['username'] || ENV['USER'] } #{ db_config['database']} < #{ filepath.shellescape }`
+```
+
+write
+
+```
+Cmds 'psql %{opts} %{db} < %{dump}',
+  db: db_config['database'],
+  dump: filepath,
+  opts: {
+    username: db_config['username'] || ENV['USER']
+  }
+```
+
+instead of
+
+```
+`aws s3 sync s3://#{ PROD_APP_NAME } #{ s3_path.shellescape }`
+```
+
+write
+
+```
+Cmds 'aws s3 sync %{uri} %{path}', uri: "s3://#{ PROD_APP_NAME }"
+                                   path: s3_path
+```
+
+instead of
+
+```
+`PGPASSWORD=#{ config[:password].shellescape } pg_dump -U #{ config[:username].shellescape } -h #{ config[:host].shellescape } -p #{ config[:port] } #{ config[:database].shellescape } > #{ filepath.shellescape }`
+```
+
+write
+
+```
+Cmds 'PGPASSWORD=%{password} pg_dump %{opts} %{database} > %{filepath}',
+  password: config[:password],
+  database: config[:database],
+  filepath: filepath,
+  opts: {
+    username: config[:username],
+    host: config[:host],
+    port: config[:port],
+  }
+```
+
+
+
+## substitutions
+
+substitutions can be positional, keyword, or both.
+
+### positional
+
+positional arguments can be substituted in order using the `arg` method call:
+
+```
+Cmds.sub "psql <%= arg %> <%= arg %> < <%= arg %>", [
+  {
+    username: "bingo bob",
+    host: "localhost",
+    port: 12345,
+  },
+  "blah",
+  "/where ever/it/is.psql",
+]
+# => 'psql --host=localhost --port=12345 --username=bingo\ bob blah < /where\ ever/it/is.psql'
+```
+
+internally this translates to calling `@args.fetch(@arg_index)` and increments `@arg_index` by 1.
+
+this will raise an error if it's called after using the last positional argument, but will not complain if all positional arguments are not used. this prevents using a keyword arguments named `arg` without accessing the keywords hash directly. 
+
+the arguments may also be accessed directly though the bound class's `@args` instance variable:
+
+```
+Cmds.sub "psql <%= @args[2] %> <%= @args[0] %> < <%= @args[1] %>", [
+  "blah",
+  "/where ever/it/is.psql",
+  {
+    username: "bingo bob",
+    host: "localhost",
+    port: 12345,
+  },
+]
+# => 'psql --host=localhost --port=12345 --username=bingo\ bob blah < /where\ ever/it/is.psql'
+```
+
+note that `@args` is a standard Ruby array and will simply return `nil` if there is no value at that index (though you can use `args.fetch(i)` to get the same behavior as the `arg` method with a specific index `i`).
+
+### keyword
+
+keyword arguments can be accessed by making a method call with their key:
+
+```
+Cmds.sub "psql <%= opts %> <%= database %> < <%= filepath %>",
+  [],
+  database: "blah",
+  filepath: "/where ever/it/is.psql",
+  opts: {
+    username: "bingo bob",
+    host: "localhost",
+    port: 12345,
+  }
+# => 'psql --host=localhost --port=12345 --username=bingo\ bob blah < /where\ ever/it/is.psql'
+```
+
+this translates to a call of `@kwds.fetch(key)`, which will raise an error if `key` isn't present.
+
+there are four key names that may not be accessed this way due to method definition on the context object:
+
+* `arg` (see above)
+* `initialize`
+* `get_binding`
+* `method_missing`
+
+though keys with those names may be accessed directly via `@kwds.fetch(key)` and the like.
+
+to test for a key's presence or optionally include a value, append `?` to the method name:
+
+```
+c = Cmds.new <<-BLOCK
+  defaults
+  <% if current_host? %>
+    -currentHost <%= current_host %>
+  <% end %>
+  export <%= domain %> <%= filepath %>
+BLOCK
+
+c.call domain: 'com.nrser.blah', filepath: '/tmp/export.plist'
+# defaults export com.nrser.blah /tmp/export.plist
+
+c.call current_host: 'xyz', domain: 'com.nrser.blah', filepath: '/tmp/export.plist'
+# defaults -currentHost xyz export com.nrser.blah /tmp/export.plist
+```
+
+### both
+
+both positional and keyword substitutions may be provided:
+
+```
+Cmds.sub "psql <%= opts %> <%= arg %> < <%= filepath %>",
+  ["blah"],
+  filepath: "/where ever/it/is.psql",
+  opts: {
+    username: "bingo bob",
+    host: "localhost",
+    port: 12345,
+  }
+# => 'psql --host=localhost --port=12345 --username=bingo\ bob blah < /where\ ever/it/is.psql'
+```
+
+this might be useful if you have a simple positional command like
+
+```
+Cmds "blah <%= arg %>", ["value"]
+```
+
+and you want to quickly add in some optional value
+
+```
+Cmds "blah <%= maybe? %> <%= arg %>", ["value"]
+Cmds "blah <%= maybe? %> <%= arg %>", ["value"], maybe: "yes!"
+```
+
+### shortcuts
+
+there are support for `sprintf`-style shortcuts.
+
+**positional**
+
+`%s` is replaced with `<%= arg %>`.
+
+so
+
+```
+Cmds.sub "./test/echo_cmd.rb %s", ["hello world!"]
+```
+
+is the same as
+
+```
+Cmds "./test/echo_cmd.rb <%= arg %>", ["hello world!"]
+```
+
+**keyword**
+
+`%{key}` and `%<key>s` are replaced with `<%= key %>`, and `%{key?}` and `%<key?>s` are replaced with `<%= key? %>` for optional keywords.
+
+so
+
+```
+Cmds "./test/echo_cmd.rb %{key}", key: "hello world!"
+```
+
+and
+
+```
+Cmds "./test/echo_cmd.rb %<key>s", key: "hello world!"
+```
+
+are the same is
+
+```
+Cmds "./test/echo_cmd.rb <%= key %>", key: "hello world!"
+```
+
+**escaping**
+
+strings that would be replaced as shortcuts can be escaped by adding one more `%` to the front of them:
+
+```
+Cmds.sub "%%s" # => "%s"
+Cmds.sub "%%%<key>s" # => "%%<key>s"
+```
+
+note that unlike `sprintf`, which has a much more general syntax, this is only necessary for patterns that exactly match a shortcut, not `%` in general:
+
+```
+Cmds.sub "50%" # => "50%"
+```
+
+
+
+## reuse commands
+
+```
+playbook = Cmds.new "ansible-playbook -i %{inventory} %{playbook}"
+playbook.call inventory: "./hosts", playbook: "blah.yml"
+```
+
+currying
+
+```
+dev_playbook = playbook.curry inventory: "inventory/dev"
+prod_playbook = playbook.curry inventory: "inventory/prod"
+
+# run setup.yml on the development hosts
+dev_playbook.call playbook: "setup.yml"
+
+# run setup.yml on the production hosts
+prod_playbook.call playbook: "setup.yml"
+```
+
+
+
+## defaults
+
+NEEDS TEST
+
+can be accomplished with reuse and currying stuff
+
+```
+playbook = Cmds.new "ansible-playbook -i %{inventory} %{playbook}", inventory: "inventory/dev"
+
+# run setup.yml on the development hosts
+playbook.call playbook: "setup.yml"
+
+# run setup.yml on the production hosts
+prod_playbook.call playbook: "setup.yml", inventory: "inventory/prod"
+```
+
+
+
+## future..?
+
+### formatters
+
+kinda like `sprintf` formatters or string escape helpers in Rails, they would be exposed as functions in ERB and as format characters in the shorthand versions:
+
+```
+Cmds "blah <%= j obj %>", obj: {x: 1}
+# => blah \{\"x\":1\}
+
+Cmds "blah %j", [{x: 1}]
+# => blah \{\"x\":1\}
+
+Cmds "blah %<obj>j", obj: {x: 1}
+# => blah \{\"x\":1\}
+```
+
+the `s` formatter would just format as an escaped string (no different from `<%= %>`).
+
+other formatters could include
+
+* `j` for JSON (as shown above)
+* `r` for raw (unescaped)
+* `l` or `,` for comma-separated list (which some commands like as input)
+* `y` for YAML
+* `p` for path, joining with `File.join`
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/ansible/dev.yml

@@ -0,0 +1,25 @@
+---
+- hosts: localhost
+
+  vars:
+
+    ref_repos:
+      github:
+      - owner:    rails
+        name:     rails
+        version:  master
+        dir_name: rails
+
+  tasks:
+
+  - name: install gems
+    command: bundle install --path=.bundle
+    args:
+      chdir: ..
+
+  - name: clone reference repos
+    git: repo=git@github.com:{{ item.owner }}/{{ item.name }}
+         dest="../ref/repos/{{ item.dir_name }}"
+         update=no
+         version={{ item.version }}
+    with_items: ref_repos.github

data/ansible/hosts

@@ -0,0 +1,6 @@
+localhost ansible_connection=local
+
+alamo.beiarea.com ansible_connection=ssh ansible_ssh_user=root
+
+[production]
+alamo.beiarea.com

data/cmds.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cmds/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "cmds"
+  spec.version       = Cmds::VERSION
+  spec.authors       = ["nrser"]
+  spec.email         = ["neil@ztkae.com"]
+  spec.summary       = %q{helps read, write and remember commands.}
+  # spec.description   = %q{TODO: Write a longer description. Optional.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'nrser', '~> 0.0.11'
+  spec.add_dependency 'erubis', '~> 2.7.0'
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/cmds/version.rb

@@ -0,0 +1,3 @@
+class Cmds
+  VERSION = "0.0.1"
+end