facets 1.1.0 → 1.2.0

data/lib/facets/more/times.rb

@@ -0,0 +1,327 @@
+#--
+# Time In English
+#
+# Copyright (c) 2005 Thomas Sawyer
+# Copyright (c) 2004 Rich Kilmer
+#
+# Ruby License
+#
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.
+#
+# ===========================================================================
+#  REVISION HISTORY
+# ===========================================================================
+#  * 2005.04.28 trans  Ported from Rich Kilmer's lib.
+# ===========================================================================
+#
+# TODO Extra methods
+# Add in_* methods, like in_days, in_hours, etc.
+#
+# CREDIT
+# Credit goes to Richard Kilmer for the orignal work and
+# Alexander Kellett for suggesting them for Nano (then Facets).
+#
+#++
+
+require 'facet/time/change'
+
+#:title: Time In English
+#
+# Plain-English convenience methods for dealing with dates and times.
+#
+
+class Numeric
+
+  # Enables the use of time calculations and declarations, 
+  # like 45.minutes + 2.hours + 4.years. The base unit for
+  # all of these Numeric time methods is seconds.
+  def seconds ; self ; end
+  alias_method :second, :seconds
+  #def as_seconds ; self ; end
+
+  # Converts minutes into seconds.
+  def minutes ; self * 60 ; end
+  alias_method :minute, :minutes
+  #def as_minutes ; self.to_f / 60 ; end
+
+  # Converts hours into seconds.
+  def hours ; self * 60.minutes ; end
+  alias_method :hour, :hours
+  #def as_hours ; self / 60.minutes ; end
+
+  # Converts days into seconds.
+  def days ; self * 24.hours ; end
+  alias_method :day, :days
+  #def as_days ; self / 24.hours ; end
+
+  # Converts weeks into seconds.
+  def weeks ; self * 7.days ; end
+  alias_method :week, :weeks
+  #def as_weeks ; self / 7.days ; end
+
+  # Converts fortnights into seconds.
+  # (A fortnight is 2 weeks)
+  def fortnights ; self * 2.weeks ; end
+  alias_method :fortnight, :fortnights
+  #def as_fortnights ; self / 2.weeks ; end
+
+  # Converts months into seconds.
+  # WARNING: This is not exact as it assumes 30 days to a month.
+  def months ; self * 30.days ; end
+  alias_method :month, :months
+  #def as_months ; self / 30.days ; end
+
+  # Converts years into seconds.
+  def years ; self * 365.days ; end
+  alias_method :year, :years
+  #def as_years ; self / 365.days ; end
+
+  # Calculates time _before_ a given time. Default time is now.
+  # Reads best with arguments: 10.days.before( Time.now - 1.day )
+  def before(time = ::Time.now)
+    time - self
+  end
+  alias_method :until, :before   # Reads best with argument: 10.minutes.until(time)
+  alias_method :ago, :before     # Reads best without arguments: 10.minutes.ago
+
+  # Calculates time _after_ a given time. Default time is now.
+  # Reads best with argument: 10.minutes.after(time)
+  def after(time = ::Time.now)
+    time + self
+  end
+  alias_method :since, :after    # Reads best with argument: 10.minutes.since(time)
+  alias_method :from_now, :after # Reads best without arguments: 10.minutes.from_now
+  alias_method :later, :after    # Reads best without arguments: 10.minutes.later
+
+end
+
+class Time
+
+  NEVER = Time.mktime(2038)
+  ZERO = Time.mktime(1972)
+
+  # Seconds since midnight: Time.now.seconds_since_midnight
+  def seconds_since_midnight
+    self.hour.hours + self.min.minutes + self.sec + (self.usec/1.0e+6)
+  end
+
+  # Returns a new Time representing the time a number of seconds ago.
+  # Do not use this method in combination with x.months, use months_ago instead!
+  def ago(seconds)
+    # This is basically a wrapper around the Numeric extension.
+    #seconds.until(self)
+    self - seconds
+  end
+
+  # Returns a new Time representing the time a number of seconds
+  # since the instance time. Do not use this method in combination
+  # with x.months, use months_since instead!
+  def since(seconds)
+    # This is basically a wrapper around the Numeric extension.
+    #seconds.since(self)
+    self + seconds
+  end
+  alias_method :in, :since
+
+  # Returns a new Time representing the time a number of specified
+  # months ago.
+  def months_ago(months)
+    if months >= self.month 
+      change(:year => self.year - 1, :month => 12).months_ago(months - self.month)
+    else
+      change(:year => self.year, :month => self.month - months)
+    end
+  end
+
+  def months_since(months)
+    if months + self.month > 12
+      change(:year => self.year + 1, :month => 1).months_since(months - (self.month == 1 ? 12 : (self.month + 1)))
+    else
+      change(:year => self.year, :month => self.month + months)
+    end
+  end
+
+  # Returns a new Time representing the time a number of specified
+  # years ago.
+  def years_ago(years)
+    change(:year => self.year - years)
+  end
+
+  def years_since(years)
+    change(:year => self.year + years)
+  end
+
+  # Short-hand for months_ago(1)
+  def last_year
+    years_since(1)
+  end
+
+  # Short-hand for months_since(1)
+  def next_year
+    years_since(1)
+  end
+
+  # Short-hand for months_ago(1)
+  def last_month
+    months_ago(1)
+  end
+
+  # Short-hand for months_since(1)
+  def next_month
+    months_since(1)
+  end
+
+  # Returns a new Time representing the "start" of this week (Monday, 0:00)
+  def beginning_of_week
+    (self - self.wday.days).midnight + 1.day
+  end
+  alias :monday :beginning_of_week
+  alias :at_beginning_of_week :beginning_of_week
+
+  # Returns a new Time representing the start of the given
+  # day in next week (default is Monday).
+  def next_week(day = :monday)
+    days_into_week = { :monday => 0, :tuesday => 1, :wednesday => 2,
+                       :thursday => 3, :friday => 4, :saturday => 5,
+                       :sunday => 6 }
+    since(1.week).beginning_of_week.since(days_into_week[day].day).change(:hour => 0)
+  end
+
+  # Set time to end of day
+  #def end_of_day
+  #  return Time.mktime(year, month, day, 23, 59, 59, 999)
+  #end
+
+  # Returns a new Time representing the start of the day (0:00)
+  def beginning_of_day
+    self - self.seconds_since_midnight
+  end
+  alias :midnight :beginning_of_day
+  alias :at_midnight :beginning_of_day
+  alias :at_beginning_of_day :beginning_of_day
+  alias :start_of_day :beginning_of_day
+
+  # Returns a new Time representing the start of the month
+  # (1st of the month, 0:00)
+  def beginning_of_month
+    #self - ((self.mday-1).days + self.seconds_since_midnight)
+    change(:mday => 1,:hour => 0, :min => 0, :sec => 0, :usec => 0)
+  end
+  alias_method :at_beginning_of_month, :beginning_of_month
+
+  # Returns  a new Time representing the start of the year (1st of january, 0:00)
+  def beginning_of_year
+    change(:month => 1,:mday => 1,:hour => 0, :min => 0, :sec => 0, :usec => 0)
+  end
+  alias :at_beginning_of_year :beginning_of_year
+
+  # Convenience method which returns a new Time representing
+  # the time 1 day ago
+  def yesterday
+    self.ago(1.day)
+  end
+
+  # Convenience method which returns a new Time representing
+  # the time 1 day since the instance time
+  def tomorrow
+    self.since(1.day)
+  end
+
+  # Returns a new time at start of day
+  def to_start_of_day
+    return Time.mktime(year, month, day, 0, 0, 0, 0)
+  end
+
+  # Rrturns a new time at end of day
+  def to_end_of_day
+    return Time.mktime(year, month, day, 23, 59, 59, 999)
+  end
+
+  # Returns true only if day of time is included in the
+  # range (stime..etime). Only year days are checked.
+  def in_day_range?(stime=ZERO, etime=NEVER)
+    if (etime <= stime)
+      warn "invalid end time (#{etime} < #{stime})" if $DEBUG
+      etime = NEVER
+    end
+
+    stime = stime.to_start_of_day
+    etime = etime.to_end_of_day
+
+    return (stime..etime).include?(time)
+  end
+end
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+=begin testing
+
+require 'test/unit'
+#require 'mega/multiplier'
+
+class TC_Numeric < Test::Unit::TestCase
+
+  #def test_micro_seconds
+  #  assert_equal( 0.000001, 1.microsecond )
+  #end
+
+  #def test_milli_seconds
+  #  assert_equal( 0.001, 1.millisecond )
+  #end
+
+  def test_seconds
+    assert_equal( 60**0, 1.seconds )
+  end
+
+  def test_minutes
+    assert_equal( 60**1, 1.minutes )
+  end
+
+  def test_hours
+    assert_equal( 60**2, 1.hours )
+  end
+
+  def test_days
+    assert_equal( 24*(60**2), 1.days )
+  end
+
+  def test_weeks
+    assert_equal( 7*24*(60**2), 1.weeks )
+  end
+
+  def test_fortnights
+    assert_equal( 14*24*(60**2), 1.fortnights )
+  end
+
+  def test_months
+    assert_equal( 30*24*(60**2), 1.months )
+  end
+
+  def test_years
+    assert_equal( 365*24*(60**2), 1.years )
+  end
+
+  def test_before
+    t = Time.now
+    assert_equal( t - 1.day, 1.day.before(t) )
+  end
+
+  def test_after
+    t = Time.now
+    assert_equal( t + 1.day, 1.day.after(t) )
+  end
+
+end
+
+=end

data/lib/facets/more/tracepoint.rb

@@ -0,0 +1,183 @@
+#--
+# TracePoint
+#
+# Copyright (c) 2005 Thomas Sawyer
+#
+# Ruby License
+#
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+# ============================================================================
+#  Revision History
+# ============================================================================
+#
+#  2004.05.24  trans  Wrote originally for AOP work.
+#  2005.08.24  trans  Minor modifications to documentation.
+#
+# ============================================================================
+#
+#++
+
+#:title: TracePoint
+#
+# A TracePoint is a Binding with the addition of event information.
+# Among other things, it functions very well as the join-point for
+# Event-based AOP.
+#
+# == Usage
+#
+#   TracePoint.trace { |tp|
+#     puts "#{tp.self.class}\t#{tp.called}\t#{tp.event}\t#{tp.return?}\t#{tp.back == tp.bind}"
+#   }
+#
+#   1 + 1
+#
+# produces
+#
+#   Class   trace   return     true    false
+#   Object          line       false   false
+#   Fixnum  +       c-call     false   false
+#   Fixnum  +       c-return   false   false
+#
+
+require 'facet/binding'
+
+# This is the same as a Binding. Not really needed, but I like consistency :)
+CodePoint = Binding
+
+# You can't subclass Binding, so we delegate (which is better anyway).
+class TracePoint  #< Codepoint
+
+  # -- class ---------------------
+  class << self
+
+    @@active = false
+
+    def active ; @@active ; end
+
+    def active=(x)
+      @@active = x ? true : false
+      unless @@active
+        set_trace_func nil
+      end
+    end
+
+    # Trace execution using a TracePoint.
+    def trace # :yield:
+      if active
+        bb_stack = []
+        set_trace_func proc{ |e, f, l, m, b, k|
+          #(p e, f, l, m, b, k, @@bb_stack; puts "---") if $DEBUG
+          if ['call','c-call','class'].include?(e)
+            bb_stack << b
+          elsif ['return','c-return','end'].include?(e)
+            bb = bb_stack.pop
+          end
+          b = bb if ! b    # this sucks!
+          tp = TracePoint.new(e,m,b,bb)
+          yield(tp)
+        }
+      end
+    end
+
+  end #class
+
+  # -- instance -------------------
+
+  attr_accessor :event, :binding, :back_binding
+
+  # Until Ruby has a built-in way to get the name of the calling method
+  # that information must be passed into the TracePoint.
+  def initialize( event, method, bind, back_binding=bind )
+    @event = event
+    @method = method
+    @binding = bind
+    @back_binding = back_binding
+  end
+
+  # shorthand for binding
+  def bind ; @binding ; end
+
+  # shorthand for back_binding
+  def back ; @back_binding ; end
+
+  # Delegates "self" to the binding which
+  # in turn delegates the binding object.
+  def self ; @binding.self ; end
+
+  # Returns the name of the event's method.
+  # This could delegate to the binding if Ruby had 
+  # an internal way to retrieve the current method name.
+  def called ; @method ; end
+  alias_method( :method_name, :called )
+  alias_method( :me, :called )
+
+  # delegate to binding
+  #def method_missing(meth, *args, &blk)
+  #  @binding.send(meth, *args, &blk)
+  #end
+
+  ### methods for working with events
+
+  EVENT_MAP = {
+    :all     => ['call', 'c-call', 'return', 'c-return', 'line', 'class', 'end', 'raise'],
+    :before  => ['call', 'c-call'],
+    :after   => ['return', 'c-return'],
+    :call    => ['call'],
+    :return  => ['return'],
+    :ccall   => ['c-call'],
+    :creturn => ['c-return'],
+    :line    => ['line'],
+    :class   => ['class'],
+    :end     => ['end'],
+    :raise   => ['raise']
+  }
+  def event_map(e) ; EVENT_MAP[e] ; end
+
+  # Is the trace point defined or undefined?
+  def event? ; !! @event ; end
+  def eventless? ; ! @event ; end
+
+  # For use in case conditions
+  def ===(e)
+    EVENT_MAP[e].include?(@event)
+  end
+
+  # Creates an <event>? method for each of the above event mappings.
+  EVENT_MAP.each_pair { |m,v|
+    define_method( "#{m}?" ){ v.include?(@event) }
+  }
+
+end
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+# TODO
+
+=begin #test
+
+  # Note: TracePoint will probably prove tricky to test, since
+  # manipulating set_trace_func tends to wreak havoc on errors,
+  # the call stack, and so on.
+
+  TracePoint.active = true
+
+  TracePoint.trace { |tp|
+    puts "#{tp.self.class}\t#{tp.called}\t#{tp.event}\t#{tp.return?}\t#{tp.back == tp.bind}"
+  }
+
+  1 + 1
+
+=end