fire 0.2.0

data/.index

@@ -0,0 +1,53 @@
+---
+revision: 2013
+type: ruby
+sources:
+- var
+authors:
+- name: Trans
+  email: transfire@gmail.com
+organizations:
+- name: Rubyworks
+requirements:
+- name: notify
+- groups:
+  - build
+  development: true
+  name: detroit
+- groups:
+  - build
+  development: true
+  name: mast
+conflicts: []
+alternatives: []
+resources:
+- type: home
+  uri: http://rubyworks.github.com/fire
+  label: Homepage
+- type: code
+  uri: http://github.com/rubyworks/fire
+  label: Source Code
+- type: bugs
+  uri: http://github.com/rubyworks/fire/issues
+  label: Issue Tracker
+repositories:
+- name: upstream
+  scm: git
+  uri: git://github.com/rubyworks/fire.git
+categories: []
+copyrights:
+- holder: Rubyworks
+  year: '2010'
+  license: BSD-2-Clause
+customs: []
+paths:
+  lib:
+  - lib
+created: '2010-07-05'
+summary: The best build tool, logically!
+title: Fire
+version: 0.2.0
+name: fire
+description: ! "Fire is a continuous integration build tool with a slick set logic
+  \nstate/rules system."
+date: '2013-02-12'

data/.yardopts

@@ -0,0 +1,10 @@
+--title Fire
+--readme README.md
+--plugin tomdoc
+--private
+--protected
+lib
+-
+*.md
+*.txt
+

data/HISTORY.md

@@ -0,0 +1,33 @@
+# RELEASE HISTORY
+
+## 0.2.0 / 2013-02-12
+
+This is the last version with tasks. Tasks are being deprecated
+for two reasons: a) they add a great deal of complexity to the
+syntax and the implementation via their need for dependencies;
+and b) tasks have proven to be an excuse for poorly designed 
+rules, which, if properly written, would do the job just as well
+if not better than any task. So it was decided that if tasks are
+needed, then they should be provided via dedicated task system,
+not via the rules system.
+
+Changes:
+
+* Default rule file is now `.fire/rules.rb` or `rules.rb`.
+* Rules can depend on tasks using same hash notation as tasks.
+* Modified the `#rule` method to define file rules given a string.
+* Deprecated the `file` method for defining file rules.
+
+
+## 0.1.0 / 2012-04-10
+
+This is the initial release of Fire. Fire is state and rules-based
+continuous integration and build tool.
+
+Special thanks to Ari Brown for letting us take over the fire gem
+for this project. "Fire" is perfect fit.
+
+Changes:
+
+* Happy first release day!
+

data/LICENSE.txt

@@ -0,0 +1,29 @@
+Fire - Rules-based BI and Build Tool
+(http://github.com/rubyworks/fire)
+
+Copyright (c) 2011 Rubyworks. All rights reserved. 
+
+Redistribution and use in source and binary forms,
+with or without modification, are permitted provided that the following
+conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+SPDX License: BSD-2-Clause
+

data/README.md

@@ -0,0 +1,217 @@
+# Fire (火)
+
+[Homepage](http://rubyworks.github.com/fire) /
+[Report Issue](http://github.com/rubyworks/fire/issues) /
+[Source Code](http://github.com/rubyworks/fire) /
+[IRC Channel](http://chat.us.freenode.net/rubyworks)
+
+
+Fire is a rules-based build tool and continuous integration system.
+The creative spark that created Fire is "logic programming meets build tool".
+With it the Ruby developer defines project states and rules to follow
+when those state are met. In this manner, a project can all but manage
+itself!
+
+
+## Instruction
+
+### Rule Files
+
+Rule files by default are looked up from a project's root directory
+matching `task/file.rb` or `task/*.fire.rb`. All matching files will
+be loaded. If you prefer to use a different location, you can create
+a `.fire/script.rb` file and only that file will be used. In it you
+can import any other paths you like.
+
+Rule files are Ruby scripts, containing primarily a collection of
+`state` and `rule` definitions. States define conditions and
+rules define procedures to take based on such states.
+
+### States
+
+States are  conditions upon which rule depend to decide when a
+rules procedure should run or not. States are defined using the
+`state` method with a code block to express the condition. General
+rules are given a specific name.
+
+```ruby
+  state :happy_hour? do
+    t = Time.now; t.hour >= 2 && t.hour <= 3
+  end
+```
+
+Named states define a method internally, which is called when
+defining rules (see below). But states can also be anonymous.
+A common type of anonymous state is the `file` state, which
+automatically creates a condition to check for files on disk
+that have changed since the previous "firing".
+
+```ruby
+    file('lib/**/*.rb')
+```
+
+Another such state is the `env` state, which is used to match
+system environment variables. The variable's value can be matched
+against a specific string or a regular expression.
+
+```
+    env('PATH'=>/foo/)
+```
+
+### Rules
+
+Rules take a state as an argument and attaches it to an action
+procedure. When fired, if the state condition evaluates as true,
+the rule procedure will be called.
+
+```ruby
+    # Mast handles manifest updates.
+
+    state :update_manifest? do
+      ! system "mast --recent"
+    end
+
+    rule update_manifest? do
+      system "mast -u"
+    end
+```
+
+To create a Rule for a file state, we can use the `file` state
+method mentioned previously.
+
+```ruby
+    rule file('demo/*.md') do |files|
+      system `qed #{files.join(' ')}`
+    end
+```
+
+But using `file` isn't necessary when it is the only condition b/c
+rules that use a string or a regular expression for the state are
+automatically interpreted to be a file state.
+
+```ruby
+    rule 'man/*.ronn' do |paths|
+      system 'ronn ' + paths.join(' ')
+    end
+```
+
+### State Logic
+
+Rules sometimes require more nuanced conditions based on multiple states. 
+Fire has a state logic system based on *set logic* that can be used
+to build complex states using logical operators `&` (And) and `|` (Or).
+
+```ruby
+    rule happy_hour? & file('*.happy') do |files|
+      puts "These are you happy files:"
+      puts files.join("\n")
+    end
+```
+
+### Tasks
+
+Rules work admirably for most usecases, but sometimes it is necessary
+just to trigger a single action and not have all ones rules come 
+to bare. For this Fire provides *tasks*.
+
+```ruby
+    task :test do
+      sh 'rubytest'
+    end
+```
+
+These rules are then triggered via the command line, or as prerequisite
+actions of other tasks or rules (see below). To make a tasks accessible
+via the command line, a description must be given using the `desc` method
+before the task definition.
+
+```ruby
+    desc "run all unit tests"
+    task :test do
+      sh "rubytest"
+    end
+```
+
+Btw, rules can be given descriptions too, as can states. This information
+isn't important to the Fire's functionality but can useful to a user
+who can request help information about a system.
+
+### Prerequisites
+
+Sometimes rules have prerequisite actions. And often different rules may
+share the same prerequisite actions. But a prerequisite is only ever run
+once for any given run regardless.
+
+```ruby
+    desc "Run all unit tests"
+    task :test => [:setup] do
+      sh "rubytest"
+    end
+
+    desc "Run unit tests when a test file changes."
+    rule 'test/**/test_*.rb' => [:setup] do |files|
+      sh "rubytest #{files.join(' ')}"
+    end
+
+    task :setup do
+      mkdir_p 'tmp'
+    end
+```
+
+Notice how both the test rule and the test task relay on the same 
+prequisite task.
+
+### Running
+
+To run your rules simply use the `fire` command.
+
+```
+    fire
+```
+
+There are few was to manually trigger builds. For file rules, the `-n` option
+will cause the digest to be "null and void", which will cause all files to
+appear out-of-date and thus all be triggered.
+
+Triggers are specified as a command argument.
+
+```
+    fire test
+```
+
+
+### Continuous Integration
+
+Fire can be run continuously by running autofire. To set the 
+interval provide then number of seconds to wait between firings.
+
+```
+    autofire -w 60
+```
+
+This will run fire every 60 seconds. By default the periodicity is 300
+seconds, or every 5 minutes. To stop autofiring run autofire again.
+
+
+### Building Useful Rules
+
+Fire doesn't dictate how rule procedures are coded. It's just Ruby. While it
+does provide easy access to FileUtils methods, beyond that the how of things
+is completely up to the developer.
+
+We do offer one recommendation that will likely make endeavors in this regard
+much easier. Have a look at the [Detroit Toolchain](http://rubyworks.github.com/detroit).
+It has numerous tools largely preconfigured and with built-in smarts to make
+them quick and easy to put into action.
+
+
+## Copyright & License
+
+Fire is copyrighted open-source software.
+
+  Copyright (c) 2011 Rubyworks. All rights reserved.
+
+It is modifiable and redistributable under the terms of the *BSD-2-Clause* license.
+
+See the enclosed LICENSE.txt file for details.
+

data/bin/autofire

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+require 'fire'
+$DEBUG = ARGV.include?('--debug')
+Fire::CLI.autorun
+

data/bin/fire

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+require 'fire'
+$DEBUG = ARGV.include?('--debug')
+Fire::CLI.run
+

data/demo/03_runner/01_applying_rules.md

@@ -0,0 +1,51 @@
+## Applying Rules
+
+The `Runner` class handles running rules. It takes `System` as an argument and
+can run all applicable rules or trigger a named task.
+
+### True/False Rules
+
+The simplist rule state is `true`, which means it will always run, or
+`false` which means it will never run. These states are not very useful,
+but they should still work.
+
+Given a @system defined with a simple always-true rule, and another
+always-false rule:
+
+    rule true do
+      assert true
+    end
+
+    rule false do
+      assert false
+    end
+
+Then the Runner should run the true rule and not the false rule when
+applying the system's rules.
+
+    runner = Fire::Runner.new(@system)
+
+    runner.run_rules
+
+### Simple State Rule
+
+Given a @system defined with a simple state:
+
+    state :simple do
+      true
+    end
+
+    rule simple do
+      assert true
+    end
+
+    rule false do
+      assert false
+    end
+
+Then the Runner should run the simple rule, but not the other.
+
+    runner = Fire::Runner.new(@system)
+
+    runner.run_rules
+

data/demo/03_runner/02_resolve_prerequisites.md

@@ -0,0 +1,95 @@
+# Resolving Prerequisites
+
+The `Runner` class handles running rules. It takes `System` as an argument and
+can run all applicable rules or trigger a named task.
+
+## Task Prerequisites
+
+### Handles Simple Prerequisite
+
+Given a @system defined with a simple prerequisite:
+
+    task :a => [:b] do
+    end
+
+    task :b do
+    end
+
+Then the Runner should resolve to this single prerequisite.
+
+    runner = Fire::Runner.new(@system)
+
+    a = @system.tasks[:a]
+
+    prelist = runner.send(:resolve, a)
+    prelist.assert == [:b]
+
+### Handles DAG
+
+Given a @system defined with a DAG:
+
+    task :a => [:b, :c] do
+    end
+
+    task :b => [:c] do
+    end
+
+    task :c do
+    end
+
+Then the Runner should remove the redundancy from the list of
+prerequisites to be run.
+
+    runner = Fire::Runner.new(@system)
+
+    a = @system.tasks[:a]
+
+    prelist = runner.send(:resolve, a)
+    prelist.assert == [:b, :c]
+
+### Prevents Recursion
+
+Given a @system defined with recursive prerequisites:
+
+    task :a => [:b] do
+    end
+
+    task :b => [:a] do
+    end
+
+Then the Runner should resolve the requirements without the
+infinite repetition.
+
+    runner = Fire::Runner.new(@system)
+
+    a = @system.tasks[:a]
+
+    prelist = runner.send(:resolve, a)
+    prelist.assert == [:b, :a]
+
+Note: it would be better if this raised an error reporting the recursion,
+but this has not been implemented yet.
+
+
+## Rule Prerequisites
+
+### Handles Simple Prerequisite
+
+Given a @system defined with a simple prerequisite:
+
+    rule true => [:b] do
+    end
+
+    task :b do
+    end
+
+Then the Runner should resolve to this single prerequisite.
+
+    runner = Fire::Runner.new(@system)
+
+    a = @system.rules.first  # only one there is
+
+    prelist = runner.send(:resolve, a)
+    prelist.assert == [:b]
+
+