AtlatestRepositorysigil-doc
1
Practical Sigil: Craft Useful Things with a Small, Powerful Scheme3
A Useful First Script5
The best first program is not a language demonstration. It is a small tool6
that removes a real irritation. In this chapter we will build todo-report.sgl,7
a command-line report that turns a plain text task list into a useful summary.8
The program is intentionally modest: read lines, recognize unfinished work,9
and print a compact report. That modesty lets us pay attention to the things10
that make a language pleasant in daily use: clear data flow, useful library11
procedures, honest errors, and a result you can immediately keep.13
[#first-script]14
A Useful First Script16
Create a file called tasks.txt. Each unfinished task begins with TODO, and each17
finished task begins with DONE. Real files are rarely perfect, so our script18
will ignore blank lines and preserve the text a person wrote. The important19
idea is to shape the problem as a pipeline: obtain text, split it into lines,20
select what matters, and render the answer. This is practical Scheme—small21
functions composed without ceremony.23
Save the following program as todo-report.sgl. Its compact surface is useful,24
but the point is not cleverness. Every name should make the next transformation25
obvious, and the whole program should remain easy to change six months later.27
(import (sigil core) (sigil fs))28
(define lines (string-split (read-file-string "tasks.txt") "\n"))29
(define todos (filter (lambda (line) (string-prefix? "TODO " line)) lines))30
(display (string-append "Open tasks: " (number->string (length todos))))31
(newline)32
(for-each (lambda (line) (display (string-append "- " line "\n"))) todos)34
This script uses read-file-string for the boundary with the operating system,35
then ordinary list operations for the rest. Keeping the boundary narrow makes36
the program easy to test: a future version can move the filtering logic into a37
function that accepts lines directly. Notice that nothing here needs a class,38
framework, or configuration layer. The language stays close to the problem.40
Tip: run the script on a deliberately messy file. Add blank lines, Unicode such41
as καλημέρα, and a line that merely contains the word TODO. A useful tool must42
distinguish its tiny format from accidental text, and UTF-8 should feel normal,43
not like an advanced feature.45
[#change-the-question]46
Change the Question48
Once a small program works, its value comes from how readily it can answer the49
next question. Perhaps you want tasks grouped by project, a count of completed50
items, or an error when tasks.txt does not exist. Resist rebuilding everything.51
Extract one transformation, give it a precise name, and keep the input and52
output ordinary Sigil values. This is leverage: the first useful script becomes53
a vocabulary for the next one.55
Exercise change-the-question: add a command-line word that selects TODO or DONE.56
Validate the word before reading the file, keep the selection function pure,57
and print a short usage message for an unsupported value. Then add three small58
examples that cover an empty list, mixed tasks, and non-ASCII task text. The59
finished program should still fit comfortably on one screen.61
Return to the first script when the revised version starts to feel complicated.62
The goal is not to accumulate machinery; it is to preserve the direct line from63
an everyday question to a dependable answer. [->first-script]