eyeling 1.7.19 → 1.7.20

package/README.md

@@ -21,7 +21,7 @@ Try it here:
   - Load an N3 program from a URL (in the "Load N3 from URL" box or as ?url=...).
   - Share a link with the program encoded in the URL fragment (`#...`).
 
-- [Eyeling streaming playground](https://eyereasoner.github.io/eyeling/stream)
+- Streaming demo
   - Browse a Wikidata entity, load its facts, and see Eyeling’s **deductive closure appear incrementally** as triples are derived.
   - Edit **N3 rules live** and re-run to watch how different inference rules change what gets derived.
   - Demo **CORS-safe dynamic fetching**: derived “fetch requests” can trigger extra facts (e.g., Wikiquote extracts) that are injected and re-reasoned.

package/examples/it-is-about-time.n3

@@ -0,0 +1,29 @@
+@prefix ex: <http://example.org/> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix tfn: <https://w3id.org/time-fn#> .
+@prefix math: <http://www.w3.org/2000/10/swap/math#> .
+
+ex:e1 a ex:Event ;
+    ex:when "2000-01-02T03:04:05"^^xsd:dateTime ;   # floating (no TZ)
+    ex:day  "2000-01-02"^^xsd:date ;
+    ex:tz   "Z" .
+  ex:e2 a ex:Event ;
+    ex:when "2000-01-02T03:04:05-03:00"^^xsd:dateTime ;
+    ex:day  "2000-01-02"^^xsd:date ;
+    ex:tz   "-03:00" .
+
+{
+    ?this ex:when ?whenRaw .
+    ?this ex:day ?day .
+    ?this ex:tz ?tz .
+    ?startInc math:notGreaterThan ?whenBound .
+    ?whenBound math:notGreaterThan ?endInc .
+    (?whenRaw ?tz) tfn:bindDefaultTimezone ?whenBound .
+    (?day) tfn:periodMinInclusive ?startInc .
+    (?day) tfn:periodMaxInclusive ?endInc .
+    (?day) tfn:periodMinExclusive ?startEx .
+    (?day) tfn:periodMaxExclusive ?endEx .
+} => {
+    ?this ex:occursOn ?day .
+    ?this ex:whenBound ?whenBound .
+} .

package/examples/it-is-about-time.srl

@@ -0,0 +1,36 @@
+PREFIX ex:  <http://example.org/>
+PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+PREFIX tfn: <https://w3id.org/time-fn#>
+
+DATA {
+  ex:e1 a ex:Event ;
+    ex:when "2000-01-02T03:04:05"^^xsd:dateTime ;   # floating (no TZ)
+    ex:day  "2000-01-02"^^xsd:date ;
+    ex:tz   "Z" .
+
+  ex:e2 a ex:Event ;
+    ex:when "2000-01-02T03:04:05-03:00"^^xsd:dateTime ;
+    ex:day  "2000-01-02"^^xsd:date ;
+    ex:tz   "-03:00" .
+}
+
+RULE {
+  $this ex:occursOn  ?day .
+  $this ex:whenBound ?whenBound .
+}
+WHERE {
+  $this ex:when ?whenRaw ;
+        ex:day  ?day ;
+        ex:tz   ?tz .
+
+  BIND( tfn:bindDefaultTimezone(?whenRaw, ?tz) AS ?whenBound )
+
+  BIND( tfn:periodMinInclusive(?day) AS ?startInc )
+  BIND( tfn:periodMaxInclusive(?day) AS ?endInc )
+  BIND( tfn:periodMinExclusive(?day) AS ?startEx )
+  BIND( tfn:periodMaxExclusive(?day) AS ?endEx )
+
+  # Inclusive containment: start <= whenBound <= end
+  FILTER( ?startInc <= ?whenBound && ?whenBound <= ?endInc )
+}
+

package/examples/output/it-is-about-time.n3

@@ -0,0 +1,7 @@
+@prefix ex: <http://example.org/> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ex:e1 ex:occursOn "2000-01-02"^^xsd:date .
+ex:e1 ex:whenBound "2000-01-02T03:04:05Z"^^xsd:dateTime .
+ex:e2 ex:occursOn "2000-01-02"^^xsd:date .
+ex:e2 ex:whenBound "2000-01-02T03:04:05-03:00"^^xsd:dateTime .

package/eyeling-builtins.ttl

@@ -8,6 +8,7 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix tfn: <https://w3id.org/time-fn#> .
 
 # ------------------------------------------------------------------------------
 # Builtin catalog (eyeling.js)
@@ -336,3 +337,26 @@ string:format a ex:Builtin ; ex:kind ex:Function ;
 
 string:jsonPointer a ex:Builtin ; ex:kind ex:Function ;
   rdfs:comment "JSON Pointer lookup: (jsonText pointer) -> value term. Expects rdf:JSON-typed literal (or treated as rdf:JSON); caches parsed JSON and pointer lookups." .
+
+# --- tfn: (Time Functions) -------------------------------------------
+# Source semantics: Smessaert et al., “It’s About Time: Time Functions for Comparing Partial and Floating Time Literals in SPARQL”, §2.2.
+
+tfn:periodMinInclusive a ex:Builtin ;
+  ex:kind ex:Function ;
+  rdfs:comment "Time Functions: inclusive lower bound of the period represented by a temporal literal (xsd:date, xsd:gYearMonth, xsd:gYear, xsd:dateTime, ...), returned as xsd:dateTime." .
+
+tfn:periodMaxInclusive a ex:Builtin ;
+  ex:kind ex:Function ;
+  rdfs:comment "Time Functions: inclusive upper bound of the period represented by a temporal literal, returned as xsd:dateTime." .
+
+tfn:periodMinExclusive a ex:Builtin ;
+  ex:kind ex:Function ;
+  rdfs:comment "Time Functions: exclusive lower bound of the period represented by a temporal literal, returned as xsd:dateTime." .
+
+tfn:periodMaxExclusive a ex:Builtin ;
+  ex:kind ex:Function ;
+  rdfs:comment "Time Functions: exclusive upper bound of the period represented by a temporal literal, returned as xsd:dateTime." .
+
+tfn:bindDefaultTimezone a ex:Builtin ;
+  ex:kind ex:Function ;
+  rdfs:comment "Time Functions: binds a default timezone to a floating time literal. Input is (timeLiteral timeZone). If the literal already has a timezone, it is returned unchanged; otherwise the specified timezone is applied." .

package/eyeling.js

@@ -42,6 +42,7 @@ const XSD_NS = 'http://www.w3.org/2001/XMLSchema#';
 const CRYPTO_NS = 'http://www.w3.org/2000/10/swap/crypto#';
 const MATH_NS = 'http://www.w3.org/2000/10/swap/math#';
 const TIME_NS = 'http://www.w3.org/2000/10/swap/time#';
+const TFN_NS = 'https://w3id.org/time-fn#';
 const LIST_NS = 'http://www.w3.org/2000/10/swap/list#';
 const LOG_NS = 'http://www.w3.org/2000/10/swap/log#';
 const STRING_NS = 'http://www.w3.org/2000/10/swap/string#';
@@ -3625,6 +3626,248 @@ function parseXsdDateTimeLexParts(t) {
   return { yearStr, month, day, hour, minute, second, tz };
 }
 
+// -----------------------------------------------------------------------------
+// Time Functions (tfn:) helpers
+// -----------------------------------------------------------------------------
+
+function __tfnParseTimezoneValue(t) {
+  // Accept plain string literals and xsd:string. Return "Z" or "+hh:mm" or "-hh:mm".
+  if (!(t instanceof Literal)) return null;
+  const [lex, dt] = literalParts(t.value);
+  const s = stripQuotes(lex).trim();
+  if (!s) return null;
+  if (s === 'Z') return 'Z';
+  const m = /^([+-])(\d{2}):(\d{2})$/.exec(s);
+  if (!m) return null;
+  const hh = parseInt(m[2], 10);
+  const mm = parseInt(m[3], 10);
+  if (!(hh >= 0 && hh <= 14)) return null;
+  if (!(mm >= 0 && mm <= 59)) return null;
+  // disallow offsets beyond 14:00 (e.g., +14:30)
+  if (hh === 14 && mm !== 0) return null;
+  return `${m[1]}${m[2]}:${m[3]}`;
+}
+
+function __tfnHasTimezoneSuffix(s) {
+  return /(Z|[+-]\d{2}:\d{2})$/.test(s);
+}
+
+function __tfnParseTemporalLiteralParts(t) {
+  if (!(t instanceof Literal)) return null;
+  const [lex, dt] = literalParts(t.value);
+  if (!dt) return null;
+  const val = stripQuotes(lex);
+
+  // xsd:dateTime
+  if (dt === XSD_NS + 'dateTime') {
+    const m = /^(-?\d{4,})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:\d{2})?$/.exec(val);
+    if (!m) return null;
+    const year = BigInt(m[1]);
+    const month = parseInt(m[2], 10);
+    const day = parseInt(m[3], 10);
+    const hour = parseInt(m[4], 10);
+    const minute = parseInt(m[5], 10);
+    const second = parseInt(m[6], 10);
+    const frac = m[7] || '';
+    const tz = m[8] || null;
+
+    if (!(month >= 1 && month <= 12)) return null;
+    if (!(day >= 1 && day <= 31)) return null;
+    if (!(hour >= 0 && hour <= 23)) return null;
+    if (!(minute >= 0 && minute <= 59)) return null;
+    if (!(second >= 0 && second <= 59)) return null;
+
+    // Keep milliseconds precision (3 digits), truncating extra digits.
+    const msStr = (frac + '000').slice(0, 3);
+    const millis = parseInt(msStr, 10);
+
+    return { kind: 'dateTime', year, month, day, hour, minute, second, millis, tz, dt };
+  }
+
+  // xsd:date
+  if (dt === XSD_NS + 'date') {
+    const m = /^(-?\d{4,})-(\d{2})-(\d{2})(Z|[+-]\d{2}:\d{2})?$/.exec(val);
+    if (!m) return null;
+    const year = BigInt(m[1]);
+    const month = parseInt(m[2], 10);
+    const day = parseInt(m[3], 10);
+    const tz = m[4] || null;
+    if (!(month >= 1 && month <= 12)) return null;
+    if (!(day >= 1 && day <= 31)) return null;
+    return { kind: 'date', year, month, day, tz, dt };
+  }
+
+  // xsd:gYearMonth
+  if (dt === XSD_NS + 'gYearMonth') {
+    const m = /^(-?\d{4,})-(\d{2})(Z|[+-]\d{2}:\d{2})?$/.exec(val);
+    if (!m) return null;
+    const year = BigInt(m[1]);
+    const month = parseInt(m[2], 10);
+    const tz = m[3] || null;
+    if (!(month >= 1 && month <= 12)) return null;
+    return { kind: 'gYearMonth', year, month, tz, dt };
+  }
+
+  // xsd:gYear
+  if (dt === XSD_NS + 'gYear') {
+    const m = /^(-?\d{4,})(Z|[+-]\d{2}:\d{2})?$/.exec(val);
+    if (!m) return null;
+    const year = BigInt(m[1]);
+    const tz = m[2] || null;
+    return { kind: 'gYear', year, tz, dt };
+  }
+
+  return null;
+}
+
+function __tfnMod(a, b) {
+  let r = a % b;
+  if (r < 0n) r += b;
+  return r;
+}
+
+function __tfnIsLeapYear(y) {
+  // Proleptic Gregorian leap-year rule.
+  // Works for negative years using normalized modulus.
+  if (__tfnMod(y, 4n) !== 0n) return false;
+  if (__tfnMod(y, 100n) !== 0n) return true;
+  return __tfnMod(y, 400n) === 0n;
+}
+
+function __tfnDaysInMonth(y, m) {
+  if (m === 2) return __tfnIsLeapYear(y) ? 29 : 28;
+  if (m === 4 || m === 6 || m === 9 || m === 11) return 30;
+  return 31;
+}
+
+function __tfnPad2(n) {
+  return n < 10 ? '0' + String(n) : String(n);
+}
+function __tfnPad3(n) {
+  const s = String(n);
+  return s.length === 1 ? '00' + s : s.length === 2 ? '0' + s : s;
+}
+function __tfnFormatYear(y) {
+  const neg = y < 0n;
+  const abs = neg ? -y : y;
+  let digits = abs.toString();
+  if (digits.length < 4) digits = '0'.repeat(4 - digits.length) + digits;
+  return neg ? '-' + digits : digits;
+}
+
+function __tfnAdd1ms(c) {
+  // Mutates and returns c; c: {year,month,day,hour,minute,second,millis}
+  if (c.millis < 999) { c.millis++; return c; }
+  c.millis = 0;
+  if (c.second < 59) { c.second++; return c; }
+  c.second = 0;
+  if (c.minute < 59) { c.minute++; return c; }
+  c.minute = 0;
+  if (c.hour < 23) { c.hour++; return c; }
+  c.hour = 0;
+
+  const dim = __tfnDaysInMonth(c.year, c.month);
+  if (c.day < dim) { c.day++; return c; }
+  c.day = 1;
+  if (c.month < 12) { c.month++; return c; }
+  c.month = 1;
+  c.year = c.year + 1n;
+  return c;
+}
+
+function __tfnSub1ms(c) {
+  // Mutates and returns c; c: {year,month,day,hour,minute,second,millis}
+  if (c.millis > 0) { c.millis--; return c; }
+  c.millis = 999;
+  if (c.second > 0) { c.second--; return c; }
+  c.second = 59;
+  if (c.minute > 0) { c.minute--; return c; }
+  c.minute = 59;
+  if (c.hour > 0) { c.hour--; return c; }
+  c.hour = 23;
+
+  if (c.day > 1) { c.day--; return c; }
+  // move to previous month
+  if (c.month > 1) {
+    c.month--;
+  } else {
+    c.month = 12;
+    c.year = c.year - 1n;
+  }
+  c.day = __tfnDaysInMonth(c.year, c.month);
+  return c;
+}
+
+function __tfnMakeDateTimeLiteral(c, tz) {
+  const y = __tfnFormatYear(c.year);
+  const lex = `${y}-${__tfnPad2(c.month)}-${__tfnPad2(c.day)}T${__tfnPad2(c.hour)}:${__tfnPad2(c.minute)}:${__tfnPad2(c.second)}.${__tfnPad3(c.millis)}${tz}`;
+  return internLiteral(`"${lex}"^^<${XSD_NS}dateTime>`);
+}
+
+function __tfnComputePeriodBounds(parts) {
+  // Returns { tzMin, tzMax, startC, endC } where startC/endC are component objects.
+  const tzMin = parts.tz || '+14:00';
+  const tzMax = parts.tz || '-14:00';
+
+  if (parts.kind === 'dateTime') {
+    const base = {
+      year: parts.year,
+      month: parts.month,
+      day: parts.day,
+      hour: parts.hour,
+      minute: parts.minute,
+      second: parts.second,
+      millis: parts.millis,
+    };
+    return { tzMin, tzMax, startC: { ...base }, endC: { ...base } };
+  }
+
+  if (parts.kind === 'date') {
+    const startC = { year: parts.year, month: parts.month, day: parts.day, hour: 0, minute: 0, second: 0, millis: 0 };
+    const endC = { year: parts.year, month: parts.month, day: parts.day, hour: 23, minute: 59, second: 59, millis: 999 };
+    return { tzMin, tzMax, startC, endC };
+  }
+
+  if (parts.kind === 'gYearMonth') {
+    const dim = __tfnDaysInMonth(parts.year, parts.month);
+    const startC = { year: parts.year, month: parts.month, day: 1, hour: 0, minute: 0, second: 0, millis: 0 };
+    const endC = { year: parts.year, month: parts.month, day: dim, hour: 23, minute: 59, second: 59, millis: 999 };
+    return { tzMin, tzMax, startC, endC };
+  }
+
+  if (parts.kind === 'gYear') {
+    const startC = { year: parts.year, month: 1, day: 1, hour: 0, minute: 0, second: 0, millis: 0 };
+    const endC = { year: parts.year, month: 12, day: 31, hour: 23, minute: 59, second: 59, millis: 999 };
+    return { tzMin, tzMax, startC, endC };
+  }
+
+  return null;
+}
+
+function __tfnBindDefaultTimezone(timeLit, tzLit) {
+  if (!(timeLit instanceof Literal) || !(tzLit instanceof Literal)) return null;
+  const tz = __tfnParseTimezoneValue(tzLit);
+  if (!tz) return null;
+
+  const [lex, dt] = literalParts(timeLit.value);
+  if (!dt) return null;
+  const v = stripQuotes(lex);
+
+  // If already has tz, return unchanged.
+  if (__tfnHasTimezoneSuffix(v)) return timeLit;
+
+  // Only support the temporal types we parse.
+  if (
+    dt !== XSD_NS + 'dateTime' &&
+    dt !== XSD_NS + 'date' &&
+    dt !== XSD_NS + 'gYearMonth' &&
+    dt !== XSD_NS + 'gYear'
+  ) return null;
+
+  const outLex = `"${v}${tz}"^^<${dt}>`;
+  return internLiteral(outLex);
+}
+
 function parseDatetimeLike(t) {
   const d = parseXsdDateTerm(t);
   if (d !== null) return d;
@@ -4920,6 +5163,73 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return [];
   }
 
+// -----------------------------------------------------------------
+// 4.3.1 tfn: Time Functions builtins
+// -----------------------------------------------------------------
+
+// tfn:periodMinInclusive / periodMaxInclusive / periodMinExclusive / periodMaxExclusive
+// Schema: ( $s.1+ )+ tfn:* $o-
+const tfnPeriodKind =
+  pv === TFN_NS + 'periodMinInclusive'
+    ? 'minInc'
+    : pv === TFN_NS + 'periodMaxInclusive'
+      ? 'maxInc'
+      : pv === TFN_NS + 'periodMinExclusive'
+        ? 'minEx'
+        : pv === TFN_NS + 'periodMaxExclusive'
+          ? 'maxEx'
+          : null;
+if (tfnPeriodKind) {
+  if (!(g.s instanceof ListTerm) || g.s.elems.length !== 1) return [];
+  const arg = g.s.elems[0];
+  const parts = __tfnParseTemporalLiteralParts(arg);
+  if (!parts) return [];
+  const bounds = __tfnComputePeriodBounds(parts);
+  if (!bounds) return [];
+
+  let out;
+  if (tfnPeriodKind === 'minInc') {
+    out = __tfnMakeDateTimeLiteral({ ...bounds.startC }, bounds.tzMin);
+  } else if (tfnPeriodKind === 'maxInc') {
+    out = __tfnMakeDateTimeLiteral({ ...bounds.endC }, bounds.tzMax);
+  } else if (tfnPeriodKind === 'minEx') {
+    const c = __tfnSub1ms({ ...bounds.startC });
+    out = __tfnMakeDateTimeLiteral(c, bounds.tzMin);
+  } else { // maxEx
+    const c = __tfnAdd1ms({ ...bounds.endC });
+    out = __tfnMakeDateTimeLiteral(c, bounds.tzMax);
+  }
+
+  if (g.o instanceof Var) {
+    const s2 = { ...subst };
+    s2[g.o.name] = out;
+    return [s2];
+  }
+  if (g.o instanceof Blank) return [{ ...subst }];
+
+  const s2 = unifyTerm(g.o, out, subst);
+  return s2 !== null ? [s2] : [];
+}
+
+// tfn:bindDefaultTimezone
+// Schema: ( $s.1+ $s.2+ )+ tfn:bindDefaultTimezone $o-
+if (pv === TFN_NS + 'bindDefaultTimezone') {
+  if (!(g.s instanceof ListTerm) || g.s.elems.length !== 2) return [];
+  const [timeLit, tzLit] = g.s.elems;
+  const out = __tfnBindDefaultTimezone(timeLit, tzLit);
+  if (!out) return [];
+
+  if (g.o instanceof Var) {
+    const s2 = { ...subst };
+    s2[g.o.name] = out;
+    return [s2];
+  }
+  if (g.o instanceof Blank) return [{ ...subst }];
+
+  const s2 = unifyTerm(g.o, out, subst);
+  return s2 !== null ? [s2] : [];
+}
+
   // -----------------------------------------------------------------
   // 4.4 list: builtins
   // -----------------------------------------------------------------
@@ -6144,6 +6454,7 @@ function isBuiltinPred(p) {
     v.startsWith(LOG_NS) ||
     v.startsWith(STRING_NS) ||
     v.startsWith(TIME_NS) ||
+    v.startsWith(TFN_NS) ||
     v.startsWith(LIST_NS)
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.7.19",
+  "version": "1.7.20",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [