pdf-storycards 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 / 2007-12-27
+
+* Initial release
+

data/Manifest.txt

@@ -0,0 +1,17 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/stories2cards
+lib/pdf/storycards.rb
+lib/pdf/storycards/scenario.rb
+lib/pdf/storycards/story.rb
+lib/pdf/storycards/story_capturing_mediator.rb
+lib/pdf/storycards/writer.rb
+spec/addition
+spec/calculator_stories
+spec/pdf/storycards/story_capturing_mediator_spec.rb
+spec/pdf/storycards/story_spec.rb
+spec/pdf/storycards/writer_spec.rb
+spec/rspec_suite.rb
+spec/spec_helper.rb

data/README.txt

@@ -0,0 +1,55 @@
+PDF StoryCards
+    by Luke Melia
+    http://www.lukemelia.com/
+
+== DESCRIPTION:
+  
+Provides a script and library to parses stories saved in the RSpec
+plain text story format and saves a PDF file with printable 3"x5"
+index cards suitable for using in agile planning and prioritization.
+
+== FEATURES/PROBLEMS:
+  
+* Create a PDF with each page as a 3x5 sheet, or as 4 cards per 8.5 x 11 sheet
+* Currently reads stories from a single file.
+* TODO: Take a directory and find all stories in it
+* TODO: Take stories via STDIN
+* TODO: Improve test coverage
+
+== SYNOPSIS:
+
+  StorycardPdfWriter.make_pdf("/tmp/stories.txt", "/tmp/storycards.pdf", :style => :card_1up)
+
+== REQUIREMENTS:
+
+* RSpec (for parsing stories)
+* PDF::Writer (for creating PDFs)
+
+== INSTALL:
+
+sudo gem install storycards
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2007 Luke Melia
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+dir = File.dirname(__FILE__)
+lib_path = File.expand_path("#{dir}/lib")
+$LOAD_PATH.unshift lib_path unless $LOAD_PATH.include?(lib_path)
+require 'pdf/storycards'
+ENV["VERSION"] = PDF::Storycards::VERSION
+
+Hoe.new('pdf-storycards', PDF::Storycards::VERSION) do |p|
+  p.rubyforge_name = 'pdf-storycards'
+  p.author = 'Luke Melia'
+  p.email = 'luke@lukemelia.com'
+  p.summary = 'Utilities for generating printable story cards for agile planning and measurement'
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  # p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.extra_deps << ['pdf-writer', '>= 1.1.7']
+  p.extra_deps << ['rspec', '>= 1.1.1']
+end
+
+# vim: syntax=Ruby

data/bin/stories2cards

@@ -0,0 +1,129 @@
+#! /usr/bin/env ruby
+
+# == Synopsis 
+#   stories2cards parses stories saved in the RSpec plain text story
+#   format and saves a PDF file with printable 3"x5"" index cards
+#   suitable for using in agile planning and prioritization.
+#
+# == Examples
+#   This command outputs a PDF consisting of one card for each story and
+#   narrative defined in stories.txt and saves it as stories.pdf
+#
+#     stories2cards stories.txt
+#
+#   Other examples
+#
+#     stories2cards stories.txt -o /tmp/cards.pdf
+#     stories2cards stories.txt --style=4up
+#
+# == Usage 
+#   stories2cards [options] text_file_with_stories
+#
+#   For help use stories2cards -h
+#
+# == Options
+#   -h, --help           Displays help message
+#   -v, --version        Display the version, then exit
+#   -o, --output=PATH    Specify the path to the PDF file
+#                        to be created, defaults to storycards.pdf
+#   -s, --style=1up|4up  Defaults to 1up
+#   -b, --[no-]borders   Print borders (only has effect with 4up style
+#
+# == Author
+#   Luke Melia
+#
+# == Copyright
+#   Copyright (c) 2007 Luke Melia. Licensed under the MIT License
+#   http://www.opensource.org/licenses/mit-license.php
+
+require 'optparse' 
+require 'rdoc/usage'
+require 'ostruct'
+
+begin
+  require 'pdf/storycards'
+rescue LoadError => le
+  if le.message =~ %r{pdf/storycards$}
+    root = File.dirname(File.dirname(File.expand_path(__FILE__)))
+    $LOAD_PATH.unshift(File.join(root, "lib"))
+    require 'pdf/storycards'
+  else
+    raise
+  end
+end
+
+class App
+
+  attr_reader :options
+
+  def initialize(arguments, stdin)
+    @arguments = arguments
+    @stdin = stdin
+
+    # Set defaults
+    @options = OpenStruct.new
+    @options.output = "storycards.pdf"
+    @options.style = :"1up"
+  end
+  
+  # Parse options, check arguments, then process the command
+   def run
+     if parsed_options? && arguments_valid?
+       process_arguments            
+       process_command
+     else
+       output_usage
+     end
+   end
+   
+   protected
+
+   def parsed_options?
+
+     # Specify options
+     opts = OptionParser.new 
+     opts.on('-v', '--version') { output_version ; exit 0 }
+     opts.on('-h', '--help') { output_help }
+     opts.on('-o', '--output [PATH]') { |path| @options.output = path }
+     opts.on('-s', '--style [STYLE]', [:"1up", :"4up"]) { |style| @options.style = style }
+     opts.on("-b", "--[no-]borders", "Print borders") { |b| options.borders = b }
+     opts.parse!(@arguments) rescue return false
+
+     true      
+   end
+
+   # True if required arguments were provided
+   def arguments_valid?
+     return false unless @arguments.length == 1
+     return false unless File.exists?(@arguments[0])
+     return true
+   end
+
+   # Setup the arguments
+   def process_arguments
+     @source_file = @arguments[0]
+   end
+
+   def output_help
+     output_version
+     RDoc::usage() #exits app
+   end
+
+   def output_usage
+     RDoc::usage('usage') # gets usage from comments above
+   end
+
+   def output_version
+     puts "#{File.basename(__FILE__)} version #{PDF::Storycards::VERSION}"
+   end
+
+   def process_command
+     style = :card_1up if @options.style == :"1up"
+     style = :letter_4up if @options.style == :"4up"
+     PDF::Storycards::Writer.make_pdf(@source_file, @options.output, :style => style)
+  end
+   end
+
+# Create and run the application
+app = App.new(ARGV, STDIN)
+app.run

data/lib/pdf/storycards.rb

@@ -0,0 +1,10 @@
+module PDF
+  module Storycards
+    VERSION = '0.0.1'
+  end
+end
+
+require 'pdf/storycards/scenario'
+require 'pdf/storycards/story'
+require 'pdf/storycards/story_capturing_mediator'
+require 'pdf/storycards/writer'

data/lib/pdf/storycards/scenario.rb

@@ -0,0 +1,21 @@
+module PDF
+  module Storycards
+    class Scenario
+      def initialize(name)
+        @name = name
+        @steps = []
+      end
+            
+      def add_step(step)
+        @steps << step
+      end
+    end
+
+    class Step
+      def initialize(type, name)
+        @type = type
+        @name = name
+      end          
+    end
+  end
+end

data/lib/pdf/storycards/story.rb

@@ -0,0 +1,24 @@
+module PDF
+  module Storycards
+    class Story
+      def initialize(title, narrative)
+        @title = title
+        @narrative = narrative
+        def @narrative.to_sentence
+          self.sub(/^\s*I want/, ", I want").gsub(/^\s*So that/, ", so that").split($/).join(" ").gsub(' ,',',').squeeze(" ")
+        end
+        @scenarios = []
+      end
+  
+      attr_accessor :title, :narrative
+            
+      def add_scenario(scenario)
+        @scenarios << scenario
+      end
+  
+      def current_scenario
+        @scenarios.last
+      end
+    end
+  end
+end

data/lib/pdf/storycards/story_capturing_mediator.rb

@@ -0,0 +1,52 @@
+# RSpec's story parser needs to be constructed with a Mediator. The mediator defined in the class
+# below simply collects stories and exposes the collection as StoryCapturingMediator#stories.
+#
+# It also sprinkles in a magic method on Story#narrative called to_sentence, which formats the
+# story narrative as a single sentence without newlines.
+module PDF
+  module Storycards
+
+    class StoryCapturingMediator
+  
+      def initialize
+          @stories = []
+      end
+
+      attr_reader :stories
+          
+      def create_story(title, narrative)
+        @stories << Story.new(title, narrative)
+      end
+  
+      def create_scenario(title)
+        current_story.add_scenario Scenario.new(title)
+      end
+  
+      def create_given(name)
+        current_scenario.add_step Step.new('Given', name)
+      end
+  
+      def create_given_scenario(name)
+        current_scenario.add_step Step.new('GivenScenario', name)
+      end
+  
+      def create_when(name)
+        current_scenario.add_step Step.new('When', name)
+      end
+  
+      def create_then(name)
+        current_scenario.add_step Step.new('Then', name)
+      end
+  
+      private
+      def current_story
+        @stories.last
+      end
+  
+      def current_scenario
+        current_story.current_scenario
+      end
+    end
+  end      
+end
+

data/lib/pdf/storycards/writer.rb

@@ -0,0 +1,91 @@
+require 'pdf/writer'
+require 'spec/story/runner/story_parser.rb'
+
+module PDF
+  module Storycards
+    class Writer
+    
+      def self.make_pdf( path, output_path = 'storycards.pdf', opts = {} )
+        output_path = 'storycards.pdf' if output_path.nil?
+        opts[:style] = :card_1up unless opts[:style]
+        opts[:border] = false unless opts[:border]
+  
+        stories = self.parse_stories(path)
+  
+        if opts[:style] == :card_1up
+          pdf = PDF::Writer.new(:paper => [7.62, 12.7], :orientation => :landscape) #3x5 card
+          pdf.margins_mm 8
+          pdf.move_pointer(-60)
+      
+          stories.each_with_index do |story, index|
+            pdf.y = 0 if index > 0
+            print_card_text(pdf, story)
+          end
+      
+          pdf.save_as(output_path)
+          return output_path
+      
+        elsif opts[:style] == :letter_4up
+      
+          pdf = PDF::Writer.new(:paper => "LETTER", :orientation => :landscape)
+          card_width = PDF::Writer.in2pts(5)
+          card_height = PDF::Writer.in2pts(3)
+          margin = PDF::Writer.in2pts(0.33)
+          gutter = margin
+          padding = 10
+
+          pdf.start_columns(2, gutter)
+          stories.each_with_index do |story, index|
+
+            is_laying_out_left_hand_column = (index < 2)
+            if is_laying_out_left_hand_column
+              rect_x = margin
+            else
+              rect_x = pdf.page_width - margin - card_width
+            end
+
+            is_laying_out_top_row = (index % 2 == 0)
+            if is_laying_out_top_row
+              pdf.start_new_page unless index == 0
+              pdf.y = pdf.page_height - margin - padding
+              rect_y = pdf.page_height - margin - card_height
+            else
+              rect_y = margin
+              pdf.y = margin + card_height - padding
+            end
+        
+            print_border(pdf, rect_x, rect_y, card_width, card_height) if opts[:border]
+            print_card_text(pdf, story, padding)
+          end
+
+          pdf.save_as(output_path)
+          return output_path
+      
+        end
+      end
+      private
+  
+      def self.print_border(pdf, x, y, width, height)
+        pdf.stroke_color(Color::RGB::Black)
+        pdf.stroke_style(PDF::Writer::StrokeStyle.new(1))
+        pdf.rectangle(rect_x, rect_y, card_width, card_height).close_stroke                                       
+      end
+  
+      def self.parse_stories(path)
+        story_mediator = StoryCapturingMediator.new
+        story_parser = Spec::Story::Runner::StoryParser.new(story_mediator)
+        story_text = File.read(path)
+        story_parser.parse(story_text.split("\n"))
+        return story_mediator.stories
+      end
+  
+      def self.print_card_text(pdf, story, padding = 0)
+        pdf.text "<b>#{story.title}</b>", :font_size => 18, :justification => :center,
+                                              :left => padding, :right => padding
+        pdf.move_pointer(12)
+        pdf.text story.narrative.to_sentence, :justification => :left, :font_size => 14,
+                                              :left => padding, :right => padding      
+      end
+    end
+  end
+end

data/spec/addition

@@ -0,0 +1,34 @@
+This is a story about a calculator. The text up here above the Story: declaration
+won't be processed, so you can write whatever you wish!
+
+Story: simple addition
+
+  As an accountant
+  I want to add numbers
+  So that I can count beans
+
+  Scenario: add one plus one
+    Given an addend of 1
+    And an addend of 1
+    
+    When the addends are addeds
+    
+    Then the sum should be 3
+    And the corks should be popped
+  
+  Scenario: add two plus five
+    Given an addend of 2
+    And an addend of 5
+    
+    When the addends are added
+    
+    Then the sum should be 7
+    Then it should snow
+    
+  Scenario: add three more
+    GivenScenario add two plus five
+    And an addend of 3
+    
+    When the addends are added
+    
+    Then the sum should be 10

data/spec/calculator_stories

@@ -0,0 +1,66 @@
+This is a story about a calculator. The text up here above the Story: declaration
+won't be processed, so you can write whatever you wish!
+
+Story: simple addition
+
+  As an accountant
+  I want to add numbers
+  So that I can count beans
+
+  Scenario: add one plus one
+    Given an addend of 1
+    And an addend of 1
+    
+    When the addends are addeds
+    
+    Then the sum should be 3
+    And the corks should be popped
+  
+  Scenario: add two plus five
+    Given an addend of 2
+    And an addend of 5
+    
+    When the addends are added
+    
+    Then the sum should be 7
+    Then it should snow
+    
+  Scenario: add three more
+    GivenScenario add two plus five
+    And an addend of 3
+    
+    When the addends are added
+    
+    Then the sum should be 10
+
+Story: simple subtraction
+
+  As an accountant
+  I want to subtract numbers
+  So that I can count beans
+
+  Scenario: subtract one minus one
+    Given an argument of 1
+    And an argument of 1
+
+    When the second argument is subtracted from the first argument
+
+    Then the different should be 0
+    And the corks should be popped
+
+  Scenario: subtract two from five
+    Given an argument of 5
+    And an argument of 2
+
+    When the second argument is subtracted from the first argument
+
+    Then the difference should be 3
+    Then it should snow
+
+  Scenario: subtract two more
+    GivenScenario subtract two from five
+    And an argument of 2
+
+    When the result is reduced by the argument
+
+    Then the result should be 1

data/spec/pdf/storycards/story_capturing_mediator_spec.rb

@@ -0,0 +1,39 @@
+require File.dirname(__FILE__) + '/../../spec_helper.rb'
+
+describe PDF::Storycards::StoryCapturingMediator do
+
+  before(:each) do
+    @mediator = PDF::Storycards::StoryCapturingMediator.new
+  end
+  
+  describe "initial state" do
+    it "should have an empty list of stories" do
+      @mediator.stories.should == []
+    end
+  end
+
+  it "should add stories when sent :create_story" do
+    @mediator.create_story('my title', 'my narrative')
+    @mediator.stories.length.should == 1
+    @mediator.stories.first.should be_an_instance_of(PDF::Storycards::Story)
+  end
+  
+  describe "after having a story added" do
+    before(:each) do
+      @mediator.create_story('User joins a Group',
+                             "As a user
+                              I want to be able to join a group
+                              So that I can connect to members with similar interests")
+    end
+    
+    it "should have a story with the specified title" do
+      @mediator.stories.first.title.should == 'User joins a Group'
+    end
+    
+    it "should have a story with the specified narrative" do
+      @mediator.stories.first.narrative.should =~ /As a user\s+I want to be able to join a group\s+So that I can connect to members with similar interests/
+    end
+    
+  end
+
+end

data/spec/pdf/storycards/story_spec.rb

@@ -0,0 +1,23 @@
+require File.dirname(__FILE__) + '/../../spec_helper.rb'
+
+describe PDF::Storycards::Story do
+  before(:each) do
+    @story = PDF::Storycards::Story.new('User joins a Group',
+                       "As a user
+                        I want to be able to join a group
+                        So that I can connect to members with similar interests")
+  end
+  
+  it "should have the specified title" do
+    @story.title.should == 'User joins a Group'
+  end
+  
+  it "should have the specified narrative" do
+    @story.narrative.should =~ /As a user\s+I want to be able to join a group\s+So that I can connect to members with similar interests/
+  end
+  
+  it "should have a narrative that can be converted to a sentence without newlines" do
+    @story.narrative.to_sentence.should == 'As a user, I want to be able to join a group, so that I can connect to members with similar interests'
+  end
+  
+end

data/spec/pdf/storycards/writer_spec.rb

@@ -0,0 +1,38 @@
+require File.dirname(__FILE__) + '/../../spec_helper.rb'
+
+module PDF
+  class Writer
+    def save_as(path)
+      #no op
+    end
+  end
+end
+
+describe PDF::Storycards::Writer do
+  
+  before(:all) do
+    @single_story_path = File.dirname(__FILE__) + '/../../addition'
+    @multiple_stories_path = File.dirname(__FILE__) + '/../../calculator_stories'
+  end
+  
+  it "should parse an example plain text story file and create a new story" do
+    stories = PDF::Storycards::Writer.send(:parse_stories, @single_story_path)
+    stories.first.title.should == 'simple addition'
+    stories.first.narrative.should == "As an accountant\nI want to add numbers\nSo that I can count beans"
+  end
+  
+  it "should not print border when printing 1-up" do
+    PDF::Storycards::Writer.should_not_receive(:print_border)
+    PDF::Storycards::Writer.make_pdf(@multiple_stories_path, 'storycards.pdf', :style => :card_1up)
+  end
+
+  it "should not print border when printing 4-up with default options" do
+    PDF::Storycards::Writer.should_not_receive(:print_border)
+    PDF::Storycards::Writer.make_pdf(@multiple_stories_path, 'storycards.pdf', :style => :letter_4up)
+  end
+
+  it "should print border when printing 4-up with border option set to true" do
+    PDF::Storycards::Writer.should_receive(:print_border).twice
+    PDF::Storycards::Writer.make_pdf(@multiple_stories_path, 'storycards.pdf', :style => :letter_4up, :border => true)
+  end
+end

data/spec/rspec_suite.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'spec'
+
+if __FILE__ == $0
+  dir = File.dirname(__FILE__)
+  Dir["#{dir}/**/*_spec.rb"].each do |file|
+#    puts "require '#{file}'"
+    require file
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'stringio'
+require 'spec'
+require 'spec/mocks'
+
+dir = File.dirname(__FILE__)
+lib_path = File.expand_path("#{dir}/../lib")
+$LOAD_PATH.unshift lib_path unless $LOAD_PATH.include?(lib_path)
+
+require 'pdf/storycards'

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification 
+name: pdf-storycards
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Luke Melia
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2007-12-29 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: pdf-writer
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.7
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.1
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.4.0
+    version: 
+description: "== FEATURES/PROBLEMS:  * Create a PDF with each page as a 3x5 sheet, or as 4 cards per 8.5 x 11 sheet * Currently reads stories from a single file. * TODO: Take a directory and find all stories in it * TODO: Take stories via STDIN * TODO: Improve test coverage  == SYNOPSIS:  StorycardPdfWriter.make_pdf(\"/tmp/stories.txt\", \"/tmp/storycards.pdf\", :style => :card_1up)  == REQUIREMENTS:"
+email: luke@lukemelia.com
+executables: 
+- stories2cards
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/stories2cards
+- lib/pdf/storycards.rb
+- lib/pdf/storycards/scenario.rb
+- lib/pdf/storycards/story.rb
+- lib/pdf/storycards/story_capturing_mediator.rb
+- lib/pdf/storycards/writer.rb
+- spec/addition
+- spec/calculator_stories
+- spec/pdf/storycards/story_capturing_mediator_spec.rb
+- spec/pdf/storycards/story_spec.rb
+- spec/pdf/storycards/writer_spec.rb
+- spec/rspec_suite.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://www.zenspider.com/ZSS/Products/pdf-storycards/
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: pdf-storycards
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: Utilities for generating printable story cards for agile planning and measurement
+test_files: []
+