rubyfocus 0.3.0

data/lib/rubyfocus/includes/searchable.rb

@@ -0,0 +1,82 @@
+module Rubyfocus
+	# The Searchable module allows you to easily search arrays of items by
+	# effectively supplying find and select methods. Passing a hash to either
+	# of these methods allows you to search by given properties - for example:
+	# 
+	#   data_store.find(name: "Foobar")
+	#
+	# Is basically the same as:
+	#
+	# 	data_store.find{ |o| o.name == "Foobard" }
+	#
+	# If you pass +find+ or +select+ a String or Fixnum, it will look for objects
+	# whose +id+ equals this value.
+	#
+	# You should ensure that your class' +array+ method is overwritten to point
+	# to the appriopriate array.
+	module Searchable
+		# This method will return only the *first* object that matches the given
+		# criteria, or +nil+ if no object is found.
+		def find(arg=nil, &blck)
+			fs_block = find_select_block(arg) || blck
+			if fs_block
+				return array.find(&fs_block)
+			else
+				raise ArgumentError, "ItemArray#find called with #{arg.class} argument."
+			end
+		end
+
+		# This method will return an array of all objects that match the given
+		# criteria, or +[]+ if no object is found.
+		def select(arg=nil, &blck)
+			fs_block = find_select_block(arg) || blck
+			if fs_block
+				return array.select(&fs_block)
+			else
+				raise ArgumentError, "ItemArray#select called with #{arg.class} argument."
+			end
+		end
+
+		# This method should be overriden
+		def array
+			raise RuntimeError, "Method #{self.class}#array has not been implemented!"
+		end
+
+		private
+		# This method determines the correct block to use in find or select operations
+		def find_select_block(arg)
+			case arg
+			when Fixnum # ID
+				string_id = arg.to_s
+				Proc.new{ |item| item.id == string_id }
+			when String
+				Proc.new{ |item| item.id == arg }
+			when Hash
+				Proc.new{ |item| arg.all?{ |k,v| item.send(k) == v } }
+			else
+				nil
+			end
+		end
+	end
+
+
+	# A sample class, SearchableArray, is basically a wrapper around a standard array
+	class SearchableArray
+		include Searchable
+		attr_reader :array
+
+		# Takes the same arguments as the array it wraps
+		def initialize(*args, &blck)
+		  @array = Array.new(*args, &blck)
+		end
+
+		# In all other respects, it's an array - handily governed by this method
+		def method_missing meth, *args, &blck
+			if @array.respond_to?(meth)
+				@array.send(meth, *args, &blck)
+			else
+				super(meth, *args, &blck)
+			end
+		end
+	end
+end

data/lib/rubyfocus/items/context.rb

@@ -0,0 +1,15 @@
+class Rubyfocus::Context < Rubyfocus::RankedItem
+	include Rubyfocus::Parser
+	def self.matches_node?(node)
+		return (node.name == "context")
+	end
+
+	idref :container
+	attr_accessor :location
+
+	def apply_xml(n)
+		super(n)
+		conditional_set(:container_id,n.at_xpath("xmlns:context")) { |e| e["idref"] }
+		conditional_set(:location, 		n.at_xpath("xmlns:location")){ |e| Rubyfocus::Location.new(e) }
+	end
+end

data/lib/rubyfocus/items/folder.rb

@@ -0,0 +1,18 @@
+class Rubyfocus::Folder < Rubyfocus::RankedItem
+	include Rubyfocus::Parser
+	def self.matches_node?(node)
+		return (node.name == "folder")
+	end
+	
+	idref :container
+
+	def apply_xml(n)
+		super(n)
+		conditional_set(:container_id, n.at_xpath("xmlns:folder")){ |e| e["idref"] }
+	end
+
+	private
+	def inspect_properties
+		super + %w(container_id)
+	end
+end

data/lib/rubyfocus/items/item.rb

@@ -0,0 +1,63 @@
+# The Rubyfocus Item represents an item found in an Omnifocus XML file, and thus also
+# any Omnifocus entity.
+#
+# The Rubyfocus Item has a parent "document" as well as a series of properties determined
+# by the XML file proper. You can pass an XML document at creation or leave it blank. You
+# can always apply XML later using Item#apply_xml or Item#<<
+#
+# By separating these two methods, we can also patch the object with another XML node, e.g.
+# through an update. This is important!
+class Rubyfocus::Item
+	include Rubyfocus::IDRef
+	include Rubyfocus::ConditionalExec
+	attr_accessor :id, :added, :modified, :document
+
+	def initialize(document=nil, n=nil)
+		self.document = document
+
+		case n
+		when Nokogiri::XML::Element
+			apply_xml(n)
+		when Hash
+			n.each do |k,v|
+				setter = "#{k}="
+				send(setter,v) if respond_to?(setter)
+			end
+		end
+	end
+
+	def apply_xml(n)
+		self.id ||= n["id"] # This should not change once set!
+		conditional_set(:added, 		n.at_xpath("xmlns:added"))		{ |e| Time.parse(e) }
+		conditional_set(:modified, 	n.at_xpath("xmlns:modified"))	{ |e| Time.parse(e) }
+	end
+	alias_method :<<, :apply_xml
+
+	#---------------------------------------
+	# Inspection method
+
+	def inspect
+		msgs = inspect_properties.select{ |sym| self.respond_to?(sym) && !self.send(sym).nil? }
+		"#<#{self.class} " + msgs.map{ |e| %|#{e}=#{self.send(e).inspect}| }.join(" ") + ">"
+	end
+
+	def to_serial
+		inspect_properties.each_with_object({}){ |s,hsh| hsh[s] = self.send(s) }
+	end
+
+	#---------------------------------------
+	# Document set/get methods
+	def document= d
+		@document.remove_element(self) if @document
+		@document = d
+		@document.add_element(self) if @document
+	end
+
+	#-------------------------------------------------------------------------------
+	# Private inspect methods
+
+	private
+	def inspect_properties
+		%w(id added modified)
+	end
+end

data/lib/rubyfocus/items/named_item.rb

@@ -0,0 +1,13 @@
+class Rubyfocus::NamedItem < Rubyfocus::Item
+	attr_accessor :name
+
+	def apply_xml(n)
+		super(n)
+		conditional_set(:name, n.at_xpath("xmlns:name"), &:inner_html)
+	end
+
+	private
+	def inspect_properties
+		super + %w(name)
+	end
+end

data/lib/rubyfocus/items/project.rb

@@ -0,0 +1,76 @@
+# The project represents an OmniFocus project object.
+class Rubyfocus::Project < Rubyfocus::Task
+	# It's parseable
+	include Rubyfocus::Parser
+
+	#-------------------------------------------------------------------------------
+	# Parsing stuff
+
+	# Projects are <task>s with an interior <project> node
+	def self.matches_node?(node)
+		return (node.name == "task" && (node/"project").size > 0)
+	end
+	
+	# Singleton: contains one-off tasks
+	attr_accessor :singleton
+
+	# How often to we review this project?
+	attr_accessor :review_interval
+
+	# When did we last review the project?
+	attr_accessor :last_review
+
+	# What's the status of the project? Valid options: :active, :inactive, :done. Default
+	# is :active
+	attr_accessor :status
+
+	# Initialize the project with a document and optional node to base it off of.
+	# Also sets default values
+	def initialize(document=nil, n=nil)
+		@singleton = false
+		@order = :sequential
+		@status = :active
+		super(document, n)
+	end
+
+	# Apply XML node to project
+	def apply_xml(n)
+		super(n)
+
+		#First, set project
+		p = n.at_xpath("xmlns:project")
+		conditional_set(:singleton, 			p.at_xpath("xmlns:singleton"))					{ |e| e.inner_html == "true" }
+		conditional_set(:review_interval, p.at_xpath("xmlns:review-interval") ) 	{ |e| Rubyfocus::ReviewPeriod.from_string(e.inner_html) }
+		conditional_set(:last_review, 		p.at_xpath("xmlns:last-review"))				{ |e| Time.parse e.inner_html }
+		conditional_set(:status,					p.at_xpath("xmlns:status"))							{ |e| e.inner_html.to_sym }							
+	end
+
+	alias_method :singleton?, :singleton
+
+	private
+	def inspect_properties
+		super + %w(singleton review_interval last_review)
+	end
+
+	public
+
+	#-------------------------------------------------------------------------------
+	# Convenience methods
+
+	# Status methods
+	def active?; status == :active; end
+	def on_hold?; status == :inactive; end
+	def completed?; status == :done; end
+	def dropped?; status == :dropped; end
+
+	#---------------------------------------
+	# Convert to a task
+	def to_task
+		t = Rubyfocus::Task.new(self.document)
+		instance_variables.each do |ivar|
+			setter = ivar.to_s.gsub(/^@/,"") + "="
+			t.send(setter, self.instance_variable_get(ivar))	if t.respond_to?(setter)
+		end
+		t
+	end
+end

data/lib/rubyfocus/items/ranked_item.rb

@@ -0,0 +1,13 @@
+class Rubyfocus::RankedItem < Rubyfocus::NamedItem
+	attr_accessor :rank
+
+	def apply_xml(n)
+		super(n)
+		conditional_set(:rank, n.at_xpath("xmlns:rank")){ |e| e.inner_html.to_i }
+	end
+
+	private
+	def inspect_properties
+		super + %w(rank)
+	end
+end

data/lib/rubyfocus/items/setting.rb

@@ -0,0 +1,17 @@
+class Rubyfocus::Setting < Rubyfocus::Item
+	include Rubyfocus::Parser
+	def self.matches_node?(node)
+		return (node.name == "xmlns:plist")
+	end
+	
+	attr_accessor :value
+
+	def apply_xml(n)
+		super(n)
+		conditional_set(:value, n.at_xpath("xmlns:plist").children.first){ |e| Rubyfocus::XMLTranslator.parse(e) }
+	end
+
+	def inspect
+		form_inspector(:id, :name, :value, :added, :modified)
+	end
+end

data/lib/rubyfocus/items/task.rb

@@ -0,0 +1,133 @@
+class Rubyfocus::Task < Rubyfocus::RankedItem
+	include Rubyfocus::Parser
+	def self.matches_node?(node)
+		return (node.name == "task")
+	end
+	
+	# Inherits from RankedItem:
+	# * rank
+	# Inherits from NamedItem:
+	# * name
+	# Inherits from Item:
+	# * id
+	# * added
+	# * modified
+	# * document
+
+	attr_accessor :note, :flagged, :order, :start, :due, :completed
+	idref :container, :context
+
+	def initialize(document, n=nil)
+		@order = :sequential
+		@flagged = false
+	  super(document,n)
+	end
+
+	def apply_xml(n)
+		super(n)
+		conditional_set(:container_id, n.at_xpath("xmlns:task") || n.at_xpath("xmlns:project/xmlns:folder")){ |e| e["idref"] }
+
+		conditional_set(:context_id, 	n.at_xpath("xmlns:context"))	{ |e| e["idref"] }
+		conditional_set(:note, 				n.at_xpath("xmlns:note"))			{ |e| e.inner_html.strip }
+		conditional_set(:order, 			n.at_xpath("xmlns:order"))		{ |e| e.inner_html.to_sym }
+		conditional_set(:flagged,			n.at_xpath("xmlns:flagged"))	{ |e| e.inner_html == "true" }
+		conditional_set(:start, 			n.at_xpath("xmlns:start"))		{ |e| Time.parse(e.inner_html) }
+		conditional_set(:due, 		 		n.at_xpath("xmlns:due"))			{ |e| Time.parse(e.inner_html) }
+		conditional_set(:completed,		n.at_xpath("xmlns:completed")){ |e| Time.parse(e.inner_html) }
+	end
+
+	# Convenience methods
+	def completed?; !self.completed.nil?; end
+	alias_method :flagged?, :flagged
+
+	# Collect all child tasks. If child tasks have their own subtasks, will instead fetch those.
+	def tasks
+		@tasks ||= if self.id.nil?
+			[]
+		else
+			t_arr = document.tasks.select(container_id: self.id)
+			i = 0
+			while i < t_arr.size
+				task = t_arr[i]
+				if task.has_subtasks?
+					t_arr += t_arr.delete_at(i).tasks
+				else
+					i += 1
+				end
+			end
+			t_arr
+		end
+	end
+
+	# Collect only immediate tasks: I don't care about this subtasks malarky
+	def immediate_tasks
+		document.tasks.select(container_id: self.id)
+	end
+
+	# The first non-completed task, determined by order
+	def next_available_task
+		nat_candidate = immediate_tasks.select{ |t| !t.completed? }.sort_by(&:rank).first
+		if nat_candidate.has_subtasks?
+			nat_candidate.next_available_task
+		else
+			nat_candidate
+		end
+	end
+
+	# A list of all tasks that you can take action on. Actionable tasks
+	# are tasks that are:
+	# * not completed
+	# * not blocked (as part of a sequential project or task group)
+	# * not due to start in the future
+	def actionable_tasks
+		@actionable_tasks ||= next_tasks.select{ |t| !t.deferred? }
+	end
+
+	# A list of all tasks that are not blocked.
+	def next_tasks
+		@next_tasks ||= incomplete_tasks.select{ |t| !t.blocked? }
+	end
+
+	# A list of all tasks that aren't complete
+	def incomplete_tasks
+		@incomplete_tasks ||= tasks.select{ |t| !t.completed? }
+	end
+
+	# Are there any tasks on this project which aren't completed?
+	def tasks_remain?
+		tasks.any?{ |t| t.completed.nil? }
+	end
+
+	# Does this task have any subtasks?
+	def has_subtasks?
+		tasks.size > 0
+	end
+
+	# Can we only start this task at some point in the future?
+	def deferred?
+		start && start > Time.now
+	end
+
+	# Can we attack this task, or does its container stop that happening?
+	def blocked?
+		container && (container.order == :sequential) && (container.next_available_task != self)
+	end
+
+	#---------------------------------------
+	# Conversion methods
+
+	# Convert the task to a project
+	def to_project
+		p = Rubyfocus::Project.new(self.document)
+		instance_variables.each do |ivar|
+			setter = ivar.to_s.gsub(/^@/,"") + "="
+			p.send(setter, self.instance_variable_get(ivar))	if p.respond_to?(setter)
+		end
+		p
+	end
+
+	private
+	def inspect_properties
+		super + %w(note container_id context_id order flagged start due completed)
+	end
+end

data/lib/rubyfocus/location.rb

@@ -0,0 +1,17 @@
+# A location file. Really a collection of properties and initializer.
+class Rubyfocus::Location
+	attr_accessor :name, :latitude, :longitude, :radius, :notification_flags
+
+	def initialize(n)
+		@notification_flags = 0
+		self.name = n["name"]
+		self.latitude = n["latitude"].to_f
+		self.longitude = n["longitude"].to_f
+		self.radius = n["radius"].to_i
+		self.notification_flags = n["notificationFlags"].to_i
+	end
+
+	def inspect
+		%|#<Rubyfocus::Location latitude="#{self.latitude}" longitude="#{self.longitude}">|
+	end
+end

data/lib/rubyfocus/patch.rb

@@ -0,0 +1,142 @@
+# The patch class represents a text-file patch, storing update, delete, and creation operations.
+# It should also be able to apply itself to an existing document.
+class Rubyfocus::Patch
+	# The fetcher this patch belongs to. We mainly use this to work out how to fetch content for the patch proper
+	attr_accessor :fetcher
+
+	# Operations to be performed on a document
+	attr_accessor :update, :delete, :create
+
+	# The file the patch loads from
+	attr_accessor :file
+
+	# These record the transformation in terms of patch ID values.
+	attr_accessor :from_ids, :to_id
+
+	# The time the file was submitted
+	attr_accessor :time
+
+	# By default we initialize patches from a file. To initialize from a string, use the .from_string method.
+	# This class will lazily load data from the file proper
+	def initialize(fetcher=nil, file=nil)
+		@fetcher = fetcher
+		@file = file
+		@update = []
+		@create = []
+		@delete = []
+
+		if file 
+			if File.basename(file) =~ /^(\d+)=(.*)\./
+				time_string = $1
+				self.time = if (time_string == "00000000000000")
+					Time.at(0)
+				else
+					Time.parse(time_string)
+				end
+
+				ids 					= $2.split("+")
+				self.to_id 		= ids.pop
+				self.from_ids = ids
+			else
+				raise ArgumentError, "Constructed patch from a malformed patch file: #{file}."
+			end
+		end
+	end
+
+	# Load from a string.
+	def self.from_string(fetcher, str)
+		n = new(fetcher)
+		n.load_data(str)
+		n
+	end
+
+	# Loads data from the file. Optional argument +str+ if you want to supply your own data,
+	# otherwise will load file data
+	def load_data(str=nil)
+		return if @data_loaded
+		@data_loaded = true
+
+		str ||= fetcher.patch(self.file)
+	  doc = Nokogiri::XML(str)
+	  doc.root.children.select{ |n| !n.text?}.each do |child|
+	  	case child["op"]
+	  	when "update"
+	  		@update << child
+	  	when "delete"
+	  		@delete << child
+	  	when "reference" # Ignore!
+	  	when nil
+	  		@create << child
+	  	else
+	  		raise RuntimeError, "Rubyfocus::Patch encountered unknown operation type #{child["op"]}."
+	  	end
+	  end
+	end
+
+	# Update, delete and create methods
+	def update; load_data; @update; end
+	def delete; load_data; @delete; end
+	def create; load_data; @create; end
+
+	# Can we apply this patch to a given document?
+	def can_patch?(document)
+		self.from_ids.include?(document.patch_id)
+	end
+
+	# Apply this patch to a document. Check to make sure ids match
+	def apply_to(document)
+		if can_patch?(document)
+			apply_to!(document)
+		else
+			raise RuntimeError, "Patch ID mismatch (patch from_ids: [#{self.from_ids.join(", ")}], document.patch_id: #{document.patch_id}"
+		end
+	end
+
+	# Apply this patch to a document. Who needs error checking amirite?
+	def apply_to!(document)
+		# Updates modify elements
+		self.update.each do |node|
+			elem = document[node["id"]]
+
+			# Tasks can become projects and v.v.: check this.
+			if [Rubyfocus::Task, Rubyfocus::Project].include?(elem.class)
+				should_be_project = (node.at_xpath("xmlns:project") != nil)
+				if (elem.class == Rubyfocus::Project) && !should_be_project
+					elem.document = nil # Remove this from current document
+					elem = elem.to_task # Convert to task
+					elem.document = document # Insert again!
+				elsif (elem.class == Rubyfocus::Task) && should_be_project
+					elem.document = nil # Remove this from current document
+					elem = elem.to_project # Convert to task
+					elem.document = document # Insert again!
+				end
+			end
+
+			elem.apply_xml(node) if elem
+		end
+
+		# Deletes remove elements
+		self.delete.each do |node|
+			document.remove_element(node["id"])
+		end
+
+		# Creates make new elements
+		self.create.each do |node|
+			if Rubyfocus::Parser.parse(document, node).nil?
+				raise RuntimeError, "Encountered unparsable XML during patch reading: #{node}."
+			end
+		end
+
+		# Modify current patch_id to show new value
+		document.patch_id = self.to_id
+	end
+
+	# String representation
+	def to_s
+		if from_ids.size == 1
+			"(#{from_ids.first} -> #{to_id})"
+		else
+			"([#{from_ids.join(", ")}] -> #{to_id})"
+		end
+	end
+end

data/lib/rubyfocus/review_period.rb

@@ -0,0 +1,43 @@
+# The ReviewPeriod represents a review period used with Projects in OmniFocus
+# The ReviewPeriod is made up of three sections:
+# * The precursor symbol (~ or @, use unknown)
+# * A numerical "size"
+# * A unit ([d]ays, [w]eeks, [m]onths or [y]ears)
+
+class Rubyfocus::ReviewPeriod
+	attr_accessor :size, :unit
+
+	ALLOWED_UNITS = %i(days weeks months years)
+
+	def self.from_string(str)
+		if str =~ /^[@~]?(\d+)([a-z])$/
+			size = $1.to_i
+			unit = {"d" => :days, "w" => :weeks, "m" => :months, "y" => :years}[$2]
+			new(size: size, unit: unit)
+		else
+			raise ArgumentError, "Unrecognised review period format: \"#{str}\"."
+		end
+	end
+
+	def initialize(size:0, unit: :months)
+		self.size = size
+		self.unit = unit
+	end
+
+	def unit= value
+		raise ArgumentError, "Tried to set ReviewPeriod.unit to invalid value \"#{value}\"." unless ALLOWED_UNITS.include?(value)
+		@unit = value
+		@short_unit = nil
+	end
+
+	def short_unit
+		@short_unit ||= @unit.to_s[0]
+	end
+
+	def to_s
+		"#{size}#{short_unit}"
+	end
+
+	alias_method :inspect, :to_s
+	alias_method :to_serial, :to_s
+end

data/lib/rubyfocus/xml_translator.rb

@@ -0,0 +1,36 @@
+module Rubyfocus::XMLTranslator
+	class << self
+		VALID_NODE_NAMES = %w(string true false integer array)
+
+		# Actual parsing method
+		def parse(node)
+			method_name = node.name
+			if VALID_NODE_NAMES.include?(method_name)
+				self.send(method_name, node)
+			else
+				raise RuntimeError, "Does not recognise node type: #{method_name}."
+			end
+		end
+
+		# Individual parsing methods
+		def string(node)
+			node.inner_html
+		end
+
+		def true(node)
+			true
+		end
+
+		def false(node)
+			false
+		end
+
+		def integer(node)
+			node.inner_html.to_i
+		end
+
+		def array(node)
+			node.children.map{ |child| parse(child) }
+		end
+	end
+end

data/lib/rubyfocus.rb

@@ -0,0 +1,16 @@
+require "time"
+require "nokogiri"
+require "zip"
+require "yaml"
+require "httparty"
+
+module Rubyfocus; end
+# Require library files
+Dir[File.join(__dir__, "rubyfocus/includes/*")].each{ |f| require f }
+%w(fetcher local_fetcher oss_fetcher).each{ |f| require File.join(__dir__, "rubyfocus/fetchers", f) }
+Dir[File.join(__dir__, "rubyfocus/*.rb")].each{ |f| require f }
+
+# Need to load items in a specific order
+%w(item named_item ranked_item task project context folder setting).each do |f|
+	require File.join(__dir__, "rubyfocus/items", f)
+end