AtlatestRepositorysigil-doc

sigil-doc / tree / test / fixturespractical-sigil-chapter.txt

1Practical Sigil: Craft Useful Things with a Small, Powerful Scheme
2
3A Useful First Script
4
5The best first program is not a language demonstration. It is a small tool
6that removes a real irritation. In this chapter we will build todo-report.sgl,
7a command-line report that turns a plain text task list into a useful summary.
8The program is intentionally modest: read lines, recognize unfinished work,
9and print a compact report. That modesty lets us pay attention to the things
10that make a language pleasant in daily use: clear data flow, useful library
11procedures, honest errors, and a result you can immediately keep.
13[#first-script]
14A Useful First Script
16Create a file called tasks.txt. Each unfinished task begins with TODO, and each
17finished task begins with DONE. Real files are rarely perfect, so our script
18will ignore blank lines and preserve the text a person wrote. The important
19idea is to shape the problem as a pipeline: obtain text, split it into lines,
20select what matters, and render the answer. This is practical Scheme—small
21functions composed without ceremony.
23Save the following program as todo-report.sgl. Its compact surface is useful,
24but the point is not cleverness. Every name should make the next transformation
25obvious, 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)
34This script uses read-file-string for the boundary with the operating system,
35then ordinary list operations for the rest. Keeping the boundary narrow makes
36the program easy to test: a future version can move the filtering logic into a
37function that accepts lines directly. Notice that nothing here needs a class,
38framework, or configuration layer. The language stays close to the problem.
40Tip: run the script on a deliberately messy file. Add blank lines, Unicode such
41as καλημέρα, and a line that merely contains the word TODO. A useful tool must
42distinguish its tiny format from accidental text, and UTF-8 should feel normal,
43not like an advanced feature.
45[#change-the-question]
46Change the Question
48Once a small program works, its value comes from how readily it can answer the
49next question. Perhaps you want tasks grouped by project, a count of completed
50items, or an error when tasks.txt does not exist. Resist rebuilding everything.
51Extract one transformation, give it a precise name, and keep the input and
52output ordinary Sigil values. This is leverage: the first useful script becomes
53a vocabulary for the next one.
55Exercise change-the-question: add a command-line word that selects TODO or DONE.
56Validate the word before reading the file, keep the selection function pure,
57and print a short usage message for an unsupported value. Then add three small
58examples that cover an empty list, mixed tasks, and non-ASCII task text. The
59finished program should still fit comfortably on one screen.
61Return to the first script when the revised version starts to feel complicated.
62The goal is not to accumulate machinery; it is to preserve the direct line from
63an everyday question to a dependable answer. [->first-script]