Add docbook section for time_period_match

modules/tmrec/doc/tmrec_admin.xml

@@ -18,7 +18,8 @@
 	<para>
 		This module provides time recurrence matching functions. Definitions
 		of recurrences are based on Internet Calendaring and Scheduling Core
-		Object Specification (Calendar COS - RFC 2445).
+		Object Specification (Calendar COS - RFC 2445). It also provides a port
+		of the Perl Time::Period module for generic time period matching.
 	</para>
 	</section>
 
@@ -303,6 +304,112 @@ modparam("tmrec", "separator", ";")
 ...
 if(is_leap_year("2010"))
 ...
+</programlisting>
+	    </example>
+	</section>
+
+	<section>
+	    <title>
+		<function moreinfo="none">time_period_match(period [, timestamp])</function>
+	    </title>
+	    <para>
+			Matches the point in time specified by the timestamp parameter, or
+			the current time if the parameter is missing, against the given
+			period specification. Returns 1 if it matches, -1 if it doesn't,
+			and a value &lt;= -2 if there was an error.
+		</para>
+		<para>
+			The time period specification follows the Perl Time::Period module.
+			It is a string and consists of zero or more sub-period specifications,
+			separated by commas. The period matches if at least one of the
+			sub-periods matches, or if no sub-periods were given at all (an
+			empty string).
+		</para>
+		<para>
+			Each sub-period is a list of one or more scale definitions,
+			optionally separated by space characters. The sub-period matches if
+			all of the given scales within that sub-period match. For each scale
+			given, a single value or a range of values (which is two values
+			separated by a hyphen) can be specified. Multiple
+			values or multiple ranges (or a combination thereof) within a single
+			scale is also possible. If a certain scale is specified more than once,
+			the previous values or ranges for that scale are extended by the newly
+			given ones. If a particular scale is not mentioned at all within a
+			sub-period, then no matching is performed for that scale.
+		</para>
+		<para>
+			The following scales are supported and understood. Each scale also has
+			a respective short code, either one can be used. A single scale
+			definition consists of the scale name, followed by an opening brace,
+			followed by the list of values, followed by a closing brace.
+			<itemizedlist>
+				<listitem><para>
+					<emphasis>year</emphasis> or <emphasis>yr</emphasis>
+					- Either given as a full 4-digit number &gt;= 1970, or
+					as a 2-digit number, in which case it will be understood
+					to be within the current century.
+				</para></listitem>
+				<listitem><para>
+					<emphasis>month</emphasis> or <emphasis>mo</emphasis>
+					- Month of the year, either a number between 1 and 12,
+					or at least the first 3 letters of a spelled out month
+					name, e.g. <quote>jan</quote>, <quote>janua</quote>
+					or <quote>january</quote> will all work.
+				</para></listitem>
+				<listitem><para>
+					<emphasis>week</emphasis> or <emphasis>wk</emphasis>
+					- Week of the month, a number between 1 and 6. The
+					first day of the week is Sunday.
+				</para></listitem>
+				<listitem><para>
+					<emphasis>yday</emphasis> or <emphasis>yd</emphasis>
+					- Day of the year, a number between 1 and 366.
+				</para></listitem>
+				<listitem><para>
+					<emphasis>mday</emphasis> or <emphasis>md</emphasis>
+					- Day of the month, a number between 1 and 31.
+				</para></listitem>
+				<listitem><para>
+					<emphasis>wday</emphasis> or <emphasis>wd</emphasis>
+					- Day of the week, either a number between 1 and 7, or
+					at least the first 2 letters of a spelled out weekday
+					name (analogous to the <quote>month</quote> scale).
+					Sunday is the first day of the week.
+				</para></listitem>
+				<listitem><para>
+					<emphasis>hour</emphasis> or <emphasis>hr</emphasis>
+					- A number between 0 and 23. Unlike the Perl Time::Period
+					module, <quote>am</quote> or <quote>pm</quote>
+					specifications are not supported.
+				</para></listitem>
+				<listitem><para>
+					<emphasis>minute</emphasis> or <emphasis>min</emphasis>
+					- A number between 0 and 59.
+				</para></listitem>
+				<listitem><para>
+					<emphasis>second</emphasis> or <emphasis>sec</emphasis>
+					- A number between 0 and 60 (to allow for leap seconds).
+				</para></listitem>
+			</itemizedlist>
+		</para>
+		<para>
+			The parameters can include pseudo-variables. Whitespace (more
+			precisely, the space character only) can occur anywhere, but is
+			optional. Ranges in all scales (with the exception of the
+			<quote>year</quote> scale) are allowed to wrap-around, e.g. a weekday
+			scale of <quote>{fri-tue}</quote> is equivalent to
+			<quote>{fri-sat,sun-tue}</quote>.
+		</para>
+		<example>
+		<title><function>time_period_match</function> usage</title>
+		<programlisting format="linespecific">
+...
+if(time_period_match("wd{1-5} hr{8-16}, wd{1-5} hr{17} min{0-29}"))
+	xdbg("Monday to Friday, 8:00 to 17:30\n");
+
+if(time_period_match("weekday { sat sun }, weekday {mo-fr} hr {17-8},wd{mo-wed}hr{15 16 9}"))
+	xdbg("We're closed - open only Monday to Wednesday 10:00-15:00, Thursday and Friday 9:00-17:00");
+...
 </programlisting>
 	    </example>
 	</section>