graffle 0.1.0

data/lib/graffle.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-06.
+#  Copyright (c) 2007. All rights reserved.
+
+
+
+require 's4t-utils'
+require 'ostruct'
+require 'plist'
+
+require 'graffle/version'
+require 'graffle/nodoc/hacks'
+require 'graffle/styled-text-reader'
+require 'graffle/stereotypes'
+require 'graffle/point'
+
+# See README.txt[link:files/README_txt.html]
+module Graffle
+  
+  # Parse the given data and stereotype the result. Returns an object
+  # stereotyped as Graffle::Document.
+  def self.parse(filename_or_xml)
+    if File.directory?(filename_or_xml)
+      filename_or_xml = File.join(filename_or_xml, "data.plist")
+    end
+    
+    prog1(Plist.parse_xml(filename_or_xml)) do | doc |
+      Document.takes_on(doc)
+    end
+  end
+
+  def self.stereotype(o)        # :nodoc:
+    return true if ShapedGraphic.takes_on(o)
+    return true if LineGraphic.takes_on(o)
+    return true if Group.takes_on(o)
+    # Sheet has no distinguishing marks.
+    false
+  end
+  
+
+end
+

data/lib/graffle/.document

@@ -0,0 +1,4 @@
+point.rb
+stereotypes.rb
+styled-text-reader.rb
+version.rb

data/lib/graffle/lib-skeleton

@@ -0,0 +1,3 @@
+module Graffle
+  # Your code here
+end

data/lib/graffle/nodoc/hacks.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-06.
+#  Copyright (c) 2007. All rights reserved.
+
+require 'pp'
+
+class Object
+
+  def behaves_like?(mod)
+    kind_of?(mod)
+  end  
+
+  def behave_like(mod)
+    @_stereotyped_as_module__bemhack = mod
+    def self.stereotype; @_stereotyped_as_module__bemhack; end
+    
+    _cause_printing_to_include_stereotype__bemhack
+    
+    extend(self.stereotype)
+    self
+  end
+  alias and_behave_like behave_like
+  
+  
+  private
+  def _cause_printing_to_include_stereotype__bemhack
+    @_stereotype_print_tag__bemhack = "acts as #{stereotype.basename}: "
+
+    @_original_inspect__bemhack = self.method(:inspect)
+    def self.inspect 
+      @_stereotype_print_tag__bemhack + @_original_inspect__bemhack.call
+    end
+
+    @_original_to_s__bemhack = self.method(:to_s)
+    def self.to_s
+      @_stereotype_print_tag__bemhack + @_original_to_s__bemhack.call
+    end
+
+    @_original_pretty_print__bemhack = self.method(:pretty_print)
+    def self.pretty_print(printer)
+      printer.text(@_stereotype_print_tag__bemhack)
+      @_original_pretty_print__bemhack.call(printer)
+    end
+  end
+end
+
+
+
+class Hash
+  def << (hash)
+    self.merge!(hash)
+    self
+  end
+  
+  # Default Hash to_s is lame. Note that to_s doesn't just call
+  # inspect because inspect might be overridden. We want what 
+  # inspect does by default, not whatever inspect does at the moment.
+  alias_method :_unchanging_inspect__bemhack, :inspect
+  def to_s; _unchanging_inspect__bemhack; end
+end
+
+class Module
+  def basename
+    name.split("::").last
+  end
+end
+
+

data/lib/graffle/point.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-06.
+#  Copyright (c) 2007. All rights reserved.
+
+
+module Graffle
+  
+  # An {x,y} coordinate relative to the origin of a Sheet.
+  class Point
+    
+    attr_reader :x, :y
+    
+    # If two arguments, they are the x and y coordinates of the 
+    # Point. Otherwise, the single argument is a string to be
+    # parsed to find the coordinates.
+    def initialize(*args)
+      if args.length == 2
+        @x = args[0]; @y = args[1]
+      elsif args[0] =~ /\{\{(.*),\s(.*)\}, \{.*,\s.*\}\}/
+        initialize(Float($1), Float($2))
+      elsif args[0] =~ /\{(.*),\s(.*)\}/
+        initialize(Float($1), Float($2))
+      else
+        # TODO: this should be user_is_bewildered(msg = "how could this point be reached?")
+        user_disputes("this point can be reached") { "unreachable?"}
+      end
+    end
+    
+    include Comparable
+        
+    # One Point is "less than" another if it starts higher
+    # than it on the page. If they start at the same height, the 
+    # one furthest to the left is less.
+    def <=>(other)
+      return self.x <=> other.x if self.y == other.y
+      return self.y <=> other.y
+    end
+  end
+  
+  
+end

data/lib/graffle/stereotypes.rb

@@ -0,0 +1,446 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-06.
+#  Copyright (c) 2007. All rights reserved.
+
+module Graffle
+  module Builders # :nodoc: 
+    def self.raw(mod, basic_structure = {}, &block)
+      g = basic_structure.dup
+      g.behave_like(mod)
+      g.instance_eval(&block) if block
+      g
+    end
+    
+    def self.classed(mod, basic_structure = {}, &block)
+      g = raw(mod, basic_structure, &block)
+      g['Class'] = mod.basename
+      g
+    end
+    
+    def abstract_graphic(&block)
+      Builders.raw(Graffle::AbstractGraphic, &block)
+    end
+
+    def shaped_graphic(&block)
+      Builders.classed(Graffle::ShapedGraphic, &block)
+    end    
+
+    def line_label(&block)  
+      prog1(shaped_graphic) do | g |
+        g.act_as_line_label
+        g.instance_eval(&block) if block
+      end
+    end
+
+    def line_graphic(&block)
+      Builders.classed(Graffle::LineGraphic, &block)
+    end      
+
+    def sheet(&block)    
+      Builders.raw(Graffle::Sheet, {'GraphicsList' => []}, &block)
+    end
+
+    def group(&block)
+      Builders.classed(Graffle::Group, {'Graphics' => []}, &block)
+    end
+
+    def document(&block)
+      prog1(Builders.raw(Graffle::Document, &block)) { | doc | 
+        doc['Creator'] = 'graffle.rb'
+      }
+    end
+    
+    def text(string, &block)
+      prog1(Builders.raw(Graffle::Text, &block)) { | text |
+        text['Text'] = string
+      }
+    end
+    
+  end
+  
+  
+  # TODO: rename AbstractGraphic Nestable
+  
+  # Behavior that's common to all visible objects, be they lines,
+  # rectangles, text objects, etc.
+  module AbstractGraphic
+    include Comparable
+    
+    # TODO: I'm not wild about the way this both checks if something's
+    # possible and also does it. Separate in caller?
+    def self.takes_on(o, mod) # :nodoc: 
+      if graffle_class_matches?(o, mod)
+        o.behave_like(mod)
+        return true
+      end
+    end
+    
+    def self.graffle_class_matches?(o, mod) # :nodoc: 
+      o.is_a?(Hash) && o['Class'] == mod.basename
+    end
+
+    # The Group or Sheet containing the object. Mostly for internal use.
+    attr_accessor :container
+
+    # Every visible graffle object has an integer ID.
+    # Mostly for internal use.
+    def graffle_id; self['ID']; end
+    def graffle_id_is(id) # :nodoc: 
+      self['ID'] = id
+    end
+
+    # One AbstractGraphic is before another if its origin starts higher
+    # than the other's. If their origins are at the same height, the 
+    # one furthest to the left comes before.
+    def before?(other)
+      self.origin < other.origin
+    end
+    
+    # A Point. Must be defined in the whatever includes this module.
+    def origin; includer_responsibility; end
+    
+  end
+  
+  
+  # An entire Graffle file, parsed. The only thing of interest is 
+  # an array of objects stereotyped as Sheet. A Sheet is the internal
+  # name for what the OmniGraffle Pro GUI calls "canvases."
+  #
+  # OmniGraffle non-Pro can only produce one-canvas documents. 
+  #
+  # Some one-canvas OmniGraffle documents don't actually have Sheets. So
+  # that you don't have to worry about that, a one-element Sheet array
+  # is inserted if needed.
+
+  module Document
+    include Builders
+    
+    def sheets; self['Sheets']; end
+    def first_sheet; sheets[0]; end
+    
+    
+    def with(*objects) # :nodoc: 
+      self['Sheets'] = [] unless self.has_key?('Sheets')
+      objects.each do | o |
+        self['Sheets'] << o
+      end
+    end
+
+    def self.takes_on(hash) # :nodoc: 
+      doc = hash.behave_like(self)
+      doc.make_sure_has_sheets
+      doc.sheets.each do | child |
+        Sheet.takes_on(child)
+      end
+      true
+    end
+
+
+    # If this is a graffle document with an implicit single 
+    # sheet, make it explicit.
+    # TODO: Check that OmniGraffle non-pro can read such a doc. Probably 
+    # more needs to go along with the GraphicsList.
+    def make_sure_has_sheets # :nodoc: 
+      splice_in_single_sheet unless self.has_key?('Sheets')
+      self
+    end
+
+    private
+    
+    def splice_in_single_sheet
+      graphics = self.delete("GraphicsList")
+      self['Sheets'] = [ { 'GraphicsList' => graphics }]
+    end
+  end
+
+  # Visible graphics that aren't lines. (Those are stereotyped 
+  # LineGraphic.)
+  module ShapedGraphic
+    include AbstractGraphic
+    include Builders
+    
+    def self.takes_on(o) # :nodoc: 
+      if AbstractGraphic.takes_on(o, self)
+        o.content.behave_like(Text) if o.has_content?
+        o.act_as_line_label if o.is_line_label?
+        true
+      end
+    end
+    
+    # Does this object contain Text? (The kind you put in when you 
+    # double-click on the object.)
+    def has_content?; self.has_key?('Text'); end    
+    
+    # Is this object the label for some LineGraphic?
+    def is_line_label?; self.has_key?('Line'); end
+    
+    def act_as_line_label  # :nodoc:
+      
+      def self.for_line(graffle_id) # :nodoc:
+        self['Line'] = { 'ID' => graffle_id }
+      end
+
+      # The integer ID of the LineGraphic this ShapedGraphic labels.
+      # This method only exists if the object really is a label.
+      #
+      # BUG: A line can have more than one label.
+      def self.line_id; self['Line']['ID']; end
+
+      # The LineGraphic this ShapedGraphic labels.
+      # This method only exists if the object really is a label, so 
+      # use is_line_label? first.
+      def self.line
+        container.find_by_id(line_id)
+      end
+    end        
+    
+        
+    # The x coordinate of this object's bounding box.
+    def x; bounds.x; end
+    # The y coordinate of this object's bounding box.
+    def y; bounds.y; end
+    # The width of this object's bounding box.
+    def width; bounds.width; end
+    # The height of this object's bounding box.
+    def height; bounds.height; end
+    
+    # This object's bounding box, an OpenStruct with methods x, y, 
+    # width, and height.
+    def bounds
+      self['Bounds'] =~ /\{\{(.*),\s(.*)\}, \{(.*),\s(.*)\}\}/
+      OpenStruct.new(:x => Float($1), :y => Float($2), 
+                         :width => Float($3), :height => Float($4))
+    end
+    
+    def origin # :nodoc:
+      Point.new(self['Bounds'])
+    end
+    
+    def bounded_by(x, y, width, height) # :nodoc: 
+      self << {"Bounds" => "{{#{x}, #{y}}, {#{width}, #{height}}}" }
+    end
+    
+    
+    
+    # The Text within the object (or nil if there isn't any).
+    def content; self['Text']; end
+    alias_method :contents, :content
+    
+    def with_text(string)  # :nodoc:
+      self['Text'] = text(string)
+    end
+  end
+  
+  # A line, be it straight, curved, or jagged. Lines can be connected to 
+  # other objects. Even if there's no arrowhead on the line, it still has 
+  # a notion of a _head_ and _tail_. (Alternate notation: it goes from one, 
+  # to the other). The head or tail can be nil.
+  module LineGraphic
+    include AbstractGraphic
+    include Builders
+    
+    def self.takes_on(o)   # :nodoc: 
+      AbstractGraphic.takes_on(o, self)
+    end
+
+
+    # The AbstractGraphic the line comes from.
+    def from; _follow__bemhack('Tail'); end
+    alias_method :tail, :from
+
+    # The AbstractGraphic the line goes to.
+    def to; _follow__bemhack('Head'); end
+    alias_method :head, :to
+    
+    # The label attached to a line. In the document, the label is a
+    # ShapedGraphic in the same Container as its line. The label points
+    # to the line, not the reverse. This method, though, pretends the
+    # line points to the label and returns it (or nil if there is no 
+    # label).
+    def label
+      container.graphics.find do |g|
+        g.respond_to?(:line_id) && g.line_id == self.graffle_id
+      end
+    end
+    
+    # Almost certainly, what you care about is the Text of the label, which
+    # you could get like this:
+    #   line.label.content 
+    # This method is shorthand for that. 
+    def label_rtf
+      label.content
+    end
+    
+    # An array of Point objects that make up the line. Not editable (yet).
+    def points
+      self['Points'].collect do |p|
+        p =~ /\{(.*),\s(.*)\}/
+        Point.new(Float($1), Float($2))
+      end
+    end
+    
+    # The origin of the LineGraphic is the first Point in the points array.
+    # That's the place the mouse pointer was when some person began to 
+    # create the LineGraphic. It is _not_ necessarily the Point in the line
+    # closest to {0,0}.
+    def origin
+      Point.new(self['Points'][0])
+    end
+    
+    private
+    def points_at(*points)
+      self['Points'] = points.collect { |p| "{#{p[0]}, #{p[1]}}" }
+    end
+    
+    def go_from(thing); _link__bemhack('Tail', thing); end
+    def go_to(thing); _link__bemhack('Head', thing); end
+
+    def _follow__bemhack(which)
+      container.find_by_id(self[which]['ID'])
+    end
+  
+    # TODO: note this is no good for updating, since fields other than
+    # ID may be destroyed.
+    def _link__bemhack(type, thing)
+      id = thing.respond_to?(:graffle_id) ? thing.graffle_id : thing
+      self << { type => { 'ID' => id } }
+    end
+    
+  end
+
+  # Behavior common to Sheet and Group, both of which contain an array
+  # of AbstractGraphic.
+  # :stopdoc: 
+  # TODO: perhaps some cleverness with Enumerator would be in order?
+  # :startdoc:
+  module Container
+
+    def with(*objects) # :nodoc: 
+      objects.each do | o |
+        self.graphics << o
+        o.container = self  # works because instance_evaled.
+      end
+    end
+
+    # Find the AbstractGraphic matching the integer id. Returns nil
+    # if not found.
+    #
+    # Mostly for internal use.
+    def find_by_id(id)
+      result = graphics.find { | elt | elt.graffle_id == id }
+      unless result
+        return nil unless respond_to?(:container) # at the top of the tree.
+        return nil unless container  # A null container should only happen 
+                                     # in tests. Consider a test that 
+                                     # uses find_by_id on a group, but the 
+                                     # group is not contained in a sheet.
+        result = container.find_by_id(id)
+      end
+      result
+    end
+
+    def self.stereotype_children_of(parent) # :nodoc:
+      parent.graphics.each do | child |
+        if Graffle.stereotype(child)
+          child.container = parent
+        else
+          puts "TODO: can not yet stereotype child with id #{child['ID'].inspect} and class #{child['Class'].inspect}."
+          pp child.keys
+        end
+      end
+      true
+    end
+
+  end
+  
+  # A Sheet is what the UI calls a "canvas." It's the drawing surface.
+  # OmniGraffle Pro lets you have multiple canvases.
+  module Sheet
+    include Builders
+    include Container
+    
+    # All the visible graphics within the Sheet: objects stereotyped 
+    # as ShapedGraphic, LineGraphic, or Group.
+    def graphics
+      self['GraphicsList']
+    end
+    
+    # Only the LineGraphic objects within the Sheet.
+    def all_lines
+      graphics.find_all do | g |
+        g.behaves_like?(Graffle::LineGraphic)
+      end
+    end
+
+    # The first LineGraphic within the Sheet.
+    # Warning: currently, that does _not_ mean the one highest on 
+    # the page, so this is really useful only for finding the only
+    # line.
+    def first_line; all_lines[0]; end
+
+    def self.takes_on(hash) # :nodoc: 
+      sheet = hash.behave_like(self)
+      Container.stereotype_children_of(sheet)
+      true
+    end
+      
+  end
+  
+  # What you get when you group graphics in the UI.
+  module Group
+    include Builders
+    include Container
+    include AbstractGraphic
+    
+    # The visible objects that were grouped.
+    def graphics
+      self['Graphics']
+    end
+
+    def self.takes_on(hash)  # :nodoc: 
+      if AbstractGraphic.takes_on(hash, self)
+        Container.stereotype_children_of(hash)
+        true
+      end
+    end
+
+    # TODO: What should the origin be for groups?
+    
+    # TODO: When a group gets a collective bounding-box, how
+    # should that incorporate lines within the group?
+    
+  end
+
+  # OmniGraffle text is RTF. This gives access to an object's text.
+  module Text
+    # Return the text as the original RTF string.
+    def as_rtf
+      self['Text']
+    end
+    
+    # Strip all the styling from the RTF string and return it as
+    # humble ASCII.
+    def as_plain_text
+      StyledTextReader.new(self.as_rtf).as_lines.join("\n")
+    end
+    
+    # Return an array of arrays. Each of the inner arrays represents
+    # a line in the original. At the moment, the inner array is what 
+    # you get when you split the line at double-quote boundaries. For
+    # example, given this string:
+    #
+    #     He visits the "login" page.
+    #     His login is "peter", his password is "paul"
+    #
+    # the method returns:
+    #
+    #     [ ['He visits the', 'login', 'page.']
+    #       ['His login is', 'peter', 'his password is', 'paul']]
+    #
+    # There's more to come here.
+    def as_tokens_within_lines
+      StyledTextReader.new(self.as_rtf).as_tokens_within_lines
+    end
+  end
+end