saga 0.5.2 → 0.6.0

data/.gitignore

@@ -1,2 +1,4 @@
 html
-pkg
+pkg
+*.swp
+*.swo

data/README.rdoc

@@ -2,15 +2,22 @@
 
 Saga is a tool to convert the requirements format used at Fingertips to HTML.
 
-The Saga document consists of three major parts: an introduction, the stories, and definitions. The document is usually a succinct and complete description of a piece of software. Anyone reading the document should get a fairly good idea of the application without further information.
+The Saga document consists of three major parts: an introduction, the stories,
+and definitions. The document is usually a succinct and complete description of
+a piece of software. Anyone reading the document should get a fairly good idea
+of the application without further information.
+
 
 === The introduction
 
-The first line of the document is the title. You can start the line with ‘Requirements’, but this is not compulsory.
+The first line of the document is the title. You can start the line with
+‘Requirements’, but this is not compulsory.
 
   Requirements Saga
 
-After the title follows a list of authors. It's encouraged to add all the authors, this way people know who to speak to for more information about the stories. Only the name of the author is compulsory.
+After the title follows a list of authors. It's encouraged to add all the
+authors, this way people know who to speak to for more information about the
+stories. Only the name of the author is compulsory.
 
   - Manfred Stienstra, manfred@fngtps.com, Fingertips, http://www.fngtps.com
 
@@ -18,28 +25,39 @@ The final part of the introduction is a concise description of the project.
 
   Saga is a tool to convert the requirements format used at Fingertips to HTML.
 
+
 === The stories
 
 The stories section starts with the USER STORIES header.
 
   USER STORIES
 
-After this follows a list of stories. You can choose to add section headers, but this is optional. For example:
+After this follows a list of stories. You can choose to add section headers,
+but this is optional. For example:
+
+  As a writer I would like to convert my description of the project to a nice format. - #1 todo
 
-  As a writer I want to convert my description of the project to a nice format. - #1 todo
-  
   Workflow
-  
-  As a writer I want an example so I don't have to remember all the details of the format. – #2 todo
+
+  As a writer I would like to see an example so that I don't have to remember all the details of the format. – #2 todo
     Try to find author details for the system information and autofill that in the generated stub.
-  As a writer I want to debug the parse process so I can find out what I did wrong. - #3 todo
-  
+  As a writer I would like to debug the parse process so I can find out what I did wrong. - #3 todo
+
+Stories consist of a description and some extra information. The number behind
+the hash is the unique number of the story. We use the id to point to a story
+without having to type the whole description in everyday conversation. The
+little text label at the end describes the status of the story.
+
+A TextMate bundle for the stories format is available from:
+https://github.com/Fingertips/stories.tmbundle
 
-Stories consist of a description and some extra information. The number behind the hash is the unique number of the story. We use the id to point to a story without having to type the whole description in everyday conversation. The little text label at the end describes the status of the story.
 
 === Definitions
 
-The document ends with a list of definitions. Here we define words used throughout the document. We only define words if they need a strict definition or if they might be misunderstood by someone. Like with the stories sections are optional.
+The document ends with a list of definitions. Here we define words used
+throughout the document. We only define words if they need a strict definition
+or if they might be misunderstood by someone. Like with the stories sections
+are optional.
 
   ROLES
   
@@ -50,16 +68,33 @@ The document ends with a list of definitions. Here we define words used througho
   
   Project: The software project the developers are working on.
 
+
+=== Template
+
+By default the Fingertips template is used when converting requirements to HTML.
+You can, however, create a custom template. To start from the default one use
+the <tt>template</tt> command:
+
+  $ saga template design/requirements_template
+
+Edit the files in the created directory to your liking and then convert your
+requirements with the <tt>--template</tt> option:
+
+  $ saga convert --template design/requirements_template requirements.txt > requirements.html
+
+
 === Usage
 
   Usage: saga [command]
-  
+
   Commands:
       new                 - prints a blank stub
       convert <filename>  - convert the stories to HTML
       inspect <filename>  - print the internals of the document
       autofill <filename> - adds an id to stories without one
       planning <filename> - shows the planning of stories in iterations
-  
+      template <dir>      - creates a template directory
+
   Options:
+      -t, --template DIR               Use an external template for conversion to HTML
       -h, --help                       Show help

data/Rakefile

@@ -6,9 +6,7 @@ task :default => [:spec]
 
 desc "Run all specs"
 task :spec do
-  Dir[File.dirname(__FILE__) + '/test/**/*_spec.rb'].each do |file|
-    load file
-  end
+  sh 'bacon test/*_spec.rb'
 end
 
 namespace :documentation do
@@ -32,4 +30,4 @@ begin
     s.add_development_dependency('mocha-on-bacon')
   end
 rescue LoadError
-end
+end

data/VERSION

@@ -1 +1 @@
-0.5.2
+0.6.0

data/lib/saga/formatter.rb

@@ -7,20 +7,23 @@ module Saga
     def initialize(document, options={})
       @document = document
       @options  = options
-      @options[:template] ||= 'default'
+      @options[:template] ||= File.join(self.class.template_path, 'default')
     end
     
     def format
-      template_path = File.join(self.class.template_path, @options[:template])
+      helpers_file = File.join(@options[:template], 'helpers.rb')
+      if File.exist?(helpers_file)
+        load helpers_file
+        @document.extend(Helpers)
+      end
       
-      helpers_file = File.join(template_path, 'helpers.rb')
-      load helpers_file
-      @document.extend(Helpers)
-      binding = @document.send(:binding)
-      
-      template_file = File.join(template_path, 'document.erb')
-      template = Erubis::Eruby.new(File.read(template_file))
-      template.result(binding)
+      template_file = File.join(@options[:template], 'document.erb')
+      if File.exist?(template_file)
+        template = Erubis::Eruby.new(File.read(template_file))
+        template.result(@document.send(:binding))
+      else
+        raise ArgumentError, "The template at path `#{template_file}' could not be found."
+      end
     end
     
     def self.format(document, options={})
@@ -31,5 +34,9 @@ module Saga
     def self.template_path
       TEMPLATE_PATH
     end
+
+    def self.saga_format(document)
+      format(document, :template => File.join(template_path, 'saga'))
+    end
   end
-end
+end

data/lib/saga/runner.rb

@@ -17,9 +17,13 @@ module Saga
         opts.separator "    inspect <filename>  - print the internals of the document"
         opts.separator "    autofill <filename> - adds an id to stories without one"
         opts.separator "    planning <filename> - shows the planning of stories in iterations"
+        opts.separator "    template <dir>      - creates a template directory"
         opts.separator ""
         opts.separator "Options:"
-        opts.on("-h", "--help", "Show help") do
+        opts.on("-t", "--template DIR", "Use an external template for conversion to HTML") do |template_path|
+          @options[:template] = File.expand_path(template_path)
+        end
+        opts.on("-h", "--help",     "Show help") do
           puts opts
           exit
         end
@@ -40,11 +44,11 @@ module Saga
         :definition => 'Someone who is responsible for writing down requirements in the form of stories'
       }]
       
-      Saga::Formatter.format(document, :template => 'saga')
+      Saga::Formatter.saga_format(document)
     end
     
-    def convert(filename)
-      Saga::Formatter.format(Saga::Parser.parse(File.read(filename)))
+    def convert(filename, options)
+      Saga::Formatter.format(Saga::Parser.parse(File.read(filename)), options)
     end
     
     def write_parsed_document(filename)
@@ -60,34 +64,46 @@ module Saga
     def autofill(filename)
       document = Saga::Parser.parse(File.read(filename))
       document.autofill_ids
-      Saga::Formatter.format(document, :template => 'saga')
+      Saga::Formatter.saga_format(document)
     end
     
     def planning(filename)
       Saga::Planning.new(Saga::Parser.parse(File.read(filename))).to_s
     end
     
+    def copy_template(destination)
+      if File.exist?(destination)
+        puts "The directory `#{destination}' already exists!"
+      else
+        require 'fileutils'
+        FileUtils.mkdir_p(destination)
+        FileUtils.cp(File.join(Saga::Formatter.template_path, 'default/helpers.rb'), destination)
+        FileUtils.cp(File.join(Saga::Formatter.template_path, 'default/document.erb'), destination)
+      end
+    end
+    
     def run_command(command, options)
       case command
       when 'new'
         puts new_file
       when 'convert'
-        puts convert(File.expand_path(@argv[1]))
+        puts convert(File.expand_path(@argv[0]), options)
       when 'inspect'
-        write_parsed_document(File.expand_path(@argv[1]))
+        write_parsed_document(File.expand_path(@argv[0]))
       when 'autofill'
-        puts autofill(File.expand_path(@argv[1]))
+        puts autofill(File.expand_path(@argv[0]))
       when 'planning'
-        puts planning(File.expand_path(@argv[1]))
+        puts planning(File.expand_path(@argv[0]))
+      when 'template'
+        copy_template(File.expand_path(@argv[0]))
       else
-        puts convert(File.expand_path(command))
+        puts convert(File.expand_path(command), options)
       end
     end
     
     def run
-      argv = @argv.dup
-      parser.parse!(argv)
-      if command = argv.shift
+      parser.parse!(@argv)
+      if command = @argv.shift
         run_command(command, @options)
       else
         puts parser.to_s
@@ -99,4 +115,4 @@ module Saga
       {:name => name}
     end
   end
-end
+end

data/saga.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{saga}
-  s.version = "0.5.2"
+  s.version = "0.6.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Manfred Stienstra"]
-  s.date = %q{2010-08-13}
+  s.date = %q{2011-02-17}
   s.default_executable = %q{saga}
   s.description = %q{Saga is a tool to convert stories syntax to a nicely formatted document.}
   s.email = %q{manfred@fngtps.com}
@@ -43,6 +43,7 @@ Gem::Specification.new do |s|
      "test/cases/definition.txt",
      "test/cases/story.txt",
      "test/cases/story_attributes.txt",
+     "test/fixtures/document.erb",
      "test/saga_document_spec.rb",
      "test/saga_formatter_spec.rb",
      "test/saga_parser_spec.rb",

data/test/fixtures/document.erb

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<title>Requirements <%= title %> &middot; Fingertips</title>
+<link rel="stylesheet" type="text/css" media="all" href="http://resources.fngtps.com/2006/doc.css" />
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<style type="text/css">
+  td.id { text-align: right !important; }
+  td.id a { color: #000; }
+  table.review { border-bottom: 1px solid #ccc; margin-top: -1em;}
+  table.review td { padding: .25em 0; vertical-align: top; text-align: left; min-width: 1em; }
+  table.review th { padding: .25em 0; vertical-align: top; text-align: right; }
+  table.review td.story { width: 100%; border-top: 1px solid #ccc; }
+  table.review td.meta { padding-left: 1em; border-top: 1px solid #ccc; text-align: right !important; white-space: nowrap; }
+  table.review td.notes { color: #666; padding: 0 0 .25em 0; font-style: italic; }
+  table.review .dropped { color: #666; text-decoration: line-through; }
+  table.review .done { color: #666; background-color: #f0f8ff; }
+</style>
+<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js"></script>
+</head>
+<body id="doc" class="requirements">
+
+<p id="logo"><img src="http://resources.fngtps.com/2006/print-logo.png" alt="Fingertips design &amp; development" /> </p>
+
+<h1>Requirements <br /><%= title %></h1>
+
+<% authors.each do |author| %>
+<p class="author"><%= author %></p>
+<% end %>
+
+<% introduction.each do |paragraph| %>
+<p><%= paragraph %></p>
+<% end %>
+
+<% unless stories.empty? %>
+<h2>User stories</h2>
+<% stories.each do |header, stories| %>
+<% unless header.strip == '' %>
+<h3><%= header %></h3>
+<% end %>
+<table class="review">
+<tr>
+  <th></th>
+  <th title="id">#</th>
+  <th title="Estimate">e</th>
+  <th title="Iteration">i</th>
+  <th title="Status">s</th>
+</tr>
+<% stories.each do |story| %>
+<tr class="<%= story[:status] %>" id="story<%= story[:id] %>">
+  <td class="story"><%= story[:description] %></td>
+  <td class="meta id"><%= story[:id] %></td>
+  <td class="meta estimate"><%= story[:estimate] %></td>
+  <td class="meta iteration"><%= story[:iteration] %></td>
+  <td class="meta status"><%= story[:status] %></td>
+</tr>
+<% if story[:notes] %>
+<tr class="<%= story[:status] %>">
+  <td class="notes" colspan="5"><%= story[:notes] %></td>
+</tr>
+<% end %>
+<% end %>
+</table>
+<% end %>
+<% end %>
+
+<% definitions.each do |header, definitions| %>
+<% unless header.strip == '' %>
+<h2><%= header %></h2>
+<% end %>
+<dl>
+<% definitions.each do |definition| %>
+<dt><%= definition[:title] %></dt>
+<dd><%= definition[:definition] %></dd>
+<% end %>
+</dl>
+<% end %>
+</body>
+</html>

data/test/saga_formatter_spec.rb

@@ -24,7 +24,21 @@ describe "Formatter" do
   end
   
   it "formats a saga document to saga" do
-    saga = Saga::Formatter.format(@document, :template => 'saga')
+    saga = Saga::Formatter.saga_format(@document)
     saga.should.include('Requirements Requirements API')
   end
-end
+
+  describe "with an external template" do
+    it "raises when the document.erb file doesn't exist" do
+      lambda {
+        Saga::Formatter.format(@document, :template => '/does/not/exist')
+      }.should.raise(ArgumentError, "The template at path `/does/not/exist/document.erb' could not be found.")
+    end
+
+    it "omits the helpers.rb file it it doesn't exist" do
+      formatter = Saga::Formatter.new(@document, :template => File.expand_path('../fixtures', __FILE__))
+      formatter.expects(:load).never
+      formatter.format.should.not.be.empty
+    end
+  end
+end

data/test/saga_runner_spec.rb

@@ -61,7 +61,7 @@ describe "A Runner" do
   
   it "converts the provided filename" do
     runner = Saga::Runner.new(%w(requirements.txt))
-    runner.expects(:convert).with(File.expand_path('requirements.txt')).returns('output')
+    runner.expects(:convert).with(File.expand_path('requirements.txt'), {}).returns('output')
     collect_stdout do
       runner.run
     end.should == "output\n"
@@ -69,12 +69,22 @@ describe "A Runner" do
   
   it "converts the provided filename when the convert command is given" do
     runner = Saga::Runner.new(%w(convert requirements.txt))
-    runner.expects(:convert).with(File.expand_path('requirements.txt')).returns('output')
+    runner.expects(:convert).with(File.expand_path('requirements.txt'), {}).returns('output')
     collect_stdout do
       runner.run
     end.should == "output\n"
   end
   
+  it "converts the provided filename with an external template" do
+    Saga::Parser.stubs(:parse)
+    File.stubs(:read)
+    Saga::Formatter.expects(:format).with do |_, options|
+      options[:template].should == File.expand_path('path/to/a/template')
+    end
+    runner = Saga::Runner.new(%W(convert --template path/to/a/template requirements.txt))
+    collect_stdout { runner.run }
+  end
+  
   it "inspects the parsed document" do
     runner = Saga::Runner.new(%w(inspect requirements.txt))
     runner.expects(:write_parsed_document).with(File.expand_path('requirements.txt'))
@@ -96,4 +106,32 @@ describe "A Runner" do
       runner.run
     end.should == "output\n"
   end
-end
+  
+  it "copies the default template to the specified path" do
+    begin
+      destination = "/tmp/saga-template-dir"
+      Saga::Runner.new(%W(template #{destination})).run
+      File.read(File.join(destination, 'helpers.rb')).should ==
+        File.read(File.join(Saga::Formatter.template_path, 'default/helpers.rb'))
+      File.read(File.join(destination, 'document.erb')).should ==
+        File.read(File.join(Saga::Formatter.template_path, 'default/document.erb'))
+    ensure
+      FileUtils.rm_rf(destination)
+    end
+  end
+  
+  it "complains when tryin to create a template at an existing path" do
+    begin
+      destination = "/tmp/saga-template-dir"
+      FileUtils.mkdir_p(destination)
+      runner = Saga::Runner.new(%W(template #{destination}))
+      collect_stdout do
+        runner.run
+      end.should == "The directory `#{destination}' already exists!\n"
+      File.should.not.exist File.join(destination, 'helpers.rb')
+      File.should.not.exist File.join(destination, 'document.erb')
+    ensure
+      FileUtils.rm_rf(destination)
+    end
+  end
+end

data/test/saga_spec.rb

@@ -24,7 +24,7 @@ describe "Saga" do
   it "round-trips through the parser and formatter" do
     document = @document
     2.times do
-      saga     = Saga::Formatter.format(document, :template => 'saga')
+      saga     = Saga::Formatter.saga_format(document)
       document = Saga::Parser.parse(saga)
     end
     
@@ -32,4 +32,4 @@ describe "Saga" do
     document.authors.should == @document.authors
     document.stories.should == @document.stories
   end
-end
+end

data/test/spec_helper.rb

@@ -7,4 +7,4 @@ require 'mocha-on-bacon'
 
 Bacon.extend Bacon::TapOutput
 $:.unshift(File.expand_path('../../lib', __FILE__))
-require 'saga'
+require 'saga'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: saga
 version: !ruby/object:Gem::Version 
-  hash: 15
+  hash: 7
   prerelease: false
   segments: 
   - 0
-  - 5
-  - 2
-  version: 0.5.2
+  - 6
+  - 0
+  version: 0.6.0
 platform: ruby
 authors: 
 - Manfred Stienstra
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-13 00:00:00 +02:00
+date: 2011-02-17 00:00:00 +01:00
 default_executable: saga
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -96,6 +96,7 @@ files:
 - test/cases/definition.txt
 - test/cases/story.txt
 - test/cases/story_attributes.txt
+- test/fixtures/document.erb
 - test/saga_document_spec.rb
 - test/saga_formatter_spec.rb
 - test/saga_parser_spec.rb