konjac 0.3.3 → 0.3.4

data/Rakefile

@@ -1,5 +1,5 @@
 require "bundler/gem_tasks"
-require "rdoc/task"
+# require "rdoc/task"  this is weirdly busted for some reason
 require "rspec/core/rake_task"
 require "sdoc"
 

data/lib/konjac/office.rb

@@ -12,15 +12,31 @@ module Konjac
   # following will work too:
   #
   #   doc = Konjac::Office.word
+  #
+  # From there, you can send some basic reading and writing instructions to the
+  # document:
+  #
+  #   doc.read 1
+  #   doc.read :paragraph => 1
+  #   doc.read 1, :type => :shape
+  #
+  #   doc.write "First paragraph", 1
+  #
+  #   doc.export
+  #   doc.import
   module Office
-    autoload :Generic,   "konjac/office/generic"
-    autoload :Mac,       "konjac/office/mac"
-    autoload :OS,        "konjac/office/os"
-    autoload :Tag,       "konjac/office/tag"
-    autoload :Windows,   "konjac/office/windows"
-    autoload :XML,       "konjac/office/windows"
+    autoload :Base,    "konjac/office/base"
+    autoload :Mac,     "konjac/office/mac"
+    autoload :OS,      "konjac/office/os"
+    autoload :Tag,     "konjac/office/tag"
+    autoload :Windows, "konjac/office/windows"
+    autoload :XML,     "konjac/office/windows"
 
     class << self
+      # Creates a new object inheriting from Base. The application chosen is
+      # based on the user's environment and the type of the document. For
+      # example, a file with a .docx extension will default to Microsoft Word,
+      # and on OSX it will default to Konjac::Office::Mac::Word
       def new(path)
         env = environment
         return nil if env.nil?
@@ -35,6 +51,10 @@ module Konjac
         end
       end
 
+      # The user's environment. Currently, this just detects whether an OS is
+      # Windows, Mac or other (simply because Microsoft Office is unavailable
+      # on Linux, so scripting something like LibreOffice or OpenOffice is more
+      # long-term).
       def environment
         if OS.mac?
           Mac
@@ -47,6 +67,18 @@ module Konjac
 
       private
 
+      # If possible, retrieves the appropriate class inheriting from Office::Base for the user
+      # based on his environment or OS. For example, if a user types
+      #
+      #   doc = Konjac::Office.word
+      #
+      # on Mac that will be the same thing as a call to
+      #
+      #   doc = Konjac::Mac::Office.new
+      #
+      # whereas for a user on Windows it will be equivalent to
+      #
+      #   doc = Konjac::Windows::Office.new
       def method_missing(name, *args, &block)
         env = environment
         return super if env.nil?
@@ -58,6 +90,8 @@ module Konjac
         end
       end
 
+      # A list of valid environments based on the directories in the
+      # lib/konjac/office folder of this gem
       def valid_environments
         return @environments unless @environments.nil?
 
@@ -71,6 +105,7 @@ module Konjac
         @environments
       end
 
+      # Converts snake_case into CamelCase
       def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
         if first_letter_in_uppercase
           lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
@@ -79,6 +114,7 @@ module Konjac
         end
       end
 
+      # Converts CamelCase into snake_case
       def underscore(camel_cased_word)
         camel_cased_word.to_s.gsub(/::/, '/').
           gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').

data/lib/konjac/office/{generic.rb → base.rb}

@@ -3,11 +3,13 @@ module Konjac
   module Office
     # This is a basic class that contains all the methods that are universal
     # across OSes, file formats, applications, etc.
-    class Generic
+    class Base
       autoload :Item, "konjac/office/item"
 
-      attr_reader :document, :index, :current
+      # The active document
+      attr_reader :document
 
+      # Creates a new Base object
       def initialize(location = nil)
         @document = open(File.expand_path(location)) unless location.nil?
         @document = active_document
@@ -21,10 +23,29 @@ module Konjac
           :document    => @document,
           :delimiter   => "\v"
         }
-        @index = 0
-        @current = nil
       end
 
+      # Finds the item at the specified indices. This method accepts both
+      # variadic inputs (i.e. <tt>1, 2, 3</tt>) or the equivalent hash (i.e.
+      # <tt>:sheet => 1, :row => 2, :cell => 3</tt>. The following pairs are
+      # equivalent:
+      #
+      #   doc[1]
+      #   doc[:paragraph => 1]
+      #   doc.item_at 1
+      #   doc.item_at :paragraph => 1
+      #
+      #   xl[1, 1, 1]
+      #   xl.item_at :sheet => 1, :row => 1, :cell => 1
+      #
+      #   pp[1, 1]
+      #   pp.item_at :slide => 1, :shape => 1
+      #
+      #   doc[1, :type => :shape]
+      #   doc :shape => 1, :type => :shape
+      #   doc.shape_at 1
+      #
+      # along with all the obvious permutations.
       def [](*args)
         opts = parse_args(*args)
         return shape_at(opts) if opts[:type] == :shape
@@ -33,10 +54,13 @@ module Konjac
       end
       alias :item_at :[]
 
+      # Sets the item at the specified indices to the value of the first
+      # argument or the <tt>:text</tt> member of the supplied hash
       def []=(*args)
         write args.pop, *args
       end
 
+      # Retrieves the shape at the specified indices
       def shape_at(*args)
         last_item = args.last
         last_item = { :type => :shape }.merge(last_item) if last_item.is_a?(Hash)
@@ -44,22 +68,27 @@ module Konjac
         Item.new @shape_opts.merge(opts)
       end
 
+      # Writes to the item at the specified indices
       def write(text, *args)
         item_at(*args).write text
       end
 
+      # Reads from the item at the specified indices
       def read(*args)
         item_at(*args).read
       end
 
+      # Loads Tags from the supplied path
       def tags
         Tag.load path
       end
 
+      # Exports Tags to the specified path
       def export
         Tag.dump data, path
       end
 
+      # Imports Tags from the specified path into the +document+
       def import
         tags.each do |tag|
           if tag.changed? && !tag.blank?
@@ -90,10 +119,6 @@ module Konjac
           parsed = Hash[@item_opts[:ref_path].zip(args)].merge(parsed)
         end
       end
-
-      def clean(text, opts)
-
-      end
     end
   end
 end

data/lib/konjac/office/item.rb

@@ -1,8 +1,14 @@
 # coding: utf-8
 module Konjac
   module Office
-    class Generic
+    class Base
+      # An item class dealing with hierarchy in which to search the
+      # document. For example, with Word it will search paragraphs and for
+      # PowerPoint it will search slides then shapes.  This class then will
+      # follow the hierarchy to text objects and is capable of reading from and
+      # writing to them.
       class Item
+        # Creates a new Item
         def initialize(opts = {})
           @opts = opts
 
@@ -13,6 +19,9 @@ module Konjac
           @ref = item
         end
 
+        # Retrieves the content from the Item. Note that without getter or
+        # setter methods this may not actually retrieve anything but the message
+        # we intend to send to the scripting interface.
         def content
           return @content unless @content.nil?
 
@@ -23,10 +32,13 @@ module Konjac
           @content
         end
 
+        # Reads the item's text content, cleaned up according to the supplied
+        # delimiters and strippable items
         def read
           clean content.send(@opts[:read])
         end
 
+        # Writes to the item
         def write(text)
           content.send @opts[:write], text
         end
@@ -41,7 +53,11 @@ module Konjac
         end
 
         def clean(text)
-          text.gsub(@opts[:strippable], "").split(@opts[:delimiter])
+          if text == :missing_value
+            [""]
+          else
+            text.gsub(@opts[:strippable], "").split(@opts[:delimiter])
+          end
         end
       end
     end

data/lib/konjac/office/mac.rb

@@ -1,6 +1,7 @@
 # coding: utf-8
 module Konjac
   module Office
+    # The Office for Mac namespace
     module Mac
       autoload :Excel,      "konjac/office/mac/excel"
       autoload :PowerPoint, "konjac/office/mac/power_point"

data/lib/konjac/office/mac/excel.rb

@@ -2,7 +2,9 @@
 module Konjac
   module Office
     module Mac
+      # Excel for Mac
       class Excel < Shared
+        # Creates a new Excel object
         def initialize(path = nil)
           super "Microsoft Excel", path
           @strippable = //

data/lib/konjac/office/mac/power_point.rb

@@ -2,7 +2,9 @@
 module Konjac
   module Office
     module Mac
+      # PowerPoint for Mac
       class PowerPoint < Shared
+        # Creates a new PowerPoint object
         def initialize(path = nil)
           super "Microsoft PowerPoint", path
           @strippable = //

data/lib/konjac/office/mac/shared.rb

@@ -4,7 +4,9 @@ require "appscript"
 module Konjac
   module Office
     module Mac
-      class Shared < Generic
+      # Inherits from Base and adds some shared methods to the Mac interface 
+      class Shared < Base
+        # Creates a new Shared object
         def initialize(app_name, path = nil)
           @application  = Appscript.app(app_name)
           super path
@@ -18,6 +20,7 @@ module Konjac
           })
         end
 
+        # Open the document at the supplied +path+ using the current application
         def open(path)
           @application.open path
         end

data/lib/konjac/office/mac/word.rb

@@ -2,8 +2,16 @@
 module Konjac
   module Office
     module Mac
+      # Word for Mac
       class Word < Shared
+        # A basic class to deal with Word's ridiculously awful handling
+        # of replacing text in paragraphs.  Instead of simply setting the
+        # paragraph's text to something new, you have to select all but the last
+        # character (which is a newline) then write.  Otherwise, your paragraph
+        # might inherit the formatting of the line below it, which is especially
+        # a problem with tables.
         class WordItem < Item
+          # Writes to a Word item
           def write(text)
             para_start = @ref.text_object.start_of_content.get
             para_end   = @ref.text_object.end_of_content.get
@@ -14,10 +22,9 @@ module Konjac
           end
         end
 
+        # Creates a new Word item
         def initialize(path = nil)
           super "Microsoft Word", path
-          @index = 1
-          @current = @document.paragraphs[@index]
           @item_opts.merge!({
             :ref_path     => [:paragraph],
             :content_path => [:text_object, :content],
@@ -89,16 +96,6 @@ module Konjac
           @document.paragraphs.get.size
         end
         alias :length :size
-
-        # Goes to the next paragraph
-        def succ
-          @index  += 1
-          @current = @current.next_paragraph
-        rescue
-          @index  -= 1
-          nil
-        end
-        alias :next :succ
       end
     end
   end

data/lib/konjac/office/tag.rb

@@ -1,9 +1,22 @@
 # coding: utf-8
 module Konjac
   module Office
+    # A tag item, used to export and import data to and from the document
     class Tag
-      attr_accessor :indices, :removed, :added, :type
+      # The indices used to scan the document's hierarchy to reach the item
+      attr_accessor :indices
+      
+      # The text that has been removed
+      attr_accessor :removed
+      
+      # The text with which to replaced the removed content
+      attr_accessor :added
+      
+      # The type, used to identify special objects such as a
+      # <tt>:shape</tt>. Defaults to +nil+.
+      attr_accessor :type
 
+      # Creates a new tag item
       def initialize
         @indices = nil
         @removed = []
@@ -42,6 +55,8 @@ module Konjac
       end
 
       class << self
+        # A list of regular expressions for parsing a document in unified
+        # diff-esque style into Tags
         TAG_MATCHES = {
           :header  => /^(?:---|\+\+\+)/,
           :comment => /^\@\@ ([a-z]*) ?([\d, ]+) \@\@$/i,
@@ -73,6 +88,8 @@ module Konjac
           tags
         end
 
+        # Dumps the tags into a .diff document with the same name as the
+        # document from which those tags were extracted
         def dump(tags, path, opts = {})
           original_path = path.sub(/\.diff$/, "")
           diff_path     = "#{original_path}.diff"

data/lib/konjac/office/windows.rb

@@ -1,6 +1,7 @@
 # coding: utf-8
 module Konjac
   module Office
+    # The Office for Windows namespace
     module Windows
       autoload :Excel,      "konjac/office/windows/excel"
       autoload :PowerPoint, "konjac/office/windows/power_point"

data/lib/konjac/office/windows/shared.rb

@@ -1,2 +1 @@
-# coding: utf-8
 

data/lib/konjac/office/xml.rb

@@ -1,7 +1,8 @@
 # coding: utf-8
 module Konjac
   module Office
-    module xml
+    # The XML (Open Office XML, that is) namespace
+    module XML
       autoload :Excel,      "konjac/office/xml/excel"
       autoload :PowerPoint, "konjac/office/xml/powerpoint"
       autoload :Shared,     "konjac/office/xml/shared"

data/lib/konjac/office/xml/shared.rb

@@ -1,6 +1,8 @@
 # coding: utf-8
 module Konjac
   module Office
+    # Specialized XML handling for with the Office Open XML-based formats in
+    # Office 2007+
     module XML
       # Imports the text content of a tag file into a Word 2003+, utilizing a
       # cleaned-up version of the document's original XML structure

data/lib/konjac/version.rb

@@ -1,4 +1,4 @@
 module Konjac
   # The current version number of Konjac
-  VERSION = "0.3.3"
+  VERSION = "0.3.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: konjac
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-15 00:00:00.000000000 Z
+date: 2012-03-06 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amatch
-  requirement: &70324813508240 !ruby/object:Gem::Requirement
+  requirement: &70346758881440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70324813508240
+  version_requirements: *70346758881440
 - !ruby/object:Gem::Dependency
   name: git
-  requirement: &70324813507600 !ruby/object:Gem::Requirement
+  requirement: &70346758880980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70324813507600
+  version_requirements: *70346758880980
 - !ruby/object:Gem::Dependency
   name: highline
-  requirement: &70324813506800 !ruby/object:Gem::Requirement
+  requirement: &70346758880560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70324813506800
+  version_requirements: *70346758880560
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &70324813505260 !ruby/object:Gem::Requirement
+  requirement: &70346758880140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70324813505260
+  version_requirements: *70346758880140
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &70324813504560 !ruby/object:Gem::Requirement
+  requirement: &70346758879720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70324813504560
+  version_requirements: *70346758879720
 - !ruby/object:Gem::Dependency
   name: rb-appscript
-  requirement: &70324813503920 !ruby/object:Gem::Requirement
+  requirement: &70346758879300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70324813503920
+  version_requirements: *70346758879300
 - !ruby/object:Gem::Dependency
   name: sdoc
-  requirement: &70324813503360 !ruby/object:Gem::Requirement
+  requirement: &70346758878840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70324813503360
+  version_requirements: *70346758878840
 - !ruby/object:Gem::Dependency
   name: term-ansicolor
-  requirement: &70324813502040 !ruby/object:Gem::Requirement
+  requirement: &70346758878420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70324813502040
+  version_requirements: *70346758878420
 - !ruby/object:Gem::Dependency
   name: trollop
-  requirement: &70324813500600 !ruby/object:Gem::Requirement
+  requirement: &70346758878000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70324813500600
+  version_requirements: *70346758878000
 - !ruby/object:Gem::Dependency
   name: autotest
-  requirement: &70324813499600 !ruby/object:Gem::Requirement
+  requirement: &70346758877580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,10 +120,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70324813499600
+  version_requirements: *70346758877580
 - !ruby/object:Gem::Dependency
   name: autotest-fsevent
-  requirement: &70324813498700 !ruby/object:Gem::Requirement
+  requirement: &70346758877120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -131,10 +131,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70324813498700
+  version_requirements: *70346758877120
 - !ruby/object:Gem::Dependency
   name: autotest-growl
-  requirement: &70324813498080 !ruby/object:Gem::Requirement
+  requirement: &70346758876700 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -142,10 +142,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70324813498080
+  version_requirements: *70346758876700
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70324813497640 !ruby/object:Gem::Requirement
+  requirement: &70346758876280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -153,10 +153,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70324813497640
+  version_requirements: *70346758876280
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70324813497100 !ruby/object:Gem::Requirement
+  requirement: &70346758875840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -164,7 +164,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70324813497100
+  version_requirements: *70346758875840
 description: A Ruby command-line utility for translating files using a YAML wordlist
 email:
 - bryan.mckelvey@gmail.com
@@ -191,7 +191,7 @@ files:
 - lib/konjac/installer.rb
 - lib/konjac/language.rb
 - lib/konjac/office.rb
-- lib/konjac/office/generic.rb
+- lib/konjac/office/base.rb
 - lib/konjac/office/item.rb
 - lib/konjac/office/mac.rb
 - lib/konjac/office/mac/excel.rb
@@ -246,7 +246,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: konjac
-rubygems_version: 1.8.10
+rubygems_version: 1.8.17
 signing_key: 
 specification_version: 3
 summary: A Ruby command-line utility for translating files using a YAML wordlist