Skip to content

Commit

Permalink
Item11806: implementing ISO date support as DateTimeContrib - first b…
Browse files Browse the repository at this point in the history 
…atch

git-svn-id: http://svn.foswiki.org/trunk/DateTimeContrib@14696 0b4bb1d4-4e5a-0410-9cc4-b2b747904278
  • Loading branch information
ArthurClemens authored and ArthurClemens committed May 6, 2012
0 parents commit 97a1f9c
Show file tree
Hide file tree
Showing 914 changed files with 552,266 additions and 0 deletions.
111 changes: 111 additions & 0 deletions data/System/DateTimeContrib.txt
@@ -0,0 +1,111 @@
---+!! <nop>DateTime Contrib
This topic is primarily meant for Foswiki developers.

%TOC%

---++ Introduction
<noautolink>
DateTime Contrib enables the use of the data type =datetime= in data forms. Under the hood it uses the extensive [[http://datetime.perl.org/][DateTime]] libraries, including:
* [[http://search.cpan.org/~drolsky/DateTime-0.74/lib/DateTime.pm][DateTime]]
* =DateTime::Format::Strptime=
* =DateTime::Locale=
* =DateTime::Timezone=

DateTime Contrib adds the field definition =Datetime= to =/lib/Foswiki/Forms/=
</noautolink>


---++ Usage
---+++ Working with dates
* Date-time strings are parsed as dates as long as they adhere to one of the input formats (see below).
* The format is similar to [[http://www.w3.org/TR/NOTE-datetime][W3C Date and Time Formats]], but without the string delimiters. For example: =2012-05-31 19:59:59=.
* Dates are rendered in local time and formatted according to Configure setting ={<nop>DefaultDateTimeFormat}=.
* Times are in UTC and can have a time zone offset specified, either an offset number or a time zone name.
* A time zone offset number is relative to UTC, in the form of a sign character (+/-) followed by a four digit time providing hours and minutes of the offset; no colon is used.
* A time zone name is one of the [[http://en.wikipedia.org/wiki/List_of_tz_database_time_zones][Olson Time Zone names]].


---+++ Supported input formats
| Simplest | =2012-05-05 15:28:37= | UTC time is assumed |
| Time zone offset (number) | =2012-05-05 15:28:37 -0500= | Offset should not include Daylight Savings |
| Time zone name | =2012-05-05 15:28:37 America/Nassau= | One of the [[http://en.wikipedia.org/wiki/List_of_tz_database_time_zones][Olson Time Zone names]]. Offset will be calculated automatically. |
| Time zone offset plus time zone name | =2012-05-05 15:28:37 -0500 America/Nassau= | Probably redundant format |


---+++ Supported output formats
Dates are rendered according to Configure setting ={<nop>DefaultDateTimeFormat}=, which may contain tokens shown in the table below.
<noautolink>
| *Token* | *Rendering* |
| =%a= | The abbreviated weekday name. |
| =%A= | The full weekday name. |
| =%b= | The abbreviated month name. |
| =%B= | The full month name. |
| =%c= | The default datetime format for the object's locale. |
| =%C= | The century number (year/100) as a 2-digit integer. |
| =%d= | The day of the month as a decimal number (range 01 to 31). |
| =%D= | Equivalent to =%m/%d/%y=. This is not a good standard format if you want folks from both the United States and the rest of the world to understand the date! |
| =%e= | Like =%d=, the day of the month as a decimal number, but a leading zero is replaced by a space. |
| =%F= | Equivalent to =%Y-%m-%d= (the ISO 8601 date format) |
| =%G= | The ISO 8601 year with century as a decimal number. The 4-digit year corresponding to the ISO week number (see =%V=). This has the same format and value as =%Y=, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ) |
| =%g= | Like =%G=, but without century, i.e., with a 2-digit year (00-99). |
| =%h= | Equivalent to =%b=. |
| =%H= | The hour as a decimal number using a 24-hour clock (range 00 to 23). |
| =%I= | The hour as a decimal number using a 12-hour clock (range 01 to 12). |
| =%j= | The day of the year as a decimal number (range 001 to 366). |
| =%k= | The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also =%H=.) |
| =%l= | The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also =%I=.) |
| =%m= | The month as a decimal number (range 01 to 12). |
| =%M= | The minute as a decimal number (range 00 to 59). |
| =%n= | A newline character. |
| =%N= | The fractional seconds digits - <span class='foswikiAlert'>not supported</span>. |
| =%p= | Either 'AM' or 'PM' according to the given time value, or the corresponding strings for the current locale. Noon is treated as 'pm' and midnight as 'am'. |
| =%P= | Like =%p= but in lowercase: 'am' or 'pm' or a corresponding string for the current locale. |
| =%r= | The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to ='%I:%M:%S %p'=. |
| =%R= | The time in 24-hour notation (=%H:%M=). (SU) For a version including the seconds, see =%T= below. |
| =%s= | The number of seconds since the epoch. |
| =%S= | The second as a decimal number (range 00 to 61). |
| =%t= | A tab character. |
| =%T= | The time in 24-hour notation (=%H:%M:%S=). |
| =%u= | The day of the week as a decimal, range 1 to 7, Monday being 1. See also =%w=. |
| =%U= | The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also =%V= and =%W=. |
| =%V= | The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. See also =%U= and =%W=. |
| =%w= | The day of the week as a decimal, range 0 to 6, Sunday being 0. See also =%u=. |
| =%W= | The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01. |
| =%x= | The default date format for the object's locale. |
| =%X= | The default time format for the object's locale. |
| =%y= | The year as a decimal number without a century (range 00 to 99). |
| =%Y= | The year as a decimal number including the century. |
| =%z= | The time-zone as hour offset from UTC. Required to emit RFC822-conformant dates (using ="%a, %d %b %Y %H:%M:%S %z"=). |
| =%Z= | The time zone or name or abbreviation. |
| =%%= | A literal ='%'= character. |
</noautolink>
Overview copied from [[http://search.cpan.org/~drolsky/DateTime-0.74/lib/DateTime.pm][DateTime]].


---+++ Data form template
In a data form, specify =datetime= as type. For instance:
<verbatim>
| *Name* | *Type* | *Size* |
| Name | text | 100 |
| Date | datetime | 35 |
</verbatim>


---++ Installation Instructions
%$INSTALL_INSTRUCTIONS%


---++ Contrib Info
| Contrib Author: | Foswiki:Main.ArthurClemens |
| Copyright: | &copy; 2012 Arthur Clemens and Foswiki Contributors |
| License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
| Version: | %$VERSION% |
| Release: | %$RELEASE% |
| Change History: | <!-- versions below in reverse order -->&nbsp; |
| 06 May 2012 | 1.0 Arthur Clemens First release |
| CPAN Dependencies: | none |
| Other Dependencies: | none |
| Perl Version: | 5.005 |
| License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
| Plugin Home: | http://foswiki.org/Extensions/%TOPIC% |
| Support: | http://foswiki.org/Support/%TOPIC% |
174 changes: 174 additions & 0 deletions lib/CPAN/lib/Attribute/Params/Validate.pm
@@ -0,0 +1,174 @@
package Attribute::Params::Validate;

use strict;
use warnings;

use attributes;

use Attribute::Handlers 0.79;

# this will all be re-exported
use Params::Validate qw(:all);

require Exporter;

our $VERSION = 1.07;

our @ISA = qw(Exporter);

my %tags = (
types => [
qw( SCALAR ARRAYREF HASHREF CODEREF GLOB GLOBREF SCALARREF HANDLE UNDEF OBJECT )
],
);

our %EXPORT_TAGS = (
'all' => [ qw( validation_options ), map { @{ $tags{$_} } } keys %tags ],
%tags,
);
our @EXPORT_OK = ( @{ $EXPORT_TAGS{all} }, 'validation_options' );


sub UNIVERSAL::Validate : ATTR(CODE, INIT) {
_wrap_sub( 'named', @_ );
}

sub UNIVERSAL::ValidatePos : ATTR(CODE, INIT) {
_wrap_sub( 'positional', @_ );
}

sub _wrap_sub {
my ( $type, $package, $symbol, $referent, $attr, $params ) = @_;

my @p = ref $params ? @{$params} : $params;

my $subname = $package . '::' . *{$symbol}{NAME};

my %attributes = map { $_ => 1 } attributes::get($referent);
my $is_method = $attributes{method};

{
no warnings 'redefine';
no strict 'refs';

# An unholy mixture of closure and eval. This is done so that
# the code to automatically create the relevant scalars from
# the hash of params can create the scalars in the proper
# place lexically.

my $code = <<"EOF";
sub
{
package $package;
EOF

$code .= " my \$object = shift;\n" if $is_method;

if ( $type eq 'named' ) {
$params = {@p};
$code .= " Params::Validate::validate(\@_, \$params);\n";
}
else {
$code .= " Params::Validate::validate_pos(\@_, \@p);\n";
}

$code .= " unshift \@_, \$object if \$object;\n" if $is_method;

$code .= <<"EOF";
\$referent->(\@_);
}
EOF

my $sub = eval $code;
die $@ if $@;

*{$subname} = $sub;
}
}

1;

=head1 SYNOPSIS
use Attribute::Params::Validate qw(:all);
# takes named params (hash or hashref)
# foo is mandatory, bar is optional
sub foo : Validate( foo => 1, bar => 0 )
{
...
}
# takes positional params
# first two are mandatory, third is optional
sub bar : ValidatePos( 1, 1, 0 )
{
...
}
# for some reason Perl insists that the entire attribute be on one line
sub foo2 : Validate( foo => { type => ARRAYREF }, bar => { can => [ 'print', 'flush', 'frobnicate' ] }, baz => { type => SCALAR, callbacks => { 'numbers only' => sub { shift() =~ /^\d+$/ }, 'less than 90' => sub { shift() < 90 } } } )
{
...
}
# note that this is marked as a method. This is very important!
sub baz : Validate( foo => { type => ARRAYREF }, bar => { isa => 'Frobnicator' } ) method
{
...
}
=head1 DESCRIPTION
The Attribute::Params::Validate module allows you to validate method
or function call parameters just like Params::Validate does. However,
this module allows you to specify your validation spec as an
attribute, rather than by calling the C<validate> routine.
Please see Params::Validate for more information on how you can
specify what validation is performed.
=head2 EXPORT
This module exports everything that Params::Validate does except for
the C<validate> and C<validate_pos> subroutines.
=head2 ATTRIBUTES
=over 4
=item * Validate
This attribute corresponds to the C<validate> subroutine in
Params::Validate.
=item * ValidatePos
This attribute corresponds to the C<validate_pos> subroutine in
Params::Validate.
=back
=head2 OO
If you are using this module to mark B<methods> for validation, as
opposed to subroutines, it is crucial that you mark these methods with
the C<:method> attribute, as well as the C<Validate> or C<ValidatePos>
attribute.
If you do not do this, then the object or class used in the method
call will be passed to the validation routines, which is probably not
what you want.
=head2 CAVEATS
You B<must> put all the arguments to the C<Validate> or C<ValidatePos>
attribute on a single line, or Perl will complain.
=head1 SEE ALSO
Params::Validate
=cut

0 comments on commit 97a1f9c

Please sign in to comment.