calfilter 1.1.3 → 1.1.4

data/History.txt

@@ -1,3 +1,7 @@
+=== 1.1.4 / 2008-05-05
+
+* Documentation!
+
 === 1.1.3 / 2008-05-04
 
 * Bug fixes:
@@ -5,6 +9,8 @@
   * Monkey-patched Icalendar to deal with Dates (as opposed to
     DateTimes) correctly.
 
+  * Monkey-patched Icalendar to preserve UTC on times.
+
 === 1.1.2 / 2008-05-04
 
 * Bug fix in calfilter.rb

data/README.txt

@@ -12,13 +12,15 @@ various purposes, including:
 * removing private information from your own calendar before publishing it to others
 * reformatting a provided calendar to highlight particular information
 
-== FEATURES/PROBLEMS:
+A calfilter script does most of its work using the filter_calendars[link:files/lib/calfilter_rb.html] method.
 
-* require 'calfilter/tripit' to add some methods specific to
+== FEATURES:
+
+* require '{calfilter/tripit}[link:files/lib/calfilter/tripit_rb.html]' to add some methods specific to
   tripit.com calendar feeds.
 
-* require 'calfilter/cgi' to automatically turn your filter into
-  a CGI script.  The CGI object is available as 'CalFilter::CGI'.
+* require '{calfilter/cgi}[link:files/lib/calfilter/cgi_rb.html]' to automatically turn your filter into
+  a CGI script.  The CGI object is available as <tt>CalFilter::CGI</tt>.
 
 == SYNOPSIS:
 
@@ -43,6 +45,10 @@ calfilter depends on the icalendar gem.
 
 sudo gem install calfilter
 
+== AUTHOR
+
+Glenn Vanderburg <glenn@thinkrelevance.com>
+
 == LICENSE:
 
 (The MIT License)

data/Rakefile

@@ -12,6 +12,9 @@ class Hoe
   end
 end
 
+# Class structure isn't complex enough to make diagrams worthwhile.
+ENV['NODOT'] = "true"
+
 Hoe.new('calfilter', CalFilter::VERSION) do |p|
   p.rubyforge_name = 'thinkrelevance'
   p.developer('Glenn Vanderburg', 'glenn@thinkrelevance.com')

data/ToDo.txt

@@ -1,5 +1,3 @@
-* Greatly improve (i.e., existing) RDocs
-
 * Ensure timezone information is retained
 
 * Improved set of TripIt methods
@@ -15,3 +13,6 @@
 
 * Similar to the cgi module, it should be easy to require modules
   to turn a filter into a camping app, a webrick service, etc.
+
+* Perhaps have real methods for filter_{events,freebusys,journals,todos}
+  to improve the rdocs.

data/lib/calfilter/cgi.rb

@@ -1,10 +1,19 @@
+# Turns a calfilter script into a CGI script.  
+# 
+# Simply require this file at the top of a calfilter script
+# to turn it into a CGI script.  The CGI object will be accessible
+# as <tt>CalFilter::CGI</tt>.
+#
+# (This file makes use of CalFilter.output_stream, so please don't
+# set that yourself if using calfilter/cgi.)
+
 require 'calfilter'
 require 'cgi'
 require 'stringio'
 
 module CalFilter
 
-  class CGIWrapper
+  class CGIWrapper  # :nodoc: all
     attr_reader :output_stream
     
     def initialize(output_stream)
@@ -25,7 +34,7 @@ module CalFilter
     end
   end
 
-  def self.make_cgi_wrapper
+  def self.make_cgi_wrapper # :nodoc:
     CGIWrapper.new(StringIO.new)
   end
   

data/lib/calfilter/datetime_extensions.rb

@@ -1,4 +1,4 @@
-class DateTime
+class DateTime  # :nodoc: all
   attr_writer :utc
   
   def utc?

data/lib/calfilter/icalendar_extensions.rb

@@ -1,18 +1,20 @@
-class Icalendar::Parser
-  def parse_datetime_with_date_check(name, params, value)
-    if /\d{8}T/ =~ value
-      dt = parse_datetime_without_date_check(name, params, value)
-      dt.utc = true if /Z/ =~ value
-      dt
-    else
-      begin
-        Date.parse(value)
-      rescue Exception
-        value
+module Icalendar  # :nodoc: all
+  class Parser
+    def parse_datetime_with_date_check(name, params, value)
+      if /\d{8}T/ =~ value
+        dt = parse_datetime_without_date_check(name, params, value)
+        dt.utc = true if /Z/ =~ value
+        dt
+      else
+        begin
+          Date.parse(value)
+        rescue Exception
+          value
+        end
       end
     end
-  end
   
-  alias :parse_datetime_without_date_check :parse_datetime
-  alias :parse_datetime :parse_datetime_with_date_check
-end
+    alias :parse_datetime_without_date_check :parse_datetime
+    alias :parse_datetime :parse_datetime_with_date_check
+  end
+end

data/lib/calfilter/time_extensions.rb

@@ -1,4 +1,4 @@
-class Time
+class Time  # :nodoc: all
   attr_writer :utc
   
   def utc?

data/lib/calfilter/tripit.rb

@@ -1,23 +1,56 @@
+# Mixes methods into CalFilter::ResourceWrapper that help when 
+# dealing with calendars from TripIt[http://tripit.com/].  Just
+# require this file at the top of a calfilter script to gain the
+# extra functionality.
+
 require 'calfilter'
 
 module CalFilter
   module TripIt
+    # The keys are the $1 strings from description =~ /^\[(.*?)\]/m
     EVENT_TYPES = {
-      # The keys are the $1 strings from description =~ /^\[(.*?)\]/m
       nil          => :trip,
-      'Flight'     => :flight,
+      'Activity'   => :activity,
+      'Article'    => :article,
       'Car Rental' => :car,
-      'Hotel'      => :hotel,
+      'Cruise'     => :cruise,
       'Directions' => :directions,
-      'Activity'   => :activity
+      'Flight'     => :flight,
+      'Hotel'      => :hotel,
+      'Map'        => :map,
+      'Meeting'    => :meeting,
+      'Note'       => :note,
+      'Rail'       => :rail,
+      'Restaurant' => :restaurant
     }
     
+    # :call-seq:
+    #   tripit_type => tripit_type_symbol
+    #   tripit_type(tripit_type_symbol, ...) => true or false
+    #
+    # Investigates the type of an event, based on <tt>[<em>Type</em>]</tt> strings in the descriptions used by Trip<b></b>It.
+    #
+    # TripIt[http://tripit.com/] uses <tt>[<em>Event Type</em>]</tt> strings in its
+    # event descriptions to signal what kind of event it is.  The known types are the
+    # keys used in EVENT_TYPES.
+    # 
+    # This method facilitates querying an event to learn its Trip<b></b>It event type.
+    #
+    # When called with no arguments, the method will return an event type
+    # symbol (one of the values from EVENT_TYPES) to indicate the type of 
+    # event, or :unknown if an unknown type is encountered (or if the target is
+    # some other kind of Icalendar resource, such as a todo).
+    #
+    # When called with argumetns, those arguments must be event type symbols,
+    # and the method will return true if the event is one of those types, and
+    # false otherwise (or if the target is not an event).
     def tripit_type(*args)
-      return :unknown unless __kind__ == 'event'
       if args.empty?
+        return :unknown unless __kind__ == 'event'
         description =~ /^\[(.+?)\]/m
         TripIt::EVENT_TYPES[$1] || :unknown
       else
+        return false unless __kind__ == 'event'
         args.include?(tripit_type)
       end
     end

data/lib/calfilter.rb

@@ -4,12 +4,17 @@ $:.unshift(File.dirname(__FILE__))
 %w{datetime icalendar time}.each{|l| require "calfilter/#{l}_extensions"}
 
 module CalFilter
-  VERSION = '1.1.3'
+  VERSION = '1.1.4'
   
+  # The output stream for filtered icalendar output.
+  # If this is not nil, filter_calendars will automatically
+  # write the filtered calendars to this stream in 
+  # icalendar format.
   def self.output_stream
     @output_stream
   end
   
+  # Sets output_stream.
   def self.output_stream=(stream)
     @output_stream = stream
   end
@@ -17,46 +22,77 @@ module CalFilter
   class FilterError < RuntimeError
   end
 
+  # A filtering wrapper for an 
+  # Icalendar[http://icalendar.rubyforge.org/] 
+  # resource object.  The wrapped object will be one of:
+  #
+  # * {Icalendar::Event}[http://icalendar.rubyforge.org/classes/Icalendar/Event.html]
+  # * {Icalendar::Freebusy}[http://icalendar.rubyforge.org/classes/Icalendar/Freebusy.html]
+  # * {Icalendar::Journal}[http://icalendar.rubyforge.org/classes/Icalendar/Journal.html]
+  # * {Icalendar::Todo}[http://icalendar.rubyforge.org/classes/Icalendar/Todo.html]
+  #
+  # All unrecognized methods are delegated to the underlying
+  # resource object, so methods such as #description and #summary
+  # work as expected.  (The resource object can be accessed directly
+  # using the #\__delegate__ method.)
+  #
+  # In addition to delegating to the resource, ResourceWrapper objects
+  # provide a few additional methods: 
+  # 
+  # * #\_\_delegate__
+  # * #keep
+  # * #remove
   class ResourceWrapper
-    def initialize(delegate, kind)
+    def initialize(delegate, kind)  # :nodoc:
       @delegate = delegate
       @kind = kind
     end
     
+    # Provides access to the underlying resource being wrapped.
     def __delegate__
       @delegate
     end
     
-    def __action__
+    def __action__    # :nodoc:
       @keep_or_remove || :default
     end
     
-    def __kind__
+    def __kind__      # :nodoc:
       @kind
     end
 
+    # Marks this resource for removal from the calendar.
+    # For a particular kind of resource (e.g., events, todos,
+    # journals) in a given calendar, you can call either #remove
+    # or #keep on some of the resources, but not both.
     def remove
       __flag__ :remove
     end
     
+    # Marks this resource to be kept in the calendar.  
+    # If this is called on some resources, all others in the
+    # collection will be removed.
+    # For a particular kind of resource (e.g., events, todos,
+    # journals) in a given calendar, you can call either #remove
+    # or #keep on some of the resources, but not both.
     def keep
       __flag__ :keep
     end
     
-    def method_missing(symbol, *args, &block)
+    def method_missing(symbol, *args, &block)     # :nodoc:
       __delegate__.send(symbol, *args, &block)
     end
 
     protected
     
-    def __flag__(sym)
+    def __flag__(sym)                             # :nodoc:
       other_sym = (sym == :keep ? :remove : :keep)
       raise FilterError, "Cannot both keep and remove the same #{@kind}", __caller__ if @keep_or_remove == other_sym
       @keep_or_remove = sym
       throw :bailout if sym == :remove
     end
     
-    def __caller__
+    def __caller__                                # :nodoc:
       f = __FILE__
       stack = caller
       stack.each_with_index do |s, i|
@@ -66,13 +102,62 @@ module CalFilter
     
   end
 
+  # A filtering wrapper for an 
+  # {Icalendar::Calendar}[http://icalendar.rubyforge.org/classes/Icalendar/Calendar.html] 
+  # object.
+  #
+  # All unrecognized methods are delegated to the underlying
+  # Calendar object, so methods such as #events and find_event
+  # work as expected.  (The Calendar object can be accessed directly
+  # using the #\_\_delegate__ method.)
+  #
+  # In addition to delegating to the Calendar, CalendarWrapper objects
+  # provide a few additional methods: 
+  # 
+  # * #\_\_delegate__
+  # * #keep
+  # * #remove
+  # * #filter_events
+  # * #filter_freebusys
+  # * #filter_journals
+  # * #filter_todos
+  #
+  # === Filtering Resource Collections
+  #
+  # If you want to remove one or more of a calendar's resource collections
+  # in their entirety, use #remove (or #keep).  
+  # But you can also filter the collections themselves:
+  #
+  # * <b>filter_events</b> <em>{|event| ... }</em>
+  # * <b>filter_freebusys</b> <em>{|freebusy| ... }</em>
+  # * <b>filter_journals</b> <em>{|journal| ... }</em>
+  # * <b>filter_todos</b> <em>{|todo| ... }</em>
+  #
+  # Each of these methods iterates over all of the elements of 
+  # the named resource collection, allowing the individual resources
+  # to be modified or removed.  See ResourceWrapper for the methods
+  # available for working with individual resource instances.
   class CalendarWrapper < ResourceWrapper
     RESOURCE_TYPES = %w{events freebusys journals todos}
     
-    def initialize(calendar)
+    def initialize(calendar)   # :nodoc:
       super(calendar, 'calendar')
     end
     
+    # :call-seq:
+    #   remove
+    #   remove(collection_symbol, [collection_symbol, ...])
+    #
+    # Marks this calendar (or collection of resources in the calendar) for removal.
+    #
+    # If called with no arguments, removes the entire calendar.  
+    #
+    # Any arguments must be one of <tt>:events</tt>, <tt>:freebusys</tt>, 
+    # <tt>:journals</tt>, or <tt>:todos</tt>, and 
+    # the named resource collections will be removed from this calendar.
+    #
+    # For a given calendar or resource collection, you can call either #remove
+    # or #keep, but not both.
     def remove(*args)
       if args.empty?
         super
@@ -81,6 +166,22 @@ module CalFilter
       end
     end
     
+    # :call-seq:
+    #   keep
+    #   keep(collection_symbol, [collection_symbol, ...])
+    #
+    # Marks this calendar (or collection of resources in the calendar) to be kept.
+    #
+    # If called with no arguments, keeps the entire calendar; any calendars
+    # not kept will be removed.
+    #
+    # Any arguments must be one of <tt>:events</tt>, <tt>:freebusys</tt>, 
+    # <tt>:journals</tt>, or <tt>:todos</tt>, and 
+    # the named resource collections will be kept in this calendar, and
+    # all resource collections not kept will be removed.
+    #
+    # For a given calendar or resource collection, you can call either #remove
+    # or #keep, but not both.
     def keep(*args)
       if args.empty?
         super
@@ -89,7 +190,7 @@ module CalFilter
       end
     end
     
-    def method_missing(symbol, *args, &block)
+    def method_missing(symbol, *args, &block)  # :nodoc:
       if symbol.to_s =~ /^filter_(.*)$/ && RESOURCE_TYPES.include?($1)
         __filter_resource__($1, *args, &block)
       else
@@ -121,17 +222,17 @@ module CalFilter
     
   end
   
-  def self.wrap_calendar(cal)
+  def self.wrap_calendar(cal)   # :nodoc:
     CalendarWrapper.new(cal)
   end
   
-  def self.wrap_resource(res, plural_resource_type)
+  def self.wrap_resource(res, plural_resource_type)  # :nodoc:
     # This works with the particular resource names in Icalendar:
     singular_resource_type = plural_resource_type.sub(/s$/, '')
     ResourceWrapper.new(res, singular_resource_type)
   end
   
-  def self.keep_or_delete_items(items, type, actions)
+  def self.keep_or_delete_items(items, type, actions)   # :nodoc:
     if actions.include?(:keep) && actions.include?(:remove)
       raise CalFilter::FilterError, "Cannot both keep and remove #{type} in the same group.", caller(2)
     end
@@ -143,6 +244,30 @@ module CalFilter
   
 end
 
+# Filters the calendars found at sources.
+#
+# The sources can be 
+#
+# * {Icalendar::Calendar}[http://icalendar.rubyforge.org/classes/Icalendar/Calendar.html]
+#   objects, 
+# * arrays of those objects (because Icalendar.parse returns arrays
+#   of calendars),
+# * URLs pointing to iCalendar[http://en.wikipedia.org/wiki/ICalendar] streams, or
+# * strings containing iCalendar[http://en.wikipedia.org/wiki/ICalendar] streams.
+#
+# The sources are resolved/fetched/parsed into Icalendar::Calendar
+# objects, and passed into the supplied block one by one (as
+# CalendarWrapper objects).  The block can filter the calendars,
+# choosing to remove entire calendars or classes of calendar resources,
+# and/or simply modifying those resources as desired.  Each calendar object
+# has a #source method that contains associated source parameter from the
+# #filter_calendars call (so that you can recognize different calendars and
+# handle them in distinct ways).
+#
+# The method returns an array of Calendar objects representing the filtered
+# result.  If CalFilter::output_stream is not nil, the method will also write
+# the filtered result (as an iCalendar stream) to that output stream before
+# returning.
 def filter_calendars(*sources, &block)
   cals = convert_to_icalendars(sources)
   return cals unless block_given?
@@ -161,19 +286,32 @@ def filter_calendars(*sources, &block)
   new_cals
 end
 
-def convert_to_icalendars(sources)
+def convert_to_icalendars(sources)  # :nodoc:
   sources.inject([]){|accum, source| accum += convert_to_icalendar(source)}
 end
 
-def convert_to_icalendar(source)
-  case source
-  when Icalendar::Calendar
-    [source]
-  when Array
-    source
-  when /^\s*BEGIN:VCALENDAR/m
-    Icalendar.parse(source)
-  else
-    Icalendar.parse(open(source, 'r'))
+def convert_to_icalendar(source)  # :nodoc:
+  icalendars = case source
+               when Icalendar::Calendar
+                 [source]
+               when Array
+                 source
+               when /^\s*BEGIN:VCALENDAR/m
+                 Icalendar.parse(source)
+               else
+                 Icalendar.parse(open(source, 'r'))
+               end
+  attach_source_to_icalendars(source, icalendars)
+  icalendars
+end
+
+def attach_source_to_icalendars(source, icalendars)             
+  icalendars.each do |icalendar|
+    class <<icalendar
+      attr_reader :source
+    end
+    icalendar.instance_variable_set("@source", source)
   end
+  
+  icalendars
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: calfilter
 version: !ruby/object:Gem::Version 
-  version: 1.1.3
+  version: 1.1.4
 platform: ruby
 authors: 
 - Glenn Vanderburg
@@ -30,11 +30,12 @@ cert_chain:
   zrNa6ECLh1VS/pV78rYbAO1ZXsg3l7bY
   -----END CERTIFICATE-----
 
-date: 2008-05-04 00:00:00 -05:00
+date: 2008-08-06 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: icalendar
+  type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
@@ -42,7 +43,17 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-description: "calfilter is a small library to assist in writing filtering programs for icalendar files or streams.  It can be used for various purposes, including:  * removing items from icalendar feeds that are not interesting to you * removing private information from your own calendar before publishing it to others * reformatting a provided calendar to highlight particular information"
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.7.0
+    version: 
+description: "calfilter is a small library to assist in writing filtering programs for icalendar files or streams.  It can be used for various purposes, including:  * removing items from icalendar feeds that are not interesting to you * removing private information from your own calendar before publishing it to others * reformatting a provided calendar to highlight particular information  A calfilter script does most of its work using the filter_calendars[link:files/lib/calfilter_rb.html] method."
 email: 
 - glenn@thinkrelevance.com
 executables: []
@@ -92,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: thinkrelevance
-rubygems_version: 1.0.1
+rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
 summary: calfilter is a small library to assist in writing filtering programs for icalendar files or streams