saga 0.2.0 → 0.3.0

data/README.rdoc

@@ -1,3 +1,64 @@
 = Saga
 
-Saga is a tool to convert the story format used at Fingertips to a readable document.
+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 introduction
+
+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.
+
+  - Manfred Stienstra, manfred@fngtps.com, Fingertips, http://www.fngtps.com
+
+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:
+
+  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
+    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
+  
+
+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.
+
+  ROLES
+  
+  Writer: Someone who was appointed the task of writing the stories.
+  Developer: A person developing the application.
+  
+  DEFINITIONS
+  
+  Project: The software project the developers are working on.
+
+=== 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
+  
+  Options:
+      -h, --help                       Show help

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/lib/saga/document.rb

@@ -11,5 +11,35 @@ module Saga
       @stories      = ActiveSupport::OrderedHash.new
       @definitions  = ActiveSupport::OrderedHash.new
     end
+    
+    def used_ids
+      @stories.values.inject([]) do |ids, stories|
+        ids.concat stories.map { |story| story[:id] }
+        ids
+      end.compact
+    end
+    
+    def unused_ids(limit)
+      position = 1
+      used_ids = used_ids()
+      (1..limit).map do
+        while used_ids.include?(position) do position += 1 end
+        used_ids << position
+        position
+      end
+    end
+    
+    def length
+      stories.inject(0) { |total, (_, stories)| total + stories.length }
+    end
+    
+    def autofill_ids
+      unused_ids = unused_ids(length - used_ids.length)
+      stories.each do |_, stories|
+        stories.each do |story|
+          story[:id] ||= unused_ids.shift
+        end
+      end
+    end
   end
 end

data/lib/saga/runner.rb

@@ -15,6 +15,7 @@ module Saga
         opts.separator "    new                 - prints a blank stub"
         opts.separator "    convert <filename>  - convert the stories to HTML"
         opts.separator "    inspect <filename>  - print the internals of the document"
+        opts.separator "    autofill <filename> - adds an id to stories without one"
         opts.separator ""
         opts.separator "Options:"
         opts.on("-h", "--help", "Show help") do
@@ -31,6 +32,10 @@ module Saga
       Saga::Formatter.format(document, :template => 'saga')
     end
     
+    def convert(filename)
+      Saga::Formatter.format(Saga::Parser.parse(File.read(filename)))
+    end
+    
     def write_parsed_document(filename)
       document = Saga::Parser.parse(File.read(filename))
       puts document.title
@@ -41,10 +46,13 @@ module Saga
       document.definitions.each { |header, definitions| puts header; definitions.each { |definition| p definition } }
     end
     
-    def convert(filename)
-      Saga::Formatter.format(Saga::Parser.parse(File.read(filename)))
+    def autofill(filename)
+      document = Saga::Parser.parse(File.read(filename))
+      document.autofill_ids
+      Saga::Formatter.format(document, :template => 'saga')
     end
     
+    
     def run_command(command, options)
       case command
       when 'new'
@@ -53,6 +61,8 @@ module Saga
         puts convert(File.expand_path(@argv[1]))
       when 'inspect'
         write_parsed_document(File.expand_path(@argv[1]))
+      when 'autofill'
+        puts autofill(File.expand_path(@argv[1]))
       else
         puts convert(File.expand_path(command))
       end

data/saga.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{saga}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Manfred Stienstra"]
-  s.date = %q{2010-03-31}
+  s.date = %q{2010-04-02}
   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}

data/templates/saga/document.erb

@@ -4,4 +4,19 @@ Requirements <%= title %>
 - <%= format_author(author) %>
 <% end %>
 
-USER STORIES
+USER STORIES
+<% stories.each do |header, stories| %>
+
+<%= "#{header}\n" if header %>
+<% stories.each do |story| %>
+<%= format_story(story) %>
+<% end %>
+<% end %>
+
+<% definitions.each do |header, definitions| %>
+
+<%= "#{header}\n" if header %>
+<% definitions.each do |definition| %>
+<%= format_definition(definition) %>
+<% end %>
+<% end %>

data/templates/saga/helpers.rb

@@ -4,4 +4,18 @@ module Helpers
       author[key]
     end.compact.join(', ')
   end
+  
+  def format_story(story)
+    story_attributes = []
+    story_attributes << "##{story[:id]}" if story[:id]
+    story_attributes << "##{story[:status]}" if story[:status]
+    
+    parts = [[story[:description], story_attributes.join(' ')].join(' - ')]
+    parts << "  #{story[:notes]}" if story[:notes]
+    parts.join("\n\n")
+  end
+  
+  def format_definition(definition)
+    [definition[:title], definition[:definition]].join(': ')
+  end
 end

data/test/saga_document_spec.rb

@@ -25,4 +25,61 @@ describe "A Document" do
     end
     document.definitions.keys.should == sections
   end
+  
+  it "should return a list of used IDs" do
+    document = Saga::Document.new
+    document.used_ids.should == []
+    
+    document.stories[''] = []
+    document.stories[''] << { :id => 2 }
+    document.used_ids.should == [2]
+    
+    document.stories['Non-functional'] = []
+    document.stories['Non-functional'] << { :id => 12 }
+    document.used_ids.should == [2, 12]
+    
+    document.stories['Non-functional'] << { :id => 3 }
+    document.used_ids.should == [2, 12, 3]
+  end
+  
+  it "should return a list of unused IDs" do
+    document = Saga::Document.new
+    document.unused_ids(0).should == []
+    document.unused_ids(3).should == [1,2,3]
+    document.unused_ids(4).should == [1,2,3,4]
+    
+    document.stories[''] = []
+    document.stories[''] << { :id => 2 }
+    document.stories[''] << { :id => 4 }
+    document.stories[''] << { :id => 5 }
+    document.stories[''] << { :id => 6 }
+    document.stories[''] << { :id => 100 }
+    
+    document.unused_ids(0).should == []
+    document.unused_ids(1).should == [1]
+    document.unused_ids(2).should == [1,3]
+    document.unused_ids(3).should == [1,3,7]
+    document.unused_ids(4).should == [1,3,7,8]
+  end
+  
+  it "should autofills ids" do
+    document = Saga::Document.new
+    document.autofill_ids
+    
+    document.stories[''] = []
+    document.stories[''] << { :description => 'First story'}
+    document.stories[''] << { :description => 'Second story'}
+    
+    document.stories['Non-functional'] = []
+    document.stories['Non-functional'] << { :id => 1, :description => 'Third story' }
+    
+    document.stories['Developer'] = []
+    document.stories['Developer'] << { :description => 'Fourth story' }
+    document.stories['Developer'] << { :id => 3, :description => 'Fifth story' }
+    
+    document.autofill_ids
+    document.stories[''].map { |story| story[:id] }.should == [2, 4]
+    document.stories['Non-functional'].map { |story| story[:id] }.should == [1]
+    document.stories['Developer'].map { |story| story[:id] }.should == [5, 3]
+  end
 end

data/test/saga_runner_spec.rb

@@ -80,4 +80,12 @@ describe "A Runner" do
     runner.expects(:write_parsed_document).with(File.expand_path('requirements.txt'))
     runner.run
   end
+  
+  it "autofills the parsed document" do
+    runner = Saga::Runner.new(%w(autofill requirements.txt))
+    runner.expects(:autofill).with(File.expand_path('requirements.txt')).returns('output')
+    collect_stdout do
+      runner.run
+    end.should == "output\n"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: saga
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Manfred Stienstra
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-31 00:00:00 +02:00
+date: 2010-04-02 00:00:00 +02:00
 default_executable: saga
 dependencies: 
 - !ruby/object:Gem::Dependency