intervals

Commentary

added in 0.4.0

Invokes different functions according to the current wallclock time. This is useful when you want to change a generator's behavior depending on the time or day.

With this function, you specify intervals of time and the corresponding value to use if the current time is within the interval. Intervals are specified with UNIX Cron syntax, in pairs of Cron expression and values.

A few Cron expression examples:

• 0-29 1 * * * matches 1:00 - 1:29 AM of every day.
• * * * * 5 matches all day Friday.
• * 0-12 * 2 5 matches the first 12 hours of the day for all Friday's in Feburary.

UNIX Cron expressions have granularity down to the minute, so specifying 0-29 1 * * * captures all wallclock times >= 1:00 AM and strictly < 1:30 AM.

Within the intervals, Cron expressions are evaluated in the order they're specified, so if more than one expression matches, the earlier one is used.

If no Cron expressions match, then the defaultValue or defaultIndex will be used instead. defaultValue is a simple value to use instead. defaultIndex is the index of the array of Cron expressions, starting from 0. If both defaultValue and defaultIndex are provided, defaultValue is used.

---

Examples

Match an interval

This Cron expression matches every wallclock time, so the corresponding function is always called. In other words, the defaultValue is never used.

{
    "_gen": "intervals",
    "intervals": [
        [
            "* * * * *",
            {
                "_gen": "sequentialString",
                "expr": "event-~d"
            }
        ]
    ],
    "defaultValue": "fallback value"
}

[
    "event-0",
    "event-1",
    "event-2",
    "event-3",
    "event-4"
]

Fallback value

This Cron expression (all day Wednesday) doesn't match the wallclock time, so the fallback value is used.

{
    "_gen": "intervals",
    "intervals": [
        [
            "* * * * 3",
            {
                "_gen": "sequentialString",
                "expr": "event-~d"
            }
        ]
    ],
    "defaultValue": "fallback value"
}

[
    "fallback value",
    "fallback value",
    "fallback value",
    "fallback value",
    "fallback value"
]

Fallback index

None of these Cron expressions (all day Sunday, Monday, and Tuesday respectively) match the wallclock time so the fallback index is used. Index 1 corresponds to second element of the intervals.

{
    "_gen": "intervals",
    "intervals": [
        [
            "* * * * 0",
            50
        ],
        [
            "* * * * 1",
            60
        ],
        [
            "* * * * 2",
            70
        ]
    ],
    "defaultIndex": 1
}

[
    60,
    60,
    60,
    60,
    60
]

Multiple expressions

For convenience, you can specify multiple Cron expressions in a single line.

{
    "_gen": "intervals",
    "intervals": [
        [
            [
                "* * * * 4",
                "0-29 * * * *"
            ],
            50
        ],
        [
            "* * * * 2",
            20
        ]
    ],
    "defaultValue": 64
}

[
    50,
    50,
    50,
    50,
    50
]

Priority

When multiple Cron expressions match, the earlier one is used. Both of these Cron expressions match all times, so the first one gets used.

{
    "_gen": "intervals",
    "intervals": [
        [
            "* * * * *",
            50
        ],
        [
            "* * * * *",
            42
        ]
    ],
    "defaultValue": 64
}

[
    50,
    50,
    50,
    50,
    50
]

---

Specification

JSON schema

{
    "type": "object",
    "properties": {
        "defaultValue": {},
        "defaultIndex": {
            "type": "integer",
            "minimum": 0
        },
        "intervals": {
            "type": "array",
            "minItems": 1,
            "items": {
                "type": "array",
                "items": [
                    {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                },
                                "minItems": 1
                            }
                        ]
                    },
                    {}
                ]
            }
        }
    },
    "oneOf": [
        {
            "required": [
                "intervals",
                "defaultValue"
            ]
        },
        {
            "required": [
                "intervals",
                "defaultIndex"
            ]
        }
    ]
}