Namespace Standards

This document attempts to define the the various 2nd tier DateTime namespaces and the appropriate functionality of modules residing there. Namespace Allocation

Module authors who want to put a module in the DateTime::* namespace are strongly encouraged to write to the [email protected] mailing list first. Please do not create a new 2nd tier namespace without first seeking approval from the list. Unless specifically noted as open most 2nd tier namespaces should not be used for new modules.

All DateTime authors are encouraged to consult the [email protected] mailing list before uploading any modules that start with DateTime::.

The Namespaces

Currently there are 18 official 2nd tier namespaces in the DateTime Suite.

DateTime

Obviously this is the root namespace. DateTime.pm is the generic DateTime object implementing the Gregorian calendar.

DateTime::Calendar

Modules implementing calendars that can be converted to/from other DateTime and other DateTime::Calendar::* objects. Please see datetime-calendar.pod for developer documentation.

This is an open namespace.

DateTime::Duration

This is a simple class for representing duration objects. These objects are used whenever you do date math with DateTime.pm.

DateTime::Event

Modules implementing the occurrence of an event.

This is an open namespace.

DateTime::Fiction

Conceding that all calendars are merely imperfect human works is a requirement before placing your module here.

"Weighing in late, but I just don't buy the idea that a 'fictional' calendar is any more fictional than, say, the Discordian or Napoleonic calendar. All calendars are the creation of some human - they are all artificial in some respect. Squirreling these away in some other name space seems even more artificial." - Rich Bowen

This is somewhat of an unusual namespace. It is intended for modules implementing calendars from fictional works. This namespace is exempted from the requirement to be interoperable with DateTime and DateTime::*. It is suggested that the namespace include the author's name at the 3rd/4th tier. For Example:

• DateTime::Fiction::Brust::Steven::Dragaera
• DateTime::Fiction::Sony::Utopia
• DateTime::Fiction::Tolkien::JRR::MiddleEarth
• DateTime::Fiction::Bear::Greg::Mars

This is an open namespace.

DateTime::Fiscal

Financial and business oriented calculations.

This is an open namespace.

DateTime::Format

Modules capable of parsing specific Date/Time formats and/or being able to format strings. The word "Format" in this namespace should be read as a noun, not a verb. In other words, modules in this namespace deal with a format, as opposed to doing formatting only.

Modules in this namespace are expected to implement an API that is substantially similar to other format modules, notably methods such as parse_datetime, parse_duration, format_datetime, etc.

This is an open namespace.

DateTime::HiRes

Sub-second current time resolution.

DateTime::Incomplete

Supports the partial date & time thing.

DateTime::Infinite

Infinite past and future DateTime objects.

DateTime::Language

Deprecated. See DateTime::Locale

DateTime::LeapSecond

Leap seconds table and utilities.

DateTime::Locale

Provides localization support for DateTime.pm.

DateTime::Locale::Catalog

Contains the ICU locale listings.

DateTime::Precise

This namespace pre-dates DateTime.pm and is unrelated to the DateTime Suite.

DateTime::Set

DateTime sets and set math.

DateTime::Span

DateTime time-ranges.

DateTime::SpanSet

Sets of DateTime spans.

DateTime::TimeZone

Time zone objects and base class.

DateTime::TimeZone::Catalog

Contains the Olson time zone listings.