Formal Specification and Documentation Using Z: a Text

A Text Formatting Tool (Case Study). Last updated: July 3, 1998

Z Z Z Z Z Z Z Z Z Z

Formal Speciﬁcation and Documentation using Z: A Case Study Approach

A Text Formatting Tool (Case Study)

Jonathan Bowen Department of Computer Science University of Reading

Email: [email protected]

URL:

http://www.comlab.ox.ac.uk/oucl/users/jonathan.bowen/zbook.html

A Text Formatting Tool

Simple text processing tool for UNIX called pos.

Allows left, centred and right justiﬁcation of lines.

Assumes an ASCII text ﬁle.

Tab characters and newline must be considered.

Cf. UNIX manual page

Basic Concepts

UNIX text ﬁles consist of ASCII characters. ] [ CHAR

space : CHAR seq

LINE == CHAR seq DOC == LINE

Repeating a sequence ]

(seq ) N ! seq

rep : X X

8 : seq ; : N

s X n 1

= hi ^

srep0

= ( 1)) srepn s (srep n

Some laws about rep:

seq ` 0 = hi

s : X srep

seq ` 1 =

s : X srep s

N ` hi = hi

n : rep n

seq ; : N ` #( ) = #

s : X n srepn s n

: seq ; : N ` ran( ) = ran

s X n 1 srepn s

seq ; : N ` 8 : N j <

s : X n m m n

) (# ) = (srepn after s m for n s

Processing the Input

Removing leading spaces from a line: !

clipleft : LINE LINE

= hi

clipleft hi

: j 6= hi

8 l LINE l

= ) = ^

head l 6 space clipleft l l

) = ( ) head l = space clipleft l clipleft tail l

Removing trailing spaces: !

clipright : LINE LINE

o o

= 9 clipright rev 9 clipleft rev

Removing leading and trailing spaces: !

clip : LINE LINE

o =

clip clipleft 9 clipright

Spaces may be removed in either order:

o o

` = 9 clipleft 9 clipright clipright clipleft

Indenting to a given column position:

Column alignment

: N ! !

left0 LINE LINE

: N ; :

8 n l LINE

= (h i )

left0 nl space rep n l

Centering a line:

: N ! !

centre0 LINE LINE

: N ; :

8 n l LINE

2 )

#l n

= (h i ( (# 2))) ^

centre0 nl space rep n l div l

> 2 )

#l n =

centre0 nl l

Right-alignment of a line:

: N ! !

right0 LINE LINE

: N ; :

8 n l LINE

# ) =

l n right0 nl

h i ( # )) ^

( space rep n l l

# > ) =

l n right0 nl l

Clipping lines ﬁrst:

left ;

centre;

N ! !

right : LINE LINE

: N ; :

8 n l LINE

= ( ) ^

left n l left0 n clip l

= ( ) ^

centre n l centre0 n clip l

= ( )

right n l right0 n clip l

Documents TEXT

text : DOC

Changes in this document:

= ^ TEXT TEXT TEXT

Change selected using an option:

Option ::= j LeftOption j CentreOption RightOption

POS0

TEXT :

option? Option

: N

column?

= )

option? LeftOption

= ( ?)

text text 9 left column

= )

option? CentreOption

= ( ?)

text text 9 centre column

= )

option? RightOption

= ( ?)

text text 9 right column

Implementation Details

Previous assumption: all printable characters of the same width.

Tabs

Horizontal tab:

tab : CHAR = tab 6 space

‘Tabulate’ to the next tab column position. N

tabsize : 1 tabsize >

Introduces additional complication into the speciﬁcation.

Split a sequence into a series of segments. ]

: (seq ) N ! seq(seq )

split X 1 X

8 : seq ; : N ; : seq (seq )

s X n 1 ss X

1 1 1

= hi ^

hi split n ,

s split n = ss

= ^

= ss s

8 : seq j 2 ran( ) # = ) ^

( t X t front ss t n

< #( ) 0 last ss n

Convert trailing spaces to a tab.

addtab : LINE LINE

: j 2= ran

8 l LINE tab l

= ^ #( ) < # 1) )

(#l tabsize clipright l l

( ) h i ^

addtab l = clipright l tab

6= _ #( ) # 1) ) (#l tabsize clipright l l

addtab l = l

Converting spaces to tabs

Convert spaces in a line to tabs where appropriate:

unexpand : LINE LINE

: j 2= ran

8 l LINE tab l

= = (( ) )

unexpand l l split tabsize 9 addtab

ooo Only use on lines not containing tabs.

Can only reduce the length of the line:

8 : j 2= ran #( ) # ` l LINE tab l unexpand l l

Converting tabs to spaces

First cut a sequence into segments (a sequence of

sequences) using another sequence (e.g., a tab): ]

(seq ) (seq ) !7 seq(seq )

cut : X X X

: seq ; ; : seq j : ( ( ))

8 p X s t X p front s p

= hi ^

hi cut p

= hi ) = h i ^

s 6 s cut p s

a a a a

) = h i ( ) (s p t cut p s p t cut p

Recombining the segments gives the original sequence:

: seq ` =( ) = a; b X a cut b a

A trailing tab can be substituted with spaces: !

addspace : LINE LINE

= hi

addspacehi

: j 6= hi

8 l LINE l )

last l = tab

( ) (h i

addspace l = front l space rep

+1 (# ))) ^

(tabsize l mod tabsize

= ) = last l 6 tab addspace l l

Expanding tabs to spaces !

expand : LINE LINE

8 l LINE

= =(( h i) )

expand l l cut tab 9 addspace

Properties of expanding lines

Expanding tabs to spaces can only increase the length:

` #( ) # l : LINE expand l l

Converting spaces to tabs and back gives the same line:

8 : j 2= ran ( ) = ` l LINE tab l expand unexpand l l

But converting tabs to spaces and back may not:

9 : ( ) 6= ` l LINE unexpand expand l l

Column width of a line

! N

width : LINE

8 l LINE

#( ) width l = expand l

Adding tabs does not affect the width of a line:

` ( ) = l : LINE width unexpand l width l

Lines

A non-empty unique newline character sequence may be

used to terminate lines: seq

nl : CHAR

; g; ran i disjoint hfspace tab nl

Under UNIX this sequence is the ASCII line-feed ‘control’ character.

ooo The characters should not occur within any line.

Combine a sequence of segments using another

sequence as a terminator: ]

(seq(seq )) (seq ) ! seq

comb : X X X

; : seq ; : seq (seq )

8 s p X ss X

= hi ^

hi comb p

i = ^

hs comb p s p

a a a

(h i ) = ) s ss comb p s p (ss comb p

ooo With a terminator rather than a separator, an empty

document and a single empty line can be distinguished:

seq ` hi = hi

p : X comb p

seq ` hhii = p : X comb p p

Separate a sequence into a series of segments using a

non-empty pattern. ]

(seq ) (seq ) ! seq(seq )

sep : X X X

: seq ; : seq ; : seq(seq )

8 s X p X ss X

1 ,

s sep p = ss ^

ss comb p = s

8 : seq j 2 ran : ( )) ( t X t ss p t

N.B.: the sequence to be separated must be terminated with the pattern or be empty to be valid.

Files

A UNIX ﬁle is implemented as a sequence of characters: seq FILE == CHAR

On input, several ﬁles can be combined with tabs converted to spaces:

PrePOS0

TEXT

: seq

input ? FILE

= (( = ?) )

text input sep nl 9 expand

Output of a single document

Optionally, spaces may be be converted to tabs where

possible. j Blanks ::= Yes No

PostPOS0 :

blanks? Blanks : output ! FILE

TEXT 0

= )

blanks? Yes

0 =

output ! text comb nl

= )

blanks? No

! = ( )

output text 9 unexpand comb nl

Combined new speciﬁcation for the behaviour of the tool:

= ^ ^

0 0 POS PrePOS0 POS PostPOS

Conclusion

Some differences with the actual pos tool.

Post hoc speciﬁcation Ð may be useful for re-engineering and documentation.

Reduction of ambiguity; reasoning about properties.

UNIX tool

Main differences:

Pos allows the positioning to be optionally determined by the position of the ﬁrst line in each input ﬁle.

Pos does not format lines with a ‘.’ in the ﬁrst column.

Only the leading spaces are converted to tabs on output by pos.

19 POS(1) UNIX Manual POS(1)

NAME pos Ð simple text column positioning SYNOPSIS pos [ Ðb ] [ column ] [ file ... ] DESCRIPTION Pos is a simple text formatter which reads the concatenation of input files (or standard input if none are given) and produces on standard output a version of its input with lines positioned according to the column parameter. Column is a number specifying a column position starting from column 1. If it is un- signed then text is centered about that position. If it is negative, -column then the left hand margin of the text is positioned at the specified column. If it is signed positive, +column then the right hand margin of the text is positioned at that column. If the column parameter is ‘–’, ‘+’or‘0’ then the positioning is calculated from the first line in each file. The default value for column is 40. All tabs are converted to spaces, although tabs are used for leading space where appropriate unless the Ðb option is used in which case only spaces are used on output. Interword spacing on each line is preserved. If a line is too long then it is simply outputted with its leading white spaces removed so that no non-blank text is lost. Lines starting with a ‘.’ are not formatted but are simply outputted as read. Pos is meant to format headings and other short pieces of text. For instance, within visual mode of the ex editor (e.g., vi) the command

!gpos will center a paragraph. AUTHOR Jonathan Bowen, University of Reading SEE ALSO colrm(1), expand(1), fmt(1), nroff(1) BUGS The program is designed to be simple and fast Ð for more complex operations, the standard text processors are likely to be more appropriate. Control characters other than tabs will confuse pos.