maux
Star on GitHub Buy me a coffee

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 →