home *** CD-ROM | disk | FTP | other *** search
Text File | 1988-05-03 | 17.1 KB | 1,035 lines |
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PAGER, Version 1.6
-
-
-
-
-
- by Richard Conn, TI Ada Technology Branch
-
-
-
-
-
-
-
-
-
-
-
- PAGER is a tool for creating, extracting from, and scanning paged
-
- files, where a paged file is a file composed of one or more files
-
- prefixed by banners. PAGER is based in concept on the UNPAGE tool
-
- submitted to the Ada Repository on SIMTEL20 by Mitre Corporation.
-
-
-
- Paged files are convenient mechanisms for storing related files.
-
- They reduce cluttering in the directories and simplify the file
-
- transfer process (to and from the Ada Repository, for example) by
-
- requiring the user to transfer only one file in order to obtain all
-
- files pertinent to a particular project or tool. Additionally, paged
-
- files are text files which can be handled more readily than the 8-bit
-
- binary images associated with other file grouping mechanisms (see the
-
- file LBR.DOC in the directory MICRO:<ADA.GENERAL> in the Ada
-
- Repository). Paged files may be manipulated by a text editor if
-
- necessary.
-
-
-
- For these reasons, paged files have been adopted as a standard
-
- for file storage in the Ada Repository. The file type of SRC (as in
-
- MYFILE.SRC) is designated to indicate that a file is paged.
-
-
-
- PAGER 1.5 is an operational improvement over PAGER 1.4. It has
-
- been discovered that the limitation (range) of the type NATURAL cannot
-
- be assumed to be "large" for all Ada compilers. The Telesoft Ada
-
- compiler, version 2.1, uses 16 bits for objects of type NATURAL. This
-
- proved to be restrictive. Consequently, PAGER 1.5 provides numerous
-
- constraint error traps whenever counts are made.
-
- Page 2
-
-
-
-
-
- 1 PAGED FILE FORMAT
-
-
-
- A paged file is a file composed of one or more files prefixed by
-
- banners of the form
-
-
-
- ::::::::::
-
- filename
-
- ::::::::::
-
-
-
- or
-
-
-
- --::::::::::
-
- --filename
-
- --::::::::::
-
-
-
-
-
- The first banner conforms to the PAGE standard employed on UNIX.
-
- The second banner is an adaptation of the first form which resembles
-
- Ada comments. The second banner is convenient when the paged file
-
- contains several files associated with a particular Ada program and
-
- they are placed in the paged file in compilation order. The resulting
-
- paged file may then be compiled without being disassembled first.
-
-
-
- A paged file is of the following general form
-
-
-
- Section Example
-
- ======= =======
-
- ::::::::::
-
- banner firstfile.txt
-
- ::::::::::
-
- body
-
- first file of
-
- first file
-
- ::::::::::
-
- banner secondfile.txt
-
- ::::::::::
-
- body
-
- second file of
-
- second file
-
-
-
- Page 3
-
-
-
-
-
- 2 FUNCTIONS OF PAGER
-
-
-
- PAGER performs the following functions:
-
-
-
- * CHECK - Count the number of Ada statements, Ada comments, and
-
- text lines in the indicated file (the indicated file does not
-
- have to be a paged file); CHECK also computes a checksum of
-
- all the printable characters in this file
-
-
-
- * LIST - Create a text file containing the names of the
-
- component files of a paged file. One name is stored per
-
- line, and each name is prefixed with "$$ " to allow easy
-
- editing for inserting compile commands before the file names
-
- in the preparation of batch command files.
-
-
-
- * PAGE - Create a paged file from one or more existing files;
-
- the component files may be specified individually or by
-
- include files
-
-
-
- * SCAN - Perform a CHECK and then report on the name and number
-
- of text lines in each component file of the indicated paged
-
- file; if the file is not a paged file, SCAN presents the same
-
- information as CHECK
-
-
-
- * TOGGLE - Display and toggle options
-
-
-
- * UNPAGE - Extract the component files from the indicated paged
-
- file; the paged file is left intact
-
-
-
-
-
- There are several options available under PAGER, and they are
-
- toggled and displayed by the TOGGLE command. These options are:
-
-
-
- * TOGGLE COMMENT - Select the comment banner
-
-
-
- * TOGGLE INCLUDE - Place include files in paged files
-
-
-
- * TOGGLE VERBOSE - Enable verbose mode
-
-
-
-
-
- More discussion of these options will be presented in the
-
- discussions of the functions of PAGER which follow.
-
-
-
- Only the first letter of each command and each option for the
-
- TOGGLE command is significant. All other letters in a command or
-
- option are ignored. Only with file names are all letters of
-
- significance. Hence,
-
-
-
- PAGE filename
-
- and
-
- P filename
-
-
-
-
-
- are equivalent, as are
-
-
-
- Page 4
-
-
-
-
-
-
-
- TOGGLE INCLUDE
-
- and
-
- T I
-
-
-
-
-
- Any PAGER command beginning with a dash (-) is a comment line to
-
- PAGER and is not processed in any way.
-
-
-
-
-
-
-
- 2.1 CHECK Function
-
-
-
- CHECK counts the number of Ada statements, Ada comments, and text
-
- lines in the indicated file. It also computes a checksum of all the
-
- printable characters in this file. The indicated file does not have
-
- to be a paged file. The syntax of the CHECK command is:
-
-
-
- CHECK filename
-
-
-
-
-
- CHECK is useful in providing a validity check of a file transfer.
-
- By running CHECK on a file residing on a source computer, transferring
-
- the file from the source computer to a destination computer, and then
-
- running CHECK on the file as transferred to a destination computer,
-
- the user can verify the transfer. If the checksums match, it is
-
- likely that the transfer was successful. Since the checksum is
-
- computed on the printable characters (which do not include spaces,
-
- tabs, carriage returns, or line feeds), this check does not reflect
-
- any differences caused by tab expansion (expanding tab characters into
-
- spaces) and the like which may be caused by the transfer mechanism.
-
-
-
-
-
-
-
- 2.2 HELP Function
-
-
-
- The HELP command displays a brief help text to the user. The
-
- syntax of this command is:
-
-
-
- HELP
-
-
-
- Page 5
-
-
-
-
-
- 2.3 LIST Function
-
-
-
- The LIST function is used to create a text file containing the
-
- names of the component files within a paged file. The syntax of the
-
- LIST command is:
-
-
-
- LIST paged_file_name
-
-
-
-
-
- Upon execution, this command will prompt the user for the name of
-
- the output file. If he strikes just the RETURN key, PAGER aborts the
-
- LIST function and does not generate an output file.
-
-
-
- The output file has the following general format:
-
- $$ file_name_1
-
- $$ file_name_2
-
- ...
-
-
-
- A text editor can be used to make a global substitution of the
-
- "$$ " characters. For instance, if the component files were to be
-
- compiled in the order they were stored in the paged file, substituting
-
- "$ ada " for "$$ " in this listing file creates a DEC submit file
-
- which compiles all files named. Likewise, a substitution of "$ print
-
- " would print all files named.
-
-
-
-
-
-
-
- 2.4 PAGE Function
-
-
-
- The PAGE function is used to created a paged file from one or
-
- more component files. The syntax of the PAGE command is:
-
-
-
- PAGE filename
-
-
-
-
-
- When the PAGE command is issued, the user is prompted for the
-
- name of a file. He may then type the name of a component file, strike
-
- return, and he will be prompted again. This process continues until
-
- the user strikes only a return in response to the file name prompt.
-
- At this point, PAGE will create the paged file from the component
-
- files named by the user.
-
-
-
- If the user prefixes the name of a component file with an atsign
-
- character (@), the indicated file is processed as an include file. An
-
- include file is a file which contains the names of zero or more
-
- component files, one name per line starting in the first column.
-
- Other include files may be referenced within an include file by
-
- prefixing their names with the atsign character. Comments may be
-
- placed within an include file by placing two dashes in the first two
-
- columns of a line. The following is an example of an include file:
-
- Page 6
-
-
-
-
-
-
-
- Example Comments
-
- ======= ========
-
- --
-
- -- This is an include file for Comment at the beginning
-
- -- my favorite tool
-
- --
-
- Blank lines are allowed
-
- --
-
- -- The following include file
-
- -- contains the names of the Another comment
-
- -- Ada source files in compilation
-
- -- order
-
- --
-
- @mytool.cmp
-
- --
-
- -- The following are the documentation
-
- -- files
-
- --
-
- mytool.ref
-
- mytool.doc
-
- mytool.idx
-
-
-
-
-
- The following toggled options are applicable to the PAGE command:
-
-
-
- * TOGGLE COMMENT - If the COMMENT option is ON, the Ada comment
-
- banner (--::::::::::) is used; if the COMMENT option is OFF,
-
- the standard banner (::::::::::) is used.
-
-
-
- * TOGGLE INCLUDE - If the INCLUDE option is ON, any include
-
- file referenced is placed in the paged file as a component
-
- file; if the INCLUDE option is OFF, include files are not
-
- placed in the paged file unless explicitly named. For
-
- example, if @MYTOOL.DIS is specified with INCLUDE off, only
-
- the files named in MYTOOL.DIS are included; if INCLUDE is on,
-
- MYTOOL.DIS is included as well as the files named within it.
-
-
-
- * TOGGLE VERBOSE - If the VERBOSE option is ON, more
-
- information is displayed during the execution of the PAGE
-
- command; if the VERBOSE option is OFF, less information is
-
- displayed
-
-
-
- Page 7
-
-
-
-
-
- 2.5 SCAN Function
-
-
-
- The SCAN function is similar to the CHECK function, but it also
-
- lists the names and number of text lines in the component files in a
-
- paged file. If SCAN is run on a file which is not a paged file, the
-
- output is identical to CHECK. The syntax of SCAN is:
-
-
-
- SCAN filename
-
-
-
-
-
- The VERBOSE toggle causes SCAN to present the count of text lines
-
- to the user as well as the file names of the component files.
-
-
-
-
-
-
-
- 2.6 TOGGLE Function
-
-
-
- The TOGGLE command displays and toggles the options of PAGER.
-
- TOGGLE with no argument displays the options. TOGGLE followed by a
-
- valid option toggles the state (ON/OFF) of that option.
-
-
-
- The options to the TOGGLE command are:
-
-
-
- * COMMENT - Comment banner (PAGE command only)
-
-
-
- * INCLUDE - Include file (PAGE command only)
-
-
-
- * VERBOSE - Verbose mode
-
-
-
-
-
-
-
-
-
- 2.7 UNPAGE Function
-
-
-
- The UNPAGE command extracts the components from the indicated
-
- paged file, leaving the original paged file intact. The syntax of
-
- UNPAGE is:
-
-
-
- UNPAGE filename
-
-
-
-
-
- The VERBOSE toggle causes UNPAGE to present the count of text
-
- lines to the user as each component file is extracted.
-
- Page 8
-
-
-
-
-
- 2.8 X Function
-
-
-
- The X command exits PAGER. Its syntax is:
-
-
-
- X
-
-
-
-
-
-
-
-
-
- 3 SAMPLE SESSION
-
-
-
- The following is a sample PAGER session. It was run on a VAX
-
- 11/785 running VMS 4.0.
-
-
-
-
-
- $ dir
-
-
-
- Directory USER4:[CONN.ADA]
-
-
-
- CAS3.ADA;1 15 (RWE,RWED,RE,RE)
-
- CHARACTER_SET.ADA;1
-
- 21 (RWE,RWED,RE,RE)
-
- LIB.DIR;1 3 (RE,RWE,RE,RE)
-
- PAGER.ADA;2 13 (RWE,RWED,RE,RE)
-
- PAGER_COMPILE.DIS;1
-
- 1 (RWE,RWED,RE,RE)
-
- PAGER_SUPPORT.ADA;1
-
- 47 (RWE,RWED,RE,RE)
-
-
-
- Total of 6 files, 100 blocks.
-
-
-
- $ type pager_compile.dis
-
-
-
- --
-
- -- Compilation order for all files required to create the
-
- -- PAGER program
-
- --
-
- character_set.ada
-
- cas3.ada
-
- pager_support.ada
-
- pager.ada
-
-
-
- $ pager
-
- PAGER, Version 1.6
-
- Type HELP for Help
-
- PAGER> h
-
- PAGER Commands:
-
- CHECK filename -- Ada Check on File
-
- LIST filename -- List Names of Component Files
-
- PAGE filename -- Create Paged File
-
- SCAN filename -- List Files in Paged File
-
- TOGGLE -- Indicate Flag Settings
-
- TOGGLE flag -- Toggle Indicated Flag:
-
- Comment, Include File, or
-
- Verbose
-
- Page 9
-
-
-
-
-
- UNPAGE filename -- Extract from Paged File
-
- X (Exit) -- Exit PAGER
-
- PAGER> t
-
- Comment Prefix is Disabled
-
- Include File Prefix is Enabled
-
- Verbose Mode is Enabled
-
- PAGER> -- I will now create PAGER.SRC, which is
-
- PAGER> -- composed of PAGER_SUPPORT.ADA and PAGER.ADA
-
- PAGER> page pager.src
-
- Enter Names of Files (RETURN when done)
-
- Input File Name > pager_support.ada
-
- Input File Name > pager.ada
-
- Input File Name >
-
-
-
- Component Files --
-
- pager_support.ada
-
- 714 Lines
-
- pager.ada
-
- 150 Lines
-
- PAGER> -- PAGER_FULL.SRC contains all files required to compile
-
- PAGER> -- PAGER.ADA. The file PAGER_COMPILE.DIS contains those
-
- PAGER> -- file names in compilation order.
-
- PAGER> toggle comment
-
- Comment Prefix is Enabled
-
- PAGER> t
-
- Comment Prefix is Enabled
-
- Include File Prefix is Enabled
-
- Verbose Mode is Enabled
-
- PAGER> page pager_full.src
-
- Enter Names of Files (RETURN when done)
-
- Input File Name > @pager_compile.dis
-
- Include File: pager_compile.dis
-
- pager_compile.dis
-
- character_set.ada
-
- cas3.ada
-
- pager_support.ada
-
- pager.ada
-
- End of Include File pager_compile.dis
-
- Input File Name >
-
-
-
- Component Files --
-
- pager_compile.dis
-
- 8 Lines
-
- character_set.ada
-
- 321 Lines
-
- cas3.ada
-
- 194 Lines
-
- pager_support.ada
-
- 714 Lines
-
- pager.ada
-
- 150 Lines
-
- PAGER> x
-
-
-
-
-
- $ cd upload r
-
- Page 10
-
-
-
-
-
- USER4:[CONN.UPLOAD]
-
- $ pager
-
- PAGER, Version 1.6
-
- Type HELP for Help
-
- PAGER> -- Demo of CHECK
-
- PAGER> check [conn.ada]pager_full.src
-
- Input File: [conn.ada]pager_full.src
-
- Ada Statements: 628
-
- Ada Comments: 309
-
- Text Lines: 1402
-
- Checksum: 91
-
- PAGER> -- Demo of SCAN
-
- PAGER> scan [conn.ada]pager_full.src
-
- Input File: [conn.ada]pager_full.src
-
- Ada Statements: 628
-
- Ada Comments: 309
-
- Text Lines: 1402
-
- Checksum: 91
-
- Component Files --
-
- pager_compile.dis
-
- 8 Lines
-
- character_set.ada
-
- 321 Lines
-
- cas3.ada
-
- 194 Lines
-
- pager_support.ada
-
- 714 Lines
-
- pager.ada
-
- 150 Lines
-
- PAGER> -- Demo of UNPAGE
-
- PAGER> unpage [conn.ada]pager_full.src
-
- pager_compile.dis
-
- 8 Lines
-
- character_set.ada
-
- 321 Lines
-
- cas3.ada
-
- 194 Lines
-
- pager_support.ada
-
- 714 Lines
-
- pager.ada
-
- 150 Lines
-
- PAGER> -- Check/Scan on a "normal" file
-
- PAGER> check pager_support.ada
-
- Input File: pager_support.ada
-
- Ada Statements: 324
-
- Ada Comments: 172
-
- Text Lines: 714
-
- Checksum: 22
-
- PAGER> scan pager_support.ada
-
- Input File: pager_support.ada
-
- Ada Statements: 324
-
- Ada Comments: 172
-
- Text Lines: 714
-
- Checksum: 22
-
- PAGER> check pager.ada
-
- Page 11
-
-
-
-
-
- Input File: pager.ada
-
- Ada Statements: 74
-
- Ada Comments: 8
-
- Text Lines: 150
-
- Checksum: 61
-
- PAGER> x
-
- $
-
-
-
-