toggle 0.0.0.alpha → 1.0.0.rc

data/.gitignore

@@ -3,6 +3,7 @@
 .bundle
 .config
 .yardoc
+.rvmrc
 Gemfile.lock
 InstalledFiles
 _yardoc

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/CONTRIBUTING.md

@@ -0,0 +1,14 @@
+Contributing
+============
+
+If you would like to contribute code to Toggle you can do so through GitHub by
+forking the repository and sending a pull request.
+
+When submitting code, please make every effort to follow existing conventions
+and style in order to keep the code as readable as possible.
+
+Before your code can be accepted into the project you must also sign the
+[Individual Contributor License Agreement (CLA)][1].
+
+
+ [1]: https://spreadsheets.google.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in toggle.gemspec
+# Specify your gem's dependencies in switch.gemspec
 gemspec

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2013 Square Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -1,6 +1,37 @@
 # Toggle
 
-Toggle is coming soon!
+Toggle provides an organized and flexible framework to set up, manage, and
+switch between different configuration settings in your Ruby scripts.
+
+## Why?
+
+Ensuring that a script has the correct configuration settings can become a real
+headache. Have you ever had to run a script under different environment
+specifications or had to share a script that requires different settings based
+on who is running the code?
+
+You may have resorted to storing configuration information in a hash to the top
+of a given script to provide some flexibility. This can work for a script or
+two and when your on a small team, but as you write more code or increase your
+team's size the need for organization while still maintaining flexibility
+quickly arises.
+
+Having a common pattern around how per-project configurations are handled
+becomes a big plus. Projects like [rbenv-vars](https://github.com/sstephenson/rbenv-vars)
+came about to help solve issues like these.
+
+Toggle provides a project with rbenv-vars-like functionality with two main
+additions:
+
+1. rbenv is not required
+2. you can specify *multiple* environment setups instead of just one on a
+   per-project basis, each of which is easily switchable to either programmatically
+   or at runtime.
+
+Additionally, Toggle provides a command line interface to facilitate setting up
+this framework along with a set of options to quickly inspect which variables are
+available within a project and what each variable is set to for a given environment
+specification.
 
 ## Installation
 
@@ -16,14 +47,279 @@ Or install it yourself as:
 
     $ gem install toggle
 
-## Usage
+## Basic Usage
+
+To start using Toggle you first need a configuration file. This file
+will typically be in YAML format and can contain inline ERB. The file's content
+will include all the different configuration sections you want to be able to toggle to.
+Each section should be namespaced appropriately.
+
+As an example let's say we have two different script configurations we'd like to
+have available and we name each `alpha` and `beta` respectively. Then our
+configuration file might look like:
+
+```yaml
+# Sample config.yml demonstrating Toggle usage.
+# Notice that each section contains the same keys but the values vary.
+:alpha:
+  :name: mr_alpha
+  :secret: <%= ENV['ALPHA_SECRET'] %> # pretend this is "alpha-secret"
+
+:beta:
+  :name: mr_beta
+  :secret: <%= ENV['BETA_SECRET'] %> # pretend this is "beta-secret"
+```
+
+Now in any script we can leverage Toggle to toggle between each configuration
+section by setting the `key` attribute, which will load the corresponding
+configuration section:
+
+```ruby
+require 'toggle'
+toggle = Toggle.new config_filepath: './config.yml'
+
+toggle.key = :alpha
+puts "#{toggle[:name]} has a secret: #{toggle[:secret]}!"
+#=> mr_alpha has a secret: alpha-secret
+
+toggle.key = :beta
+puts "#{toggle[:name]} has a secret: #{toggle[:secret]}!"
+#=> mr_beta has a secret: beta-secret
+```
+
+Toggle also supports temporary access to a configuration section by passing a
+block to `#using`:
+
+```ruby
+require 'toggle'
+
+toggle = Toggle.new config_filepath: './config.yml',
+                    key:             :beta
+
+toggle.using(:alpha) do |s|
+  puts "#{s[:name]} has a secret: #{s[:secret]}!"
+  #=> mr_alpha has a secret: alpha-secret
+end
+
+puts "#{toggle[:name]} has a secret: #{toggle[:secret]}!"
+#=> mr_beta has a secret: beta-secret
+```
+
+As an alternative to specifying the `key` attribute programmatically, you can
+create a key file:
+
+```yaml
+# sample key.yml file
+alpha
+```
+
+and then set Toggle's `key_filepath` attribute to specify where the `key`'s
+value should be derived from:
+
+```ruby
+require 'toggle'
+
+toggle = Toggle.new config_filepath: './config.yml',
+                    key_filepath:    './key.yml'
+
+puts "#{toggle[:name]} has a secret: #{toggle[:secret]}!"
+#=> mr_alpha has a secret: alpha-secret
+```
+
+## Realworld Use Case: Runtime Toggling
+
+Let's say there is a developer named Jane and she wants to author a script that
+connects to a database server, pulls in data and does some processing, and then
+emails the results to her team.
+
+As she developes the script she wants to pull data from a staging database and
+just email the results to herself so she can see how the final product would
+look without bothering the whole team until the finished product is ready.
+
+Once everything is complete she wants to pull data from a production database
+and send the email.
+
+With Toggle, this is easy:
+
+```yaml
+# Jane's sample config.yml
+:development:
+  :who_to_email: 'jane@company.com'
+
+  :database:
+    :host: https://staging.data.company.com
+    :name: some_staging_db
+    :table: some_staging_table
+    :username: jane
+    :password: <%= ENV['DATABASE_PASSWORD'] %>
+
+:production:
+  :who_to_email: 'team@company.com'
+
+  :database:
+    :host: https://prod.data.company.com
+    :name: some_prod_db
+    :table: some_prod_table
+    :username: jane
+    :password: <%= ENV['DATABASE_PASSWORD'] %>
+```
+
+```ruby
+# Jane's sample email_data.rb script
+require 'toggle'
+
+toggle = Toggle.new config_filepath: './config.yml',
+                    key:             ENV['key']
+
+connection = SomeDBDriver.connect host:     toggle[:database][:host]
+                                  username: toggle[:database][:username]
+                                  password: toggle[:database][:password]
 
-TODO: Write usage instructions here
+data = connection.get_data_from database: toggle[:database][:name],
+                                table:    toggle[:database][:table]
+
+SomeEmailer.send to:   toggle[:who_to_email],
+                 what: data
+```
+
+Now running `email_data.rb` under the development configuration settings is a
+snap:
+
+    $ key=development ruby email_data.rb
+    # => will connect to the staging db + just email jane
+
+And when it's deemed ready for primetime it can be run with the production
+configuration settings via:
+
+    $ key=production ruby email_data.rb
+    # => will connect to the prod db + email the team
+
+## Realworld Use Case: Abstracted Configuration and Sharing
+
+Continuing with our example from above, let's say that Jane needs to share the
+script with John who is another developer on her team so he can work on it
+(perhaps he wants to add in logic that does not send an email if no data is
+returned so the team doesn't receive an empty email).
+
+Jane can further abstract her `config.yml` file to faciliate quick sharing
+between co-workers:
+
+```yaml
+# Jane's new sample config.yml
+#
+# Notice that we have abstracted out the email address, database username and
+# password into ENV vars
+:development:
+  :who_to_email: <%= ENV['USER_EMAIL'] %>
+
+  :database:
+    :host: https://staging.data.company.com
+    :name: some_staging_db
+    :table: some_staging_table
+    :username: <%= ENV['DATABASE_USERNAME'] %>
+    :password: <%= ENV['DATABASE_PASSWORD'] %>
+
+:production:
+  :who_to_email: 'team@company.com'
+
+  :database:
+    :host: https://prod.data.company.com
+    :name: some_prod_db
+    :table: some_prod_table
+    :username: <%= ENV['DATABASE_USERNAME'] %>
+    :password: <%= ENV['DATABASE_PASSWORD'] %>
+```
+
+John is a `git clone` (or whatever vcs he is using) away from having the
+script downloaded locally and ready to run without requiring any configuration
+edits.
+
+In fact, anyone that has `DATABASE_USERNAME`, `DATABASE_PASSWORD`
+and `USER_EMAIL` set in their environment can run this script without requiring
+any configuration adjustments.
+
+In general if your team uses any common variables you should consider
+abstracting each into environment variables and including them via ERB. Toggle
+comes with an easy way to set this up on a per-computer basis. First, run:
+
+    $ toggle --init-local
+
+This will create `~/.toggle.local`, which you can then edit to `export` any
+variables you want to be available in your environment. Finally, make sure
+you source this file so your variables are ready to go.
+
+## Ignoring the Config and Key Files
+
+If you can effectively abstract out all configuration settings in environment
+variables, you may be able to just commit your `config.yml` and your `key.yml`
+files to source control.
+
+However, consider .gitignore-ing each and providing a `config.yml.default` and
+key.yml.default` in their place. With these default files in place you provide
+runtime guidance, but allow each developer to make any local adjustments without
+running the risk of having these changes committed back to the project's repo
+and breaking someone else's settings when they pull in the latest changes.
+
+Again, borrowing from the above example, if Jane were to instead provide
+`config.yml.default` and `key.yml.default` files in her repo, anyone that
+downloaded her repo would need to copy each file to their appropriate location
+(`config.yml` and `key.yml` respectively) so the script could run. This can be
+easily accomplished via:
+
+    $ toggle --copy-defaults project/path
+
+or you can do this manually via:
+
+    $ cp project/path/config.yml.default project/project/config.yml
+    $ cp project/path/key.yml.default    project/project/key.yml
+
+## Toggle CLI
+
+Toggle comes bundled with a commandline interface:
+
+```
+$ toggle --help
+Usage: toggle <args>
+
+Specific arguments:
+    -g, --init-local [PATH]           Adds [PATH]/.toggle.local with var placeholders. Default is $HOME.
+    -k, --keys file                   Show available keys for the specified config FILE
+        --values FILE,KEY             Show values for the KEY in the config FILE
+        --copy-config-defaults [PATH]
+                                      Copy all toggle config defaults to actuals in PATH. Default is pwd.
+    -c, --copy-defaults [PATH]        Copy all .toggle.default to .toggle for PATH. Default is pwd.
+        --ensure-key [PATH]           Copies the default key in [PATH] if actual key is not present, does nothing otherwise. Default [PATH] is pwd.
+    -m, --make-defaults [PATH]        Create [PATH]/{config|key}{,.*}.default. Default is pwd.
+    -v, --version                     Show version
+    -h, --help                        Show this message
+```
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+If you would like to contribute code to Toggle you can do so through GitHub by
+forking the repository and sending a pull request.
+
+When submitting code, please make every effort to follow existing conventions
+and style in order to keep the code as readable as possible.
+
+Before your code can be accepted into the project you must also sign the
+[Individual Contributor License Agreement (CLA)][1].
+
+
+ [1]: https://spreadsheets.google.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1
+
+## License
+
+Copyright 2013 Square Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/Rakefile

@@ -1 +1,28 @@
+#!/usr/bin/env rake
 require "bundler/gem_tasks"
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.rspec_opts = '-b'
+  end
+
+  task default: :spec
+rescue LoadError
+  $stderr.puts "rspec not available, spec task not provided"
+end
+
+begin
+  require 'cane/rake_task'
+
+  desc "Run cane to check quality metrics"
+  Cane::RakeTask.new(:quality) do |cane|
+    cane.abc_max    = 10
+    cane.style_glob = "lib/**/*.rb"
+    cane.no_doc     = true
+  end
+
+  task :default => :quality
+rescue LoadError
+  warn "cane not available, quality task not provided."
+end

data/bin/toggle

@@ -0,0 +1,200 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+
+require 'toggle'
+require 'optparse'
+require 'fileutils'
+
+def default_key_filepath
+  File.expand_path('../../defaults/key.yml.default', __FILE__)
+end
+
+def default_config_filepath
+  File.expand_path('../../defaults/config.yml.default', __FILE__)
+end
+
+def wants_to_force_copy? current_file
+  respond_yes_to? "File #{current_file} exists. Replace?"
+end
+
+def actual_key_in path
+  find_file_in path, /^(key(\.yml))?$/
+end
+
+def actual_config_in path
+  find_file_in path, /^config\.yml$/
+end
+
+# finds the first file in "path" arg that matches "regex" pattern
+# returns path + filename
+def find_file_in path, regex
+  file = Dir[File.join(path, '*')].map { |filepath|
+    File.basename filepath
+  }.find { |filename|
+    filename =~ regex
+  }
+
+  file ? File.join(path, file) : nil
+end
+
+# Returns true if response starts with a 'y' or 'Y' (as in 'yes')
+# Returns false if response starts with a 'n' or 'N' (as in 'no')
+# Aborts if response starts with a 'q' or 'Q' (as in 'quit')
+def respond_yes_to? prompt
+  print "#{prompt} (y/n/q) "
+  normalized_response = gets[0].chomp.downcase
+  normalized_response.eql?('q') ? abort('... quitting') : normalized_response.eql?('y')
+end
+
+# The reference file is guaranteed to exist
+def identical_files? reference_file, other_file
+  File.exists?(other_file) && FileUtils.identical?(reference_file, other_file)
+end
+
+# Method requires a path and file_pattern and recursively searchs for matching
+# files.
+#
+# When a match is found, method detects if the default is the same as the
+# "actual" (the same filename just without the .default).
+#
+# If the files are identical, the method does nothing. If the actual file does
+# not exist OR the user opts to clobber the existing, the default will replace
+# the actual. Otherwise, the actual is left as is.
+def recursively_copy_defaults path, file_pattern, options = {}
+  defaults = {attempt_force_copy: true}
+  options  = defaults.merge(options)
+
+  attempt_force_copy = options[:attempt_force_copy]
+
+  Dir[File.join(path, '/**/', file_pattern)].each do |default_file|
+    file = default_file.slice(/(.*)\.default$/, 1)
+
+    if identical_files? default_file, file
+      puts "Default is identical to #{file}, skipping!"
+    elsif !File.exists?(file) || (attempt_force_copy && wants_to_force_copy?(file))
+      puts "Copying #{file} from default"
+      FileUtils.cp default_file, file
+    else
+      puts "Not changing #{file}"
+    end
+  end
+end
+
+opt_parser = OptionParser.new do |opts|
+  opts.banner = "Usage: toggle <args>"
+  opts.separator ""
+  opts.separator "Specific arguments:"
+
+  opts.on('-g', '--init-local [PATH]', String, 'Adds [PATH]/.toggle.local with var placeholders. Default is $HOME.') do |path|
+    path ||= ENV['HOME']
+
+    if path && path.empty?
+      raise RuntimeError, 'You must specify a PATH or have HOME env set!'
+    end
+
+    local_config = File.join(path, '.toggle.local')
+    sourcing_bash_instructions = "if [ -s ~/.toggle.local ] ; then source ~/.toggle.local ; fi"
+
+    if !File.exists?(local_config) || wants_to_force_copy?(local_config)
+      content = <<-EOS.strip_heredoc
+        # Add any variables that you'd like below.
+        #
+        # We've included a few suggestions, but please feel free
+        # to modify as needed.
+        #
+        # Make sure that you source this file in your ~/.bash_profile
+        # or ~/.bashrc (or whereever you'd like) via:
+        #
+        # #{sourcing_bash_instructions}
+        export DATABASE_HOST=''
+        export DATABASE_NAME=''
+        export DATABASE_USERNAME=''
+        export DATABASE_PASSWORD=''
+        export USER_EMAIL=''
+      EOS
+
+      %x(echo "#{content}" > #{local_config})
+      puts "Local toggle config added at #{local_config}"
+      puts "Now edit the file and source it from ~/.bash_profile or ~/.bashrc via: #{sourcing_bash_instructions}"
+    else
+      puts "Not changing #{local_config}"
+    end
+  end
+
+  opts.on("-k", "--keys file", String, "Show available keys for the specified config FILE") do |file|
+    opts.banner = "Usage: toggle --keys FILE"
+
+    if File.exists? file
+      toggle = Toggle::Compiler.new(file).parsed_content
+      puts toggle.keys.map{|k| "- #{k}"}.join("\n")
+    else
+      puts "toggle config file not found, please check specified path"
+    end
+  end
+
+  # TODO: remove yaml preamble
+  opts.on("--values FILE,KEY", Array, "Show values for the KEY in the config FILE") do |params|
+    opts.banner = "Usage: toggle --values FILE,KEY"
+
+    if File.exists?(file = params[0])
+      toggle = Toggle::Compiler.new(file).parsed_content
+      if toggle.keys.include?(key = params[1].to_sym)
+        puts toggle[key].to_yaml.gsub(/(:password:).+/, "\\1 [redacted]")
+      else
+        puts "#{key} not found in #{file}"
+      end
+    else
+      puts "toggle config file not found, please check specified path"
+    end
+  end
+
+  opts.on('--copy-config-defaults [PATH]', String, 'Copy all toggle config defaults to actuals in PATH. Default is pwd.') do |path|
+    path ||= Dir.pwd
+    recursively_copy_defaults(path, 'config{,.*}.default')
+  end
+
+  opts.on('-c', '--copy-defaults [PATH]', String, 'Copy all .toggle.default to .toggle for PATH. Default is pwd.') do |path|
+    path ||= Dir.pwd
+    recursively_copy_defaults(path, '{key,config}{,.*}.default')
+  end
+
+  opts.on('--ensure-key [PATH]', String, 'Copies the default key in [PATH] if actual key is not present, does nothing otherwise. Default [PATH] is pwd.') do |path|
+    path ||= Dir.pwd
+    recursively_copy_defaults(path, 'key{,.*}.default', attempt_force_copy: false)
+  end
+
+  opts.on('-m', '--make-defaults [PATH]', String, 'Create [PATH]/{config|key}{,.*}.default. Default is pwd.') do |path|
+    path ||= Dir.pwd
+
+    default_key    = actual_key_in(path)    || default_key_filepath
+    default_config = actual_config_in(path) || default_config_filepath
+
+    key_destination    = File.join(path, 'key.yml.default')
+    config_destination = File.join(path, 'config.yml.default')
+
+    if !File.exists?(key_destination) || wants_to_force_copy?(key_destination)
+      FileUtils.cp(default_key, key_destination) unless identical_files?(default_key, key_destination)
+      puts "Default key written to #{key_destination}"
+      puts "Now go edit it!"
+    end
+
+    if !File.exists?(config_destination) || wants_to_force_copy?(config_destination)
+      FileUtils.cp(default_config, config_destination) unless identical_files?(default_config, key_destination)
+      puts "Default config written to #{config_destination}"
+      puts "Now go edit it!"
+    end
+  end
+
+  opts.on_tail("-v", "--version", "Show version") do
+    puts "Toggle version #{Toggle::VERSION}"
+    exit
+  end
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+end
+
+opt_parser.parse!