amp-front 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,24 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+.hg*
+.bundle
+
+## PROJECT::SPECIFIC
+*.gemspec

data/Ampfile

@@ -0,0 +1,3 @@
+# Default: load all rubygems plugins.
+
+Amp::Plugins::Base.load_rubygems_plugins

data/Gemfile

@@ -0,0 +1,10 @@
+# This is an install-only file - it's not used by the application
+# require 'bundler/setup' adds over 400ms to startup time
+source "http://rubygems.org"
+
+group :development do
+  gem 'jeweler'
+  gem 'rspec', '< 2.0.0'
+  gem 'yard'
+  gem 'cucumber'
+end

data/Gemfile.lock

@@ -0,0 +1,36 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    builder (2.1.2)
+    cucumber (0.9.2)
+      builder (~> 2.1.2)
+      diff-lcs (~> 1.1.2)
+      gherkin (~> 2.2.5)
+      json (~> 1.4.6)
+      term-ansicolor (~> 1.0.5)
+    diff-lcs (1.1.2)
+    gemcutter (0.6.1)
+    gherkin (2.2.9)
+      json (~> 1.4.6)
+      term-ansicolor (~> 1.0.5)
+    git (1.2.5)
+    jeweler (1.4.0)
+      gemcutter (>= 0.1.0)
+      git (>= 1.2.5)
+      rubyforge (>= 2.0.0)
+    json (1.4.6)
+    json_pure (1.4.6)
+    rspec (1.3.1)
+    rubyforge (2.0.4)
+      json_pure (>= 1.1.7)
+    term-ansicolor (1.0.5)
+    yard (0.6.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  cucumber
+  jeweler
+  rspec (< 2.0.0)
+  yard

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Michael Edgar
+
+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,50 @@
+# Rules
+
+We've learned a lot about software development. Time to get serious.
+
+## Commits
+
+* In the past our commits weren't really well-factored, or really had structure. This makes reading our history hard.
+* Use hg collapse to collapse several small commits into one logical commit.
+* Branch locally to work on separate features. 
+
+To do that, clone a local repo to another local repo. Change the branch on that other local repo. Make your commits. Then, in that clone, collapse your commits into something logical. Then, merge your changes into the `default` branch. This will show up as a fast-forward commit. Finally, push those to your main checkout. 
+
+* One commit, one feature. If your feature doesn't fit in one nicely-sized commit, then prefix your commit message with "PARTIAL:".
+* Until we have our own server, we can't really have code reviews. Until then: every commit that goes through, respond to it with *any* questions you have about the code. If you see nothing wrong, respond "LGTM". That stands for "Looks good to me." Continue this conversation until the other person says "LGTM". Otherwise, consider that commit incomplete.
+
+## Tests
+
+* Nothing goes in without a test of some kind. If you need to submit code that is untested, include a justification in your commit.
+* Tests are either small, medium, or large.
+* * Small tests are unit tests. They may need mocks to avoid interaction with other modules.
+* * Medium tests are integration tests. This is testing modules' interactions with each other.
+* * Large tests are functional tests. They test the whole system at once.
+
+## Design
+
+* Don't use anonymous arrays/hashes. Use objects. We're in rubyland.
+* Defining classes is cheap. In Java, it'll take you thirty lines of code to make a small struct-like object. In Ruby, it takes us 3 or 4. Go for it! It's better to model the data you're moving around using classes than stuffing it into arrays and whatnot.
+* * Exception: Returning two values can be okay. Justify it and make it crystal clear in the docs.
+
+## Documentation
+
+* Use YARD.
+* Don't worry too hard about 1-liners.
+* Document why, not what. If
+
+## Code Style
+
+* Strive for 80 columns.
+* Never more than 100 columns.
+* Don't make between 80-100 a habit.
+* Descriptive method names.
+* Parentheses in method declarations unless there are no arguments.
+* Spaces around operators.
+* No mathematic operator overloading. `[]`, `[]=` are fair game though.
+
+## License
+
+MIT. See LICENSE. No GPL code is allowed in this codebase.
+
+By contributing code to the Amp Project, you agree to license your work under the MIT license.

data/Rakefile

@@ -0,0 +1,64 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "amp-front"
+    gem.summary = %Q{Generic front-end for Amp.}
+    gem.description = %Q{The generic front-end used by Amp. May be completely published as a generic library in the future, at which point a name change will be necessary.}
+    gem.email = "michael.j.edgar@dartmouth.edu"
+    gem.homepage = "http://github.com/michaeledgar/amp-front"
+    gem.authors = ["Michael Edgar"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "yard", ">= 0"
+    gem.add_development_dependency "cucumber", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/test*.rb']
+  t.verbose = true
+end
+
+task :spec => :check_dependencies
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+
+  task :features => :check_dependencies
+rescue LoadError
+  task :features do
+    abort "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+  end
+end
+
+task :default => [:spec, :test, :features]
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/design_docs/commands.md

@@ -0,0 +1,91 @@
+# Command Dispatch Design Doc
+
+This design document intends to describe how commands will be dispatched
+by Amp.
+
+The user's invocations are in the form:
+
+    amp --logging=WARN add --force some_file
+    amp config set key value --fiddler="fiddly"
+    amp git twiddle --dee="x" --dum="y"
+    
+## Command classes
+
+Each command is its own class. It must inherit (either directly or indirectly)
+from Amp::Command::Base.
+
+Commands are discovered by looking up the class with the name of the requested
+command. Thus, the three amp invocations above would run the following (hypothetical)
+code to create the command object:
+
+    cmd = Amp::Command::Add.new
+    cmd = Amp::Command::Config::Set.new
+    cmd = Amp::Command::Git::Twiddle.new
+    
+## Command Groups
+
+There are a number of commands that will be built into Amp Core: help, add, commit, push,
+and so on. These will always be searched first.
+
+Then, we go to command groups. Each plugin comprises a command group, and the Amp::Plugin
+subclass that defines a plugin declares a way to access its commands as a group.
+
+Each plugin's command groups are searched using the names provided on the command line, such
+as "config set key value --fiddler='fiddly'". Every plugin (hg, git, server, etc.) will be
+searched for a "config" command, then a "config set" command, then a "commit set key" command,
+and a "config set key value" command. The results are collected, and then only the most
+specific matches are kept. If the user has defined a "default command group", and one of the
+resulting matches is in that default command group, it is moved to the top of the choice list.
+The rest are sorted by how often they have been invoked by the user. This list is presented
+to the user, and the user picks which command they intended.
+
+Partial matches *do not match*. Thus, if the user entered:
+
+    amp config --fiddler='fiddly'
+    
+Then the following commands would match:
+
+    Amp::Command::Config
+    Amp::Command::GitPlugin::Config
+    Amp::Command::HgPlugin::Config
+
+But the following commands would not:
+
+    Amp::Command::Config::Set
+    Amp::Command::Config::Get
+    Amp::Command::GitPlugin::Config::Set
+    Amp::Command::GitPlugin::Config::Get::ByKey
+    
+## Command definition
+
+A command definition is roughly as follows:
+
+    command "search" do
+      # This command has a repository. Pull in helpers for this common
+      # case, and add the --repository (-R) command-line option.
+      has_repo
+
+      # Define options using Trollop syntax
+      opt :verbose, "Verbose output", :type => :boolean
+      opt :query, "The query to search for", :type => :string
+      
+      # Use macros to quickly add features
+      has_paging_options
+      
+      # Add validations
+      validates_length_of :query, :in => 4..32
+      validates_inclusion_of :query
+      validates_has_repository  # validates :repository option
+      
+      # specify on_call
+      on_call do
+        repo = self.repository
+        p repo.search(options[:query])
+      end
+    end
+
+When the command runs, its on\_call block is instance\_eval'd by the command
+object. That way, any helper methods defined by the command class can be used
+in the on\_call block. One particularly useful helper for on\_call is "repository"
+which will get the current repository, regardless of type. This is provided by
+amp-core.

data/design_docs/dependencies.md

@@ -0,0 +1,35 @@
+# Amp Dependancies Design Doc
+
+Amp has so far avoided Rubygems dependancies, due to performance concerns.
+Required libraries are included wholesale; so far all such libraires have
+been modified in some way.
+
+## Dependancies
+
+### Maruku
+
+Maruku is a pure ruby markdown interpreter.
+Amp uses a highly hacked version of Maruku
+(it adds an output form with ANSI color codes)
+that was trimmed down to try to make it lightweight.
+
+### Trollop
+
+Trollop is a command-line parsing library.
+It didn't originally expose its --help behavior,
+which is really nice because it lists options automatically.
+The Amp version exposes the parser object so we can run parser.educate!.
+
+## The Case Against Rubygems
+
+Loading Rubygems on each invocation of amp adds at least 150-500ms+ to each invocation.
+With the current plugin architecture, we require users to either use rubygems,
+or individually download each repo and load plugins manually using their Ampfile.
+An installer script down the line could automate the latter option.
+
+### Bundler
+
+Bundler (require 'bundler/setup') adds another 400ms+ to startup time.
+A Gemfile is used to streamline gem installation, but it is not used by
+Amp itself.
+

data/design_docs/plugins.md

@@ -0,0 +1,47 @@
+# Amp Frontend Plugin Design Doc
+
+This document intends to specify how plugins will be managed by the generic
+Amp front-end.
+
+## Amp::Plugin Subclasses
+
+By tracking the subclasses (and subclasses of subclasses) of Amp::Plugin, we
+can look up all plugins that are loaded. Thus, to register a plugin, one simply
+needs to load a Ruby file that contains the definition of an Amp::Plugin subclass.
+
+The list of all plugins can be retrieved with the following Ruby code:
+
+    Amp::Plugin.all_plugins
+
+Which is simply an accessor to an ivar on the Amp::Plugin metaclass. Following
+the Ruby convention of preferring convention over configuration, the default
+Ampfile contains the following, single statement:
+
+    Amp::Plugin.load_rubygems_plugins
+
+which, when run, all gems are searched for the file 'amp/plugin.rb'. All such files
+are loaded in an arbitrary order.
+
+If a plugin is automatically loaded that you *do not* wish to be loaded, you
+will have to require each one individually. You do not need to manually load
+amp-core. amp-core will be loaded first.
+
+## Plugin Callbacks
+
+Each plugin class in `Amp::Plugin.all_plugins` is instantiated with the current
+global configuration as the sole parameter:
+
+    class Amp::Plugin::Git < Amp::Plugin::Base
+      def initialize(settings)
+        puts "oh noez" if settings[:failboatz]
+      end
+    end
+    
+Or the simpler:
+
+    amp_plugin 'git' do
+      init do |settings|
+        puts "oh noez" if settings[:failboatz]
+      end
+    end
+

data/features/amp.feature

@@ -0,0 +1,8 @@
+Feature: Amp command
+  In order to see what amp does
+  A user will run amp by itself
+  to find out what it does
+
+  Scenario: Running amp with no parameters
+    When I run dispatch
+    Then I should see "Thanks for using Amp!"

data/features/amp_help.feature

@@ -0,0 +1,36 @@
+Feature: Help Command
+  In order to learn to use Amp
+  A user can use the help command
+  to be delivered useful information
+
+  Scenario: Running help with no parameters
+    Given the argument help
+    When I run dispatch
+    Then I should see "Thanks for using Amp!"
+
+  Scenario: Running help commands
+    Given the argument help
+    And the argument commands
+    When I run dispatch
+    Then I should see "Prints the help for the program."
+    And I should see "^help"
+  
+  Scenario: Running help ampfiles
+    Given the argument help
+    And the argument ampfiles
+    When I run dispatch
+    Then I should see "What'?s an Ampfile?"
+
+  Scenario: Running help new-commands
+    Given the argument help
+    And the argument new-commands
+    When I run dispatch
+    Then I should see "commands are the driving force behind"
+
+  Scenario: Running help help
+    Given the argument help
+    And the argument help
+    When I run dispatch
+    Then I should see "  --help, -h"
+    And I should see "Show this message"
+    And I should see "Prints the help for the program."