lib/Time/gmtime.pm

   1 package Time::gmtime;
   2 use strict;
   3 use Time::tm;
   4
   5 BEGIN {
   6     use Exporter   ();
   7     use vars       qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
   8     @ISA         = qw(Exporter Time::tm);
   9     @EXPORT      = qw(gmtime gmctime);
  10     @EXPORT_OK   = qw(
  11                         $tm_sec $tm_min $tm_hour $tm_mday
  12                         $tm_mon $tm_year $tm_wday $tm_yday
  13                         $tm_isdst
  14                     );
  15     %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
  16 }
  17 use vars      @EXPORT_OK;
  18
  19 sub populate (@) {
  20     return unless @_;
  21     my $tmob = Time::tm->new();
  22     @$tmob = (
  23                 $tm_sec, $tm_min, $tm_hour, $tm_mday,
  24                 $tm_mon, $tm_year, $tm_wday, $tm_yday,
  25                 $tm_isdst )
  26             = @_;
  27     return $tmob;
  28 }
  29
  30 sub gmtime (;$)    { populate CORE::gmtime(shift||time)}
  31 sub gmctime (;$)   { scalar   CORE::gmtime(shift||time)}
  32
  33 1;
  34 __END__
  35
  36 =head1 NAME
  37
  38 Time::gmtime - by-name interface to Perl's built-in gmtime() function
  39
  40 =head1 SYNOPSIS
  41
  42  use Time::gmtime;
  43  $gm = gmtime();
  44  printf "The day in Greenwich is %s\n",
  45     (qw(Sun Mon Tue Wed Thu Fri Sat Sun))[ gm->wday() ];
  46
  47  use Time::gmtime w(:FIELDS;
  48  printf "The day in Greenwich is %s\n",
  49     (qw(Sun Mon Tue Wed Thu Fri Sat Sun))[ gm_wday() ];
  50
  51  $now = gmctime();
  52
  53  use Time::gmtime;
  54  use File::stat;
  55  $date_string = gmctime(stat($file)->mtime);
  56
  57 =head1 DESCRIPTION
  58
  59 This module's default exports override the core gmtime() function,
  60 replacing it with a version that returns "Time::tm" objects.
  61 This object has methods that return the similarly named structure field
  62 name from the C's tm structure from F<time.h>; namely sec, min, hour,
  63 mday, mon, year, wday, yday, and isdst.
  64
  65 You may also import all the structure fields directly into your namespace
  66 as regular variables using the :FIELDS import tag.  (Note that this
  67 still overrides your core functions.)  Access these fields as variables
  68 named with a preceding C<tm_> in front their method names.  Thus,
  69 C<$tm_obj-E<gt>mday()> corresponds to $tm_mday if you import the fields.
  70
  71 The gmctime() funtion provides a way of getting at the
  72 scalar sense of the original CORE::gmtime() function.
  73
  74 To access this functionality without the core overrides,
  75 pass the C<use> an empty import list, and then access
  76 function functions with their full qualified names.
  77 On the other hand, the built-ins are still available
  78 via the C<CORE::> pseudo-package.
  79
  80 =head1 NOTE
  81
  82 While this class is currently implemented using the Class::Template
  83 module to build a struct-like class, you shouldn't rely upon this.
  84
  85 =head1 AUTHOR
  86
  87 Tom Christiansen