Browse files


  • Loading branch information...
1 parent e673d14 commit b9bf760c4b23549c0b79a44ffaaa6e661c01d228 @laserlemon laserlemon committed Dec 15, 2011
Showing with 35 additions and 15 deletions.
  1. +35 −15
@@ -1,29 +1,49 @@
# Gemnasium::Parser [![Build Status](]( [![Dependency Status](](
-TODO: Write a gem description
+The [Gemnasium]( parser determines gem dependencies from gemfiles and gemspecs, without evaluating the Ruby.
-## Installation
+## Why?
-Add this line to your application's Gemfile:
+[Bundler]( is wonderful. It takes your gemfile and your gemspec (both just Ruby) and evaluates them, determining your gem dependencies. This works great locally and even on your production server… but only because you can be trusted!
- gem 'gemnasium-parser'
+An untrustworthy character could put some pretty nasty stuff in a gemfile. If Gemnasium were to blindly evaluate that Ruby on its servers, havoc would ensue.
-And then execute:
+### Solution #1
- $ bundle
+If evaluating Ruby is so dangerous, just sandbox it! [Travis CI]( runs its builds inside isolated environments built with [Vagrant]( That way, if anything goes awry, it’s in a controlled environment.
-Or install it yourself as:
+This is entirely possible with Gemnasium, but it’s impractical. Gemfiles often `require` other files in the repository. So to evaluate a gemfile, Gemnasium needs to clone the entire repo. That’s an expensive operation when only a couple files determine the dependencies.
- $ gem install gemnasium-parser
+### Solution #2
-## Usage
+Parse Ruby like Ruby parses Ruby.
-TODO: Write usage instructions here
+Ruby 1.9 includes a library called Ripper. Ripper is a Ruby parsing library that can break down a gemfile or gemspec into bite-sized chunks, without evaluating the source. Then it can be searched for just the methods that matter.
-## Contributing
+The problem is that it’s hard to make heads or tails from Ripper’s output, at least for me. I could see the Gemnasium parser one day moving to this strategy. But not today.
+### Third try’s the charm
+If we can’t evaluate the Ruby and Ripper’s output is unmanageable, how else can we find patterns in a gemfile or gemspec and get usable output?
+Regular expressions!
+The Gemnasium parser, for both gemfiles and gemspecs, is based on a number of Ruby regular expressions. These patterns match `gem` method calls in gemfiles and `add_dependency` calls in gemspecs.
+For a more comprehensive list of its abilities, see the [specs](
+## Contributing <a name="contributing"></a>
1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+2. Create your branch (`git checkout -b my-bugfix`)
+3. Commit your changes (`git commit -am "Fix my bug"`)
+4. Push your branch (`git push origin my-bugfix`)
+5. Send a pull request
+## Problems?
+If you have a gemfile or gemspec that the Gemnasium parser screws up…
+1. Boil it down to its simplest problematic form
+2. Write a failing spec
+3. See [Contributing](#contributing)

0 comments on commit b9bf760

Please sign in to comment.