Module blocks 

Time blocks: a task pinned to a time is an event in a calendar, tied to the task both ways (docs/tasks.md, “Pinned to a time”). An event shows in every calendar application, a phone’s too, and moves there like any other; a line of the task’s own would be Sioul’s alone, and a time on the task’s start breaks when its date asked is a date (RFC 5545 §3.8.2.3: servers that check, Sabre for Nextcloud, refuse the task).

• Written: the task’s title, kept in step; its start and end in UTC; busy (TRANSP:OPAQUE); X-SIOUL-TASK:<the task's UID> and an RFC 9253 link to it (LINK;LINKREL="…/block-of";VALUE=UID). The task links back (…/time-block), to its current block only: a task that comes back every week would gather a link a week. No alarm unless Tasks ⚙ asks for one: Sioul reminds of a block as of any event, and a phone would remind twice.
• Read: the block of a task known here is the task’s time, never an event of its own to the plan, the day or the record (without_blocks). A task is pinned to its first block still to come (Blocks::of); over, a block pins nothing and stays as it was, nothing said of it. A block whose task is not known here (not come yet, deleted elsewhere) is an event like any other.
• A repeating task: a block pins one turn (X-SIOUL-TURN, that turn’s date when it was pinned); once that turn is done, it pins no other.
• Set right (upkeep), only when something differs: a block not begun of a task done or dropped goes, its time freed; one under way ends then; one over stays, the record of when the work was done. One not begun of a turn done elsewhere goes. One to come takes its task’s title again.

Structs

Blocks

The blocks read, sorted out: where each task is pinned, and what held the work of a task done.

Pin

Where a task is pinned: its block, and the day it is on.

Enums

Closing

What becomes of a block once its task is done, dropped or left to the plan.

Fix

Something to set right in a block (upkeep).

Place

Where a task’s blocks go.

Constants

AHEAD_DAYS

How far ahead blocks are read in their own calendars: as far as the plan lays tasks.

ALARM_BEFORE

A block’s alarm, when Tasks ⚙ asks for one: five minutes before it starts.

BLOCK_OF

The link from a block to its task (RFC 9253 §6.3: LINKREL takes a registered relation or a URI; a tag URI, RFC 4151, as task kinds are).

CALENDAR

The calendar made for blocks at first use, the same on every device: its folder here and its address on the server (made with MKCALENDAR at the next sync; one another device made already counts as made).

SHORTEST

The least a block lasts, in minutes.

TASK

The task a block is the time of, by its UID, in the block.

TIME_BLOCK

The link from a task to its block.

TURN

The turn of a repeating task a block pins: its date asked, else its day to start, as they were when it was pinned (“2026-10-09”).

Functions

calendars

The calendars blocks are looked for in, beyond the four weeks of events the plan reads: the one chosen for them (chosen, “account/id”), and those made for them, on every account.

closing

What becomes of a block from start to end when its task is done, dropped or left to the plan at at (Unix seconds).

default_minutes

A block’s length by default, in minutes: what the plan lays for the task (laid: its corrected estimate, less the time spent, with its margins), its margins aside; else its estimate, else default_estimate. By whole five minutes, a quarter of an hour at least.

ended

The block ending at end, its start as it is.

given_times

Times given by a drag before blocks (X-SIOUL-AT) still to honour, each to become a block once: an open task’s, for today or later, as (task, its start in Unix seconds), in zone.

is_block_link

Whether a task’s link is to a block of its.

known 🔒

The UIDs of the tasks known here.

make_calendar

The calendar for blocks made on account (“local”: this device only), named name in your language; the next sync makes it on the server.

moved

The block moved to start..end, as a drag in the agenda moves an event (agenda::moved): what Sioul does not edit is kept (an alarm another application added). A block another application made repeat moves its first time only.

new_block

A new block for task, start to end (Unix seconds), with its own uid; an alarm five minutes before it when asked (alarm), else none.

of_a_turn_done 🔒

A block of a turn done since: the task’s turn is later than the one it pinned (a turn done moves the dates on, never back).

one_line 🔒

A value written as it is: no line break nor other control character.

place_for

Where a task’s blocks go: the calendar chosen in Tasks ⚙ (chosen, “account/id”) while it can be written and takes events; else the one made for them on the account of the task’s list (list_account), or on this device when that list is kept here or its account makes no calendar from Sioul (makes: Google’s makes none).

read

The blocks of calendars between from and to (Unix seconds); times without a zone in zone.

task_link

The task’s link to its block.

task_pinned

The task’s text pinned to the block uid, or to none: its links to blocks made that one alone, and a time given by a drag before blocks (X-SIOUL-AT) taken out; the text as it was when nothing changes.

titled

The block titled as its task (SUMMARY, its stamps and SEQUENCE moved on); None when it is already (its line as Sioul writes it, or read the same), or holds no event: never written twice for one title.

turn_of

The turn of a repeating task a block made now pins: its date asked, else its day to start (“2026-10-09”); “” for a task that does not come back.

turned

The block pinning another turn of its repeating task (X-SIOUL-TURN: its dates changed in Sioul, the block follows them); “” for none.

upkeep

What to set right in blocks as of now, by file: the blocks of a task done (from when it was done) or dropped (from now), as closing says; a block not begun of a turn done elsewhere goes; one to come of an open task takes its title again. Nothing for a block of a task unknown here, nor for one another application made repeat. Each file once.

utc 🔒

without_blocks

The events without the blocks of the tasks known here: what holds time as an event, to the plan, the day and the record. A block is its task’s time.