README FOR readinfo 2.3 ----------------------- readinfo lets you employ text files as simple relational databases. The data in a readinfo-formatted text file is organized in rows and columns, and using readinfo you can print out arbitrary columns in any order. (To select individual rows, you can use good ol' grep or awk to filter readinfo's output.) readinfo was once part of the updatehosts software project, which was used to manage DNS zone and host files. It's useful on its own, and is now being released separately. One tool which is built to make use of readinfo is rshall (also located at ). INSTALLATION ------------ In the Makefile, set INST_DIR to wherever you want the software installed. You may also need to change the INSTALL command, depending on the location and version of "install" on your system. Then run "make install". USE --- readinfo accepts flat ASCII text as input. A file in readinfo format is a self-defining relation. It has a special #FIELDS (or $FIELDS) line which defines each field in the file. An example is probably the best way to describe the format. Here is a file which could be used to define a CNAME relation: #FIELDS GLOBAL no=. host suffix=.tic.com alias suffix=.tic.com ttl xfrsparc mail xfrsparc smtp xfrsparc mail.zilker.net. Comments in this file use the standard # convention. However, the #FIELDS line is a special comment which defines the name and some characteristics of each field. (This may also be written as $FIELDS instead.) This particular relation has 3 fields: "host", "alias", and "ttl". The #FIELDS comment names each of the fields in the order they appear in each line of the file. Each field is described by its name, followed by an optional prefix=, suffix=, no=, or null= descriptor. Fields may be empty. In this example the "ttl" field is empty for each record. The format is freeform. Fields are simply strings of characters separated by tabs. The prefix= and suffix= describe what will be prepended or appended to the field value when readinfo outputs the field. The no= field argument is a single character which directs readinfo to display the host value as given and ignore any prefix or suffix arguments. In this example, the suffix for the "host" and "alias" fields is ".tic.com", and the no= value is a period ("."). This allows a convenient shorthand for domain names. Note that readinfo knows nothing about domain names. So the suffix in this case is the literal string ".tic.com". The null= defines a special string to stand for the empty value. Defining this as, say, "X" is a convenient way to set a place holder for an empty value. You can also use a quoted empty string as the empty field value. In addition, in this example, the "ttl" field is empty since it is the last field of the relation and no value appears in the field. There is also a special GLOBAL field where values can be set for all fields in a single place. This is often where the empty value is set for all fields. You can have multiple #FIELDS lines in an input file. Each one applies to all the lines following it in the text file, up to the next #FIELDS line, or to the end of the file if it's the last one. Field values are separated by tab characters. You can continue lines across multiple lines by using the standard UNIX convention of having the last character on a line be a backslash ("\"). If there are fewer values than field names, the extra fields are set to the empty string. readinfo outputs all fields with the defined suffix and prefix attached to each value. The output fields are separated by single tab characters (unless the -P switch is used), which makes parsing the output simple. For example, here's some output generated using the CNAME file above: % readinfo -i cname_file alias host mail.tic.com xfrsparc.tic.com smtp.tic.com xfrsparc.tic.com mail.zilker.net xfrsparc.tic.com The "#INCLUDE filename" and "#INLINE filename" directives can be used to merge input from multiple files. An #INCLUDEd file is processed separately by readinfo (so it needs its own #FIELDS line(s)), and then its output is merged with the output from the master file. An #INLINEd file's contents is directly merged into the master input file before processing by readinfo. "readinfo -h" will print out a usage statement. See the included man page for more info and examples. Also, see the included "systems" file for an example input file. PLATFORMS --------- readinfo has been written for portability to most UNIX systems. It's been tested on the following platforms: - Darwin/Mac OS X - version 7.x/10.3.x - Linux - Cobalt Linux (variant of Red Hat) - NEXTSTEP/OPENSTEP - version 3.3 - Solaris - versions 2.4 through 9 - SunOS - versions 4.1.x CHANGES ------- You're not required by the license to submit changes back to the source, but I'd appreciate portability improvements or enhancements of general applicability. You can email new versions or contextual diffs ("diff -c old_file new_file") to . Some things to keep in mind if you do this: - Formatting - I use tabs for indentation, and sometimes to align code segments for readability. Please do the same. - Please don't use NotePad or some other Windows editor to make changes. Or if you do, get rid of the DOS linefeeds before submitting changes. - Please try to follow the formatting conventions established in the existing code. - Readability - Usually, I will trade off efficiency (of running time or of development time) in favor of readability. - Insert meaningful comments where appropriate. - Portability - All shell scripts are Bourne-compatible. I won't use shell- specific constructs from bash, ksh, etc. - Don't use OS-specific features, pathnames, etc., unless they're guarded by code checking the OS version, or they're in user-settable variables toward the top of the script. CONTRIBUTORS ------------ Smoot Carl-Mitchell (original author, contributor up to versions 1.x) Leon Towns-von Stauber Enjoy! Copyright (c) 2005. All rights reserved. See the LICENSE file distributed with this code for restrictions on its use and further distribution. Original distribution available at .