L3. Your own filter
Learn / L3
Goal: a program of about forty lines that composes with every other program on the machine.
What you need
L2: you can assemble, link and run a program.
This lesson builds by hand with nas and ld;
L5 hands that to make.
The file
The program reads one byte at a time with GETC until end of
file, raises it if it is a letter from a to z, and writes it with
PUTC.
examples/upcase/upcase.s — on the disk as /usr/src/examples/UPCASE/upcase.s*---------------------------------------------------------------
* upcase.s -- a filter: read stdin to EOF, raise a-z, write
* stdout.
*
* nas -o upcase.o upcase.s
* ld -o upcase upcase.o -L /usr/lib -l a
* ./upcase < /usr/man/ECHO
*
* GETC, PUTC and EXIT are liba's. GETC reads one byte from the
* fd in X and returns it in A; carry set means end of file.
* PUTC writes A to the fd in X.
*
* The test is made on the low seven bits, so it does not care
* whether the byte arrived as maux text (high bit set, lines
* ended by $8D) or as ProDOS-standard text (low ASCII, lines
* ended by $0D). Every byte that is not a-z goes out exactly
* as it came in, so the output has the same convention as the
* input. That is the README "Text" rule for a filter.
*
* Clearing bit 5 turns a into A in either polarity: $61 -> $41
* and $E1 -> $C1.
*---------------------------------------------------------------
rel
lst off
xc ;enable the 65C02 (bra)
GETC ext
PUTC ext
EXIT ext
put /usr/inc/sc.fd.equ
LOWA equ $61
LOWZ1 equ $7B ;one past z
SEVEN equ $7F
CASEBIT equ $DF ;clears bit 5
START ldx #FD_STDIN
jsr GETC
bcs :eof
pha
and #SEVEN
cmp #LOWA
bcc :keep
cmp #LOWZ1
bcs :keep
pla
and #CASEBIT
bra :emit
:keep pla
:emit ldx #FD_STDOUT
jsr PUTC
bra START
:eof lda #0
jsr EXIT
The session
The program is run three ways: with its input redirected from a file
(<), as the last stage of a pipe, and in the middle of one.
$ mkdir /tmp/l3 $ cd /tmp/l3 $ cp /usr/src/examples/UPCASE/upcase.s upcase.s $ nas -o upcase.o upcase.s nas: 36 bytes -> upcase.o $ ld -o upcase upcase.o -L /usr/lib -l a $ ./upcase < /usr/src/examples/HELLOSH/hello #!/BIN/SH ECHO HELLO, WORLD $ echo mixed Case 123 | ./upcase MIXED CASE 123 $ ls /bin | ./upcase | head -3 AS BASENAME BPATCH $ echo Hello | ./upcase | tr A-Z a-z hello
What just happened
A maux program has three files open when it starts: standard input (0),
standard output (1) and standard error (2), the constants FD_STDIN,
FD_STDOUT and FD_STDERR from /usr/inc/sc.fd.equ.
GETC takes the file number in X; the byte comes back in
A with the carry clear, and a set carry means end of file. The shell
connects those three files before the program starts, so upcase neither
knows nor cares whether its input is a file, a keyboard or another program.
The one subtle line is the test for a letter. maux writes text with the high bit
set and ends lines with $8D; a file that came from another Apple II
program has the high bit clear and ends lines with $0D. The program
tests only the low seven bits and passes every other byte through untouched, so it
gives back the convention it was given. That is the rule for every maux filter. The
session's second line is #!/BIN/SH because it is the shell script from
L1, raised.
You may notice the pipelines stop at three programs. A pipeline of four, such as
ls /bin | ./upcase | sort | head -3, prints
sh: syntax error: the shell holds at most three stages. Three is
enough for this lesson.
Try next
Make a second filter, downcase, by changing the range test and the bit
you clear. Which instruction changes? Which one sets a bit instead?
← Hello, world in assembly | All lessons | Shell scripting →