Source Code 1992 March/Source_Code_CD-ROM_Walnut_Creek_March_1992.iso/usenet/altsrcs/1/1440

Internet Message Format | 1990-12-28 | 54.4 KB

From: [e-mail] (Istvan Mohos)
Newsgroups: alt.sources
Subject: Subject: ILIB Unix Toolkit in C
Message-ID: <[e-mail]>
Date: 8 Jun 90 20:57:45 GMT


---- Cut Here and unpack ----
#!/bin/sh
# This is part 07 of a multipart archive
if touch 2>&1 | fgrep '[-amc]' > /dev/null
 then TOUCH=touch
 else TOUCH=true
fi
# ============= iman/ifamily.tex ==============
echo "x - extracting iman/ifamily.tex (Text)"
sed 's/^X//' << 'SHAR_EOF' > iman/ifamily.tex &&
X% XREF ifamily igroup inumstrcmp
X
X\def\name{IFAMILY}
X\def\IT{{\bb ifamily()}}
X
X\S{NAME}
X{\bb ifamily} --- tell whether two alhanumeric strings are related
X
X{\bb igroup} --- compute places for separators in string lists
X
X{\bb inumstrcmp} --- alphanumeric comparison of two strings
X
X\S{SYNOPSIS}
X\settabs\+{\bb mdefine SHORTUPMO} & mmm &\cr
X\+{\bb\#define SPACE\_LINE}&\hfill {\bb--1}\cr
X\+{\bb\#define LINE\_ONLY}&\hfill {\bb 0}\cr
X\+{\bb\#define LINE\_SPACE}&\hfill {\bb 1}\cr
X\L
X{\obeylines \bb
Xint
Xifamily (ptr1, ptr2)
Xchar *ptr1;
Xchar *ptr2;
X\L
Xint
Xigroup (ptr1, ptr2, modval)
Xchar *ptr1;
Xchar *ptr2;
Xint modval;
X\L
Xint
Xinumstrcmp (ptr1, ptr2)
Xchar *ptr1;
Xchar *ptr2;
X}
X
X\S{DESCRIPTION}
XAlphanumeric ordering of strings is an important capability in
Xthe fields of electronic design and logic simulation.
XPoints of interface to integrated circuits (IC legs or {\myit pins\/})
Xtypically are labeled with a name that begins with a leading
Xalphabetic string, continues with a string of digits, and sometimes
Xends with another alphabetic string.
XIndividual {\myit pin\/} names
Xwithin groups of functionally related names are made distinct
Xby the integer value embedded in otherwise identical labels.
XGroups of related {\myit pins\/} form a {\myit bus\/}.
XMotorola's ``68000'' integrated circuits for example, interface
Xwith their electronic environment through an {\myit address bus\/}
Xof 23 pins labeled {\myit A1\/} through {\myit A23\/}, a
X{\myit data bus\/}
Xof 16 pins labeled {\myit D0\/} through {\myit D15\/}, a set of
X{\myit interrupt lines\/} named
X{\myit IPL0N\/} through {\myit IPL2N\/}, among other {\myit buses\/}
Xand functionally discreet terminals.
X\L
XThe generic Unix toolset
Xtends to overlook the somewhat specialized problem of alphanumeric
Xordering.  The shell's own
Xfilename order leaves things to be desired if the names
Xcontain multi-byte embedded digit strings: {\myit foo11\/} will
Xfollow {\myit foo1\/}, and {\myit foo2\/} will only appear when
Xall the embedded ``tens'' have been listed.  The ILIB
Xfunctions \IT, {\bb igroup()} and {\bb inumstrcmp} round out the
Xstring ordering capabilities of the standard functions.
XThis supplemental set also includes {\bb inumsort()}
Xand {\bb inumsearch()} described under {\myit isort()\/} and
X{\myit isearch()\/}, respectively.
X\L
X\IT\ returns TRUE or FALSE to indicate whether
Xthe two null terminated parameter stings
Xare ``related''.  \IT\ considers
Xtwo strings related if either they are identical, or if
Xthe first numerical digit (0-9) in both strings is preceded by
Xidentical leading sub-strings.  For example,
X\smallskip
X\settabs\+ ABCDEFGHIJKLMN & andand & ABCDEFGHIJ &\cr
X
X\+\qquad \dx{abc} & and & \dx{abcd} & are not related,\cr
X\smallskip
X\+\qquad \dx{-+ =123oooo} & and & \dx{-+ =7xxxxx} & are related,\cr
X\smallskip
X\+\qquad \dx{testing123} & and & \dx{testing} & are not related,\cr
X\smallskip
X\+\qquad \dx{7 brides for} & and & \dx{7 brothers} & are related.\cr
X\L
XDuring the evaluation process, \IT\ compares
Xeach successive non-digit character beginning
Xat {\myit ptr1\/} to the same-position
Xcharacter beginning at {\myit ptr2\/}.
XIf the (non-digit) characters don't match, the
Xtwo strings are not related, and the function returns FALSE.
XIf the pointers reach a digit (0-9) simultaneously,
Xthe strings are related, and the function returns TRUE.
XIf same-length, non-digit strings end without a mismatch,
Xthe relation is TRUE.
X\L
X\IT\ considers address~0 ({\myit (char~*)NULL\/}) passed for
Xeither {\myit ptr1\/} or {\myit ptr2\/} an error; and will
Xretaliate by calling
X{\myit ierror()\/} and returning the negative {\myit sys\_nerr\/}.
X\L
X{\bb inumstrcmp} performs a more detailed evaluation of the
Xtwo strings than \IT\ does, returning ``1'' if the
Xstring pointed to by {\myit ptr1\/}
Xis ``alphanumerically'' greater than the string at {\myit ptr2\/};
Xreturning ``-1'' if the second string is greater than the first;
Xand returning ``0'' if the strings are equivalent.
X\L
XThe comparison proceeds byte-by-byte, form left to right.  If
Xthe next examined byte of both strings is a {\myit digit\/},
Xthe {\myit atoi()\/} function is utilized for converting
Xthe encountered digit strings to numbers.
XThe actual digit sub-strings are skipped, and the numerical
Xvalues returned by {\myit atoi()\/} are compared instead.  If these
Xnumbers are identical, the process continues at the
Xnext non-digit bytes.  A not obvious outcome of this process
Xis a blindness toward leading zero digits:
X``agent 007'' is totally indistinguishable for example, from
X``agent 7''.
X\L
XIdentically to \IT, {\bb inumstrcmp()} considers the NULL pointer
Xpassed as {\myit ptr1\/} or {\myit ptr2\/} an error.
X\L
XThe {\bb igroup()} function is a {\myit formatting aid\/}, not
Xparalleling the functionality of any standard library routine.
X{\bb igroup()} computes punctuation for elements of an ordered
Xlist of strings.
XThe list is assumed to contain an arbitrary number of
X{\myit families\/} of alphanumerically related items, as well as
Xdiscreet strings not related to other strings in the list.
X{\myit Family members\/} are assumed to hold adjacent positions in
Xthe list.  The question
X{\bb igroup()} attempts to answer is how to break up the list into
Xsmaller parts for visual display, while retaining the sense of
Xrelations within families, and separating unrelated list items from
Xfamily groups.
XThe printing routine that makes use of the results from
X{\bb igroup()} is assumed to insert extra {\myit white space\/}
Xbetween the computed list segments.
X\L
XThe simplest rule of
X{\bb igroup()} prescribes the separation of
Xsuccessive {\myit unrelated\/} strings of the list at
X{\myit modval\/} intervals, and also, separating
Xsuccessive {\myit related\/} strings at {\myit modval\/} intervals.
XAnother rule forces the immediate completion of a segment and the
Xstarting of a new segment if either the last item (already part of
Xthe current
Xsegment) or the next item evaluated, belongs in a {\myit family\/}
Xbut the other doesn't.
XA third rule causes completion of a segment and the starting of a
Xnew segment if the last item already part of the current segment
Xbelongs to a different {\myit family\/} then the next string of the
Xlist.
X\L
XThe mechanics of {\bb igroup()} require a succession of calls to
X{\bb igroup()} with {\myit ptr1\/} set to the next item of the list,
Xand {\myit ptr2\/} set to the next item after the one dereferenced by
X{\myit ptr1\/}.  In effect,
X{\myit ptr2\/} provides ``look-ahead'' capability in the list,
Xallowing a determination of whether or not the new string at
X{\myit ptr1\/} will prove to be a member of a family just ahead.
XAt the end of the call sequence to
X{\bb igroup()}, a zero length string or
Xa {\myit (char~*)NULL\/} should be passed for
X{\myit ptr2\/}, as a {\myit sentinel\/} value informing
X{\bb igroup()} that the list has ended.  Since the call sequence
Xalmost invariably is coded as a {\myit loop\/}, it is easiest
Xto just allocate an extra last pointer in the list of pointers
Xdereferencing the strings of the to-be-formatted list, and set this
Xlast pointer to NULL.  The iteration count of the loop can then be
Xone less than the total number of pointers in the list.
X\L
XSimilarly to acquiring look-ahead information,
X{\bb igroup()} retains the memory of the characteristics of the
Xtoken evaluated during the previous call, to ascertain whether or
Xnot the current item is related to the previous one.
XThis internal memory makes
X{\bb igroup()} a {\myit dynamic\/} function.  At the first call,
Xthe {\bb igroup()} state machine automatically comes to life
Xin its initial, ``start'' state.  At the last call
X(when {\myit (char~*)NULL\/} or a zero length string
Xis passed for {\myit ptr2\/}), the
Xstate machine is cleared in preparation for a restart with
Xanother list.  To abort the current list,
X{\myit (char~*)NULL\/} or \key{""} may be passed for
X{\myit ptr1\/} instead;
Xthis also clears the state machine but skips the computation of
Xspacing.
X\L
X{\bb igroup()} returns
XSPACE\_LINE, LINE\_ONLY or LINE\_SPACE.  The
Xthree integer alternatives are defined
Xin {\myit ilib.h\/}.
XSPACE\_LINE indicates that the existing cluster of strings
Xshould be completed and output, followed by extra {\myit white space\/},
Xand that the string dereferenced by {\myit ptr1\/} should begin
Xa new cluster.  LINE\_ONLY recommends that the string of
X{\myit ptr1\/} should be added to the segment currently under
Xconstruction, with no extra
X{\myit white space\/} either before or after the string.
XLINE\_SPACE suggests that the string at
X{\myit ptr1\/} should be added to the current cluster, and then
Xseparated from future strings by extra
X{\myit white space\/}.
XDuring the succession of calls, redundant spacing will be never be
Xproduced: SPACE\_LINE will never follow LINE\_SPACE.
X
X\S{group PROGRAM EXAMPLE}
XAlphanumeric labeling (for example of stars, stadium seats, or
Xelectronic component terminals)
Xrequires word ordering
Xwith alphabetic substrings sorted
Xin alphabetical order, and numerical substrings in numerical
X(decimal) order.
XThe {\bb group} program reads a single file
X(or \stin\ if no file name is given),
Xand writes the alphanumerically sorted lines of the input, to
X\stout.  In addition to sorting the lines to alphanumeric order,
Xthe program also organizes lines into related groups according to
Xthe rules of {\bb igroup()} given above; printing an extra
X{\myit linefeed\/} to partition the output.
X\L
XA mandatory number following the command name on the command line
Xspecifies the maximum number of lines that may comprise a group;
Xif this number is ``1'' the sorted lines are output without
Xseparation.  The input list is sorted into reverse order
Xif the number following the command name is prepended with a dash
X(minus).
XThe maximum size of the input is a function of the
Xavailable dynamic memory:
Xthe entire input is read into core before the sorting commences.
XIn addition to buffer space, a lesser
Xamount of memory is allocated for the list of pointers dereferencing
Xthe individual lines.
X
X\S{OUTPUT EXAMPLE}
XThe command
X\smallskip
X\I{\mytt
Xgroup 5 area.lis | pr -5 -l33 -t}
X\smallskip
Xtakes an unsorted list of {\myit area codes\/} in {\myit area.lis\/},
Xalphanumerically sorts the lines of the list and inserts blank lines
Xat least as often as every five lines (according to the {\bb igroup}
Xrules), then formats the list into five columns with the Unix
X{\myit pr\/}:
X\L
X{\obeylines \mytt
XAK\ \ \ 907\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ MICH\ 313\ \ \ \ \ \ NY\ \ \ 212\ \ \ \ \ \ TEX\ \ 214
XALA\ \ 205\ \ \ \ \ \ IA\ \ \ 319\ \ \ \ \ \ MICH\ 517\ \ \ \ \ \ NY\ \ \ 315\ \ \ \ \ \ TEX\ \ 409
XARK\ \ 501\ \ \ \ \ \ IA\ \ \ 515\ \ \ \ \ \ MICH\ 616\ \ \ \ \ \ NY\ \ \ 516\ \ \ \ \ \ TEX\ \ 512
XAZ\ \ \ 602\ \ \ \ \ \ IA\ \ \ 712\ \ \ \ \ \ MICH\ 906\ \ \ \ \ \ NY\ \ \ 518\ \ \ \ \ \ TEX\ \ 713
X\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ NY\ \ \ 607\ \ \ \ \ \ TEX\ \ 806
XCA\ \ \ 209\ \ \ \ \ \ IDA\ \ 208\ \ \ \ \ \ MINN\ 218
XCA\ \ \ 213\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ MINN\ 507\ \ \ \ \ \ NY\ \ \ 716\ \ \ \ \ \ TEX\ \ 817
XCA\ \ \ 408\ \ \ \ \ \ ILL\ \ 217\ \ \ \ \ \ MINN\ 612\ \ \ \ \ \ NY\ \ \ 718\ \ \ \ \ \ TEX\ \ 915
XCA\ \ \ 415\ \ \ \ \ \ ILL\ \ 309\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ NY\ \ \ 914
XCA\ \ \ 619\ \ \ \ \ \ ILL\ \ 312\ \ \ \ \ \ MISS\ 601\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ UT\ \ \ 801
X\ \ \ \ \ \ \ \ \ \ \ \ \ \ ILL\ \ 618\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ OH\ \ \ 216
XCA\ \ \ 707\ \ \ \ \ \ ILL\ \ 815\ \ \ \ \ \ MO\ \ \ 314\ \ \ \ \ \ OH\ \ \ 419\ \ \ \ \ \ VA\ \ \ 703
XCA\ \ \ 714\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ MO\ \ \ 417\ \ \ \ \ \ OH\ \ \ 513\ \ \ \ \ \ VA\ \ \ 804
XCA\ \ \ 805\ \ \ \ \ \ IND\ \ 219\ \ \ \ \ \ MO\ \ \ 816\ \ \ \ \ \ OH\ \ \ 614
XCA\ \ \ 818\ \ \ \ \ \ IND\ \ 317\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ VT\ \ \ 802
XCA\ \ \ 916\ \ \ \ \ \ IND\ \ 812\ \ \ \ \ \ MONT\ 406\ \ \ \ \ \ OKLA\ 405
X\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ OKLA\ 918\ \ \ \ \ \ WASH\ 206
XCOLO\ 303\ \ \ \ \ \ KANS\ 316\ \ \ \ \ \ NC\ \ \ 704\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ WASH\ 509
XCOLO\ 719\ \ \ \ \ \ KANS\ 913\ \ \ \ \ \ NC\ \ \ 919\ \ \ \ \ \ OREG\ 503
X\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ WIS\ \ 414
XCONN\ 203\ \ \ \ \ \ KY\ \ \ 502\ \ \ \ \ \ NDAK\ 701\ \ \ \ \ \ PA\ \ \ 215\ \ \ \ \ \ WIS\ \ 608
XDC\ \ \ 202\ \ \ \ \ \ KY\ \ \ 606\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ PA\ \ \ 412\ \ \ \ \ \ WIS\ \ 715
XDEL\ \ 302\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ NEB\ \ 308\ \ \ \ \ \ PA\ \ \ 717
X\ \ \ \ \ \ \ \ \ \ \ \ \ \ LA\ \ \ 318\ \ \ \ \ \ NEB\ \ 402\ \ \ \ \ \ PA\ \ \ 814\ \ \ \ \ \ WVA\ \ 304
XFLA\ \ 305\ \ \ \ \ \ LA\ \ \ 504\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ WYO\ \ 307
XFLA\ \ 407\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ NEV\ \ 702\ \ \ \ \ \ PUER\ 809
XFLA\ \ 813\ \ \ \ \ \ MASS\ 413\ \ \ \ \ \ NH\ \ \ 603\ \ \ \ \ \ RI\ \ \ 401
XFLA\ \ 904\ \ \ \ \ \ MASS\ 508\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ SC\ \ \ 803
X\ \ \ \ \ \ \ \ \ \ \ \ \ \ MASS\ 617\ \ \ \ \ \ NJ\ \ \ 201\ \ \ \ \ \ SDAK\ 605
XGA\ \ \ 404\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ NJ\ \ \ 609
XGA\ \ \ 912\ \ \ \ \ \ MD\ \ \ 301\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ TENN\ 615
X\ \ \ \ \ \ \ \ \ \ \ \ \ \ ME\ \ \ 207\ \ \ \ \ \ NMEX\ 505\ \ \ \ \ \ TENN\ 901
XHAW\ \ 808
X\smallskip}
X
X\S{group.c PROGRAM TEXT}
X\listing{../iex/group.c}
X\eject
SHAR_EOF
$TOUCH -am 0607105490 iman/ifamily.tex &&
chmod 0644 iman/ifamily.tex ||
echo "restore of iman/ifamily.tex failed"
set `wc -c iman/ifamily.tex`;Wc_c=$1
if test "$Wc_c" != "13518"; then
    echo original size 13518, current size $Wc_c
fi
# ============= iman/ifilter.tex ==============
echo "x - extracting iman/ifilter.tex (Text)"
sed 's/^X//' << 'SHAR_EOF' > iman/ifilter.tex &&
X% XREF ifilter
X
X\def\name{IFILTER}
X\def\IT{{\bb ifilter()}}
X
X\S{NAME}
X{\bb ifilter} --- read file or \stin\ into buffer at mallocp,
Xreturn buffer size
X
X\S{SYNOPSIS}
X{\obeylines \bb
Xint
Xifilter (fname, mallocp)
Xchar *fname;
Xchar **mallocp;
X}
X
X\S{DESCRIPTION}
XAn alternate to the {\myit iread()\/} function, \IT\ is used to read
Xan entire file, or a complete sequence of inputs from \stin\ until
X{\myit EOF\/}, into internal space.  The accent here is on the
Xcompleteness of the input set: the entire file or the entire
Xset of lines constituting the \stio\ input stream is
Xnecessary for example, to sort input into order.
X\L
XStandard Unix
Xtools find it convenient to check for the presence or absence of
Xa single input file on the command line.  If the file is there, it
Xwill supply the input data; if it is missing, the tool closes
X\stin\ and reopens it as if it was the input file.
X\IT\ similarly allows reading data from \stin\ if the passed
Xfile name {\myit fname\/} is a NULL pointer (pointing to address~0).
X\L
XIf  {\myit fname\/} is non-NULL, \IT\ itself calls {\myit iread()\/}
Xwith its own parameters.  {\myit iread()\/} tests for file access,
X{\myit malloc\/}s a buffer, reads
Xthe file into the buffer, closes the file, and returns the
Xfile size.  An unreported ASCII NUL byte immediately following the
Xlast byte of the buffer, is guaranteed.  The buffer address is
Xreturned in {\myit mallocp\/}.  Errors encountered by {\myit iread()\/}
Xtrigger error reporting via {\myit ierror()\/} in the normal
Xmanner, and error values are
Xpassed back to the routine that called \IT.
X\L
XIf  {\myit fname\/} is NULL, \IT\ calls {\myit freopen()\/}
Xto convert \stin\ into the missing file.  Starting with
Xa dynamically allocated buffer of {\myit BUFSIZ\/} capacity, \IT\
Xthen repeatedly calls {\myit fread()\/} to fill the buffer, while
Xalso increasing the buffer size by
X{\myit BUFSIZ\/} after each {\myit fread()\/}.  If the
X{\myit malloc()\/} or
X{\myit realloc()\/} system calls fail, \IT\ reports the failure
Xvia the {\myit ierror()\/} mechanism.  On {\myit EOF\/}, \IT\
Xadds an extra NUL byte to the end of the collected image, and returns
Xthe image size (and the address of the allocated buffer
Xin {\myit mallocp\/}) identically to {\myit iread()\/}.
X
X\S{SEE ALSO}
X{\myit iread, iwrite, ierror\/}.
X
X\S{EXAMPLE PROGRAM}
XThe {\bb group} program (under the {\myit ifamily()\/} entry),
Xthe {\bb rot} program links (under {\myit irotate()\/}),
X{\bb nest}, and other ILIB example programs of {\myit filter\/}
Xstructure, use
X\IT\ for procuring the full input text prior to commencing
Xtransformations.
X\eject
SHAR_EOF
$TOUCH -am 0509104090 iman/ifilter.tex &&
chmod 0644 iman/ifilter.tex ||
echo "restore of iman/ifilter.tex failed"
set `wc -c iman/ifilter.tex`;Wc_c=$1
if test "$Wc_c" != "2601"; then
    echo original size 2601, current size $Wc_c
fi
# ============= iman/ifonetic.tex ==============
echo "x - extracting iman/ifonetic.tex (Text)"
sed 's/^X//' << 'SHAR_EOF' > iman/ifonetic.tex &&
X% XREF ifonetic
X
X\def\name{IFONETIC}
X\def\IT{{\bb ifonetic()}}
X
X\S{NAME}
X{\bb ifonetic} --- convert phonetic control strings to ASCII bytes
X
X\S{SYNOPSIS}
X{\obeylines \bb
Xint
Xifonetic (start)
Xchar *start;
X}
X
X\S{DESCRIPTION}
XIn order to bypass the {\myit wild card expansion} of a shell,
Xprograms linking with ILIB can allow the user to substitute
Xstraightforward, alphanumeric, ``phonetic control strings'' for
Xnon-alphanumeric characters in command line parameters.
XEach of these control strings is a three-character token prepended
Xby a capital X.  The leading
XX serves as a trigger, forcing \IT\ to recognize and parse
Xthe following three bytes as a ``control token''.
X\L
X\IT\ receives from the caller a
Xnull terminated string beginning at {\myit start\/}.  \IT\ reads the
Xbuffer from
Xleft to right, and collapses each encountered phonetic control token
X(including the trigger byte X) to the real ASCII byte value
Xrepresented by the control token.  If the buffer did in fact contain
Xcontrol tokens, the buffer contents are modified in-place, the
Xstring within gets shorter and is terminated with a NUL byte.
XIf the buffer did not contain control tokens, it is left intact.
X\IT\ returns the byte length of the processed string, not including
Xthe terminal NUL byte.
X\L
XDetails of the phonetic control token system are given in the
Xfollowing paragraphs.  Capital~X was
Xselected as the trigger character because
Xit is the least frequently occurring character in
Xnatural English (and in Unix).
XA ``real'' X character
Xoccurring in the byte stream of command line arguments
Xshould be given as its own phonetic control token \dx{Xexx}, unless
Xit is less than four bytes from the end of the argument.  (In this
Xcase, \IT\ will recognize that there are not enough bytes left for
Xa control token, and will not attempt a conversion.)  The three bytes
Xfollowing any other X in the string are contrasted against a list of
Xvalid control syllables; if there is
Xno match \IT\ uses the literal value of the substring.
X
X\S{CONCERNS OF WILD CARD EXPANSION}
XThe proliferation of wild cards in the various Unix shells can be a
Xmixed blessing.  On one hand, the command line expansion performed by
Xthe shell is perhaps
X{\bb the} key mechanism of {\myit shell programming\/}.  On the other
Xhand, the need to occasionally
Xescape the the shell's expansion mechanism tends to sidetrack the
Xuser's attention from his/her work and re-focus it on shell syntax,
Xbreaking the user's concentration, and sometimes degenerating
Xinto a frustrating ``battle of wits'' against the uncooperative shell.
XA slight lack of orthogonality between the expansion mechanism of
Xdifferent shells, the irregularity and arbitrariness of the ASCII list,
Xa lack of concensus among standard Unix tools as to how (or whether)
Xto handle ``special characters'', all contribute to a list of
Xannoyances.
X\L
XApparently, the only character
Xset universally recognized, unexpanded, and
X``holy'' to all shells and software tools is the {\myit alphanumeric\/}
Xcharacter set, containing twentysix uppercase letters A\mydots Z,
Xtwentysix lowercase letters a\mydots z, and the ten numerals
X0 through 9.  (Contrary to Unix and C, major tools such as
X\TeX\ fail to recognize the underscore as alphanumeric.)
XILIB's phonetic control system provides an alphanumeric
Xname for all non-alphanumeric values of the ASCII character set.
XTo allow control names to be differentiated from normal
Xalphanumeric strings, one letter had to be ``sacrificed'', becoming a
Xwild card unbeknownst to all shells.  The capital letter X is so
Xunder-utilized in everyday usage, that raising it to special status
Xappeared to pose no inconvenience to eventual users.  The system
Xuses X to signal the reader that the next three bytes of the text
Xform a control name.
X
X\S{PHONETIC CONTROL TOKEN SYSTEM}
X{\obeylines \mytt
Xnul\ \ \ \ \ \ \ \ \ \ \ \cir @\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ban\ exc\ \ !\ \ BANg,\ EXClamation
Xsoh\ cca\ \ \ \ \ \ \ \cir A\ \ Start\ Of\ Header\ \ \ \ \ \ \ \ \ \ \ \ quo\ \ \ \ \ \ "\ \ QUOte
Xstx\ ccb\ \ \ \ \ \ \ \cir B\ \ Start\ of\ TeXt\ \ \ \ \ \ \ \ \ \ sha\ pou\ has\ \ \#\ \ SHArp,\ POUnd,\ HASh
Xetx\ ccc\ \ \ \ \ \ \ \cir C\ \ End\ of\ TeXt\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ dol\ \ \ \ \ \ \$\ \ DOLlar
Xeot\ ccd\ \ \ \ \ \ \ \cir D\ \ End\ Of\ Transmission\ \ \ \ \ \ \ \ per\ \ \ \ \ \ \%\ \ PERcent
Xenq\ cce\ \ \ \ \ \ \ \cir E\ \ ENQuiry\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ amp\ \ \ \ \ \ \&\ \ AMPersand
Xack\ ccf\ \ \ \ \ \ \ \cir F\ \ ACKnowledge\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ tic\ apo\ \ '\ \ TICk,\ APOstrophe
Xbel\ ccg\ \ \ \ \ \ \ \cir G\ \ BELl\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ lpa\ \ \ \ \ \ (\ \ Left\ PArenthesis
Xbsp\ cch\ \ (BS)\ \cir H\ \ BackSPace\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rpa\ \ \ \ \ \ )\ \ Right\ PArenthesis
Xtab\ cci\ \ (HT)\ \cir I\ \ horizontal\ TAB\ \ \ \ \ \ \ \ \ \ \ \ \ sta\ ast\ \ *\ \ STAr,\ ASTerisk
Xnew\ ccj\ \ (LF)\ \cir J\ \ NEWline\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ plu\ \ \ \ \ \ +\ \ PLUs
Xver\ cck\ \ (VT)\ \cir K\ \ VERtical\ tab\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ com\ \ \ \ \ \ ,\ \ COMma
Xpag\ ccl\ \ (FF)\ \cir L\ \ PAGe\ break\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ min\ das\ \ -\ \ MINus,\ DASh
Xret\ ccm\ \ (CR)\ \cir M\ \ RETurn\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ dot\ poi\ \ .\ \ DOT,\ POInt
Xsou\ ccn\ \ (SO)\ \cir N\ \ Shift\ OUt\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ sla\ \ \ \ \ \ /\ \ SLAsh
Xsin\ cco\ \ (SI)\ \cir O\ \ Shift\ IN\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ col\ \ \ \ \ \ :\ \ COLon
Xdle\ ccp\ \ \ \ \ \ \ \cir P\ \ Data\ Link\ Escape\ \ \ \ \ \ \ \ \ \ \ sem\ \ \ \ \ \ ;\ \ SEMicolon
Xdc1\ ccq\ \ \ \ \ \ \ \cir Q\ \ Device\ Control\ 1\ \ \ \ \ \ \ \ \ \ \ les\ lan\ \ <\ \ LESs\ than,\ Left\ ANgle
Xdc2\ ccr\ \ \ \ \ \ \ \cir R\ \ Device\ Control\ 2\ \ \ \ \ \ \ \ \ \ \ equ\ \ \ \ \ \ =\ \ EQUal
Xdc3\ ccs\ \ \ \ \ \ \ \cir S\ \ Device\ Control\ 3\ \ \ \ \ \ \ \ \ \ \ gre\ ran\ \ >\ \ GREater,\ Right\ Angle
Xdc4\ cct\ \ \ \ \ \ \ \cir T\ \ Device\ Control\ 4\ \ \ \ \ \ \ \ \ \ \ que\ \ \ \ \ \ ?\ \ QUEstion
Xnak\ ccu\ \ \ \ \ \ \ \cir U\ \ Negative\ AcKnowledge\ \ \ \ \ \ \ ats\ \ \ \ \ \ @\ \ AT\ Sign
Xsyn\ ccv\ \ \ \ \ \ \ \cir V\ \ SYNchronous\ idle\ \ \ \ \ \ \ \ \ \ \ exx\ eks\ \ X
Xetb\ ccw\ \ \ \ \ \ \ \cir W\ \ End\ Transmission\ Block\ \ \ \ \ lsq\ \ \ \ \ \ [\ \ Left\ SQuare\ bracket
Xcan\ ccx\ \ \ \ \ \ \ \cir X\ \ CANcel\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ bsl\ \ \ \ \ \ \bsl \ \ BackSLash
Xeme\ ccy\ \ (EM)\ \cir Y\ \ End\ of\ MEdium\ \ \ \ \ \ \ \ \ \ \ \ \ \ rsq\ \ \ \ \ \ ]\ \ Right\ SQuare\ bracket
Xsub\ ccz\ \ \ \ \ \ \ \cir Z\ \ SUBstitute\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ car\ cir\ \ \cir \ \ CARet,\ CIRcumflex
Xesc\ \ \ \ \ \ \ \ \ \ \ \cir [\ \ ESCape\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ und\ \ \ \ \ \ \und \ \ UNDerscore
Xfil\ \ \ \ \ \ (FS)\ \cir \bsl \ \ FILe\ separator\ \ \ \ \ \ \ \ \ \ \ \ \ bqu\ gra\ \ `\ \ BackQUote,\ GRAve
Xgro\ \ \ \ \ \ (GS)\ \cir ]\ \ GROup\ separator\ \ \ \ \ \ \ \ \ \ \ \ lcu\ \ \ \ \ \ \lcu \ \ Left\ CUrly\ brace
Xrec\ \ \ \ \ \ (RS)\ \cir \cir \ \ RECord\ separator\ \ \ \ \ \ \ \ \ \ \ pip\ bar\ \ |\ \ PIPe,\ vertical\ BAR
Xuni\ \ \ \ \ \ (US)\ \cir \und \ \ UNIt\ separator\ \ \ \ \ \ \ \ \ \ \ \ \ rcu\ \ \ \ \ \ \rcu \ \ Right\ CUrly\ brace
Xspa\ \ \ \ \ \ (SP)\ \ \ \ \ SPAce\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ til\ \ \ \ \ \ \til \ \ TILde
X\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ del\ \ \ \ \ \ \cir ?\ DELete
X\smallskip}
X\L
XThe easy separation of the previous table into left and right side
Xlists suggests that
Xnon-alphanumeric characters form two
Xgroups almost equal in size: non-printing and printing characters.
XNon-printing characters are ordered within the ASCII list as
Xa linear sequence of byte values from
X0 to 32.  A single non-printing character, {\myit delete\/}
X(DEL, 127) is at the very end of
Xthe ASCII list.  Two- and three-character ``official'' or ``standard''
Xnames had been in
Xuse to reference the non-printing ASCII values, competing with an
Xalternative two-character ``control sequence'' representation.
XThe byte pairs of the latter form begin with a caret \key{\car}.
XFor example, BEL or {\mytt \car G} officially both refer to ASCII~7.
X\L
XThe phonetic system described here, retains the ``official''
Xthree-character
Xnames, but expands or changes
Xtwo-character names
X(BS, HT, LF, VT, etc., shown in parentheses).  The new names
Xare all three characters long, in lowercase.  For
Xconvenience of use, control-byte pairs ending with an
Xalphabetic character ({\mytt \car A}, etc.)
Xare also translated into alternative phonetic
Xidentifiers, by prepending the lowercase
Xalphabetic byte of the control byte pair with ``cc''
X(for ``control character'').  For example, Xnew and Xccj both
Xrepresent the {\myit newline\/} character (ASCII LF, byte value 10).
X\L
XUsing a total of four bytes to represent a single ASCII byte is
Xsomewhat wasteful of space, although not any more so than using
X\dx{\mytt'\bsl 077'}\ for example, to represent \key{\mytt?}
Xin octal notation.
XA four-byte phonetic token can always be specified without the
Xsingle quotes on a shell command line, requiring a string two bytes
Xshorter than its equivalent octal version in the above example.
XBut more importantly, the three bytes of the phonetic name
Xform an easily recognized identifier, produced in most cases by
Xtaking the first syllable of the full official
Xname of the ASCII character in question.
XThe easy syntax means that the user does not have to invest time to
Xlearn a new vocabulary, nor is there a need for conversion reference
Xcards.
X\L
XPhonetic names for characters in the printing byte group were
Xtaken from the first three characters of the written form of
Xa commonly used name of the character; or the first two characters
Xprepended by ``l'' for ``left'' or ``r'' for ``right'' in the case of
Xall symmetrical delimiter
Xpairs; or the first two characters of the name prepended by ``b''
Xif the name followed the ``back'' preposition.
XVarious alternate names are recognized: for example,
Xtypewriters often print
Xthe \# character as {\myit \char36\/} (hence the name of
Xthe ``{\myit pound~define\/}''
Xmacro instead of ``{\myit sharp~define\/}'').  \IT\ understands
Xeither Xpou (pound), Xsha (sharp), or Xhas (hash) as ASCII~35.
XThe alias name that did not get
Xonto the phonetic control list is the abbreviation for ``period'',
Xbecause it would have been in collision with ``percent''.  But
XXdot and Xpoi (``dot'' and ``point'') are common enough names for
X\key{.}.
X\L
XIn order to keep the list extendible and to allow modifications,
X\IT\ uses binary search into the phonetic keyword map for producing
Xa translation to the real value, instead of hashing, which would
Xhave been
Xfaster.  It is expected that calls to \IT\ would be made from the
Xoperational periphery of processes, excluding \IT\ from becoming
Xpart of a ``bottleneck''.  In this case
Xtrading speed to gain maintainability has advantages.
XThe conversion process uses
Xtwo arrays defined in {\myit ifonetic.h\/}.  The {\myit listfonet\/}
Xarray is a static {\myit char *\/} list, its pointers dereferencing
Xdiscreet identifiers, sorted alphabetically.
XThe {\myit mapfonet\/}
Xarray is a {\myit char\/} list of the ``real'' byte values corresponding
Xto the names of {\myit listfonet\/}.
X\L
XDuring operation, \IT\ recognizes a control token in the passed
Xstring by virtue of the preceding X, and searches
X{\myit listfonet\/} for a match.  The offset of the matching pointer
Xfrom the base address of
X{\myit listfonet\/} is used as the index into
X{\myit mapfonet\/}, producing the real byte value associated with
Xthe control token.
XThe system could easily be made to include {\myit meta\/} byte
Xvalues (in the 128 -- 255) range, by changing {\myit mapfonet\/}
Xto {\myit unsigned char\/} type, and adding new control names
XX128 to X255.
X
X\S{char EXAMPLE PROGRAM}
X{\bb char} is a
Xvery simple routine that expands character ranges
Xgiven on its command line, into space-separated
Xcharacter lists.  The command line
X\smallskip
X\I{\mytt char AF zo 99 1}
X\smallskip
Xspecifies character ranges A--F, z--o, 9--9, and 1--1; and produces the
Xoutput
X\smallskip
X\I{\mytt A B C D E F z y x w v u t s r q p o 9 1}
X\smallskip
XThe output in all cases is terminated
Xwith a {\myit newline\/}.
XLike the other ILIB examples that expect string arguments on the
Xcommand line, {\bb char} submits each string argument to \IT\ in
Xturn, in order to ease typing non-printing or
Xspecial characters in the command line.  Thus,
X\smallskip
X\I{\mytt char XnulXdel}
X\smallskip
Xoutputs a space-separated list of all ASCII characters.
X
X\S{char.c PROGRAM TEXT}
X\listing{../iex/char.c}
X
X\S{xec EXAMPLE PROGRAM}
XILIB program examples expecting string arguments from the command line,
Xall call \IT\ to resolve embedded phonetic control sequences.
XOther programs will likely not be so obliging, however.  The user
Xmay still hide ``special characters'' from the shell, by executing
Xthe target program via {\bb xec} instead of through the shell.
XAs a simple example without control sequences, one may type:
X\smallskip
X\I{\mytt xec echo hello}
X\smallskip
Xto produce identical results as the command
X\smallskip
X\I{\mytt echo hello}
X\smallskip
XIn the latter case, the {\myit echo\/}
Xcommand was directly handed to the shell;
Xin the first case it was {\myit exec'd\/} by {\bb xec}.  The command
Xstructure of {\bb xec} is trivial: its parameters  {\bb must} form
Xa complete command.  At least one argument (the name of the command
Xto be executed) is required to follow {\bb xec} on the command line.
XAny additional arguments are handed over by {\bb xec} to
X\IT\ in a loop, potentially modifying the original list by collapsing
Xembedded phonetic control sequences into the represented object bytes.
XAfter this, {\bb xec} calls {\myit execvp()\/} with the (modified)
X{\myit argv\/} list, causing its own
Xdemise as the specified program overlays the executing process with
Xits own data and text segments.
X\L
XSuppose that the original \dx{\mytt echo hello}\ command was to be
Xexpanded to output three extra blank lines following the
X\dx{\mytt hello}.  Instead of mulling over how to do this in the shell,
Xthe user could just type
X\dx{\mytt xec echo helloXnewXnewXnew}.
X\L
XThe {\myit execvp()\/} call utilized by {\bb xec}  will search the
Xuser's \dol{\myit PATH\/} to find the absolute path to the text
Xof the given command, unless the path is part of the command.
X{\myit execvp()\/} also understands the user's environment,
Xterminal control characters, and so on.  If the text of
Xthe target command is a {\myit shell script\/},
X{\myit execvp()\/} will pass it to the shell executive specified by
Xthe user's \dol{\myit SHELL\/} variable (usually
X{\myit /bin/sh\/}).  If the script was written for a different shell,
Xthis may cause an ``exec format error''.  The remedy in such cases is to
Xadd a new first line to the script, explicitly stating which shell it
Xwas written for, for example:
X\dx{\mytt \#!\ /bin/csh}.
XThe \twokey{\#!} byte pair, the following space, and the full pathname
Xof the shell are mandatory.  The new
Xline will induce {\myit execvp()\/} to
Xexecute the specified script through {\myit /bin/csh\/} instead of via
X\dol{\myit SHELL\/}.
X
X\S{xec.c PROGRAM TEXT}
X\listing{../iex/xec.c}
X
X\S{defilter EXAMPLE PROGRAM}
XTaking {\bb xec} one step further, {\bb defilter} combines
Xthe ``command execution through {\myit execvp()\/}'' idea with the
X``in-place file transformation using the {\myit system(''mv'')\/}
Xcommand'' (utilized by and described under
Xthe {\myit excise\/} example).  The
Xcombined algorithm expects a complete
Xcommand string as its first parameter, followed by a list of files.
XThe text of each of the files in turn, is input
Xto the command, then the original file text is overwritten by
Xthe output produced by
Xthe command.  As a simple example,
X\smallskip
X\I{\mytt defilter sort file1 file2 file3}
X\smallskip
Xuses {\myit sort\/} to alphabetize
Xthe lines of {\myit file1\/}
Xand replaces the original text of {\myit file1\/} with the
Xsorted version; then
Xsorts the lines of {\myit file2\/} and
Xreplaces the original text of {\myit file2\/} with its
Xsorted version; then again,
Xsorts {\myit file3\/} in place.
X\L
XThe command string following {\bb defilter} on the command line
Xshould be the name of an executable object or the name of an
Xexecutable shell script, with or without various
Xoption flags and options understood by the executable; but
Xwithout shell pipes or redirection characters.
XTo avoid some artificial, strained convention that would
Xsignal {\bb defilter} the end of the command string
Xand the beginning of the file list, the
X``to be executed command string''
Xmust form a single token, a single ``arg'' in
Xthe {\myit argv\/} list passed to the {\myit main()\/} function of
X{\bb defilter}.  This is not expected to be a problem, since ---
Xexcept for the most complex command strings --- the command
Xand its options can be just enclosed in quotes.
X\L
XIn generating a new {\myit argv\/} list to be handed down to
X{\myit execvp()\/}, the ILIB function {\myit ilist()\/} breaks the
Xoriginal \dx{\mytt argv\lsq 1\rsq}\ into null terminated
Xstrings (zeroing out spaces and TAB characters of the quoted
Xcommand string), and returns an array of pointers to the
X{\bb defilter} process in {\myit newargv\/}.  To allow
Xelements of the new {\myit argv\/} list to contain spaces or
Xtabs (and other non-alphanumeric characters),
X{\bb defilter} does not call \IT\ when examining the
Xcommand as its own first argument,
Xbut calls \IT\ for each string of {\myit newargv\/} instead.
X\L
XFor each {\myit file\/} argument on its own command line,
X{\bb defilter} maps in the file name as the last argument following
Xthe command particulars in {\myit newargv\/}, and then {\myit fork\/}s
Xa new process that will {\myit exec\/} the target command,
Xreading its standard input (\stin) from {\myit file\/}, and writing
Xits output to the temporary file renamed \stout.
XWhen the child process dies, {\bb defilter} replaces the original
Xtext of {\myit file\/} with the new text of the temporary file,
Xexactly as during the {\myit excise\/} program.  Then the process
Xrepeats, reading and altering the text of the next file in the list.
X\L
XA reasonably complex command example would use the {\myit sed\/}
Xeditor to ``hunt down'' occurrences of the string
X\dx{\mytt hello, world!}\ (not split across line breaks) in
Xfile {\myit F\/}, and directly substitute
X\dx{\mytt bye, cr\bsl"uel world!}\ instead.  To begin with,
Xthe {\myit sed\/} ``substitute'' command would have to be quoted even
Xas a normal shell command, because
X\smallskip
X\I{\mytt sed -e s/hello,\ world!/bye,\ cr\bsl "uel world!/g F}
X\smallskip
Xhas ``holes'' in the exchange strings, and would return (under
XSystem~V) with an error message from {\myit sed\/}:
X\smallskip
X\I{\mytt command garbled: s/hello,}
X\smallskip
XIn the C shell, the {\myit sed\/} command would not even be called:
Xthe {\myit history substitution mechanism\/} would assume that the
Xexclamation marks were to recall a previous command, and would
Xrespond:
X\smallskip
X\I{\mytt /bye,: Event not found.}
X\smallskip
XThen there is the small problem of the \TeX\ {\myit umlaut\/}
Xcontrol sequence (intended
Xto place a double dot over the \key{u} in \dx{\mytt cr\"uel}), which
Xwould evoke a complaint:
X\smallskip
X\I{\mytt Unmatched ".}
X\smallskip
XA plausible attempt to silence all these complaints at once, may
Xlook like:
X\smallskip
X\I{\mytt defilter 'sed -e "s/hello, worldXban/bye, cr\bsl Xquouel worldXban/g"' F}
X\smallskip
XThis would shut up the shell, and deliver the entire {\myit sed\/}
Xcommand to {\bb defilter} in one piece, to be sure.
XBut as mentioned, the current implementation of {\bb defilter}
Xre-tokenizes the ``command'' argument, breaking it apart at spaces
Xand TABs.
XThe new token list would then see a resurgence of the ``holes'':
X\smallskip
X\I{\mytt sed\hole
X-e\hole
X"s/hello,\hole
XworldXban/bye,\hole
Xcr\bsl Xquouel\hole
XworldXban/g"\hole
X}
X\smallskip
XAnother implementation may conceivably use different tokenizing rules,
Xperhaps recreating all or a part of the shell's quoting mechanism;
Xand such an implementation could accept the entire double-quoted
Xsubstitution string as a single argument in the {\myit newargv\/} list.
XApart  from the observation that this ``quoting'' implementation
Xcould hardly be used to expound the merits of phonetic sequence
Xexpansion, it would involve significant amount of tedious detail work
Xto resolve precedences, nesting, escaped quotes (just to name a few
Xof the problems), while almost certainly denying the user
Xthe ability to conceptually separate the quotes resolved by the
Xshell at the top level of the command, from the quotes resolved by
Xthe internal tokenizer, or from quotes intended for the {\myit exec\/}'d
Xcommand itself!
X\L
XThe current rules of quoting for {\bb defilter} are:
X
X\item{1.}
XSurround the command with quotes to make it a single token from the
Xvantage point of the shell.
X
X\item{2.}
XDo not quote inside the command unless the quote character itself is
Xintended to be passed through the {\myit exec\/}'d command.
X
X\item{3.}
XFill in the holes in the command's own arguments with phonetic control
Xsequences.
X\smallskip
XThe final format of the command caters to the syntax
Xrequirements of {\myit sed\/}, escaping the backslash with another
Xbackslash:
X\smallskip
X{\mytt defilter\ 'sed\ -e\ s/hello,XspaworldXban/bye,Xspacr\bsl \bsl XquouelXspaworldXban/g'\ F}
X\smallskip
X
X\S{defilter.c PROGRAM TEXT}
X\listing{../iex/defilter.c}
X\eject
SHAR_EOF
$TOUCH -am 0607110690 iman/ifonetic.tex &&
chmod 0644 iman/ifonetic.tex ||
echo "restore of iman/ifonetic.tex failed"
set `wc -c iman/ifonetic.tex`;Wc_c=$1
if test "$Wc_c" != "21527"; then
    echo original size 21527, current size $Wc_c
fi
# ============= iman/ifrombit.tex ==============
echo "x - extracting iman/ifrombit.tex (Text)"
sed 's/^X//' << 'SHAR_EOF' > iman/ifrombit.tex &&
X% XREF ifrombit itobit
X
X\def\name{IFROMBIT}
X\def\IT{{\bb ifrombit()}}
X\def\ALT{{\bb itobit()}}
X
X\S{NAME}
X
X{\bb ifrombit} --- convert a character string of binary bits to
X{\myit int\/}
X
X{\bb itobit} --- convert a {\myit char, short,\/} or {\myit int\/} into
Xa character string of binary bits
X
X\S{SYNOPSIS}
X{\obeylines \bb
Xint
Xifrombit (bitstring, bits, zero, one)
Xchar *bitstring;
Xint bits;
Xchar zero;
Xchar one;
X\L
Xchar *
Xitobit (val, bits, zero, one)
Xint val;
Xint bits;
Xchar zero;
Xchar one;
X}
X
X\S{DESCRIPTION}
XIn the author's experience the need to convert to and from the
Xbinary radix arises with persistence, albeit infrequently enough
Xthat previous work on implementing the conversions is forgotten
Xor is not on-line anymore.  Including \IT\ and \ALT\ in ILIB
Xrepresents an effort to keep such rarely used but necessary
Xroutines visible and easily accessible.
X\L
X\IT\ reads the {\myit bitstring\/} buffer passed to it, looking for
X{\myit zero\/} and {\myit one\/} characters.  Each {\myit zero\/}
Xcharacter in the string represents a ``binary zero'' bit, each
X{\myit one\/} character represents a ``binary one'' bit.  The
Xactual ASCII values used for
X{\myit zero\/} and {\myit one\/} are irrelevant, but should be
Xnon-NUL.  The leftmost
X{\myit zero\/} or {\myit one\/} character
Xof the buffer is understood to be the ``most significant'' bit of
Xthe binary value of {\myit bitstring\/}.
X\IT\ reads
X{\myit bitstring\/} until it has found {\myit bits\/} number of
X{\myit zero\/}s and {\myit one\/}s, collectively.
XNon-{\myit zero\/} and non-{\myit one\/} characters of the string
Xare skipped.  \IT\ returns the {\myit int\/} value of the
Xbinary number string.
X\ALT\ converts {\myit val\/} to a binary string of digits
X{\myit bits\/} wide, using
X{\myit zero\/} characters to represent binary zero bits,
Xand {\myit one\/} characters as binary one bits, in the digit string.
XThe null terminated string is returned.
X\L
XBoth \IT\ and \ALT\ restrict the size of the binary number
X(expressed by {\myit bits\/}) to be at least one bit, and maximally
X32 bits.  Callers of \IT\ are responsible to pass a {\myit bitstring\/}
Xbuffer containing enough
X{\myit zero\/} and {\myit one\/} characters to satisfy the
X{\myit bits\/} count.  Out-of-bound {\myit bits\/} values cause a
Xcall to {\myit ierror()\/}, returning negative {\myit sys\_nerr\/} from
X\IT\ and {\myit (char *)\/}NULL from \ALT.
X
X\S{banner EXAMPLE PROGRAM}
XThe {\bb banner} program listed here is a functional clone of the
XSystem~V {\myit banner}, echoing command line arguments to the
Xscreen in large letters.  Each argument of the command line is
Xprinted as a line of large text by itself; if a line of text
Xis to contain multiple words, the group of words should be quoted,
Xmaking them a single token on the command line.  {\bb banner} does
Xnot make assumptions about the width of the screen, but it does
Xlimit the size of a single token (text line) to 256 characters.
X(Wide output can be redirected to {\myit rotr\/} or {\myit rotl\/}
Xto reorient the text vertically, making it suitable for printing
X``banners'' on continuous, pinfeed computer paper.)
X\L
XThe token list given to {\bb banner} undergoes ILIB's customary
Xphonetic control character conversion to allow painless inclusion
Xof ``special characters'' within the words, although {\bb banner}
Xdoes not produce output for {\myit control characters\/} with
XASCII values less than 32.  Tokens of the command line are processed
Xsequentially; characters of a token are converted to a seven-line
Xhigh ``banner string''.  The width of the enlarged characters is
Xseven columns, followed by a one-column space.
X\L
XThe shape of each
Xcharacter is retrieved from the twodimensional {\myit char\/} array
X{\myit banchars\/}.  The first dimension of the array is used to index
Xthe array address of a character (by the character's ASCII value).
XThe second dimension indexes the ``width'' contents for the seven
Xlines of a banner character.  Each byte of data in the array
Xrepresents the ``raster image'' of seven consecutive columns
Xof (one of seven horizontal lines of) the enlarged character.
XThe {\myit char\/} data is converted ``on-the-fly'' into
X{\myit weighted binary bits\/} by \ALT; and the character string of
Xbinary bits produced by \ALT\ is concatenated in a line buffer, with
Xone space added between strings.  The line buffer is re-made
Xand printed seven times to produce a banner text line.  A blank
Xline is output after each banner line.
X
X\S{banner.c PROGRAM TEXT}
X\listing{../iex/banner.c}
X
X\eject
SHAR_EOF
$TOUCH -am 0524122790 iman/ifrombit.tex &&
chmod 0644 iman/ifrombit.tex ||
echo "restore of iman/ifrombit.tex failed"
set `wc -c iman/ifrombit.tex`;Wc_c=$1
if test "$Wc_c" != "4510"; then
    echo original size 4510, current size $Wc_c
fi
# ============= iman/ifunclist.tex ==============
echo "x - extracting iman/ifunclist.tex (Text)"
sed 's/^X//' << 'SHAR_EOF' > iman/ifunclist.tex &&
X\def\name{TABLE 2}
X
X\S{Function Returns, Parameters, Chapter Name}
X{\bb
X\settabs\+char * & inumsearch &
X(start, end, tobuf, header, ender, breakc, maxc, more); &\cr
X\smallskip
X\+{\smallcaps Value}&{\smallcaps Name}&{\smallcaps Parameters}&{\smallcaps Manual Entry}\cr
X\L
X\+char*&ialntok&(start, end, wbuf);\linef&{\myletr IALNTOK}\cr
X\+char*&ianymatch&(start, end, str);\linef&{\myletr IMATCH}\cr
X\+char*&ianytok&(start, end, wbuf);\linef&{\myletr IALNTOK}\cr
X\+int&ibcmp&(s1, s2, bytes);\linef&{\myletr IBCMP}\cr
X\+void&ibcopy&(tobuf, frombuf, bytes);\linef&{\myletr IBCMP}\cr
X\+void&iblank&(start, end);\linef&{\myletr IBLANK}\cr
X\+int&ibreakl&(start, end, tobuf, header, ender, breakc, maxc, all);\linef&{\myletr IBREAKL}\cr
X\+char*&ictok&(start, end, wbuf);\linef&{\myletr IALNTOK}\cr
X\+char*&icopy&(start, end);\linef&{\myletr ICOPY}\cr
X\+int&icount&(type);\linef&{\myletr ICOUNT}\cr
X\+void&icue&(ptr);\linef&{\myletr ICUE}\cr
X\+int&idamage&(error);\linef&{\myletr IERROR}\cr
X\+char*&idate&(format);\linef&{\myletr IDATE}\cr
X\+void&idump&(start, end, ch);\linef&{\myletr IDUMP}\cr
X\+int&iego&(ptr, wbuf, delim, ext);\linef&{\myletr IEGO}\cr
X\+int&ierror&(ustr);\linef&{\myletr IERROR}\cr
X\+int&iexpect&(start, end, word, skiptok, toktype);\linef&{\myletr IEXPECT}\cr
X\+int&ifamily&(ptr1, ptr2);\linef&{\myletr IFAMILY}\cr
X\+int&ifilter&(fname, mallocp);\linef&{\myletr IFILTER}\cr
X\+int&ifonetic&(start);\linef&{\myletr IFONETIC}\cr
X\+int&ifrombit&(bitstring, bits, zero, one);\linef&{\myletr IFROMBIT}\cr
X\+int&igroup&(ptr1, ptr2, modval);\linef&{\myletr IFAMILY}\cr
X\+int&ihash&(ptr, modval, upcase);\linef&{\myletr IHASH}\cr
X\+int&ihasharg&(ptr, delim);\linef&{\myletr IHASH}\cr
X\+char*&ihms&(key);\linef&{\myletr IHMS}\cr
X\+int&iinput&(ptr, message);\linef&{\myletr IINPUT}\cr
X\+char*&ilast&(ptr, c);\linef&{\myletr IBCMP}\cr
X\+int&iline&(start, end);\linef&{\myletr ILINE}\cr
X\+int&ilist&(start, end, delims, ptrlist);\linef&{\myletr ILIST}\cr
X\+int&ilistn&(start, end, delims, ptrlist);\linef&{\myletr ILIST}\cr
X\+int&illistn&(start, end, ptrlist);\linef&{\myletr ILIST}\cr
X\+int&ilongest&(start, end, lcount);\linef&{\myletr IROTATE}\cr
X\+int&ilower&(start, end);\linef&{\myletr ILOWER}\cr
X\+char*&imatch&(start, end, str);\linef&{\myletr IMATCH}\cr
X\+int&imode&(fname, perm);\linef&{\myletr IMODE}\cr
X\+int&imonth&(ptr);\linef&{\myletr IDATE}\cr
X\+int&inest&(start, end, ldelim, rdelim, infopair);\linef&{\myletr INEST}\cr
X\+char*&inl&(start);\linef&{\myletr ICUE}\cr
X\+char*&inull&(start);\linef&{\myletr ICUE}\cr
X\+int&inumsearch&(comparee, wordlist, listcount);\linef&{\myletr ISEARCH}\cr
X\+void&inumsort&(ptr, itemcount);\linef&{\myletr ISORT}\cr
X\+int&inumstrcmp&(ptr1, ptr2);\linef&{\myletr IFAMILY}\cr
X\+char*&inextl&(start, end, skiptok);\linef&{\myletr IEXPECT}\cr
X\+int&ioctal&(ptr);\linef&{\myletr IOCTAL}\cr
X\+int&iopt&(ptr);\linef&{\myletr IOPT}\cr
X\+int&iread&(fname, mallocp);\linef&{\myletr IREAD}\cr
X\+int&irotate&(start, llength, lcount, mallocp, type);\linef&{\myletr IROTATE}\cr
X\+int&iround&(start, end, maxfrac);\linef&{\myletr IROUND}\cr
X\+int&isearch&(comparee, wordlist, listcount);\linef&{\myletr ISEARCH}\cr
X\+void&isort&(ptr, itemcount);\linef&{\myletr ISORT}\cr
X\+char*&istartl&(start, end, word);\linef&{\myletr IEXPECT}\cr
X\+int&istripcom&(start, end, lcom, rcom);\linef&{\myletr ISTRIPCOM}\cr
X\+int&istripdq&(start, end);\linef&{\myletr ISTRIPCOM}\cr
X\+int&istripsq&(start, end);\linef&{\myletr ISTRIPCOM}\cr
X\+int&istripstr&(start, end, str);\linef&{\myletr ISTRIPCOM}\cr
X\+int&iswap&(start, end, from, to);\linef&{\myletr ISWAP}\cr
X\+int&itexrect&(start, end, mallocp, lcount);\linef&{\myletr IROTATE}\cr
X\+char*&itobit&(val, bits, zero, one);\linef&{\myletr IFROMBIT}\cr
X\+int&itoday&();\linef&{\myletr IDATE}\cr
X\+int&itohour&();\linef&{\myletr IDATE}\cr
X\+int&itok&(context, start, end, result);\linef&{\myletr ITOK}\cr
X\+int&itomin&();\linef&{\myletr IDATE}\cr
X\+int&itomonth&();\linef&{\myletr IDATE}\cr
X\+int&itosec&();\linef&{\myletr IDATE}\cr
X\+int&itoyear&();\linef&{\myletr IDATE}\cr
X\+int&itran&(start, end, fromc, toc);\linef&{\myletr IBLANK}\cr
X\+int&iuniq&(item);\linef&{\myletr IUNIQ}\cr
X\+int&iupper&(start, end);\linef&{\myletr ILOWER}\cr
X\+char*&iwhich&(item, perm);\linef&{\myletr IWHICH}\cr
X\+int&iwrite&(fname, start, end);\linef&{\myletr IWRITE}\cr
X\+int&iwritopn&(fname, start, end);\linef&{\myletr IWRITE}\cr
X\+char*&ixmatch&(start, end, word);\linef&{\myletr IMATCH}\cr
X\+int&ixsearch&(comparee, wordlist, listcount);\linef&{\myletr ISEARCH}\cr
X\+int&ixswap&(start, end, from, to);\linef&{\myletr ISWAP}\cr
X}
X\eject
SHAR_EOF
$TOUCH -am 0531092590 iman/ifunclist.tex &&
chmod 0644 iman/ifunclist.tex ||
echo "restore of iman/ifunclist.tex failed"
set `wc -c iman/ifunclist.tex`;Wc_c=$1
if test "$Wc_c" != "4588"; then
    echo original size 4588, current size $Wc_c
fi
# ============= iman/ifunlines.tex ==============
echo "x - extracting iman/ifunlines.tex (Text)"
sed 's/^X//' << 'SHAR_EOF' > iman/ifunlines.tex &&
X\def\name{TABLE 1}
X
X\S{ILIB's Function List and Summary}
X\settabs\+{\bb inumstrcmp }&\cr
X\smallskip
X\+{\bb ialntok} & copy first alphanumeric token into word buffer\cr
X\+{\bb ianymatch} & find a specific string in a buffer\cr
X\+{\bb ianytok} & copy first token of source into word buffer\cr
X\+{\bb ibcmp} & compare two byte strings\cr
X\+{\bb ibcopy} & copy bytes from one place to another\cr
X\+{\bb iblank} & change all bytes to spaces\cr
X\+{\bb ibreakl} & break long lines into shorter ones\cr
X\+{\bb icopy} & copy buffer into dynamically allocated memory\cr
X\+{\bb icount} & count how many times a specific parameter was passed\cr
X\+{\bb ictok} & copy first C token of source into word buffer\cr
X\+{\bb icue} & buffer management\cr
X\+{\bb idate} & print today's date in one of four formats\cr
X\+{\bb idump} & write a buffer to \stout, show NUL bytes\cr
X\+{\bb iego} & put path-less, extension-less base name into word buffer\cr
X\+{\bb ierror} & report an ILIB error or a system error\cr
X\+{\bb idamage} & return TRUE on possible file damage\cr
X\+{\bb iexpect} & confirm or deny first token match in line\cr
X\+{\bb ifamily} & tell whether two alhanumeric strings are related\cr
X\+{\bb ifilter} & read file or \stin\ into dynamic memory, return size\cr
X\+{\bb ifonetic} & convert phonetic control strings to ASCII bytes\cr
X\+{\bb ifrombit} & convert a string of binary bits to {\myit int\/}\cr
X\+{\bb igroup} & compute places for separators in string lists\cr
X\+{\bb ihash} & return checksum of string\cr
X\+{\bb ihasharg} & return checksum of upcased final component of pathname\cr
X\+{\bb ihms} & convert duration from seconds to hh:mm:ss, time events\cr
X\+{\bb iinput} & get a string from \stin\ after \sterr\ prompt\cr
X\+{\bb ilast} & find last occurrence of character in a string\cr
X\+{\bb iline} & find {\myit newline\/}, null it, return line size\cr
X\+{\bb ilistn} & create array of pointers to strings in buffer\cr
X\+{\bb ilist} & create array of pointers to non-null strings in buffer\cr
X\+{\bb illistn} & create array of pointers to lines in buffer\cr
X\+{\bb ilongest} & find longest line in buffer\cr
X\+{\bb ilower} & change alphabetic characters in buffer to lower case\cr
X\+{\bb imatch} & find a specific token or token head in a buffer\cr
X\+{\bb imode} & find out if specified file permission bits are set\cr
X\+{\bb imonth} & convert month name to number 1 through 12\cr
X\+{\bb inest} & create array of {\myit int\/}s to nest information\cr
X\+{\bb inextl} & return location of first token in the next line\cr
X\+{\bb inl} & return pointer to next {\myit newline\/} or NUL byte\cr
X\+{\bb inull} & return pointer to next NUL byte\cr
X\+{\bb inumsearch} & binary (numeric) search in list of character pointers\cr
X\+{\bb inumsort} & sort list of character pointers to alphanumeric order\cr
X\+{\bb inumstrcmp} & alphanumeric comparison of two strings\cr
X\+{\bb ioctal} & convert octal digit strings to {\myit int}\cr
X\+{\bb iopt} & command line option manager\cr
X\+{\bb iread} & read file into buffer at mallocp, return file size\cr
X\+{\bb irotate} & rotate passed text in newly allocated buffer,\cr
X\+{\bb iround} & round to a given digit of a decimal fraction\cr
X\+{\bb isearch} & binary string search in list of character pointers\cr
X\+{\bb isort} & sort list of character pointers to alphabetic order\cr
X\+{\bb istartl} & find nearest line that starts with {\myit word\/}\cr
X\+{\bb istripcom} & ``white out'' comments in buffer with spaces\cr
X\+{\bb istripdq} & ``white out'' double quotes in buffer with spaces\cr
X\+{\bb istripsq} & ``white out'' single quotes in buffer with spaces\cr
X\+{\bb istripstr} & ``white out'' strings  in buffer with spaces\cr
X\+{\bb iswap} & change one string to another everywhere in a buffer\cr
X\+{\bb itexrect} & create rectangular array from lines of varying length\cr
X\+{\bb itobit} & convert {\myit char, short,\/} or {\myit int\/} into of binary bits\cr
X\+{\bb itoday} & integer value (1 $\ldots$\ 31) of current day of month\cr
X\+{\bb itohour} & integer value (0 $\ldots$\ 23) of current hour of day\cr
X\+{\bb itok} & dynamic tokenizer\cr
X\+{\bb itomin} & integer value (0 $\ldots$\ 59) of current minute\cr
X\+{\bb itomonth} & integer value (1 $\ldots$\ 12) of current month\cr
X\+{\bb itosec} & integer value (0 $\ldots$\ 59) of current second\cr
X\+{\bb itoyear} & four decimal-digit value of current year\cr
X\+{\bb itran} & change one character to another everywhere in buffer\cr
X\+{\bb iuniq} & return TRUE if parameter is passed for the first time\cr
X\+{\bb iupper} & change alphabetic characters in buffer to upper case\cr
X\+{\bb iwhich} & locate a file\cr
X\+{\bb iwrite} & open file, write buffer to file, close file\cr
X\+{\bb iwritopn} & open file, write buffer to file, leave file open\cr
X\+{\bb ixmatch} & find a specific token in a buffer\cr
X\+{\bb ixsearch} & binary token search in list of character pointers\cr
X\+{\bb ixswap} & change alphanumeric token to another everywhere in a buffer\cr
X\eject
SHAR_EOF
$TOUCH -am 0607122690 iman/ifunlines.tex &&
chmod 0644 iman/ifunlines.tex ||
echo "restore of iman/ifunlines.tex failed"
set `wc -c iman/ifunlines.tex`;Wc_c=$1
if test "$Wc_c" != "4956"; then
    echo original size 4956, current size $Wc_c
fi
echo "End of part 7, continue with part 8"
exit 0
--
        Istvan Mohos
        ...uunet!pyrdc!pyrnj!hhb!istvan
        RACAL-REDAC/HHB 1000 Wyckoff Ave. Mahwah NJ 07430 201-848-8000
======================================================================