portera 0.1.3

data/CHANGELOG.markdown

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.3 / 2012-02-21
+
+- Draft simple presenter
+
+## 0.1.2 / 2012-02-21
+
+- Cache availability results in `Participant#available_for?`
+
+## 0.1.1 / 2012-02-20
+
+- Re-release under Portera top-level namespace
+
+## 0.1.0 / 2012-02-20
+
+- Initial release
+- Note coalescing timeslot ranges does not quite work
+- Note `Schedule.view` has not been implemented yet

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/README.rdoc

@@ -0,0 +1,104 @@
+= portera
+
+== DESCRIPTION:
+
+An application for determining the best time to conduct meetings.
+
+Adapted from Gordon Thiesfeld's {rmu-scheduler}[https://github.com/vertiginous/rmu-scheduler]
+
+
+== SYNOPSIS:
+
+==== Basic usage
+
+    schedule = Portera::Event.new do 
+    
+      week_of       Date.civil(2010,11,21)
+      duration      90
+
+    end
+    
+    schedule.participants << 
+      Portera::Participant.new('Malcolm Reynolds').available do
+        on(:monday,    :from => "15:00", :to => "18:00" )
+        on(:wednesday, :from => "20:00", :to => "23:00" )
+        on(:friday,    :from => "16:00", :to => "19:00" )
+      end
+
+    schedule.participants <<
+      Portera::Participant.new('Hoban Washburne').available do
+        on(:monday,    :from => "15:00", :to => "18:00" )
+        on(:wednesday, :from => "20:00", :to => "23:00" )
+        on(:thursday,  :from => "15:00", :to => "18:30" )
+      end
+
+    schedule.participants <<
+      Portera::Participant.new('Jayne Cobb').available do
+        weekdays(:from => "15:00", :to => "18:00" )
+      end
+
+    schedule.participants <<
+      Portera::Participant.new('Zoe Washburne').available do
+        on([:monday, :tuesday, :thursday], :from => "15:00", :to => "18:00" )
+      end
+
+    schedule.participants <<
+      Portera::Participant.new('Inara Serra').available do
+        on([:monday, :tuesday, :thursday])
+      end
+       
+    puts Portera.view(:simple, schedule)
+
+==== Output
+
+    Monday 15:00-18:00 +00:00
+      Hoban Washburne
+      Inara Serra
+      Jayne Cobb
+      Malcolm Reynolds
+      Zoe Washburne
+    Thursday 15:00-18:00 +00:00
+      Hoban Washburne
+      Inara Serra
+      Jayne Cobb
+      Zoe Washburne
+    Tuesday 15:00-18:00 +00:00
+      Inara Serra
+      Jayne Cobb
+      Zoe Washburne
+
+    
+== REQUIREMENTS:
+
+* {tempr}[https://github.com/ericgj/tempr]
+* {tilt}[https://github.com/rtomayko/tilt]
+* {erubis}[http://www.kuwata-lab.com/erubis/]
+
+== INSTALL:
+
+* git clone 
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2012 Eric Gjertsen
+
+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/lib/portera/event.rb

@@ -0,0 +1,145 @@
+require 'set'
+
+module Portera
+
+  # Event model - see README for usage
+  class Event
+    attr_accessor :name, :duration, :range
+    def participants; @participants ||= []; end
+    
+    # Define events using a block passed to the constructor, e.g.
+    #     
+    #     Event.new do
+    #       duration 60
+    #       week_of  Date.civil(2012,2,13)
+    #     end
+    def initialize(name=nil,&proc)
+      self.name = name
+      Builder.new(self).instance_eval(&proc)
+    end
+    
+    # iterate over each timeslot in range (week),
+    # gathering participant availability for each slot
+    # parameters:
+    #    [+interval+]:  duration of timeslots in minutes (default 15)
+    #    [+all+]:       return all timeslots even if no participants available (default false)
+    def availability(params={})
+      interval = params.fetch(:interval,15)
+      keep_all = params.fetch(:all,false)
+      iterate(interval).each_with_object(TimeslotEnum.new) do |slot, accum|
+        avails = []
+        self.participants.each do |person|
+          if person.available_for?(self, slot)
+            avails << person
+          end
+        end
+        if !avails.empty? || keep_all
+          accum << Timeslot.new(slot, ::Set.new(avails.sort_by(&:name)))
+        end
+      end
+    end
+    
+    def coalesced(params={})
+      availability(params).coalesced
+    end
+    
+    private
+    
+    def iterate(i)
+      self.range.dup.extend(Tempr::DateTimeRange).each_minute(i,0,self.duration)
+    end
+    
+    # Internal builder class for events
+    class Builder
+
+      def initialize(event)
+        @event = event
+      end
+
+      # duration in minutes of the proposed event
+      def duration(minutes)
+        @event.duration = minutes
+      end
+
+      # range of possible dates for the proposed event
+      # for a weekly event, use `week_of` instead of explicit date range
+      def range(dates)
+        @event.range = dates
+      end
+      
+      # first date of week for the proposed event
+      def week_of(date)
+        range date...(date+7)
+      end
+
+    end
+
+  end
+  
+  class Timeslot < Struct.new(:range, :participants)
+  
+    # temporary, TODO use views/presenters instead
+    def to_s
+      ["#{self.range}",
+       self.participants.empty? ? nil : " #{self.participants.to_a.join("\n ")}"
+      ].compact.join("\n")
+    end
+    
+  end
+  
+  class TimeslotEnum
+    include Enumerable
+    
+    def <<(timeslot)
+      timeslots << timeslot
+      self
+    end
+    
+    def each(&b)
+      timeslots.each(&b)
+    end
+        
+    # join intersecting timeslots with identical participants
+    # note that this returns a new TimeslotEnum, so that you can call
+    #  [+enum.best+]            all timeslots sorted by highest participation
+    #  [+enum.coalesced.best+]  joined timeslots sorted by highest participation
+    #
+    # Note assumes timeslots are appended in ascending order by range.begin
+    # TODO could use some refactoring
+    def coalesced
+      accum = self.class.new
+      inject(nil) do |last_slot, this_slot|
+        if last_slot
+          rng       = this_slot.range
+          last_rng  = last_slot.range
+          if (rng.intersects?(last_rng) || rng.succeeds?(last_rng)) &&
+             (this_slot.participants ==  last_slot.participants)
+            Timeslot.new(last_rng.begin...rng.end, 
+                         this_slot.participants)
+          else
+            accum << last_slot
+            this_slot
+          end
+        else
+          this_slot
+        end
+      end
+      accum
+    end
+
+    # sort timeslot availability by 
+    # 1. most participants available
+    # 2. timeslot date/time
+    def best
+      sort do |a, b|
+        comp = b.participants.count <=> a.participants.count
+        comp.zero? ? (a.range.begin <=> b.range.begin) : comp
+      end
+    end
+    
+    private
+    def timeslots; @timeslots ||= []; end
+    
+  end
+    
+end

data/lib/portera/participant.rb

@@ -0,0 +1,157 @@
+
+module Portera
+
+  # Participant model - for use with event(s). See README for usage.
+  class Participant < Struct.new(:name, :email)
+  
+    # List of availability rules
+    def availables; @availables ||= []; end
+    
+    # Define availability rule passing a block, e.g.
+    #
+    #    participant.available('+09:00') do
+    #      weekdays :from => '11:00am', :to => '3:00pm'
+    #      on [0,6] :from => '5:00pm', :to => '6:30pm'
+    #    end
+    def available(utc_offset=nil, &sched_proc)
+      Builder.new(self.availables,utc_offset).instance_eval(&sched_proc)
+      self
+    end
+    
+    # For given event range, 
+    # evaluate if the given timeslot fits within any of the participant's available times
+    #
+    # Note that range-availability arrays are cached here per event
+    # Possibly caching should be moved down into Tempr, e.g.
+    #    avail.for_range(event.range).all   #=> caches within Tempr::SubRangeIterator
+    def available_for?(event, slot)
+      availables.any? do |avail|
+        cache[event.range] ||= avail.for_range(event.range).to_a
+        cache[event.range].any? {|free| free.subsume?(slot)}
+      end
+    end
+    
+    # Display participant as valid email `name <address>`
+    def to_s
+      [self.name  ? "#{self.name}"    : nil,
+       self.email ? "<#{self.email}>" : nil
+      ].compact.join(" ")
+    end
+    
+    private
+    
+    def cache; @cache ||= {}; end
+    
+    # Internal builder for participant availability
+    class Builder
+      
+      Days = { :sunday => 0,
+               :monday => 1,
+               :tuesday => 2,
+               :wednesday => 3,
+               :thursday => 4,
+               :friday => 5,
+               :saturday => 6,
+               :sun => 0,
+               :mon => 1,
+               :tue => 2,
+               :wed => 3,
+               :thu => 4,
+               :fri => 5,
+               :sat => 6,
+               :Sunday => 0,
+               :Monday => 1,
+               :Tuesday => 2,
+               :Wednesday => 3,
+               :Thursday => 4,
+               :Friday => 5,
+               :Saturday => 6,
+               :Sun => 0,
+               :Mon => 1,
+               :Tue => 2,
+               :Wed => 3,
+               :Thu => 4,
+               :Fri => 5,
+               :Sat => 6               
+             }
+             
+      def initialize(collect,utc_offset=nil)
+        @collect = collect
+        @utc_offset = utc_offset || 0
+      end
+      
+      # Example:
+      #   on [2,3,5], :from => '9:00am', :to => '9:30am', :utc_offset => '-05:00'
+      #
+      # Note that if not specified, timezone is 
+      # 1. the offset passed into the constructor, or
+      # 2. UTC, otherwise -- _not the process-local timezone_!
+      def on(days, time={})
+        @collect << Availability.new( Array(days).map {|d| to_weekday(d)}, 
+                                      time[:from], 
+                                      time[:to], 
+                                      time[:utc_offset] || @utc_offset
+                                    )
+      end
+      
+      # sugar for `on( [1,2,3,4,5], time)`
+      def weekdays(time={})
+        on( [1,2,3,4,5], time)
+      end
+      
+      # sugar for `on( [], time)`
+      def any_day(time={})
+        on( [], time)
+      end
+      
+      private
+
+      def to_weekday(day)
+        Days[day] || day
+      end
+      
+    end
+    
+    # This wrapper stores the parameters for participant availability rules
+    # 
+    # [+days+]       array of wday numbers, or empty array for all days
+    # [+from+]       start time (parseable time string)
+    # [+to+]         end time (parseable time string)
+    # [+utc_offset+] offset string or seconds from utc, if not specified assumes process-local offset
+    #
+    # An iterator is returned when you call `for_range`
+    class Availability < Struct.new(:days, :from, :to, :utc_offset)
+      
+      def initialize(*args)
+        super
+        self.days ||= []
+      end
+      
+      def for_range(range)
+        apply_time_range(for_day_range(range))
+      end
+      
+      def for_day_range(range)
+        r = range.extend(Tempr::DateTimeRange)
+        if self.days.empty?
+          r.each_days_of_week
+        else
+          r.each_days_of_week(*self.days)
+        end
+      end
+      
+      private
+      
+      def apply_time_range(expr)
+        if self.from && self.to
+          expr.between_times(self.from, self.to, self.utc_offset)
+        else
+          expr
+        end
+      end
+      
+    end
+    
+  end
+
+end

data/lib/portera/presenters/simple.rb

@@ -0,0 +1,88 @@
+require 'erubis'
+require 'tilt'
+
+module Portera
+
+  #TODO: delegation to event; extract base class
+  module Presenters
+  
+    class Simple
+      include Enumerable
+      
+      attr_accessor :template, :view_path
+      def template; @template ||= 'simple'; end
+      def view_path
+        @view_path ||=  File.expand_path('../views', File.dirname(__FILE__))
+      end
+      
+      def initialize(e)
+        self.event = e
+      end
+      
+      def name
+        event.name
+      end
+      
+      def description
+        present_event(event)
+      end
+      
+      def best
+        event.coalesced.best
+      end
+      
+      def each
+        best.each do |timeslot|
+          yield present_time_range(timeslot.range),
+                timeslot.participants.map {|p| present_participant(p)}
+        end
+      end
+      
+      # shortcut for typical case
+      def minimum_participants(min=2)
+        select { |timeslot, participants|
+          participants.count >= min
+        }
+      end
+      
+      def render
+        Tilt.new(Dir.glob(File.join(view_path, template + '.*')).first)
+          .render(self)
+      end
+      
+      private
+      attr_accessor :event
+      
+      def present_event(e)
+         "best times #{present_date_range(e.range)} (#{e.duration} mins)"
+      end
+      
+      def present_date_range(r)
+        if r.end - r.begin == 7
+          "week of #{present_date(r.begin)}"
+        else
+          "between #{present_date(r.begin)} and #{present_date(r.end-1)}"
+        end
+      end
+      
+      def present_time_range(r)
+        "#{present_time(r.begin)} - #{present_time(r.end)}"
+      end
+      
+      def present_date(d)
+        d.strftime("%a %-d %b")
+      end
+      
+      def present_time(t)
+        t.getutc.strftime("%l:%M%P %Z")
+      end
+      
+      def present_participant(p)
+        p.to_s
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/portera/presenters.rb

@@ -0,0 +1,15 @@
+module Portera
+
+  def self.view(type, *args)
+    Presenters.get(type).new(*args).render
+  end
+  
+  module Presenters
+    
+    def self.get(type)
+      self.const_get(type.to_s.capitalize)
+    end
+  
+  end
+
+end

data/lib/portera/version.rb

@@ -0,0 +1,8 @@
+module Portera
+  module Version
+    MAJOR  = 0
+    MINOR  = 1
+    TINY   = 3
+    STRING = "#{MAJOR}.#{MINOR}.#{TINY}"
+  end
+end

data/lib/portera/views/simple.erb

@@ -0,0 +1,9 @@
+<%= name %>
+<%= description %> 
+------------------------------
+<% minimum_participants(2).each do |slot, participants| -%>
+<%= slot %>
+  <% participants.each do |p| -%>
+  <%= p %>
+  <% end -%>
+<% end -%>    

data/lib/portera.rb

@@ -0,0 +1,13 @@
+require 'tempr'
+
+%w[ portera/version
+    portera/event
+    portera/participant
+    portera/presenters
+  ].each do |f|
+      require File.expand_path(f, File.dirname(__FILE__))
+    end
+
+Dir[File.expand_path('portera/presenters/*', File.dirname(__FILE__))].each do |f|
+  require f
+end

data/test/acceptance.rb

@@ -0,0 +1,65 @@
+require File.expand_path('test_helper',File.dirname(__FILE__))
+
+describe 'simple schedule' do
+
+  let(:schedule) do 
+    schedule = Portera::Event.new("Meeting on Frobartz project") do 
+      week_of       Date.civil(2010,11,21)
+      duration      90
+    end
+  end
+    
+  let(:malcolm) do
+    Portera::Participant.new('Malcolm Reynolds').available do
+      on(:Mon,    :from => "15:00", :to => "18:00" )
+      on(:Wed,    :from => "20:00", :to => "23:00" )
+      on(:Fri,    :from => "16:00", :to => "19:00" )
+    end
+  end
+  
+  let(:hoban) do
+    Portera::Participant.new('Hoban Washburne').available do
+      on(:monday,    :from => "15:00", :to => "18:00" )
+      on(:wednesday, :from => "20:00", :to => "23:00" )
+      on(:thursday,  :from => "15:00", :to => "18:30" )
+    end
+  end
+  
+  let(:jayne) do
+    Portera::Participant.new('Jayne Cobb').available do
+      weekdays(:from => "15:00", :to => "18:00" )
+    end
+  end
+  
+  let(:zoe) do
+    Portera::Participant.new('Zoe Washburne').available do
+      on([1, 2, 4], :from => "15:00", :to => "18:00" )
+    end
+  end
+  
+  let(:inara) do
+    Portera::Participant.new('Inara Serra').available do
+      on([:Monday, :tue, :Thu])
+    end
+  end
+  
+  before do
+    schedule.participants << malcolm << hoban << jayne << zoe << inara
+  end
+  
+  it 'should return best timeslots' do
+    puts
+    puts schedule.availability.best
+  end
+  
+  it 'should return best with coalesced timeslots' do
+    puts
+    puts schedule.coalesced.best
+  end
+  
+  it 'should display simple report' do
+    puts
+    puts Portera.view(:simple, schedule)
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require File.expand_path('../lib/portera', File.dirname(__FILE__))
+
+gem 'minitest'
+require 'minitest/spec'
+MiniTest::Unit.autorun

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: portera
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+  prerelease: 
+platform: ruby
+authors:
+- Eric Gjertsen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-24 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tempr
+  requirement: &10133680 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.1.4
+  type: :runtime
+  prerelease: false
+  version_requirements: *10133680
+- !ruby/object:Gem::Dependency
+  name: erubis
+  requirement: &10133300 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *10133300
+- !ruby/object:Gem::Dependency
+  name: tilt
+  requirement: &10132840 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *10132840
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &10132420 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *10132420
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &10132000 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *10132000
+description: ''
+email:
+- ericgj72@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.markdown
+- Gemfile
+- README.rdoc
+- Rakefile
+- lib/portera.rb
+- lib/portera/event.rb
+- lib/portera/participant.rb
+- lib/portera/presenters.rb
+- lib/portera/presenters/simple.rb
+- lib/portera/version.rb
+- lib/portera/views/simple.erb
+- test/acceptance.rb
+- test/test_helper.rb
+homepage: http://github.com/ericgj/portera
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: portera
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Group event coordination
+test_files: []