Documentation
¶
Overview ¶
Package task implements nt's todo.txt task model with the lossless round-trip guarantee from SPEC §4: a file is parsed into an ordered list of nodes (each a parsed task or a preserved raw line), and an unmodified line is re-emitted byte-for-byte. Only when a task is mutated do we re-render it from structured fields, touching only the tokens nt owns and preserving any unknown key:value tokens another todo.txt client may have written.
Index ¶
- func BlockedIDs(tasks []*Task) map[string]bool
- func EffectiveStatus(t *Task, isBlocked bool) string
- func IsPositional(handle string) bool
- func SortByUrgency(ts []*Task)
- func Urgency(t *Task) float64
- type Doc
- func (d *Doc) Append(t *Task)
- func (d *Doc) FindByID(id string) *Task
- func (d *Doc) Remove(id string) (before string, ok bool)
- func (d *Doc) Render() []byte
- func (d *Doc) ReplaceByID(id string, t *Task) bool
- func (d *Doc) Resolve(handle string) (t *Task, ambiguous bool)
- func (d *Doc) Tasks() []*Task
- type Node
- type Task
- func (t *Task) AddLink(target string)
- func (t *Task) Blocks() string
- func (t *Task) Discovered() string
- func (t *Task) Due() string
- func (t *Task) EnsureID()
- func (t *Task) ID() string
- func (t *Task) Line() string
- func (t *Task) Links() []string
- func (t *Task) Parent() string
- func (t *Task) Projects() []string
- func (t *Task) Recur() string
- func (t *Task) SetDone(done bool, today string)
- func (t *Task) SetKey(key, val string)
- func (t *Task) SetPriority(p byte)
- func (t *Task) SetState(s string)
- func (t *Task) SetText(s string)
- func (t *Task) Source() string
- func (t *Task) State() string
- func (t *Task) Status() string
- func (t *Task) Tags() []string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BlockedIDs ¶
BlockedIDs returns the set of task ULIDs that are blocked by an open task (SPEC §9). A task B with `blocks:X` blocks task X for as long as B is not done; X is then hidden from default listings.
func EffectiveStatus ¶
EffectiveStatus is the display status accounting for dependency blocking: a not-done task that is the target of an open blocker shows as "blocked" even without an explicit s:blocked marker.
func IsPositional ¶
IsPositional reports whether a handle is a positional "task:N" / "N" reference rather than a stable ULID — so adapters can refuse it from non-interactive callers, where the list index may have shifted between read and act (§7.2).
func SortByUrgency ¶
func SortByUrgency(ts []*Task)
SortByUrgency orders tasks most-urgent first (stable).
Types ¶
type Doc ¶
type Doc struct {
Nodes []Node
// contains filtered or unexported fields
}
Doc is an ordered list of nodes — the in-memory model of a tasks file. It preserves line order and the file's trailing-newline state so an unmodified document renders byte-identically (SPEC §4).
func (*Doc) Append ¶
Append adds a task as a new node. If the document is non-empty and lacks a trailing newline, one is added first so the new task starts on its own line.
func (*Doc) Remove ¶
Remove deletes the node holding the task with id, returning the removed task's raw line (its before-image) for the undo journal.
func (*Doc) ReplaceByID ¶
ReplaceByID swaps in a new task for the node with the given id, returning false if no such task exists.
type Node ¶
Node is one line of the file: a parsed Task, or a preserved raw line (blank lines, comments, anything that isn't a task). Exactly one field is set.
type Task ¶
type Task struct {
Done bool
Priority byte // 0, or 'A'..'Z'
Completed string // YYYY-MM-DD or ""
Created string // YYYY-MM-DD or ""
Text string // description, including inline +project / @tag / [[link]]
// contains filtered or unexported fields
}
Task is a single todo.txt line, parsed.
func CompletedSince ¶
CompletedSince returns the completed tasks, newest completion first, optionally bounded to those completed on or after `since` (a YYYY-MM-DD date; "" = no bound). This is the core rule behind both the TUI Logbook and `nt log`, so the ordering and the meaning of "completed" live in the domain, not an adapter.
A since bound excludes tasks with no completion date (an empty date sorts before any real one), which is the desired behaviour for "what did I finish in the last N days".
func New ¶
New builds a fresh task with a ULID. Callers add text/metadata then it is appended to a Doc.
func ParseLine ¶
ParseLine parses a single line into a Task (raw, unmodified). Used by the undo engine to restore a before-image so it renders byte-identically.
func SpawnNext ¶
SpawnNext builds the next occurrence of a recurring task (SPEC §9). The new task copies the description, priority, recurrence, and source, gets a fresh ULID, and advances the due date by the recurrence period. Call it while the original is still open (before SetDone moves the priority to a pri: key).
func (*Task) Discovered ¶
Discovered is the ULID of the task this one was discovered while working on — provenance for work an agent surfaced mid-task (key: discovered:<ULID>).
func (*Task) EnsureID ¶
func (t *Task) EnsureID()
EnsureID assigns a ULID if the task lacks one (SPEC §4: hand-added lines get an id on the next mutation that touches them).
func (*Task) Line ¶
Line returns the on-disk representation: the original raw line when unmodified, or a freshly rendered canonical line when mutated.
func (*Task) SetDone ¶
SetDone toggles completion. Marking done preserves any (A) priority as a pri:A key (SPEC §4); reopening restores it.
func (*Task) SetPriority ¶
SetPriority sets (0 clears) the priority. No-op on done tasks beyond storing the pri key.
func (*Task) SetState ¶
SetState sets s:doing / s:blocked, or clears it for "open". "done"/"" are handled via SetDone by the caller.
Source Files