[Jifty-commit] r4083 - in jifty/trunk: lib/Jifty

[jifty-commit at lists.jifty.org]

Author: sterling
Date: Tue Sep 11 16:04:38 2007
New Revision: 4083

Modified:
   jifty/trunk/   (props changed)
   jifty/trunk/lib/Jifty/DateTime.pm

Log:
 r11951 at dynpc145:  andrew | 2007-09-11 15:04:01 -0500
 Clean up the Pod, added a Synopsis, added a Why? section, added code comments, and some code tidying.


Modified: jifty/trunk/lib/Jifty/DateTime.pm
==============================================================================
--- jifty/trunk/lib/Jifty/DateTime.pm	(original)
+++ jifty/trunk/lib/Jifty/DateTime.pm	Tue Sep 11 16:04:38 2007
@@ -7,6 +7,18 @@
 
 Jifty::DateTime - a DateTime subclass that knows about Jifty users
 
+=head1 SYNOPSIS
+
+  use Jifty::DateTime;
+  
+  # Get the current date and time
+  my $dt = Jifty::DateTime->now;
+  
+  # Print out the pretty date (i.e., today, tomorrow, yesterday, or 2007-09-11)
+  Jifty->web->out( $dt->friendly_date );
+
+  # Better date parsing
+  my $dt_from_human = Jifty::DateTime->new_from_string("next Saturday");
 
 =head1 DESCRIPTION
 
@@ -14,6 +26,8 @@
 without timezone. This class loads and parses dates and sets them
 into the proper timezone.
 
+To use this DateTime class to it's fullest ability, you'll need to add a C<time_zone> method to your application's user object class. This is the class returned by L<Jifty::CurrentUser/user_object>. It must return a value valid for using as an argument to L<DateTime>'s C<set_time_zone()> method.
+
 =cut
 
 BEGIN {
@@ -27,7 +41,6 @@
 
 use base qw(Jifty::Object DateTime);
 
-
 =head2 new ARGS
 
 See L<DateTime/new>. If we get what appears to be a date, then we
@@ -42,7 +55,12 @@
     my %args  = (@_);
     my $self  = $class->SUPER::new(%args);
 
+    # XXX What if they really mean midnight offset by time zone?
+
+    # Do not bother with time zones unless time is used, we assume that
+    # 00:00:00 implies that no time is used
     if ($self->hour || $self->minute || $self->second) {
+
         # Unless the user has explicitly said they want a floating time,
         # we want to convert to the end-user's timezone.  This is
         # complicated by the fact that DateTime auto-appends
@@ -51,6 +69,8 @@
             $self->set_time_zone( $tz );
         }
     }
+
+    # No time, just use the floating time zone
     else {
         $self->set_time_zone("floating");
     }
@@ -60,15 +80,21 @@
 
 =head2 current_user_has_timezone
 
-Return timezone if the current user has it
+Return timezone if the current user has one. This is determined by checking to see if the current user has a user object. If it has a user object, then it checks to see if that user object has a C<time_zone> method and uses that to determine the value.
 
 =cut
 
 sub current_user_has_timezone {
     my $self = shift;
     $self->_get_current_user();
+
+    # Can't continue if we have no notion of a user_object
     return unless $self->current_user->can('user_object');
+
+    # Can't continue unless the user object is defined
     my $user_obj = $self->current_user->user_object or return;
+
+    # Check for a time_zone method and then use it if it exists
     my $f = $user_obj->can('time_zone') or return;
     return $f->($user_obj);
 }
@@ -80,6 +106,8 @@
 it in the floating timezone, otherwise, set it to the current user's
 timezone.
 
+As of this writing, this uses L<Date::Manip> along with some internal hacks to alter the way L<Date::Manip> normally interprets week day names. This may change in the future.
+
 =cut
 
 sub new_from_string {
@@ -87,6 +115,7 @@
     my $string = shift;
     my $now;
 
+    # Hack to use Date::Manip to flexibly scan dates from strings
     {
         # Date::Manip interprets days of the week (eg, ''monday'') as
         # days within the *current* week. Detect these and prepend
@@ -102,13 +131,18 @@
         Date::Manip::Date_Init("TZ=GMT");
         $now = Date::Manip::UnixDate( $string, "%o" );
     }
+
+    # Stop here if Date::Manip couldn't figure it out
     return undef unless $now;
+
+    # Build a DateTime object from the Date::Manip value and setup the TZ
     my $self = $class->from_epoch( epoch => $now, time_zone => 'gmt' );
     if (my $tz = $self->current_user_has_timezone) {
         $self->set_time_zone("floating")
             unless ( $self->hour or $self->minute or $self->second );
         $self->set_time_zone( $tz );
     }
+
     return $self;
 }
 
@@ -124,24 +158,48 @@
     my $self = shift;
     my $ymd = $self->ymd;
 
+    # Use the current user's time zone on the date
     my $tz = $self->current_user_has_timezone || $self->time_zone;
     my $rel = DateTime->now( time_zone => $tz );
 
+    # Is it today?
     if ($ymd eq $rel->ymd) {
         return "today";
     }
     
+    # Is it yesterday?
     my $yesterday = $rel->clone->subtract(days => 1);
     if ($ymd eq $yesterday->ymd) {
         return "yesterday";
     }
     
+    # Is it tomorrow?
     my $tomorrow = $rel->clone->add(days => 1);
     if ($ymd eq $tomorrow->ymd) {
         return "tomorrow";
     }
     
+    # None of the above, just spit out the date
     return $ymd;
 }
 
+=head1 WHY?
+
+There are other ways to do some of these things and some of the decisions here may seem arbitrary, particularly if you read the code. They are.
+
+These things are valuable to applications built by Best Practical Solutions, so it's here. If you disagree with the policy or need to do it differently, then you probably need to implement something yourself using a DateTime::Format::* class or your own code. 
+
+Parts may be cleaned up and the API cleared up a bit more in the future.
+
+=head1 SEE ALSO
+
+L<DateTime>, L<DateTime::TimeZone>, L<Jifty::CurrentUser>
+
+=head1 LICENSE
+
+Jifty is Copyright 2005-2007 Best Practical Solutions, LLC.
+Jifty is distributed under the same terms as Perl itself.
+
+=cut
+
 1;