From 99d52f95593e4ef6bfadb9b44bc23b9164093c58 Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <gerwitzm@lovullo.com>
Date: Tue, 4 Apr 2017 10:29:24 -0400
Subject: [PATCH] Add timestamp parameters

* base.xml: Modify documentation to discourage DATE_TIME.
* datetime.xml (timestamp_*): Add params.
---
 core/base.xml     |  3 ++-
 core/datetime.xml | 35 ++++++++++++++++++++++++++++++-----
 2 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/core/base.xml b/core/base.xml
index ba0203ed..6222ff72 100644
--- a/core/base.xml
+++ b/core/base.xml
@@ -51,7 +51,8 @@
     a proper value representing the current year.
 
     \todo{TAME is deterministic with this one exception; remove it and
-    have users use a param instead if they need this datum.}
+    have users use the params from {\tt datetime} instead if they need this
+    datum.}
 
     <const name="__DATE_YEAR__" magic="true"
            value="0" type="integer"
diff --git a/core/datetime.xml b/core/datetime.xml
index 7d267d0d..0f871059 100644
--- a/core/datetime.xml
+++ b/core/datetime.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!--
-  Copyright (C) 2015  LoVullo Associates, Inc.
+  Copyright (C) 2015, 2017 LoVullo Associates, Inc.
 
   This file is part of tame-core.
 
@@ -25,13 +25,38 @@
   <import package="base" />
 
 
+  Providing the current timestamp externally allows the system to be
+    wholly deterministic.
+  It also captures the state of the data in time,
+    so re-calculating in the future (e.g. using the summary pages)
+    will yield the same result.
+
+  <param name="timestamp_current" type="integer" default="0"
+         desc="Unix timestamp representing the current time of the
+               system (clock time), as it should be perceived" />
+
+  This system does not handle its own arthiemtic to figure out the
+    current date components from the given timestamp.
+
+  <param name="timestamp_year" type="integer" default="0"
+         desc="Current year (clock time), as it should be perceived" />
+
+  <param name="timestamp_month" type="integer" default="0"
+         desc="Current month (clock time), as it should be perceived;
+               1-indexed" />
+
+  <param name="timestamp_day" type="integer" default="0"
+         desc="Current day (clock time), as it should be perceived;
+               1-indexed" />
+
+
   <!--
     Determines how many years the given date is relative to the current date
 
-    Note that a positive number will be returned if the given date is in the past,
-    negative if in the future.
+    Note that a positive number will be returned if the given date is
+    in the past, negative if in the future.
   -->
-  <template name="_ageYears_" desc="Age in years of the given date relative to the current">
+  <template name="_age-years_" desc="Age in years of the given date relative to the current">
     <param name="@generates@" desc="Generator variable, per index" />
     <param name="@yearset@"   desc="Set of years to iterate on" />
     <param name="@sym@"       desc="Generator symbol" />
@@ -76,7 +101,7 @@
                 </c:when>
 
                 <c:sum label="Calculate by subtracting the given year from the current year">
-                  <c:value-of name="__DATE_YEAR__" />
+                  <c:value-of name="timestamp_year" />
 
                   <c:product>
                     <c:value-of name="NEGATE" />