grandprix 0.0.4 → 0.0.5

data/.rvmrc

@@ -1 +1 @@
-rvm use 1.9.3@grandprix --create
+rvm use 1.8.7@grandprix --create

data/README.md

@@ -63,7 +63,7 @@ and run:
 ### Usage
 An executable called `grandprix` will be installed, and can be called like this:
 
-    $ topology -t topology_file elements_file
+    $ grandprix -t topology_file elements_file
 
 The elements file argument can be omitted and grandprix will read them from
 the standard in.
@@ -92,21 +92,113 @@ The `doc/sample/as_a_library` directory has an example ruby script calling
 grandprix programatically.
 
 
-## More 
+## How it works
+
+### The Basics
+
+The basic function of grandprix is to to reorder a list of elements according to
+a separately specified happens-before relation, a _topology_. The rule is
+simple: an element **A** will be before another element **B** in the output
+whenever there is a requirement on the topology that **B** must come after
+**A**. This requirement may be direct — **B** is in the `after` list for the
+**A** node in the input topology file — or it may be indirect — **A**'s `after`
+list contains an element that itself has **B** in its list, and so on. If you
+know some graph theory you may have recognized the rule as a _topological sort_,
+and indeed **grandprix** is nothing more than a little topsort engine.
+
+The `doc/sample/simple` directory contains sample topology and input files, and
+an example of grandprix's output.
 
 Grandprix offers a few more conveniences, illustrated on the `doc/sample`
 directories:
 
-* Elements can contain extra data that will carry over to the output, such as
-  version numbers. Just append an equals sign and the info you want to each
-  element. Check out the `elements_with_extra_info` directory.
-* The topology itself can define information that will propagate to the
-  output, in the form of an `annotation` attribute. See the `annotated_topology`
-  directory.
-* Besides declaring that an element needs to come after others, grandprix also
-  allows for an element to specify that it must always be accompanied by
-  another, via the `alongside` attribute. This will extend the provided elements
-  input. See the `alongside_elements` and `alongside_elements_2` directories.
+### Extra input data
+Elements can contain extra data that will carry over to the output, such as
+version or environment information. Just append an equals sign and the information
+you want to each element. For instance if you want to append version numbers, the
+elements input file could be something like this: 
+
+```
+frontend=1.0.0
+client=2.0.3
+backend=4.0.0
+```
+
+The output would be a permutation of the input lines according to the rules
+given on the topology. This may be useful to integrate grandprix into your
+scripting workflow.
+
+Check out the `elements_with_extra_info` directory for example input and
+outputs.
+
+### Topology annotations
+Adding extra data to the input elements is great for information that changes
+with each run, but it would be tedious to have to always append long-lasting 
+information about the elements for each input. To address this, grandprix 
+offers a way to annotate the elements on the topology file:
+
+```
+frontend:
+  after: [backend, images]
+  annotation: company-frontend-script 
+
+images:
+  annotation:              
+    recipe: image-server
+    script: install-images
+
+backend:
+  after: [db]
+  annotation:    
+    - This
+    - And that
+```
+
+The above shows the types of annotations that can be added to each node: simple
+strings, hashes, and arrays of items. These values will carry over to the
+output for each `grandprix` run:
+
+```
+images=2.0.3={"recipe":"image-server","script":"install-images"}
+backend=4.0.0=["This","And that"]
+frontend=1.0.0=company-frontend-script
+```
+
+In the above outout it can be seen that annotations are output for each element
+after a second equals sign. Strings are output straight through, arrays and
+objects are converted to a JSON serialization.
+
+Sample files are on the `doc/sample/annotated_topology` directory.
+
+### Alongside Elements
+Another common occurrence is the need to specify that some elements must always
+be accompanied by others. For instance, still on the deploy use case, sometimes
+we want to say that a certain service — say, a front-end server — must always be
+deployed alongside anoter — it could a static assets server in this example. 
+
+The relationship is specified as an `alongside` entry on a node's topology file:
+
+```
+frontend:
+  after: [backend]             
+  alongside: [assets, images]   # Frontend is always accompanied
+                                # by assets and images
+
+backend:
+  alongside: [external_backend]
+
+images:
+  after: [client] #images that is an alongside dep of frontend
+                  # can declare itself as after client
+```
+
+When an element that declares alongside elements is part of the input, the
+alongside elements are output as well. They inherit their declaring node's order
+restrictions, but they can declare their own order restrictions which are also
+obeyed.
+
+See the `doc/sample/alongside_elements` and `doc/sample/alongside_elements_2`
+directories.
 
 
 ## Contributing

data/grandprix.gemspec

@@ -14,4 +14,6 @@ Gem::Specification.new do |gem|
   gem.name          = "grandprix"
   gem.require_paths = ["lib"]
   gem.version       = File.read("version").chomp
+  gem.add_dependency 'json'
+  gem.add_dependency 'activesupport'
 end

data/lib/grandprix.rb

@@ -3,7 +3,39 @@ module Grandprix
 end
 
 require 'json'
+require 'active_support'
 require 'grandprix/elements'
 require 'grandprix/graph'
 require 'grandprix/planner'
 require 'grandprix/runner'
+
+if RUBY_VERSION =~ /^1\.8/
+  class Array
+    def flat_map
+      self.reduce([]) {|so_far, current| so_far + yield(current)}
+    end
+
+    def to_ordered_hash
+      ActiveSupport::OrderedHash[self]
+    end
+  end
+
+  class Hash
+    def flat_map
+      self.reduce([]) do |so_far, current|
+        key = current[0]
+        value = current[1]
+        so_far + yield(key, value)
+      end
+    end
+  end
+end
+
+
+if RUBY_VERSION =~ /^((1\.9)|2)/
+  class Array
+    def to_ordered_hash
+      Hash[self]
+    end
+  end
+end

data/lib/grandprix/graph.rb

@@ -58,7 +58,9 @@ class Grandprix::Graph
     end
 
     def zeroes
-      @counts.select {|vertex,count| count == 0 }.keys      
+      selected = @counts.select {|vertex,count| count == 0 }
+      hash_selected = Hash[selected]
+      hash_selected.keys      
     end
 
     def zeroes_among(vertices)

data/spec/lib/grandprix/elements_spec.rb

@@ -31,13 +31,13 @@ describe Grandprix::Elements do
 
   describe :alongside do
     it "should store the extra names" do
-      (make(["a","c"]).alongside "a" => ["aa"], "c" => ["cc"]).should == make(["a", "c", "aa", "cc"]) 
+      (make(["a","c"]).alongside [["a", ["aa"]], ["c", ["cc"]]]).should == make(["a", "c", "aa", "cc"]) 
     end
 
     it "should copy extra data from the stored names to the names defined alongside" do
       elements = make ["first=0.1", "second=0.2", "third"]
-      res = elements.alongside "first" => ["one"], "second" => ["two"], "third" => ["three"]
-      res.strings.should == ["first=0.1", "second=0.2", "third", "one=0.1", "two=0.2", "three"]
+      res = elements.alongside [["first", ["one"]], ["second", ["two"]], ["third", ["three"]]]
+      res.strings.should =~ ["first=0.1", "second=0.2", "third", "one=0.1", "two=0.2", "three"]
     end
 
     it "REGRESSION: it should not add unrelated names" do
@@ -59,7 +59,11 @@ describe Grandprix::Elements do
     it "should add extra object information to the appropriate names" do
       elements = make ["first=1"]
       res = elements.annotate "first" => {:a => "some string", "b" => ["other"]}
-      res.strings.should == [%|first=1={"a":"some string","b":["other"]}|]
+      res.strings.size.should == 1
+
+      line = res.strings.first 
+      line.should match %r|first=1={.*}|
+      JSON.parse(res.strings.first.split(/=/).last).should  include({"a" => "some string", "b" => ["other"]})
     end
 
     it "should format properly when the element has no prior extra information but is annotated" do

data/spec/lib/grandprix/planner_spec.rb

@@ -19,7 +19,7 @@ describe Grandprix::Planner do
 
     elements = ["frontend", "db", "client"]
     
-    graph.should_receive(:sort).with([
+    graph.should_receive(:sort).with(in_any_order [
       ["backend", "frontend"], 
       ["db", "backend"], 
       ["mq", "backend"], 
@@ -117,7 +117,7 @@ describe Grandprix::Planner do
 
       elements = ["frontend", "db", "client"]
 
-      graph.should_receive(:sort).with([
+      graph.should_receive(:sort).with(in_any_order [
         ["backend", "frontend"], 
         ["db", "backend"], 
         ["mq", "backend"], 
@@ -144,7 +144,7 @@ describe Grandprix::Planner do
 
       elements = ["frontend=1.0.0", "backend=2.0.0", "db"]
 
-      graph.should_receive(:sort).with([
+      graph.should_receive(:sort).with(in_any_order [
         ["backend", "frontend"], 
         ["db", "backend"], 
       ]).and_return(["db", "backend", "frontend"])

data/spec/lib/grandprix_extensions_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+
+describe "Extension" do
+  describe "Array.flat_map" do
+    it { [1,2,3].flat_map{|x| [x,x]}.should == [1,1,2,2,3,3]}
+    it { [1,2,3,4].flat_map{|x| x % 2 == 0 ? [x] : [] }.should == [2,4]}
+  end
+
+  describe "Hash.flat_map" do
+    it do
+      h = {:a => 10, :b => 20}
+      res = h.flat_map do |k, v|
+        [k, v, v]
+      end
+      res.should == [:a, 10, 10, :b, 20, 20]
+    end
+
+    it do
+      h = [[:a,1], [:b,2], [:c,3], [:d,4]].to_ordered_hash
+      
+      res = h.flat_map do |k, v|
+        v % 2 == 1 ? [k] : []
+      end
+      res.should == [:a, :c]
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -86,3 +86,18 @@ RSpec::Matchers.define :beOrderedHaving do |*initial_segment|
     end
   end
 end
+
+class InAnyOrderArgumentMatcher 
+  def initialize(expected)
+    @expected = expected
+  end
+
+  def ==(value)
+    (value.is_a?(Array) && @expected.is_a?(Array) && 
+     (@expected - value) == [] && (value - @expected) == [] )
+  end
+end
+
+def in_any_order(expected)
+  InAnyOrderArgumentMatcher.new(expected)
+end

data/version

@@ -1 +1 @@
-0.0.4
+0.0.5

metadata

@@ -1,24 +1,60 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: grandprix
-version: !ruby/object:Gem::Version
-  version: 0.0.4
+version: !ruby/object:Gem::Version 
+  hash: 21
   prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 5
+  version: 0.0.5
 platform: ruby
-authors:
+authors: 
 - Rafael de F. Ferreira
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-15 00:00:00.000000000 Z
-dependencies: []
+
+date: 2013-02-12 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
 description: Deploy assistant.
-email:
+email: 
 - public@rafaelferreira.net
-executables:
+executables: 
 - grandprix
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - .rspec
 - .rvmrc
@@ -56,37 +92,48 @@ files:
 - spec/lib/grandprix/graph_spec.rb
 - spec/lib/grandprix/planner_spec.rb
 - spec/lib/grandprix/runner_spec.rb
+- spec/lib/grandprix_extensions_spec.rb
 - spec/matchers_spec.rb
 - spec/spec_helper.rb
 - version
-homepage: ''
+homepage: ""
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Deploy assistant
-test_files:
+test_files: 
 - spec/lib/grandprix/elements_spec.rb
 - spec/lib/grandprix/graph_spec.rb
 - spec/lib/grandprix/planner_spec.rb
 - spec/lib/grandprix/runner_spec.rb
+- spec/lib/grandprix_extensions_spec.rb
 - spec/matchers_spec.rb
 - spec/spec_helper.rb