Documentation Index
Fetch the complete documentation index at: https://docs.twine.se/llms.txt
Use this file to discover all available pages before exploring further.
Some source systems don’t have first-class support for date-tracked values. They expose a single text field per property, but the business meaning is “this value applies from 2024-01-01” or “these two values apply to different time ranges”. The dated property pattern is a compact string format for packing that information into a single text field, which Twine then expands into a proper list of dated property entries.
The pattern is consumed by a pattern converter step on a property mapping: the raw source text is read, the converter parses it, and the resulting entries flow into the entity like any other dated property.
Builder
Fill in the fields below to compose a valid pattern. The generated string is shown underneath, together with the dated property entries it will produce.
A value on its own
The simplest pattern is just a value:
This becomes a single dated property entry with valid_from: null - meaning the value has been in effect since the beginning of time. This is appropriate for properties where history is not meaningful.
A value with a start date
Separate the value from its effective date with a comma:
The value takes effect on the given date and stays in effect indefinitely. Whitespace around the comma is optional: 50000, 2024-01-01 parses identically.
A value within a closed interval
Add an end date to describe a value that was only valid for a bounded period:
50000,2024-01-01,2024-12-31
value: null that signals the property is no longer active. This mirrors how closed intervals are represented throughout Twine.
| valid_from | value | meaning |
|---|
2024-01-01 | 50000 | value takes effect |
2025-01-01 | null | value is cleared from this day onward |
Querying the property at end_date + 1 will return the terminator, not the value. This is almost always what you want - but it surprises people the first time they see it.
valid_from: null plus a terminator on 2025-01-01.
Multiple values in a single pattern
Separate multiple values with / to describe a full history in one string:
45000,2022-06-01 / 50000,2024-01-01
valid_from in descending order (newest first) as part of its standard dated property handling. Whitespace around / is optional.
Grouping values with an ID
Some properties can hold several independent values at the same time - see properties with multiple simultaneous values. Attach an ID to each segment with # to keep those series apart:
premium,2023-01-01#benefit_001 / standard,2023-01-01#benefit_002
/, ,, or #. A single optional space is allowed between the date and the #:
premium,2023-01-01 #benefit_001
Value types
The parser recognises the following value forms and converts them to typed values. The first rule that matches is used.
| Form | Example | Parsed as |
|---|
| Integer | 50000, -1 | integer |
| Decimal | 2.5 | float |
| Percentage | 40%, 45.5% | float divided by 100 (0.4, 0.455) |
| Hours | 4h, 7.25H | float (hours as a decimal) |
| Hours and minutes | 4:30 | float (4.5) |
| Date (in value position) | 2020-01-01 | date |
| Quoted string | "hej baberiba" | string (quotes stripped) |
| Any other text | pending, grade_a | string |
, or /, since those are structural delimiters. Use a quoted string if the value needs to contain either of them, or leading or trailing whitespace:
"cost_center/eu",2024-01-01
" after the opening quote ends the string.
Dates in value position use strict YYYY-MM-DD form with literal dash separators. Dates in start or end position accept a few additional forms - see Date formats below. Decimal numbers and the comma separator
Comma is used both as a part delimiter and, in European conventions, as a decimal separator. The parser handles both, but the rule is subtle enough to be worth stating explicitly.
A comma decimal is only recognised when the number is followed by another comma or the end of input. In every other position, the comma is treated as a delimiter.
| Pattern | Result |
|---|
2,5 | float 2.5 |
2,5,2024-01-01 | float 2.5 with start date 2024-01-01 |
45,5% | float 0.455 |
. as the decimal separator - it is unambiguous everywhere. The builder above always emits dots.
In start and end position, dates accept three forms. All three validate the calendar: invalid combinations such as 2020-02-30 cause the whole pattern to fail.
| Form | Example | Notes |
|---|
| Dashed, four-digit year | 2020-01-02 | The canonical form |
| Space-separated or compact | 2020 01 02, 20240831 | Equivalent to the dashed form |
| Two-digit year | 20-01-02 | Interpreted as 2000 + yy, so 2020-01-02 |
Whitespace
Whitespace around / and , is ignored. Inside a value or an ID, whitespace is significant and must be wrapped in quotes if the grammar would otherwise stop at it.
The parser normalises these Unicode spaces to a regular ASCII space before parsing: U+00A0 (non-breaking space), U+2007 (figure space), U+2009 (thin space), U+202F (narrow no-break space), U+200B (zero-width space). This is useful when copy-pasting from sources that inject invisible spaces. Tabs and other Unicode whitespace are not normalised.
The whole pattern is trimmed before parsing.
What is not supported
- Tabs as whitespace, and Unicode whitespace beyond the normalised set above.
- Escape sequences inside quoted strings.
- Raw text values containing
, or / - use a quoted string.
- Negative percentages and negative hours.
- Times of day (
HH:MM:SS). HH:MM is accepted, but only as a duration.
- Datetimes.
- An end date without a start date in any form other than
value,,end_date.
Errors
A pattern either parses into a list of dated property entries or returns an error. Errors are always returned as values - the converter never raises.
Two kinds of errors can occur:
- Unparsed input - the parser consumed part of the input and then got stuck at a character it did not expect. The error points to the column where parsing halted.
- Invalid content - the grammar was satisfied but the content does not make sense, for example an invalid calendar date or a malformed number.
An empty or missing pattern is not an error: it produces an empty list of entries.
