diff --git a/docs/user/support/parsedate.dox b/docs/user/support/parsedate.dox new file mode 100644 index 0000000000..0bcb80f855 --- /dev/null +++ b/docs/user/support/parsedate.dox @@ -0,0 +1,163 @@ +/** \file parsedate.h +This is a set a functions for parsing date strings in various formats. +It's mostly tailored for parsing user given data, although originally, +it was developed to parse the date strings found in usenet messages. + +The given date will be parsed relative to the specified time, and using +a predefined set of time/date formats. + +\par Valid Input Strings + +The internal formats allow parsedate() to understand a wide range of +input strings. The format list is ought to be compiled from the Date: +line of 80.000 usenet messages. + +But since this function is also used in end-user applications like the +Tracker's find panel, it's helpful to know what this function accepts +and what not. + +Here are some examples of input strings that parsedate() will be able +to convert along with some notes: + - "last friday", "this wednesday", "next July" + "last", "next", and "this" refer to the week or year (depending + on the context). So "last friday" means last week's friday. + "This wednesday" is referring to this week's wednesday, no matter + if it has already passed or not. + "Next July" refers to next year's July. All of these dates are + parsed relative to the specified time (usually "now"), and will + be set to the first moment of that time span: "next monday" is + monday, 0:00:00, midnight. + - "now" just returns the time all calculations are relative to. + - "next 5 minutes", "5 minutes", "+5 mins" all mean the same thing, + that is, current time plus exactly 5 minutes. + - "5 weeks" means in 5 weeks from now on. + - "8/5/2003", "5.8.2003", "2003-08-05" are all referring to August + 5th, 2003, again at 0:00 midnight. + - "Thursday 3:00" means this week's thursday, at 3 o'clock. + +\anchor parsedateFormats +\par Format Specifier + +While the get_dateformats() function allow you to retrieve the built-in +formats, you can also define your own and use set_dateformats() to let +parsedate() use them in all subsequent calls. + +The following is a list valid format specifiers and their meanings. + + - \b a/A weekday (Sunday, Monday, ...) + - \b d day of month (1-31) + - \b b/B month name (January, February, ...) + - \b month (1-12) + - \b y/Y year + - \b H/I hours (1-24) + - \b M minutes (0-60) + - \b S seconds (0-60) + - \b p meridian (am/pm) + - \b z/Z time zone (i.e. GMT) + - \b T time unit, like "last friday", "next 5 minutes", "-15 hours", etc. + - \b - dash or slash + +Any of ",.:" is allowed and will be expected in the input string as is. +You can enclose a \b single field with "[]" to mark it as being optional. +A blank stands for white space. No other character is allowed. +An invalid format string won't do any harm, but of course, no input string +will ever match that format. + +For example, "H:M [p]" will match against "21:33", "4:12 am", but not "30:30 pm" +(hours out of range), "15:16 GMT" (this time zone is certainly not a valid +meridian specifier), or "4:66" (minutes out of range). + +\par Note: +At the time of this writing, the parsedate() functions are not localized and +will only recognize English time specifications following the examples above. + +*/ + +/** \def PARSEDATE_RELATIVE_TIME +\brief relative time + +The time value was computed relative to the specified time. +*/ + +/** \def PARSEDATE_DAY_RELATIVE_TIME +\brief day relative time + +The time value was computed relative to the specified time, and it would vary with +every day passed in the specified time. +*/ + +/** \def PARSEDATE_MINUTE_RELATIVE_TIME +\brief minute relative time + +The time value was computed relative to the specified time, and it would vary with +every minute passed in the specified time. +*/ + +/** \def PARSEDATE_INVALID_DATE +\brief invalid date string + +This flag will be set if the specified date string could not be parsed correctly. +For example, this may happen if there are some unknown words in that string. +*/ + +/** \fn time_t parsedate(const char *dateString, time_t relativeTo) +\brief Parses \p dateString relative to \p relativeTo + +Parses the given \p dateString relative to the time specified by \p relativeTo +using the internal formats table. + +\param dateString the date that should be parsed, i.e. "next thursday" +\param relativeTo all relative dates will be relative to this time, if -1 is passed, the current time will be used +\return the parsed time value or -1 if the \p dateString could not be parsed. +*/ + +/** \fn time_t parsedate_etc(const char *dateString, time_t relativeTo, int *_storedFlags) +\brief Parses \p dateString relative to \p relativeTo + +This does basically the same as parsedate(), but will set the following +flags in \p _storedFlags: +\htmlonly + + + + + + + + + + + +
ConstantMeaning
PARSEDATE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly +
PARSEDATE_DAY_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly +
PARSEDATE_MINUTE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly +
PARSEDATE_INVALID_DATE + \endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly + This flag will only be set if the function returns -1. +
+\endhtmlonly +*/ + +/** \fn void set_dateformats(const char *formatTable[]) +\brief sets the internal format table for parsedate() + +This function let you set the format table which is used by parsedate(). +When \c formatTable is NULL, the standard built-in format table will be set again. +\param formatTable the NULL terminated formats list. This list must stay + valid when using parsedate() - it is not copied, but directly used. +\see + \ref parsedateFormats Format! + +*/ + +/** \fn const char **get_dateformats(void) +\brief returns the internal format table currently used by parsedate() + +Returns the internal format table currently used by parsedate() - this is +either a pointer to the built-in one, or one that you have previously +set using set_dateformats(). + +\see + \ref set_dateformats() +*/ + diff --git a/docs/user/support/support_intro.dox b/docs/user/support/support_intro.dox new file mode 100644 index 0000000000..6c5ec71191 --- /dev/null +++ b/docs/user/support/support_intro.dox @@ -0,0 +1,10 @@ +/** \page support The Support Kit + +The Support Kit provides a handy set of functions and classes that you can +use in your applications. It is part of libbe.so. +Documentation is avaible for the following parts: + + - \ref parsedate.h Date parsing functions + +*/ +