clamshell 0.2

data/.gitignore

@@ -0,0 +1,2 @@
+.bundle
+*.swp

data/.rspec

@@ -0,0 +1 @@
+--colour

data/Gemfile

@@ -0,0 +1,8 @@
+source :rubygems
+
+gem "thor"
+
+group :test do
+  gem "rake"
+  gem "rspec"
+end

data/Gemfile.lock

@@ -0,0 +1,22 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    rake (0.8.7)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+    thor (0.14.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  rspec
+  thor

data/README.md

@@ -0,0 +1,126 @@
+# Clamshell
+
+Clamshell is a tool that converts generic shell statements into shell specific
+statements that can be sourced to set up an environment.
+
+## Motivation
+
+While working on a legacy project that used tcsh as its primary shell, I wanted
+to use bash, but realized that some of the old schoolers actually liked tcsh.
+This was the compromise.
+
+## Installation
+
+    gem install clamshell
+
+##  Setting up an environment file
+
+Sometimes your project has a dependency that is shell specific (environment variables,
+aliases). Setup a `Shell.env` file in your project root with the following:
+
+    Environment.setup ("bash") do
+      env_var "LC_CTYPE", "en_US"
+      env_var "PATH", :prepend => "~/bin",    :delimiter => ":"
+      env_var "PATH", :append  => "/usr/bin", :delimiter => ":"
+      env_alias editor "vim"
+    end
+
+You can convert these statements to bash statements as follows:
+
+    clamshell convert SHELL.env
+
+which will print the following to standard out (or to a file using the `--shell-out=FILE` flag).
+
+    export LC_CTYPE=en_US
+    export PATH=~/bin:$PATH
+    export PATH=$PATH:/usr/bin
+    alias editor=vim
+
+### Shell independence
+
+Your environment file doesn't even need to specify a shell:
+
+    Environment.setup do
+      ...
+    end
+
+But you must pass the flag `--shell=SHELLNAME`.
+Best practices for multi-shell environments use the following command:
+
+    --shell=`ps -p $$ | awk 'NR==2 {print $4}'`
+
+which will set the shell flag to the type of shell currently being ran.
+
+Currently, the shells supported are tcsh and bash. However, I am assuming that
+csh and zsh are supported as well since they are closely related to tcsh and
+bash, respectively. Hence, aliases are set up for their respective shells.
+
+### Generic shell statements
+
+You can also call generic shell statements that are valid in all shells:
+
+    echo -n FOO
+
+But you must be verbose that you are doing so:
+
+    cmd "echo -n FOO"
+
+### Unique shell statements
+
+If you need to setup the environment and produce a shell command that is
+different depending on the shell being used, the global variable `$SHELL`
+is available:
+
+    Environment.setup do
+      if $SHELL == "tcsh"
+        cmd "unlimit coredumpsize"
+      elsif $SHELL == "bash"
+        cmd "ulimit -c unlimited"
+      end
+    end
+
+### Splitting the environment
+
+If you want to split your environment files up, the `include_file` command
+is as your disposal.
+
+    Environment.setup do
+      include_file "/path/to/another.file"
+    end
+
+`another.file`'s contents:
+
+    env_var "CLASSPATH", :append => "~/java"
+    cmd "echo FOOBAR"
+
+If you definitely need to split your environment up, take this approach.
+
+#### Pitfall
+
+Another approach you might have considered is to generate multiple
+files and source each one.
+
+__DON'T!__
+
+In tcsh, appending to an environment variable that doesn't exist throws an
+error. There is an internal mechanism in clamshell that detects if an
+environment variable doesn't exist. If it doesn't it creates one and sets
+it to an empty string before appending.
+
+So the previous example would generate the following statements:
+
+    setenv CLASSPATH ""
+    setenv CLASSPATH ${CLASSPATH}:~/java
+    echo FOOBAR
+
+This can cause some headaches if more than one file is generated.
+
+*Rule of thumb: generate one file, source one file.*
+
+### Conversion on the fly
+
+If you need to convert a generic statement without using a file, you can
+use the `convert_string` action, but you must specify a shell.
+
+    clamshell convert_string "env_var 'FOO' 'BAR'" --shell=tcsh
+    => setenv FOO BAR\n

data/Rakefile

@@ -0,0 +1,4 @@
+require 'fileutils'
+require './lib/clamshell'
+
+Dir['tasks/**/*.rake'].each { |t| load t }

data/bin/clamshell

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require File.dirname(__FILE__) + '/../lib/clamshell'
+require File.dirname(__FILE__) + '/../lib/clamshell/cli'
+
+begin
+  Clamshell::CLI.start
+rescue StandardError => e
+  puts e.message
+  exit 1
+rescue Interrupt => e
+  puts "\nQuitting..."
+  exit 1
+end

data/clamshell.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "clamshell/version"
+
+Gem::Specification.new do |s|
+  s.name        = "clamshell"
+  s.version     = Clamshell::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Eric Thomas"]
+  s.email       = ["eric.l.m.thomas@gmail.com"]
+  s.homepage    = "https://github.com/et/clamshell"
+  s.summary     = %q{Clamshell manages your environment in a shell-independent setup.}
+  s.description = %q{Clamshell allows you to setup shell statements which configure
+                     your project's environment that doesn't care about which shell
+                     (bash, tcsh) the target user will be using.}
+
+  s.rubyforge_project = "clamshell"
+
+  s.add_dependency('thor')
+
+  s.add_development_dependency('rspec')
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/clamshell.rb

@@ -0,0 +1,19 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+module Clamshell
+
+  autoload :Dsl,         'clamshell/dsl'
+  autoload :Environment, 'clamshell/environment'
+
+  class SafeExit < StandardError; end
+  class DslError < StandardError; end
+
+  class << self
+    attr_writer :settings
+
+    def settings
+      @settings ||= {}
+    end
+  end
+end

data/lib/clamshell/cli.rb

@@ -0,0 +1,41 @@
+require 'thor'
+
+module Clamshell
+  class CLI < Thor
+
+    def initialize(*)
+      super
+      Clamshell.settings = options
+    end
+
+    desc "convert FILE", "Converts an environment file to shell statements"
+    method_option :shell,     :type => :string, :banner => "Shell to create statements for"
+    method_option :shell_out, :type => :string, :banner => "File to output to"
+    def convert(file)
+      check_file(file)
+
+      file_out = Clamshell.settings[:shell_out]
+      if file_out
+        File.open(file_out, "w") {|f| f.write(Dsl.build(file) + "\n") }
+      else
+        puts Dsl.build(file)
+      end
+    end
+
+    desc "convert_string STRING", "Converts a string on the fly."
+    method_option :shell, :type => :string, :banner => "Shell to create statements for", :required => true
+    def convert_string(string)
+      input = <<-I
+        Environment.setup do
+          #{string}
+        end
+      I
+      puts instance_eval(input).inspect
+    end
+
+    private
+      def check_file(file)
+        abort("File: #{file}, not found.") unless File.exist?(file)
+      end
+  end
+end

data/lib/clamshell/dsl.rb

@@ -0,0 +1,8 @@
+module Clamshell
+  class Dsl
+    def self.build(file)
+      builder = instance_eval(IO.read(file))
+      builder.inspect
+    end
+  end
+end

data/lib/clamshell/environment.rb

@@ -0,0 +1,94 @@
+module Clamshell
+  class Environment
+
+    attr_reader :shell
+
+    def self.setup(shell = nil, &block)
+      $SHELL = shell ||= Clamshell.settings[:shell]
+      raise "No shell specified" unless shell
+
+      e = new(shell)
+      e.instance_eval(&block)
+      return e
+    end
+
+    def initialize(shell)
+      @shell = case shell
+        when "csh", "tcsh" then TcshAdapter
+        when "zsh", "bash" then BashAdapter
+        else
+          raise "Unsupported shell"
+        end
+      @stmts = []
+    end
+
+
+    def env_var(name, *args)
+      case
+      when args[0].class == String    # direct assignment
+        @stmts << @shell.env_var(name, args[0])
+
+      else                            # appending or prepending to existing variable
+
+        # In csh, concatting to an undefined environment variable
+        # results in an error. This is a safe guard that sets the
+        # environment variable to an empty string before appending/prepending.
+        unless ENV[name]
+          ENV[name] = %q{""}
+          @stmts << @shell.env_var(name, ENV[name])
+        end
+
+        delimiter = args[0][:delimiter] || ""
+        if args[0][:prepend]
+          val = args[0][:prepend] + delimiter + "${#{name}}"
+        elsif args[0][:append]
+          val = "${#{name}}" + delimiter + args[0][:append]
+        else
+          raise DslError, "Must specify prepend or append"
+        end
+        @stmts << @shell.env_var(name, val)
+      end
+    end
+
+    def env_alias(name, val)
+      @stmts << @shell.env_alias(name, val)
+    end
+
+    def cmd(stmt)
+      @stmts << stmt
+    end
+
+    def include_file(file)
+      instance_eval File.read(file), file
+    end
+
+    def to_s
+      @stmts.join("\n")
+    end
+
+    private
+      def quote(val)
+        %Q{"#{val}"}
+      end
+  end
+
+  class BashAdapter
+    def self.env_var(name, val)
+      "export #{name}=#{val}"
+    end
+
+    def self.env_alias(name, val)
+      "alias #{name}=#{val}"
+    end
+  end
+
+  class TcshAdapter
+    def self.env_var(name, val)
+      "setenv #{name} #{val}"
+    end
+
+    def self.env_alias(name, val)
+      "alias #{name} #{val}"
+    end
+  end
+end

data/lib/clamshell/version.rb

@@ -0,0 +1,3 @@
+module Clamshell
+  VERSION = "0.2"
+end

data/spec/clamshell/cli_spec.rb

@@ -0,0 +1,73 @@
+require 'tempfile'
+
+require 'spec_helper'
+require 'clamshell/cli'
+
+describe Clamshell::CLI do
+
+  # explicit subject
+  subject { Clamshell::CLI }
+
+  after :each do
+    Clamshell.settings = {}
+  end
+
+  describe "#initialize" do
+
+    it "shows the help listing with no args" do
+      capture(:stdout){ subject.start }.should =~ /Tasks:/
+    end
+  end
+
+  describe "#convert" do
+    before do
+      @action  = "convert"
+      @file_in = "#{FIXTURES_DIR}/Shell.env"
+    end
+
+    it "shows an error for a file not found" do
+      test_missing_file([@action, "missing_file"])
+    end
+
+    it "#--shell, it should set a shell option" do
+      capture(:stdout){ subject.start([@action, @file_in, "--shell=bash"])}
+      Clamshell.settings[:shell].should == "bash"
+    end
+
+    context "output" do
+      it "should print to standard out" do
+        capture(:stdout){ subject.start [@action, @file_in]}.should_not be_empty
+      end
+
+      it "#--shell-out, should output to a file" do
+        file = mock('file')
+        File.should_receive(:open).with("filename", "w").and_yield(file)
+        file.should_receive(:write)
+        subject.start ["convert", @file_in, "--shell-out=filename"]
+      end
+    end
+  end
+
+  describe "#convert_string" do
+    before do
+      @action    = "convert_string"
+      @string_in = %q{env_var "FOO", "BAR"}
+    end
+
+    it "show an error when --shell is not used" do
+      capture(:stderr) {
+        subject.start [@action, @string_in]
+      }.should =~ /No value provided for required options '--shell'/
+    end
+
+    it "should convert a string" do
+      capture(:stdout) {
+        subject.start [@action, @string_in, "--shell=tcsh"]
+      }.should == "setenv FOO BAR\n"
+    end
+  end
+end
+
+def test_missing_file(argv)
+  expect { capture(:stderr){ subject.start(argv)}}.to raise_error(SystemExit, /File: \S*, not found/)
+end

data/spec/clamshell/environment_spec.rb

@@ -0,0 +1,194 @@
+require 'spec_helper'
+
+describe Clamshell::Environment do
+
+  describe "setup" do
+    it "should raise an error when no shell is given" do
+      expect { Clamshell::Environment.setup( & proc{})}.to raise_error(RuntimeError, /No shell specified/)
+    end
+
+    it "should return an Environment object" do
+      Clamshell::Environment.setup("bash", & proc{}).should be_an_instance_of Clamshell::Environment
+    end
+  end
+
+  describe "shell initializer" do
+    it "should set up a tcsh shell" do
+      Clamshell::Environment.new("tcsh").shell.should be Clamshell::TcshAdapter
+    end
+
+    it "should set up a csh(tcsh) shell" do
+      Clamshell::Environment.new("csh").shell.should be Clamshell::TcshAdapter
+    end
+
+    it "should set up a bash shell" do
+      Clamshell::Environment.new("bash").shell.should be Clamshell::BashAdapter
+    end
+
+    it "should set up a zsh(bash) shell" do
+      Clamshell::Environment.new("zsh").shell.should be Clamshell::BashAdapter
+    end
+
+    it "should raise an error on an unknown shell" do
+      expect { Clamshell::Environment.new("sea")}.to raise_error(RuntimeError, /Unsupported shell/)
+    end
+  end
+
+  describe 'shell specific' do
+    before :each do
+      @bash = Clamshell::Environment.new("bash")
+      @tcsh = Clamshell::Environment.new("tcsh")
+    end
+
+    describe "env_alias" do
+      it "should set a tcsh alias" do
+        @tcsh.env_alias("FOO", "BAR")
+        @tcsh.inspect.should == %q{alias FOO BAR}
+      end
+      it "should set a bash alias" do
+        @bash.env_alias("FOO", "BAR")
+        @bash.inspect.should == %q{alias FOO=BAR}
+      end
+    end
+
+    describe "environment variable" do
+      describe "set" do
+
+        it "should set up a bash environment variable" do
+          @bash.env_var("FOO", "BAR")
+          @bash.inspect.should == "export FOO=BAR"
+        end
+
+        it "should set up a tcsh environment variable" do
+          @tcsh.env_var("FOO", "BAR")
+          @tcsh.inspect.should == "setenv FOO BAR"
+        end
+      end
+
+      describe "concat" do
+
+        before :all do
+          ENV['FOO'] = 'FOO'
+        end
+
+        after :all do
+          ENV['FOO'] = nil
+        end
+
+        describe "prepend" do
+          it "should prepend to a bash environment variable" do
+            @bash.env_var("FOO", :prepend => "BAR")
+            @bash.inspect.should == "export FOO=BAR${FOO}"
+          end
+
+          it "should prepend to a tcsh environment variable" do
+            @tcsh.env_var("FOO", :prepend => "BAR")
+            @tcsh.inspect.should == "setenv FOO BAR${FOO}"
+          end
+        end
+
+        describe "append" do
+          it "should append to a bash environment variable" do
+            @bash.env_var("FOO", :append => "BAR")
+            @bash.inspect.should == %q{export FOO=${FOO}BAR}
+          end
+
+          it "should append to a tcsh environment variable" do
+            @tcsh.env_var("FOO", :append => "BAR")
+            @tcsh.inspect.should == %q{setenv FOO ${FOO}BAR}
+          end
+        end
+
+        context "safe concat" do
+          before :each do
+            ENV['UNDEFINED'] = nil
+          end
+
+          it "should set the environment variable to empty string if not set" do
+            @tcsh.env_var("UNDEFINED", :append => "FOO")
+            @tcsh.inspect.should == %Q{setenv UNDEFINED ""\nsetenv UNDEFINED ${UNDEFINED}FOO}
+          end
+
+          it "should not try to keep setting the environment variable" do
+            @tcsh.env_var("UNDEFINED", :append => "FOO")
+            @tcsh.env_var("UNDEFINED", :append => "BAR")
+            @tcsh.inspect.should == %Q{setenv UNDEFINED ""\nsetenv UNDEFINED ${UNDEFINED}FOO\nsetenv UNDEFINED ${UNDEFINED}BAR}
+          end
+        end
+      end
+
+      describe "delimiter" do
+        it "should raise an error when prepend/append not defined" do
+          expect { @bash.env_var("FOO", :delimiter => ":")}.to raise_error(Clamshell::DslError, /Must specify prepend or append/)
+        end
+
+        it "should use a delimiter to append a variable" do
+          @bash.env_var("FOO", :append => "BAR", :delimiter => ":")
+          @bash.inspect.should == %q{export FOO=${FOO}:BAR}
+        end
+      end
+
+    end
+
+    describe "generic statement" do
+      it "should print out what it receives" do
+        @bash.cmd "echo blah"
+        @bash.inspect.should == %q{echo blah}
+      end
+    end
+
+    describe "include_file" do
+      it "should include a file" do
+        input = <<-I.gsub(/^\s+/, "").chop
+        env_var "FOO", "BAR"
+        cmd "echo blah"
+        I
+        File.stub!(:read).with("included_file.txt").and_return(input)
+        @bash.include_file("included_file.txt")
+        @bash.inspect.should == %Q{export FOO=BAR\necho blah}
+      end
+    end
+  end
+
+  describe "to_s" do
+    it "should convert a block" do
+      block = proc {
+        env_var "FOO", "BAR"
+        env_var "BAZ", "BUZZ"
+      }
+
+      out = <<-O.gsub(/^\s+/, "").chop
+      export FOO=BAR
+      export BAZ=BUZZ
+      O
+
+      Clamshell::Environment.setup("bash", &block).inspect.should == out
+    end
+
+    it "should convert a block with generic statements" do
+      block = proc {
+        env_var "FOO", "BAR"
+        cmd "echo -n blah"
+        env_var "BAZ", "BUZZ"
+      }
+
+      out = <<-O.gsub(/^\s+/, "").chop
+      setenv FOO BAR
+      echo -n blah
+      setenv BAZ BUZZ
+      O
+      Clamshell::Environment.setup("tcsh", &block).inspect.should == out
+    end
+
+    it "should provide a $SHELL global variable" do
+      block = proc {
+        if $SHELL == "tcsh"
+          cmd "unlimited coredumpsize"
+        elsif $SHELL == "bash"
+          cmd "ulimit -c unlimited"
+        end
+      }
+      Clamshell::Environment.setup("tcsh", &block).inspect.should == "unlimited coredumpsize"
+    end
+  end
+end

data/spec/fixtures/Shell.env

@@ -0,0 +1,24 @@
+######################################
+# The following will return:
+# export LC_CTYPE=en_US
+# export PATH=/usr/bin
+# export PATH=~/usr/bin:${PATH}
+# export PATH=~alice/bin:${PATH}
+# export PATH=~bob/bin:${PATH}
+# export PATH=~eve/bin:${PATH}
+# alias EDITOR=vim
+# echo -e FOO
+#
+Environment.setup("bash") do
+  env_var "LC_CTYPE", "en_US"
+  env_var "PATH", "/usr/bin"
+  env_var "PATH", :prepend => "~/usr/bin", :delimiter => ":"
+
+  ["~alice/bin", "~bob/bin", "~eve/bin"].each do |p|
+    env_var "PATH", :prepend => p, :delimiter => ":"
+  end
+
+  env_alias "EDITOR", "vim"
+
+  cmd "echo -e FOO"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require 'clamshell'
+require 'rspec'
+require 'stringio'
+
+FIXTURES_DIR = File.dirname(__FILE__) + '/fixtures'
+
+ARGV.clear
+
+RSpec.configure do |config|
+  def capture(stream)
+    begin
+      stream = stream.to_s
+      eval "$#{stream} = StringIO.new"
+      yield
+      result = eval("$#{stream}").string
+    ensure
+      eval("$#{stream} = #{stream.upcase}")
+    end
+
+    result
+  end
+end

data/tasks/rspec.rake

@@ -0,0 +1,22 @@
+begin
+  require 'rake'
+  require 'rspec'
+rescue LoadError
+  require 'rubygems' unless ENV['NO_RUBYGEMS']
+  require 'rspec'
+end
+begin
+  require 'rspec/core/rake_task'
+rescue LoadError
+  puts <<-EOS
+To use rspec for testing you must install rspec gem:
+    gem install rspec
+EOS
+  exit(0)
+end
+
+desc "Run all of the spec tests"
+Rspec::Core::RakeTask.new do |t|
+  t.rspec_opts  = ['--options', "spec/spec.opts"]
+  t.pattern = FileList['spec/**/*_spec.rb']
+end 

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification 
+name: clamshell
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  version: "0.2"
+platform: ruby
+authors: 
+- Eric Thomas
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-02 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thor
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: |-
+  Clamshell allows you to setup shell statements which configure
+                       your project's environment that doesn't care about which shell
+                       (bash, tcsh) the target user will be using.
+email: 
+- eric.l.m.thomas@gmail.com
+executables: 
+- clamshell
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/clamshell
+- clamshell.gemspec
+- lib/clamshell.rb
+- lib/clamshell/cli.rb
+- lib/clamshell/dsl.rb
+- lib/clamshell/environment.rb
+- lib/clamshell/version.rb
+- spec/clamshell/cli_spec.rb
+- spec/clamshell/environment_spec.rb
+- spec/fixtures/Shell.env
+- spec/spec_helper.rb
+- tasks/rspec.rake
+has_rdoc: true
+homepage: https://github.com/et/clamshell
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: clamshell
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Clamshell manages your environment in a shell-independent setup.
+test_files: 
+- spec/clamshell/cli_spec.rb
+- spec/clamshell/environment_spec.rb
+- spec/fixtures/Shell.env
+- spec/spec_helper.rb