graffle 0.1.9 → 0.2.0

data/lib/graffle.rb

@@ -38,7 +38,7 @@ module Graffle
       filename = File.join(filename, "data.plist")
     end
 
-    parse_xml(File.read(filename))
+    parse_xml(data_from(filename))
   end
   
   def self.parse_xml(content)
@@ -46,7 +46,16 @@ module Graffle
       Document.takes_on(doc)
     end
   end
-
+  
+  def self.data_from(filename)
+    possible_gzip_header = File.read(filename, 2)
+    if possible_gzip_header.unpack('CC') == [0x1f, 0x8b]
+      `gunzip < '#{filename}'`
+    else
+      File.read(filename)
+    end
+  end
+    
   def self.stereotype(o)        # :nodoc:
     return true if ShapedGraphic.takes_on(o)
     return true if LineGraphic.takes_on(o)

data/lib/graffle/nodoc/hacks.rb

@@ -3,6 +3,7 @@
 #  Created by Brian Marick on 2007-07-06.
 #  Copyright (c) 2007. All rights reserved.
 
+
 require 'pp'
 
 class Object

data/lib/graffle/point.rb

@@ -2,6 +2,7 @@
 #
 #  Created by Brian Marick on 2007-07-06.
 #  Copyright (c) 2007. All rights reserved.
+"prevent the above from infecting rdoc"
 
 
 module Graffle

data/lib/graffle/stereotypes.rb

@@ -2,6 +2,8 @@
 #
 #  Created by Brian Marick on 2007-07-06.
 #  Copyright (c) 2007. All rights reserved.
+"prevent the above from infecting rdoc"
+
 
 module Graffle
   module Builders # :nodoc: 
@@ -132,8 +134,16 @@ module Graffle
     # Pro feature)
     def has_note?; self.has_key?('Notes'); end
     alias_method :has_notes?, :has_note?
+
+    # Delete this graphic from inside its Container (a Sheet or a 
+    # Group). The name is delete_yourself to avoid overriding the
+    # delete method on the underlying class.
+    def delete_yourself
+      container.delete_graphic(self)
+    end
     
-    
+
+
   end
   
   
@@ -338,11 +348,11 @@ module Graffle
       if label
         label.content.as_lines
       else
-        label || []
+        label || []    # TODO: Remove unnecessary first condition.
       end
     end
       
-    
+      
     private
     def points_at(*points)
       self['Points'] = points.collect { |p| "{#{p[0]}, #{p[1]}}" }
@@ -379,6 +389,16 @@ module Graffle
         o.container = self  # works because instance_evaled.
       end
     end
+    
+    # Delete a graphic from inside this Container
+    # The name is delete_graphic to avoid overriding the
+    # delete method on the underlying class.
+    def delete_graphic(graphic)
+      graphic.container = nil
+      graphics.delete(graphic)
+    end
+
+    
 
     # Find the AbstractGraphic matching the integer id. Returns nil
     # if not found.
@@ -396,6 +416,15 @@ module Graffle
       end
       result
     end
+    
+    # Find a graphic whose ShapedGraphic#content matches the given
+    # _string_.
+    def find_by_content(string)
+      result = graphics.find do | elt |
+        elt.respond_to?(:content) && 
+          elt.content.as_plain_text.downcase === string.downcase
+      end
+    end
 
     def self.stereotype_children_of(parent) # :nodoc:
       parent.graphics.each do | child |
@@ -409,6 +438,7 @@ module Graffle
       end
       true
     end
+    
 
   end
   
@@ -498,6 +528,7 @@ module Graffle
     # Null object for text
     class Null # :nodoc:
       def as_lines; []; end
+      def as_plain_text; ''; end
     end
     
   end

data/lib/graffle/version.rb

@@ -2,7 +2,9 @@
 #
 #  Created by Brian Marick on 2007-07-06.
 #  Copyright (c) 2007. All rights reserved.
+"prevent the above from infecting rdoc"
+
 
 module Graffle
-  Version = '0.1.9'
+  Version = '0.2.0'
 end

data/lib/graphical_tests_for_rails.rb

@@ -5,23 +5,25 @@
 
 
 require 'graffle'
+require 'graphical_tests_for_rails/jumbled-string-canonicalizer'
 require 'graphical_tests_for_rails/orderings'
+require 'graphical_tests_for_rails/picture-applier'
+require 'graphical_tests_for_rails/stereotype-extensions'
 require 'graphical_tests_for_rails/text-appliers'
-require 'graphical_tests_for_rails/picture-appliers'
-require 'graphical_tests_for_rails/graphic-volunteers'
-require 'graphical_tests_for_rails/volunteer-pool'
+require 'graphical_tests_for_rails/user-intention'
 
 # Classes within this module help you build up Rails integration tests
 # from OmniGraffle files. The important classes are these:
 #
-# * GraphicInterpreter: These objects are 'programmed' with
-#   AbstractTextApplier objects who know how to convert lines of text
-#   into messages and arguments to send to a _target_.
-# * GraphicOrderer: These objects take a list of graphics in no
+# * PictureApplier: These objects are 'programmed' with unstructured
+#   descriptions of how they should handle particular lines in particular
+#   kinds of Graffle objects. Once programmed, they are handed Graffle
+#   objects, turn them into messages (and arguments), and send those messages
+#   to some _target_. 
+# * GraphicArrayOrderings::GraphicOrderer: These objects take a list of graphics in no
 #   particular order and put it in the right order for a particular
-#   style of test. For example, an InWorkflowOrder represents an 
+#   style of test. For example, an GraphicArrayOrderings::InWorkflowOrder represents an 
 #   order created by tracing through shapes connected by lines.
-
 module GraphicalTestsForRails
   include GraphicArrayOrderings
   include TextAppliers

data/lib/graphical_tests_for_rails/jumbled-string-canonicalizer.rb

@@ -0,0 +1,117 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-29.
+#  Copyright (c) 2007. All rights reserved.
+
+require 'ostruct'
+require 's4t-utils'
+
+module GraphicalTestsForRails
+  # A JumbledStringCanonicalizer takes a string of words and matches it 
+  # against a set of patterns, returning strings that represent each match.
+  # All of the regular expressions in the array must match for the corresponding
+  # string to be returned.
+  class JumbledStringCanonicalizer
+    
+    # The _patterns_ are a hash mapping arrays of regular expressions to strings. 
+    # The block can be used to change the default. Messages within the block are
+    # sent to this JumbledStringCanonicalizer. (The block is instance_eval'd.)
+    def initialize(patterns = {}, &block) # :yields:
+      @patterns = patterns
+      @no_match_message = proc {|source| "Cannot recognize anything in '#{source}'"}
+      @multiple_match_message = proc do |source, pretty_reasons, raw_reasons| 
+        "Multiple matches in '#{source}':\n" + 
+        pretty_reasons.join("\n")
+      end
+      instance_eval(&block) if block
+    end
+    
+    # Set a default value to return when there's no match. The default 
+    # behavior is to raise a StandardError exception.
+    def default(value)
+      @default_given = true
+      @default = value
+    end
+    
+    # If no match was found and there's no default value, the _block_ is 
+    # called with the failing string as its only argument. That block should 
+    # produce a string that's set as the raised StandardError's message.
+    def no_match_message(&block) # :yields: failing_string
+      @no_match_message = block
+    end
+
+    # If more than one of the arrays matches a string, and there's no disambiguator, 
+    # the _block_ is called with the failing string as its only argument. That block should 
+    # produce a string that's set as the raised StandardError's message.
+    def multiple_match_message(&block) # :yields: failing_string
+      @multiple_match_message = block
+    end
+    
+    # This method takes a _block_ like the ones passed to Array#sort (two arguments,
+    # a return value that's 1, 0, or -1). If there are multiple matches for a given 
+    # string, they are sorted and the first one is chosen. If there is no 
+    # disambiguator, StandardError is raised.
+    def disambiguate(&block) # :yields:  match1, match2
+      @disambiguator = block
+    end
+    
+    # Take a string, match it against one of the keys in the _patterns_ given to 
+    # JumbledStringCanonicalizer.new, and return an informative object. That object
+    # responds to these messages:
+    # * value: the string value corresponding to the match.
+    # * source: the original _string_ (unchanged)
+    # * raw_reason: an array. Each element is a list of the groups captured
+    #   by one of the regular expressions in the match, but with any nil
+    #   groups compacted out.
+    # * pretty_reason: the raw_reason converted into a tolerably understandable
+    #   string.
+    # If there 
+    # are zero matches or more than one match, the default behavior is to raise StandardError.
+    def canonicalize(string)
+      raw_reasons = []
+      matches = @patterns.keys.collect do |k|
+        raw_reasons = []
+        if k.all? { |r| r =~ string && raw_reasons << $~.captures.compact }
+          OpenStruct.new(:value => @patterns[k], :source => string, 
+                         :raw_reason => raw_reasons,
+                         :pretty_reason => prettify(raw_reasons))
+        end
+      end.compact
+      case matches.length
+      when 0: error_or_default(string)
+      when 1: matches.first
+      else error_or_disambiguation(string, matches)
+      end
+    end
+    
+    private
+    
+    def prettify(raw_reasons)
+      clauses = raw_reasons.collect do |partial_list|
+        S4tUtils.friendly_list("and", partial_list)
+      end
+      clauses.join("; and also ")
+    end
+        
+    def quote(text)
+      %Q{"#{text}"}
+    end
+    
+    def error_or_default(string)
+      if @default_given
+        OpenStruct.new(:value => @default, :source => string,
+                       :raw_reason => [],
+                       :pretty_reason => "no matching words")
+      else
+        user_is_bewildered(@no_match_message.call(string))
+      end
+    end
+    
+    def error_or_disambiguation(string, matches)
+      return matches.sort(&@disambiguator).first if @disambiguator
+      user_is_bewildered(@multiple_match_message.call(
+                            string, matches.collect { |m| m.pretty_reason },
+                            matches.collect { |m| m.raw_reason }))
+    end
+  end
+end

data/lib/graphical_tests_for_rails/orderings.rb

@@ -2,8 +2,7 @@
 #
 #  Created by Brian Marick on 2007-07-11.
 #  Copyright (c) 2007. All rights reserved.
-
-require 'graffle'
+"prevent the above from infecting rdoc"
 
 
 module GraphicalTestsForRails

data/lib/graphical_tests_for_rails/picture-applier.rb

@@ -0,0 +1,257 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-22.
+#  Copyright (c) 2007. All rights reserved.
+
+
+require 'graphical_tests_for_rails/text-appliers'
+require 'graphical_tests_for_rails/user-intention'
+
+require 'enumerator'
+require 'test/unit/assertionfailederror'
+require 'ostruct'
+
+
+module GraphicalTestsForRails
+
+  # A PictureApplier takes a list of strings and deduces what those strings
+  # say about how to generate message sends from graphics. It can then be
+  # given a list of AbstractGraphic objects to send those messages to some
+  # target object.
+  #
+  # Here are typical strings:
+  #   "ignore shape content"
+  #   "line label content is user action with arguments in quotes"
+  #   "annotations with ellipses are page names"
+  #   "in shape content with ellipses, ignore lines with one word"
+  #
+  # Here's what strings can describe. Unless noted, words don't have to be
+  # in any particular order. You can generally use either singular or 
+  # plural forms.
+  # * kind of graphic. It can be a _line_, a <i>line label</i>, or a
+  #   _shape_ (alt. <i>shaped graphic</i>). Groups are not currently 
+  #   allowed. The kind of graphic can be omitted, in which case
+  #   the string matches all kinds.
+  # * where the text of interest lives. It can be _note_ (alt. _annotation_)
+  #   or _content_. (The content is the text that appears on the normal
+  #   OmniGraffle screen. The note appears if you hover your cursor above
+  #   it or look at Notes in the Inspector.) One of these words must be present.
+  # * An action to take:
+  #   * _skip_ (alt. _ignore_). Do not turn text into message sends.
+  #   * <i>user action</i> (in that order) followed by <i>quoted</i> and 
+  #     <i>arg</i> (in any order). Variations on _quoted_ and _arg_ are 
+  #     allowed. For example, "quote all arguments" matches. This argument
+  #     means that <i>Fred controls the "widget"</i> is turned into:
+  #         target.controls_the("fred", "widget")
+  #     Strings to match are downcased
+  #     before the match and non-word-characters are stripped, so "John runs AWAY!"
+  #     turns into runs_away("john").
+  #   * _claim_ followed by _quoted_ and _arg_, as above. In this case, 
+  #     <i>Fred controls the widget</i> is turned into:
+  #         target.fred_controls_the("widget")
+  #   * _name_ and _pages_ in any order. _HOME_ is converted into
+  #         target.assert_on_page("home").
+  #   The string must describe an action. 
+  # * A description of which lines within a body of text should have the 
+  #   action applied to it. 
+  #   * <i>with one word</i> (in that order, possibly with other words
+  #     interspersed). The action only happens on lines of text that contain
+  #     a single word.
+  #   * <i>text...</i> (alt., _ellipses_). The action only happens on lines
+  #     of text that end with ellipses.
+  #   * <i>otherwise</i> (alt <i>other kinds of</i>, <i>other kind of</i>). 
+  #     The action happens for all lines. (Only useful when it follows one
+  #     of the above.)
+  #
+  # These descriptions are checked in the order given:
+  #
+  #   one word lines in shape content name pages.
+  #   shape content lines with ellipses are claims with quoted args.
+  #   otherwise, ignore shape content.
+  #
+  # There's one special case to handle a common desire: turning off 
+  # all interpretation of a graphic. Typically that's used for shape 
+  # contents or line labels that are just there for the human reader, not
+  # for the test. To ignore them, add a note containing the word "ignore"
+  # and this text as the first description:
+  #
+  #   skip when note contains 'ignore'
+  #
+  
+  class PictureApplier
+    
+    attr_reader :intentions
+
+    def initialize(intentions = [], &block) #:nodoc:
+      @intentions = intentions
+      @log = []
+
+      if block
+        STDERR.puts "Warning: old-style PictureApplier initialization is deprecated."
+        instance_eval(&block)
+      end
+    end
+
+    # Apply messages derived from the _graphics_ to the _target_, adding
+    # descriptions of each message to the _log_.
+    def apply(graphics, target, log=[])
+      return old_style_apply(graphics, target, log) if @intentions.empty?
+      
+      while_logging_for_test_errors do
+        graphics.each { |g| apply_one(g, target) }
+      end
+    end
+      
+      # Use the Key graphic in the _sheet_ to program the PictureApplier's 
+      # behavior. The Key graphic is then discarded (not used in the actual
+      # test.)
+      def self.from_sheet(sheet, *default_written_intentions)
+        key = sheet.find_by_content("key")
+        
+        if key.nil?
+          user_denies(default_written_intentions.empty?) {
+            "The sheet has no key for the tests. It needs a graphic whose visible content is 'key'."
+          }
+          from_written_instructions(*default_written_intentions)
+        else
+          user_claims(key.has_notes?) {
+            "The key graphic is supposed to have an annotation describing how to interpret the rest of the sheet."
+          }
+          key.delete_yourself
+          from_graphic(key)
+        end
+      end
+
+      # The _graphic_ should have an annotation with a list of written
+      # instructions of the form accepted by from_written_instructions.
+      def self.from_graphic(graphic)
+        written_intentions = graphic.notes.as_lines.find_all { |l| l.strip != "" }
+        from_written_intentions(*written_intentions)
+      end
+
+      # Accept a list of written instructions that are later obeyed by 
+      # apply. 
+      def self.from_written_intentions(*written_intentions)
+        intentions = written_intentions.collect do |line|
+          UserIntention.understand(line)
+        end
+        new(intentions)
+      end
+
+      # Synonym for from_written_intentions.
+      def self.from_written_instructions(*args)
+        self.from_written_intentions(*args)
+      end
+
+    include GraphicalTestsForRails::TextAppliers
+    
+    # Claim that the PictureApplier matches graphics matching
+    # the _form_description_, a string. Here are the form descriptions 
+    # currently supported:
+    #
+    # * 'shaped graphic content': A shaped graphic is a rectangle, oval, 
+    #   embedded picture, etc.: anything that is neither a line nor a 
+    #   group. The content is the text you type in when you double-click
+    #   on the object. When given the form description, the PictureApplier
+    #   will match any shaped graphic that contains text.
+    # * 'line label content': This matches any line that has a label.
+    #   (Note: lines can have more than one label. That's not handled.)
+    # * 'note': Matches any object that contains an annotation. (Annotations are
+    #   only available in OmniGraffle Pro. They're arbitrary text
+    #   associated with a line or shaped graphic. You can see the 
+    #   annotations if you hover over the object.)
+    #
+    # The _form_description_ describes the first of two matching steps.
+    # If it matches, it extracts the appropriate text (content or 
+    # annotation) and hands it to the next step, described by given.
+    #
+    # This method returns self so that other methods can be chained onto it.
+    def given(form_description) # :nodoc:
+      @new_style_place_implied = form_description
+      @new_style_text_implied = ""
+      @new_style_action_implied = ""
+      self
+    end
+    
+    # Claim that the PictureApplier matches particular text extracted from
+    # a graphical object. These _text_descriptions_ are currently supported:
+    #
+    # * 'text...': match if the text ends in ellipses (ignoring whitespace).
+    # * 'ignore': match if the text ends in the word "ignore" (ignoring whitespace).
+    #
+    # This method returns self so that other methods can be chained onto it.
+    def matching(text_description)  # :nodoc:
+      @new_style_text_implied = text_description
+      self
+    end
+    
+    # When a PictureApplier matches an object, the extracted text is 
+    # passed to the _text_applier_ to be turned into messages.
+    def use(text_applier) # :nodoc:
+      new_style_action_implied = 
+        case text_applier
+        when TextApplierThatDoesNothing: 'skip'
+        when PrefixNameAndArgsFromQuotedText: 'user action with args from quoted text'
+        when ArgsFromQuotedText: "claim with args from quoted text"
+        when TextAsNameOfPage: 'name of page'
+        else user_is_bewildered("Unknown class: #{text_applier.class}")
+        end
+      parts = [new_style_action_implied, @new_style_place_implied, @new_style_text_implied]
+      @intentions << UserIntention.understand(parts.join(" "))
+    end
+    
+    # After a PictureApplier matches a graphical object, it's ignored. 
+    # This is used to prevent text associated with the object from being
+    # turned into messages.
+    def skip # :nodoc:
+      use(TextApplierThatDoesNothing.new)
+    end
+
+    def intentions_that_apply_to(graphic) # :nodoc:
+      @intentions.find_all do |i|
+        # pi i, '#'
+        # if (pi i.applies_to_graphic?(graphic), 'applies to graphic?')
+        #   pi i.lines_from(graphic), "graphic contains"
+        #   i.applies_to_text?(i.lines_from(graphic))
+        # end
+        i.applies_to_graphic?(graphic) && 
+          i.applies_to_text?(i.lines_from(graphic))
+      end
+    end
+
+
+
+    private
+
+
+    def apply_one(graphic, target)
+      relevant_intentions = intentions_that_apply_to(graphic)
+      return if relevant_intentions.empty?
+
+      lines_chosen = relevant_intentions.first.lines_from(graphic)
+      lines_chosen.each do |line|
+        intention_for_line = relevant_intentions.find do |i|
+          i.applies_to_line?(line)
+        end
+        intention_for_line.apply(line, target, @log) if intention_for_line
+      end
+    end
+
+
+
+    def while_logging_for_test_errors
+      begin
+        yield
+      rescue Test::Unit::AssertionFailedError, StandardError, ScriptError => e
+        new_message = %Q{#{e.message}. That happened during or after the last of these commands:\n#{@log.join("\n")}}
+        new_e = e.exception(new_message)
+        new_e.set_backtrace(e.backtrace)
+        raise new_e
+      end
+    end
+
+  
+  
+
+  end
+end