ballmer 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fcae2435035fbc72f36f7e7f793b1c952da690da
+  data.tar.gz: 884e3214b7a0b7acb1653a1ce40c7b3c52f3ef84
+SHA512:
+  metadata.gz: 62c5311693846c3db3a07146b5df427b5146ebd017f370aab8b5eae98acfcc6bb94b5a8e390cf5f7999f341e28924ec07a43c1a3c5e86196dc73c49266957be2
+  data.tar.gz: 3190b41051a7c694d9574ea83d4d82b1b999a0f95d4e7266ea32a38298a0e81dbb6f699f46be1a69dd883bd53f0f5caf6334c984f9350c70b58b2997c41f2e57

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1 @@
+script: "bundle exec rspec"

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ballmer.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,11 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Run the base spec since that's where a bulk of the tests hang out.
+  watch(%r{^lib/ballmer/(.+?)/.+\.rb$})   { |m| "spec/lib/ballmer/#{m[1]}_spec.rb" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Brad Gessler
+
+MIT License
+
+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/README.md

@@ -0,0 +1,54 @@
+# Ballmer
+
+[![Build Status](https://travis-ci.org/polleverywhere/ballmer.png?branch=master)](https://travis-ci.org/polleverywhere/ballmer)
+
+The Ballmer gem provides the basis for modifying Office documents in Ruby. It provides access to low-level primitives including:
+
+* Unzip/zip Office document formats.
+* Low level "part" abstraction and rels resolution.
+* Direct access to manipulating/munging XML.
+
+PowerPoint is the only format with a higher-level, but basic abstraction that allows:
+
+* Copying and inserting slides.
+* Reading slide notes in the most basic sense. 
+* Writing to slidenotes via a subset of markdown (only paragraphs).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'ballmer'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ballmer
+
+## Usage
+
+```ruby
+# Open a pptx file
+p = Ballmer::Presentation.open("./fixtures/Presentation3.pptx")
+# Copy the first slide into the last position
+p.sides.push p.slides.first
+# Now save the file.
+p.save
+```
+
+## Contributing
+
+Microsoft Office is a complicating beast. If you need to grock documents you can help!
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Helpful Information
+
+* [PresentationML](http://msdn.microsoft.com/en-us/library/office/gg278335.aspx) - Directory and XML structure of an Office file.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+
+namespace :fixtures do
+  desc "Unpack all of the fixtures for inspection with a diff tool"
+  task :unpack do
+    Dir['./fixtures/*.pptx'].each{ |f| sh "bin/unpack #{f}" }
+  end
+end

data/ballmer.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ballmer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ballmer"
+  spec.version       = Ballmer::VERSION
+  spec.authors       = ["Brad Gessler"]
+  spec.email         = ["brad@polleverywhere.com"]
+  spec.description   = %q{Open and manipulate Office files.}
+  spec.summary       = %q{Manipulate Office files in Ruby.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "terminal-notifier-guard"
+  spec.add_development_dependency "pry"
+
+  spec.add_dependency "zipruby"
+  spec.add_dependency "nokogiri"
+end

data/bin/ballmer

@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+
+# Just run the command of a ballmer-bin. I'm faking out what should eventually be a Thor CLI.
+COMMAND=$1
+
+# Now 'shift' the $1 out of the args ($@) so we can pass it up into the CLI.
+shift
+
+# And run the command
+$0/../ballmer-$COMMAND $@

data/bin/ballmer-console

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+# This console is usefulf or interacting with a presentation, which makes debugging
+# a little easier since this is mostly munging with files.
+
+require 'pry'
+require 'ballmer'
+
+Ballmer::Presentation.open(ARGV.first || './fixtures/Presentation3.pptx').pry

data/bin/ballmer-duplicator

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+# This console is usefulf or interacting with a presentation, which makes debugging
+# a little easier since this is mostly munging with files.
+
+require 'ballmer'
+
+# Deal with piped input.
+ppt = if $stdin.tty?
+  Ballmer::Presentation.open(ARGV.shift)
+else
+  Ballmer::Presentation.read($stdin.read)
+end
+
+# Now duplicate the slides.
+ARGV.shift.to_i.times do |n|
+  # Copy the first slide to the end of the presentation.
+  ppt.slides.push(ppt.slides.first).tap do |slide|
+    slide.notes.body = "This is copy #{n + 1}.\n\nIt was created at #{Time.now}."
+  end
+end
+
+# Now delete the first slide.
+ppt.slides.delete ppt.slides.first
+
+# Save to disk or buffer
+ppt.commit
+
+# Pipe this shiz out if it was piped in.
+ppt.archive.zip.read { |chunk| $stdout.write chunk } unless $stdin.tty?

data/bin/ballmer-pack

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# Unpacks a .pptx file and makes XML readable by diff tools.
+
+# Remove the .pptx extension
+DIR=$1
+
+# First argument should be a path to the MS Office file
+OFFICE_FILE=$PWD/$2
+
+# No indents
+$XMLLINT_INDENT=''
+
+pushd $DIR
+  # TODO - Remove the whitespace
+  find $DIR \( -name "*.xml.rels" -o -name "*.xml" \) -type f -exec xmllint --output '{}' --format '{}' \; -print
+
+  # Unzip the presentation into a folder
+  zip -r $OFFICE_FILE .
+popd

data/bin/ballmer-unpack

@@ -0,0 +1,14 @@
+#!/usr/bin/env sh
+# Unpacks a .pptx file and makes XML readable by diff tools.
+
+# First argument should be a path to the MS Office file
+OFFICE_FILE=$1
+
+# Remove the .pptx extension
+DIR=${OFFICE_FILE%.*}
+
+# Unzip the presentation into a folder
+unzip $OFFICE_FILE -d $DIR
+
+# Prettify the XML so its easier to diff.
+find $DIR \( -name "*.xml.rels" -o -name "*.xml" \) -type f -exec xmllint --output '{}' --format '{}' \; -print

data/lib/ballmer/document/archive.rb

@@ -0,0 +1,89 @@
+require "zipruby"
+
+module Ballmer
+  class Document
+    # Abstraction that sits on top of ZipRuby because the original
+    # lib API is a bit cumbersom to use directly.
+    class Archive
+      attr_reader :zip
+
+      def initialize(zip)
+        @zip = zip
+        @original_files = (0...zip.num_files).map { |n| zip.get_name(n) }
+      end
+
+      # Save the office XML file to the file.
+      def commit
+        # TODO
+        # Update ./docProps
+        #   app.xml slides, notes, counts, etc
+        #   core.xml Times
+        entries.each do |path, buffer|
+          path = path.to_s
+          if @original_files.include? path
+            @zip.replace_buffer path, buffer
+          else
+            @zip.add_buffer path, buffer
+          end
+        end
+        @zip.commit
+      end
+
+      # Write to the zip file at the given path.
+      def write(path, buffer)
+        entries[self.class.path(path)] = buffer
+      end
+
+      # Read the blog from the Zifile
+      def read(path)
+        entries[self.class.path(path)]
+      end
+
+      # Copy a file in the zip from a path to a path.
+      def copy(target, source)
+        write target, read(source)
+      end
+
+      # Remove a file from the archive.
+      def delete(path)
+        path = self.class.path(path).to_s
+        zip.fopen(path).delete
+        entries.delete(path)
+      end
+
+      # Enumerates all of the entries in the zip file. Key
+      # is the path of the file, and the value is the contents.
+      def entries
+        @entries ||= Hash.new do |entries, path|
+          path = self.class.path(path).to_s
+          entries[path] = if @original_files.include? path
+            zip.fopen(path).read
+          else
+            ""
+          end
+        end
+      end
+
+      # Open an XML office file from the given path.
+      def self.open(path)
+        new Zip::Archive.open(path, Zip::TRUNC)
+      end
+
+      # Read zip data from a bufffer. Very useful when you want to load a template 
+      # into a server environment, modify, and serve up without writing to disk.
+      def self.read(data)
+        new Zip::Archive.open_buffer(data)
+      end
+
+      private
+
+      # All of the paths in the office file formats are expressed with a leading "/",
+      # but zip files are not since they are always considered relative the the archive
+      # root by ZipRuby. This method means that we can keep referring to paths in the 
+      # Document class on up while maintaining relative paths within the archive.
+      def self.path(path)
+        Pathname.new(path).expand_path('/').relative_path_from(Pathname.new('/'))
+      end
+    end
+  end
+end

data/lib/ballmer/document/content_types.rb

@@ -0,0 +1,43 @@
+module Ballmer
+  class Document
+    # Deals with everything related to content paths.
+    class ContentTypes < XMLPart
+      PATH = "[Content_Types].xml"
+
+      def initialize(doc, path = PATH)
+        super doc, path
+      end
+
+      # Get all of the parts for a given type
+      # TODO - Have this return an enumerable of parts so we can fitler by part-type.
+      # We can filter this by type from whatever is calling it if we blow open some
+      # new types...
+      def parts(type)
+        xml.xpath("//xmlns:Override[@ContentType='#{type}']").map{ |n| n['PartName'] }
+      end
+      alias :[] :parts
+
+      # Append a part to ContentTypes
+      def append(part)
+        # Don't write the part again if it already exists ya dummy
+        return nil if exists? part
+
+        edit_xml do |xml|
+          xml.at_xpath('/xmlns:Types').tap do |types|
+            types << Nokogiri::XML::Node.new("Override", xml).tap do |n|
+              n['PartName'] = part.path
+              n['ContentType'] = part.class::CONTENT_TYPE
+            end
+          end
+        end
+      end
+      alias :<< :append
+
+      # Test if the part already exists so we don't write
+      # it multiple times.
+      def exists?(part)
+        !! xml.at_xpath("//xmlns:Override[@ContentType='#{part.class::CONTENT_TYPE}' and @PartName='#{part.path}']")
+      end
+    end
+  end
+end

data/lib/ballmer/document/part.rb

@@ -0,0 +1,26 @@
+module Ballmer
+  class Document
+    # Basic behavior of a part. Whats a part? Could be an image, an XML file, or anything really. Most
+    # parts in a document will be an XMLPart, so be sure to take a look at that.
+    class Part
+      attr_reader :path, :doc
+
+      def initialize(doc, path)
+        @doc, @path = doc, Pathname.new(path)
+      end
+
+      # Get the relative path for this part from another part. This funciton
+      # is mostly used by the Rel class to figure out relationships between parts.
+      def relative_path_from(part)
+        # I think the rel_part.path bidness is not returning and absolute path. Fix and maybe this will work (and
+        # the weird + '..' won't be needed).
+        part.path.relative_path_from(path + '..')
+      end
+
+      # Commit the part to the buffer.
+      def commit(data = self.doc)
+        doc.write path, data
+      end
+    end
+  end
+end

data/lib/ballmer/document/rels.rb

@@ -0,0 +1,79 @@
+module Ballmer
+  class Document
+    # CRUD and resolve relative documents to a part. These map to .xml.rel documents
+    # in the MS Office document format.
+    class Rels < XMLPart
+      attr_reader :path, :doc
+
+      # TODO - Refactor the part_path business out here.
+      def initialize(doc, path, part_path)
+        super doc, path
+        @part_path = Pathname.new(part_path)
+      end
+
+      # Return a list of target paths given a type.
+      def targets(type)
+        xml.xpath("//xmlns:Relationship[@Type='#{type}']").map{ |n| Pathname.new(n['Target']) }
+      end
+
+      # TODO 
+      # Returns the rID of the part.
+      def id(part)
+        rel(part)['Id']
+      end
+
+      # Append a part to a rel so that we can extract an ID from it, and be
+      # really cool like that.
+      def append(part)
+        return nil if exists? part
+
+        edit_xml do |xml|
+          xml.at_xpath('/xmlns:Relationships').tap do |relationships|
+            relationships << Nokogiri::XML::Node.new("Relationship", xml).tap do |n|
+              n['Id'] = next_id
+              n['Type'] = part.class::REL_TYPE
+              # Rels require a strange path... still haven't quite figured it out but I need to.
+              n['Target'] = rel_path(part)
+            end
+          end
+        end
+      end
+
+      # TODO
+      # Check if the part exists
+      def exists?(part)
+        !! rel(part)
+      end
+
+      # Create a Rels class from a given part.
+      def self.from(part)
+        new part.doc, rels_path(part.path), part.path
+      end
+
+      # Resolve the default rels asset for a given part path.
+      def self.rels_path(part_path)
+        Pathname.new(part_path).join('../_rels', Pathname.new(part_path).sub_ext('.xml.rels').basename)
+      end
+  
+      private
+
+      def rel(part)
+        xml.at_xpath("/xmlns:Relationships/xmlns:Relationship[@Type='#{part.class::REL_TYPE}' and @Target='#{rel_path(part)}']")
+      end
+
+      # TODO - This feels dirty, dropping into kinda sorta paths (instead of parts). Refactor
+      # this so that we're only dealing with parts up in here. Use Part#relative_path_from.
+      def rel_path(rel_part)
+        # I think the rel_part.path bidness is not returning and absolute path. Fix and maybe this will work (and
+        # the weird + '..' won't be needed).
+        rel_part.path.relative_path_from(@part_path + '..')
+      end
+
+      # TODO - Figure out how to make this more MS idiomatic up 9->10 instead of incrementing
+      # the character....
+      def next_id
+        xml.xpath('//xmlns:Relationship[@Id]').map{ |n| n['Id'] }.sort.last.succ
+      end
+    end
+  end
+end

data/lib/ballmer/document/xml_part.rb

@@ -0,0 +1,29 @@
+module Ballmer
+  class Document
+    # Various helpers for editing Part XML data and resolving relative part paths.
+    class XMLPart < Part
+      # TODO - Figure out how to curry the path into this call and delegate.
+      # Also, if the DOM is what speaks the truth, this caching will cause some
+      # really stupid/weird bug down the line.
+      def xml
+        @xml ||= doc.xml(path)
+      end
+
+      # TODO - Figure out how to curry the path into this call and delegate
+      def edit_xml(&block)
+        block.call(xml)
+        commit
+      end
+
+      # Grab the rels file for this asset.
+      def rels
+        Rels.from(self)
+      end
+
+      # Commit the part XML to the buffer.
+      def commit
+        super xml.to_s
+      end
+    end
+  end
+end

data/lib/ballmer/document.rb

@@ -0,0 +1,52 @@
+module Ballmer
+  # Deals with file concerns between higher-level classes like
+  # Slides, Notes and file-system level work.
+  class Document
+    autoload :Archive,      'ballmer/document/archive'
+    autoload :Part,         'ballmer/document/part'
+    autoload :XMLPart,      'ballmer/document/xml_part'
+    autoload :Rels,         'ballmer/document/rels'
+    autoload :ContentTypes, 'ballmer/document/content_types'
+
+    # Forward method calls on document to the archive, mostly
+    # low-level read/write/copy file operations. The Document
+    # class should deal with decorating these read/writes with
+    # helper Parts.
+    extend Forwardable
+    def_delegators :archive, :read, :write, :copy, :delete, :commit
+
+    # Make the archive available in case the developer needs to perform
+    # even lower level IO functions.
+    attr_reader :archive
+
+    def initialize(archive)
+      @archive = archive
+    end
+
+    # Open an XML office file from the given path.
+    def self.open(path)
+      new Archive.open(path)
+    end
+
+    # Read zip data from a bufffer. Very useful when you want to load a template 
+    # into a server environment, modify, and serve up without writing to disk.
+    def self.read(data)
+      new Archive.read(data)
+    end
+
+    # Open an XML document at the given path.
+    def xml(path)
+      Nokogiri::XML read path
+    end
+
+    # Modify XML within a block and write it back to the zip when done.
+    def edit_xml(path, &block)
+      write path, xml(path).tap(&block).to_s
+    end
+
+    # Content types XML file.
+    def content_types
+      ContentTypes.new(self)
+    end
+  end
+end

data/lib/ballmer/presentation/notes.rb

@@ -0,0 +1,32 @@
+module Ballmer
+  class Presentation
+    class Notes < Document::XMLPart
+      # TODO, there are three types of notes. We need to figure out 
+      # how to resolve the slide number, notes, and whatever the hell else
+      # the first note type is.
+
+      # Key used to look up notes from [Content-Types].xml.
+      CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml".freeze
+
+      # Key used to look up notes from .xml.rel documents
+      REL_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide'.freeze
+
+      # TODO - Generate/update the notes with a mark-down-ish heuristic, 
+      # being that two newlines translate into the weird note formats of PPT slides.
+      def body=(body)
+        nodes_parser.parse(body)
+        commit
+      end
+
+      def body
+        nodes_parser.to_s
+      end
+      alias :to_s :body
+
+      private
+      def nodes_parser
+        NotesParser.new(xml)
+      end
+    end
+  end
+end

data/lib/ballmer/presentation/notes_parser.rb

@@ -0,0 +1,57 @@
+module Ballmer
+  class Presentation
+    class NotesParser
+      # Make this read the language set by the OS or from a configuration.
+      DEFAULT_LANG = 'en-US'
+
+      def initialize(xml)
+        @xml = xml
+      end
+
+      # MSFT Thought it would be cool to drop a bunch of different bodies
+      # and id attributes in here that don't link to anything, so lets go
+      # loosey goosey on it and find the stupid "Notes Placeholder" content.
+      def node
+        @xml.at_xpath('
+          //p:nvSpPr[
+            p:cNvPr[starts-with(@name, "Notes Placeholder")]
+          ]/following-sibling::p:txBody
+        ')
+      end
+
+      def to_s
+        node.xpath('.//a:p').map do |p| # Put each new paragraph on a line.
+          p.xpath('.//a:t').map(&:text).join # And join up each word... turd.
+        end.join("\n")
+      end
+
+      # Parses a text file with newline breaks into "paragraphs" per whatever weird markup
+      # the noteSlides is using. For now we're keeping this simple, no italics or other crazy stuff,
+      # but this is the class that would be extended, changed, or swapped out in the future.
+      def parse(body, lang = DEFAULT_LANG)
+        body_pr = Nokogiri::XML::Node.new("p:txBody", @xml)
+        # These should be blank... I don't know why, but they're always that way in the files.
+        #   <a:bodyPr/>
+        #   <a:lstStyle/>
+        body_pr << Nokogiri::XML::Node.new("a:bodyPr", @xml)
+        body_pr << Nokogiri::XML::Node.new("a:lstStyle", @xml)
+        # TODO - Reject blank lines after we chomp 'em
+        body_pr << Nokogiri::XML::Node.new("a:p", @xml).tap do |p|
+          p << Nokogiri::XML::Node.new("a:r", @xml).tap do |r|
+            r << Nokogiri::XML::Node.new("a:rPr", @xml).tap do |rpr|
+              # PPT just wants this, k?
+              rpr["lang"] = lang
+              rpr["dirty"] = "0"
+              rpr["smtClean"] = "0"
+            end
+            # This is where we finally inject content. w00.
+            r << Nokogiri::XML::Node.new("a:t", @xml).tap do |t|
+              t.content = body
+            end
+          end
+        end
+        node.replace body_pr
+      end
+    end
+  end
+end