home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / perl / scripts-osu / ptime.shar / README < prev   
Encoding:
Text File  |  1991-02-25  |  4.6 KB  |  125 lines
  1. README file for the ptime.pl perl library
  2. =========================================
  3. Author: Jeff Kellem <composer@chem.bu.edu>
  4. Last Date Modified: 21 Feb 1991
  5. Version: 0.8a (first release)
  6.  
  7. [ Note: This was quickly thrown together to provide some docs.  Just
  8.         look at the code for now.. ;-) ]
  9.  
  10. This is the ptime.pl library, a way of formatting date/time info inside
  11. perl programs.  The formatting characters were based on the versions of
  12. the unix date command that support +FORMAT for outputting the date in a
  13. user-specified format.
  14.  
  15. A friend of mine wanted something that would accept the date +FORMAT
  16. formatting characters to output the current date/time; an OS upgrade
  17. replaced a version of date that used the +FORMAT stuff with one that
  18. didn't.  That's how this started...
  19.  
  20. There's a quick replacement of the date command supporting the +FORMAT
  21. stuff included.  Look in ./date for where to set a default timezone to
  22. use if the TZ environment variable is not set.  It's currently set to
  23. EST5EDT; that's the zone I live in.  :) The `-u' switch to date will
  24. display in GMT.  You can change the format to display the date/time in
  25. via the '+FORMAT' switch, where FORMAT is made up of %-escape sequences
  26. that the &'ptime routine described below accepts.  [Also, look at the
  27. ptime.pl source.]  I'll include a man page (wrapped around date) in a
  28. following release.
  29.  
  30. The special format %-escape sequences are:
  31.       ESCAPE    REPLACED BY 
  32.     %n    newline     
  33.     %t    tab
  34.     %a    abbreviated weekday name (Sun to Sat)
  35.     %A    full weekday name
  36.     %b    abbrev. month name (Jan to Dec)
  37.     %h    abbrev. month name (Jan to Dec)
  38.     %B    full month name
  39.     %d    day of month (01 to 31)
  40.     %e    day of month ( 1 to 31) [single digits preceded by a space]
  41.     %m    month (01 to 12)
  42.     %D    mm/dd/yy
  43.     %H    hour (00 to 23)
  44.     %I    hour (01 to 12)
  45.     %M    minutes (00 to 59)
  46.     %S    seconds (00 to 59)
  47.     %p    AM or PM
  48.     %j    day of year (001 to 366)
  49.     %w    day of week (Sunday == 0)
  50.     %r    hh:mm:ss [AP]M
  51.     %R    hh:mm
  52.     %T    hh:mm:ss
  53.     %y    year (last 2 digits)
  54.     %Y    year (4 digits, 19xx, 20xx)
  55.     %Z    timezone
  56.     %%    a single `%'
  57.  
  58. The user accessible routines in the ptime.pl perl library are:
  59.  
  60.     &'ptime($format, $time);
  61.     &'zonetime($time);
  62.     &'ctime($time);
  63.  
  64. &'ptime($format, $time);
  65. &'ptime('', $time);
  66. &'ptime($format);
  67. &'ptime;
  68.  
  69. Returns the date/time specified via $time in number of seconds from the
  70. "beginning of time" formatted as specified by $format.  If $format is
  71. null or not specified, $ptime'default_format ('%a %h %d %T %Z %Y') is
  72. used.  This is the same as the ctime(3) format minus the newline.  If
  73. $time is not specified, the current time is used.  N.B.: If $time is
  74. null, the "beginning of time" (0 seconds) is used.  $format may contain
  75. the %-escape characters mentioned above.
  76.  
  77. Examples:
  78.     print &'ptime("%D %T %Z\n",time); # prints "02/17/91 14:23:54 GMT\n"
  79.     $date = &'ptime('%d %h %Y',time); # $date = "17 Feb 1991";
  80.     $filename = &'ptime('%d_%h_%Y');  # $filename = "17_Feb_1991";
  81.  
  82. $ptime'default_TZ specifies a timezone to use if the TZ environment
  83. variable is not set.  By default, this is set to 'GMT'.  If you're in
  84. EST, you can set it to 'EST5EDT' so that localtime is used, for
  85. example.
  86.  
  87. &'zonetime($time);
  88. &'zonetime;
  89.  
  90. Basically, a wrapper around gmtime/localtime.  It returns the same LIST
  91. as gmtime/localtime do.  Which function is used depends on the TZ
  92. environment variable, if set.  If TZ is not set, $ptime'default_TZ is
  93. used instead.  If $time is not specified, the current time is used.
  94.  
  95. &'ctime($time);
  96. &'ctime;
  97.  
  98. Returns a string similar to the ctime(3) function.  It's the same as
  99. the format "%a %h %d %T %Z %Y\n".  If $time is not specified, the
  100. current time is used.
  101.  
  102. Limitations
  103. -----------
  104. * based on SysV date +FORMAT stuff ;-)
  105. * doesn't parse left to right (or at all), just replaces what it finds
  106.   in the order specified in the code.  So '%%y' would return '%91'..
  107. * biased towards American date formats
  108. * needs a couple more hooks for customization for other languages
  109.   may add in the near future.
  110. * zonetime is probably an incorrect name, as you don't get back the time
  111.   struct as broken down for the specified timezone.  zonetime only
  112.   determines whether to use gmtime or localtime.
  113. * if $time is 0 and timezone is "before" the GMT, the year will print out as
  114.   2069 instead of 1969.  Oh well...  ;-}
  115.  
  116. Possible Future Enhancements
  117. ----------------------------
  118. * Complete support for other language formats for dates/times.
  119. * Is there really anything else one would want in date formatting
  120.   routines?  ;-}
  121. * Include subs for other languages, already have french and german, somewhat.
  122. * Other language time/date formats welcome.
  123. * If you have an idea that you might want included in here, let me know.
  124.   My email address is at the top of the README and inside each source file.
  125.