rubyfocus 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ba866c7a553641c90dd8804d86c198a7cd720c3e
+  data.tar.gz: 58c47389f885a131eb300e18dd57aa5aed6eb197
+SHA512:
+  metadata.gz: ba9aac7051986e1aa922a7077d388aae5202866a2342c3b64554debddf133da49cf3fc3042caec5e506a9e886aed41f66c90e53c4c9a5c5bd15d13cadaa8f403
+  data.tar.gz: 870cc1ccc452e2deecf1418a49500a3f966dbc88521161c96647f7ff7f19002720e504d4ad90ae8e2ce365864e385d63ae4cad9fc7b39ba45a66ce26c2fb2c36

data/.gitignore

@@ -0,0 +1,4 @@
+.rarity
+pkg
+stage_ofocus.rb
+spec/files/ofocus_staging

data/.rspec

@@ -0,0 +1 @@
+-c

data/Manifest

@@ -0,0 +1,36 @@
+# INCLUDE bin/**/*
+# INCLUDE lib/**/*
+# INCLUDE *
+# EXCLUDE **/.DS_Store
+# EXCLUDE .rarity
+# EXCLUDE stage_ofocus.rb
+# EXCLUDE spec/files/ofocus_staging
+
+.gitignore
+.rspec
+lib/rubyfocus.rb
+lib/rubyfocus/document.rb
+lib/rubyfocus/errors.rb
+lib/rubyfocus/fetchers/fetcher.rb
+lib/rubyfocus/fetchers/local_fetcher.rb
+lib/rubyfocus/fetchers/oss_fetcher.rb
+lib/rubyfocus/includes/conditional_exec.rb
+lib/rubyfocus/includes/idref.rb
+lib/rubyfocus/includes/parser.rb
+lib/rubyfocus/includes/searchable.rb
+lib/rubyfocus/items/context.rb
+lib/rubyfocus/items/folder.rb
+lib/rubyfocus/items/item.rb
+lib/rubyfocus/items/named_item.rb
+lib/rubyfocus/items/project.rb
+lib/rubyfocus/items/ranked_item.rb
+lib/rubyfocus/items/setting.rb
+lib/rubyfocus/items/task.rb
+lib/rubyfocus/location.rb
+lib/rubyfocus/patch.rb
+lib/rubyfocus/review_period.rb
+lib/rubyfocus/xml_translator.rb
+Manifest
+README.md
+rubyfocus.gemspec
+version.txt

data/README.md

@@ -0,0 +1,121 @@
+Rubyfocus is a one-way (read-only) ruby bridge to OmniFocus. Analyse, store, inspect, or play with your projects and tasks in OmniFocus from the comfort and flexibility of ruby!
+
+# Installation
+
+Rubyfocus is a ruby gem. It's not currently hosted on rubygems, though, so you'll have to download and install locally.
+
+## Via git
+
+First download rubyfocus to your computer:
+
+```
+git clone https://github.com/jyruzicka/rubyfocus.git
+```
+
+Now build and install it!
+
+```
+gem build rubyfocus.gemspec
+gem install rubyfocus-0.1.0.gem
+```
+
+# Usage
+
+## Getting set up
+
+To create a new database from your local OmniFocus install:
+
+```ruby
+require "rubyfocus"
+
+f = Rubyfocus::LocalFetcher.new # This class lets you access a local OmniFocus install
+d = Rubyfocus::Document.new(f)  # This is how we create a document linked up to a local fetcher
+
+d.update                        # This is how we get the document to update using its built-in fetcher
+
+d.save("ofocus.yml")            # Save the whole database to yaml!
+```
+
+To open it up again, it's even easier:
+
+```ruby
+require "rubyfocus"
+
+d = Rubyfocus::Document.load_from_file("ofocus.yml")   # Your document will remember everything
+d.update                                               # Updates it against the local cache, in case you made changes
+```
+
+## Grabbing data
+
+How do you access all that lovely data? Easy!
+
+```ruby
+d.projects
+d.tasks
+d.contexts
+d.folders
+```
+
+And if you want to select a certain project's tasks:
+
+```ruby
+d.projects.first.tasks
+```
+
+What if you want to select only certain projects? Sure, you can use standard `Array#find` or `Array#select` methods, but you can also make use of a hash of values:
+
+```
+d.projects.select(name: "Sample project")
+```
+
+Once you have your objects, you can query them for more information:
+
+```
+t = d.tasks.first
+t.name # => "Sample task"
+t.project.name # => "Sample project"
+t.deferred? # => true/false
+t.start # => Time or nil
+```
+
+## SyncServer-ing
+
+To access an instance of the [Omni Sync Server](http://sync.omnigroup.com), use an `OSSFetcher` object:
+
+```ruby
+f = Rubyfocus::OSSFetcher.new(my_username, my_password)
+d = Rubyfocus::Document.new(f)
+d.update
+```
+
+If you use the Omni Sync Server, you'll definitely want to save your data locally and just update what's necessary - it takes a while to download and apply all those files.
+
+# Behind the scenes
+
+OmniFocus stores its data as a "base" XML file plus a series of "patches". These are all stored as zip files inside an ".ofocus" package. This means that you can have several different devices, all storing the OmniFocus task database at different states, and each one can easily update its database by comparing the various patches against its own database and downloading/applying only what's needed.
+
+Rubyfocus makes use of this by fetching and reading OmniFocus' local store on your machine. As long as your local OmniFocus is up to date, `rubyfocus` will be able to fetch the database in its latest state.
+
+# Further work
+
+`rubyfocus` is a work in progress. In the near future I hope to release a more comprehensive document detailing exactly which details of OmniFocus' projects and tasks are available to the user, and what you can do with them.
+
+Other goals include:
+
+* Updating via the [Omni Sync Server](https://manage.sync.omnigroup.com/) rather than relying on local files.
+* A couple of example projects using rubyfocus
+
+# History
+
+## 0.3.0 // 2015-10-17
+
+* [New] Now supports remote syncing with the Omni Sync Server!
+
+## 0.2.0 // 2015-10-11
+
+* [Bugfix] Will now turn tasks into projects and projects into tasks if the user has done this in OmniFocus.
+* [Bugfix] Rubyfocus::Patch now does patch application, rather than delegating to the Fetcher.
+
+## 0.1.0 // 2015-10-10
+
+* Hello, world!

data/lib/rubyfocus/document.rb

@@ -0,0 +1,146 @@
+# The Document is how rubyfocus stores an OmniFocus document, both locally and otherwise.
+# A Document contains a number of arrays of contexts, settings, folders, projects, and tasks,
+# and is also able to keep track of what patch it's up to, for updating.
+#
+# You can initialize a document through +Document.new(doc)+, where +doc+ is either an XML string, or
+# a Nokogiri XML document (or +nil+). Alternatively, you can initialize through +Document.from_file(file)+,
+# which reads the file and parses it as XML
+#
+# You add XML to the document by running +Documet::apply_xml(doc)+, which takes all children of the root
+# XML node, tries to turn each child into a relevant object, and adds it to the document. This is done using
+# the private +ivar_for+ method, as well as +add_element(e)+, which you can use to add individual objects.
+class Rubyfocus::Document
+	include Rubyfocus::Searchable
+	# A number of arrays into which elements may fit
+	attr_reader :contexts, :settings, :folders, :projects, :tasks
+
+	# This is the identifier of the current patch level. This also determines
+	# which patches can be applied to the current document.
+	attr_accessor :patch_id
+
+	# This is the fetcher object, used to fetch new data
+	attr_accessor :fetcher
+
+	# Initalise with one of:
+	# * a Nokogiri document
+	# * a string
+	# * a fetcher subclass
+	def initialize(doc=nil)
+		%w(contexts settings projects folders tasks).each{ |s| instance_variable_set("@#{s}", Rubyfocus::SearchableArray.new) }
+
+		if doc
+			if doc.is_a?(String)
+				apply_xml(Nokogiri::XML(doc))
+			elsif doc.is_a?(Nokogiri::XML)
+				apply_xml(doc)
+			elsif doc.kind_of?(Rubyfocus::Fetcher)
+				self.fetcher = doc
+				base = Nokogiri::XML(doc.base)
+				self.apply_xml(base)
+				self.patch_id = doc.base_id
+			end
+		end
+	end
+
+	#...or from file! If you provide it with an XML file, it'll load up without a fetcher.
+	def self.from_xml(file)
+		new(File.read(file))
+	end
+
+	# Initialize from the local repo
+	def self.from_local
+		new(Rubyfocus::LocalFetcher.new)
+	end
+
+	# Initialize with a URL, for remote fetching.
+	# Not implemented yet
+	def self.from_url(url)
+		raise RuntimeError, "Rubyfocus::Document.from_url not yet implemented."
+		# new(Rubyfocus::RemoteFetcher.new(url))
+	end
+
+	# Load from a a hash
+	def self.load_from_file(file_location)
+		d = YAML::load_file(file_location)
+		d.fetcher.reset
+		d
+	end
+
+	#---------------------------------------
+	# Use the linked fetcher to update the document
+	def update
+		if fetcher
+			fetcher.update_full(self)
+		else
+			raise RuntimeError, "Tried to update a document with no fetcher."
+		end
+	end
+
+	#-------------------------------------------------------------------------------
+	# Apply XML!
+	def apply_xml(doc)
+		doc.root.children.select{ |e| !e.text? }.each do |node|
+			elem = Rubyfocus::Parser.parse(self, node)
+		end
+	end
+
+	# Given an object, work out the correct instance variable for it to go into
+	def ivar_for(obj)
+		{
+			Rubyfocus::Project => @projects,
+			Rubyfocus::Context => @contexts,
+			Rubyfocus::Task => @tasks,
+			Rubyfocus::Folder => @folders,
+			Rubyfocus::Setting => @settings
+		}[obj.class]
+	end
+	private :ivar_for
+
+	# Add an element. Element should be a Project, Task, Context, Folder, or Setting
+	# We assume whoever does this will set document appropriately on the element
+	def add_element(e)
+		dest = ivar_for(e)
+		if dest
+			dest << e
+		else
+			raise ArgumentError, "You passed a #{e.class} to Document#add_element - I don't know what to do with this."
+		end
+	end
+
+	# Remove an element from the document.
+	# We assume whoever does this is smart enough to also set the element's #document value
+	# to nil
+	def remove_element(e)
+		e = self[e] if e.is_a?(String)
+		return if e.nil?
+
+		dest = ivar_for(e)
+		if dest
+			dest.delete(e)
+		else
+			raise ArgumentError, "You passed a #{e.class} to Document#remove_element - I don't know what to do with this."	
+		end
+	end
+
+	#-------------------------------------------------------------------------------
+	# Searchable stuff
+	def elements
+		@tasks + @projects + @contexts + @folders + @settings
+	end
+
+	# For Searchable include
+	alias_method :array, :elements
+
+	#-------------------------------------------------------------------------------
+	# Find elements from id
+	def [] search_id
+		self.elements.find{ |elem| elem.id == search_id }
+	end
+
+	#---------------------------------------
+	# YAML export
+
+	def save(file)
+		File.open(file, "w"){ |io| io.puts YAML::dump(self) }
+	end
+end

data/lib/rubyfocus/errors.rb

@@ -0,0 +1,2 @@
+class Rubyfocus::RubyfocusError < Exception; end
+class Rubyfocus::OSSFetcherError < Rubyfocus::RubyfocusError; end

data/lib/rubyfocus/fetchers/fetcher.rb

@@ -0,0 +1,83 @@
+# The Fetcher class is a class that fetches data from a place - generally either a file location or a web address.
+# The Fetcher is initialized with (by default) no options, although subclasses of Fetcher may change this.
+#
+# Each Fetcher has two important methods:
+#
+# * Fetcher#base returns the text of the main xml file, upon which all patch are applied.
+# * Fetcher#patch returns the text of each update file as an array.
+#
+# You may also use the Fetcher#each_patch to iterate through all updates.
+#
+# To patch a document, simply call +Fetcher#update_full()+, passing it the document to be patched.
+# +Document#update+ will automatically send the fetcher the document.
+
+class Rubyfocus::Fetcher
+
+	# This method is called when loading a fetcher from YAML
+	def init_with(coder)
+		raise RuntimeError, "Method Fetcher#init_with called for abstract class Fetcher"
+	end
+	
+	# Returns the content of the base file
+	def base
+		raise RuntimeError, "Method Fetcher#base called for abstract class Fetcher."
+	end
+
+	# Returns the id of the base
+	def base_id
+		raise RuntimeError, "Method Fetcher#base_id called for abstract class Fetcher."
+	end
+
+	# Returns an array of patch paths - either files or urls
+	def patches
+		raise RuntimeError, "Method Fetcher#patches called for abstract class Fetcher."
+	end
+
+	# Returns the contents of a given patch
+	def patch(filename)
+		raise RuntimeError, "Method Fetcher#patch called for abstract class Fetcher."
+	end
+
+	#---------------------------------------
+	# Patching methods
+
+	# Update the document as far as we can
+	def update_full(document)
+		update_once(document) while can_patch?(document)
+	end
+
+	# Update the document one step. Raises an error if the document cannot be updated.
+	def update_once(document)
+		np = self.next_patch(document)
+		if np
+			np.apply_to(document)
+		else
+			raise RuntimeError, "Patcher#update_once called, but I can't find a patch to apply!"
+		end
+	end
+
+	# Can we patch this document? You should call this before update_onceing
+	def can_patch?(document)
+		!next_patch(document).nil?
+	end
+
+	# Collect the next patch to the document. If more than one patch can be applied,
+	# apply the latest one.
+	def next_patch(document)
+		all_possible_patches = self.patches.select{ |patch| patch.can_patch?(document) }
+		return all_possible_patches.sort_by(&:time).last
+	end
+
+
+	#---------------------------------------
+	# Serialisation info
+	def encode_with(coder)
+		raise RuntimeError, "Fetcher#encode_with called on abstract class."
+	end
+
+	# Remove all cached information
+	def reset
+		@patches = nil
+		@base = nil
+	end
+end

data/lib/rubyfocus/fetchers/local_fetcher.rb

@@ -0,0 +1,66 @@
+class Rubyfocus::LocalFetcher < Rubyfocus::Fetcher
+	# This is where the files are usually stored
+	LOCATION = File.join(ENV["HOME"], "/Library/Containers/com.omnigroup.OmniFocus2/Data/Library/Application Support/OmniFocus/OmniFocus.ofocus")
+
+	#---------------------------------------
+	# Parent method overrides
+
+	# Init from yaml
+	def init_with(coder)
+		if coder["location"]
+			@location = coder["location"]
+		end
+	end
+
+	# Fetches the contents of the base file
+	def base
+		@base ||= begin
+			zip_file = Dir[File.join(self.location,"*.zip")].first
+			if zip_file
+				Zip::File.open(zip_file){ |z| z.get_entry("contents.xml").get_input_stream.read }
+			else
+				raise RuntimeError, "Rubyfocs::LocalFetcher looking for zip files at #{self.location}: none found."
+			end
+		end
+	end
+
+	# Fetches the ID Of the base file
+	def base_id
+		base_file = File.basename(Dir[File.join(self.location,"*.zip")].first)
+		if base_file =~ /^\d+\=.*\+(.*)\.zip$/
+			$1
+		else
+			raise RuntimeError, "Malformed patch file #{base_file}."
+		end
+	end
+
+	# Fetches a list of every patch file
+	def patches
+		@patches ||= Dir[File.join(self.location, "*.zip")][1..-1].map{ |f| Rubyfocus::Patch.new(self, File.basename(f)) }
+	end
+
+	# Fetches the contents of a given patch file
+	def patch(file)
+		filename = File.join(self.location, file)
+		if File.exists?(filename)
+			Zip::File.open(filename){ |z| z.get_entry("contents.xml").get_input_stream.read }
+		else
+			raise ArgumentError, "Trying to fetch patch #{file}, but file does not exist."
+		end
+	end
+
+	# Save to disk
+	def encode_with(coder)
+		coder.map = {"location" => @location}
+	end
+
+	#---------------------------------------
+	# Location file setters and getters
+	def location
+		@location || LOCATION
+	end
+
+	def location= l
+		@location = l
+	end
+end

data/lib/rubyfocus/fetchers/oss_fetcher.rb

@@ -0,0 +1,102 @@
+# This fetcher fetches data from the OmniSyncServer.
+# NOTE: This does *not* register a client with the OmniSyncServer. As such, if you don't
+# sync with the database regularly, you will likely lose track of the head and have to re-sync.
+class Rubyfocus::OSSFetcher < Rubyfocus::Fetcher
+	# Used to log in to the Omni Sync Server. Also determines the URL of your file
+	attr_accessor :username
+	attr_accessor :password
+
+	# The engine used to fetch data. Defaults to HTTParty
+	attr_accessor :fetcher
+
+	#---------------------------------------
+	# Parent method overrides
+
+	# Initialise with username and password
+	def initialize(u,p)
+		@username = u
+		@password = p
+		@fetcher = HTTParty
+	end
+
+	# Init from yaml
+	def init_with(coder)
+		@username = coder["username"]
+		@password = coder["password"]
+		@fetcher = HTTParty
+	end
+
+	# Fetches the contents of the base file
+	def base
+		@base ||= if self.patches.size > 0
+			fetch_file(self.patches.first.file)
+		else
+			raise Rubyfocus::OSSFetcherError, "Looking for zip files at #{url}: none found."
+		end
+	end
+
+	# Fetches the ID Of the base file
+	def base_id
+		if self.patches.size > 0
+			base_file = self.patches.first
+			if base_file.file =~ /^\d+\=.*\+(.*)\.zip$/
+				$1
+			else
+				raise Rubyfocus::OSSFetcherError, "Malformed patch file #{base_file}."
+			end
+		else
+			raise Rubyfocus::OSSFetcherError, "Looking for zip files at #{url}: none found."
+		end
+	end
+
+	# Fetches a list of every patch file
+	def patches
+		@patches ||= begin
+			response = self.fetcher.get(url, digest_auth: auth).body
+			# Text is in first table, let's assume
+			table = response[/<table>(.*?)<\/table>/m,1]
+			if table
+				links = table.scan(/<a href="([^"]+)"/).flatten.select{ |f| f.end_with?(".zip") }
+				links.map{ |u| Rubyfocus::Patch.new(self,u) }
+			else
+				[]
+			end
+		end
+	end
+
+	# Fetches the contents of a given patch file
+	def patch(file)
+		fetch_file(file)
+	end
+
+	# Save to disk
+	def encode_with(coder)
+		coder.map = {
+			"username" => @username,
+			"password" => @password
+		}
+	end
+
+	#---------------------------------------
+	# Private aux methods
+	private
+	def auth
+		{username: @username, password: @password}
+	end
+
+	def url
+		"https://sync.omnigroup.com/#{@username}/OmniFocus.ofocus"
+	end
+
+	def fetch_file(f)
+		f = File.join(url,f)
+		data = self.fetcher.get(f, digest_auth: auth).body
+		io = StringIO.new(data)
+		Zip::InputStream.open(io) do |io|
+			while (entry = io.get_next_entry)
+				return io.read if entry.name == "contents.xml"
+			end
+			raise Rubyfocus::OSSFetcherError, "Malformed OmniFocus zip file #{zipfile}."
+		end
+	end
+end

data/lib/rubyfocus/includes/conditional_exec.rb

@@ -0,0 +1,7 @@
+module Rubyfocus
+	module ConditionalExec
+		def conditional_set(key, object, &blck)
+			send("#{key}=", blck[object]) if object
+		end
+	end
+end

data/lib/rubyfocus/includes/idref.rb

@@ -0,0 +1,29 @@
+module Rubyfocus
+	module IDRef
+		module ClassMethods
+			def idref *names
+				names.each do |name|
+					name_id = "#{name}_id".to_sym
+					attr_accessor name_id
+					define_method(name) do
+						return document && document.find(send(name_id))
+					end
+
+					define_method("#{name}=") do |o|
+						if o.nil?
+							self.send("#{name}_id=", nil)
+						elsif o.respond_to?(:id)
+							self.send("#{name}_id=", o.id)
+						else
+							raise ArgumentError, "#{self.class}##{name}= called with argument #{o}, which does not respond to :id."
+						end
+					end
+				end
+			end
+		end
+
+		def self.included(mod)
+			mod.extend ClassMethods
+		end
+	end
+end

data/lib/rubyfocus/includes/parser.rb

@@ -0,0 +1,36 @@
+module Rubyfocus
+	module Parser
+		@subclasses = []
+		
+		def self.parse(document, node)
+			matching_classes = @subclasses.select{ |klass| klass.matches_node?(node) }
+
+			# More than one matches? Take the most specific
+			if matching_classes.size > 1
+				classes_with_subclasses = matching_classes.select{ |c| matching_classes.any?{ |sc| sc < c } }
+				matching_classes = matching_classes - classes_with_subclasses
+			end
+
+			case matching_classes.size
+			when 0
+				nil
+			when 1
+				return matching_classes.first.new(document, node)
+			else
+				raise RuntimeError, "Node #{node.inspect} matches more than one Rubyfocus::Item subclass."
+			end
+		end
+
+		def self.included(mod)
+			@subclasses << mod
+			mod.extend ClassMethods
+		end
+
+		module ClassMethods
+			# Filler method
+			def matches_node?(node)
+				false
+			end
+		end
+	end
+end