diff options
Diffstat (limited to 'static/v10/man1/mint.1')
| -rw-r--r-- | static/v10/man1/mint.1 | 420 |
1 files changed, 420 insertions, 0 deletions
diff --git a/static/v10/man1/mint.1 b/static/v10/man1/mint.1 new file mode 100644 index 00000000..9f9bd7a3 --- /dev/null +++ b/static/v10/man1/mint.1 @@ -0,0 +1,420 @@ +.TH MINT 1 "02 June 1987" "University of Waterloo" +.ds ]W "Symbolic Comp. Group +.SH NAME +mint \- produce usage report from a maple program +.SH SYNOPSIS +.B mint +[ +.B \-i +info_level +] +[ +.B \-l +] +[ +.B \-d +library_database +] +[ +.B \-a +database_file +] +[ +.B \-q +] +[ file ] +.SH DESCRIPTION +\fIMint\fP produces a report about possible errors in a Maple source file +and also reports about how variables are used in the file. +If \fIfile\fP is not given, then the standard input file is used to +read Maple source statements. +Unlike \fImaple\fP, \fImint\fP is not terminated when it reads a +quit statement. +It is terminated when it reaches the end of file. +When started, \fImint\fP normally produces a mint leaf logo. +This can be suppressed by the use of the \fB\-q\fP (quiet) option. + +The amount of information to be produced by \fImint\fP is specified by the +\fIinfo_level\fP argument. +The values allowed for this argument are: +.nf + + 0 \- Display no information. + 1 \- Display only severe errors + 2 \- Display severe and serious errors + 3 \- Display warnings as well as severe and serious errors + 4 \- \kxGive a full report on variable usage as well as + \h'|\nxu'displaying errors and warnings + +.fi +A report for each procedure in the file is displayed +separately followed by a global report for statements not contained +within any procedure. +If the severity of errors found within a procedure is less than +what \fIinfo_level\fP specifies, then no report is produced for +that procedure. +In all cases, the most severe error found in the file will be used +to set the exit status for \fImint\fP. +Thus, by using an \fIinfo_level\fP of 0, \fImint\fP can be used to +determine the severity of errors in a file without actually producing +any output at all. +If no value is given for \fIinfo_level\fP on the command line, a default +value of 2 (severe and serious errors) is used. + +The types of errors and warnings found are classified as severe, +serious, and warning. A severe error is an undisputable error. +A serious error +is almost certainly an error. However, persons defining procedures +for addition to the Maple library may choose to ignore these ``errors''. +Warnings are possible errors. +They point to constructs that may be correct in some contexts, but +probable errors in other contexts. +The types of errors and warnings produced are: +.in +0.8i +.ti -0.8i + +\fBSEVERE\fP + +.ti -0.4i +Syntax errors +.br +A caret symbol will point to the token +that is being read when the error occurred. + +.ti -0.4i +Duplicated parameter +.br +A name appears more than once in a parameter list for a +procedure. + +.ti -0.4i +Duplicated local +.br +A name is declared more than once in the list of local +variables for a procedure. + +.ti -0.4i +Local variable and parameter conflict +.br +A name is used both as a parameter and a local +variable within a procedure. In further analysis, +the name is treated as a parameter. + +.ti -0.4i +Local variable and system-defined name conflict +.br +The name of a local variable is also used by Maple as a +system-defined name. + +.ti -0.4i +Parameter and system-defined name conflict +.br +The name of a parameter is also used by Maple as a +system-defined name. + +.ti -0.4i +Duplicated loop name +.br +A loop nested within another loop uses as its loop +control variable the same name that the outer loop uses. + +.ti -0.4i +Break or next statement outside of a loop +.br +A break or a next statement occurs outside of any loop. +(Break or next may still be used as names within an +expression outside of a loop.) + +.ti -0.4i +RETURN or ERROR function call outside of a procedure +.br +A function call to RETURN or ERROR occurs outside of +a procedure body. (RETURN or ERROR may still be used +as names if they are not invoked as functions.) + +.ti -0.4i +Unreachable code +.br +There are statements which follow directly after a goto type +of statement. These statements are unreachable and will never +be executed. A goto statement is a next statement, a break +statement, a quit, stop, or done statement, a RETURN() call, +an ERROR() call. +An if statement all branches of which end in a goto statement +is also considered a goto statement. + +.ti -0.8i +\fBSERIOUS\fP + +.ti -0.4i +Overly long name +.br +A name whose length is too long is used. The length of +the name is truncated to the maximum allowed. + +.ti -0.4i +Unused local variable +.br +A local variable is declared for a procedure but never +used within the procedure body. + +.ti -0.4i +Local variable assigned a value but not used otherwise +.br +A local variable is assigned a value within a procedure but +is not otherwise used. + +.ti -0.4i +Local variable never assigned a value but used as a value +.br +A local variable was never assigned a value in a procedure but +within the procedure its value is used in an expression. +Such an expression would contain a pointer to a non-existent +local variable if the expression were returned or assigned to +a global variable. + +.ti -0.4i +System-defined name is overwritten +.br +A name which is treated as a system-defined name by Maple +is assigned a value. +The class of system-defined names includes names which are +special names for the Maple kernel, e.g., true and Digits, +names of built-in functions, e.g., anames and lprint, +names of functions which are automatically readlib-defined, e.g., +cat or help. +Also included are names that are special to routines for evalf, +diff, expand, etc. +Examples of these are Pi and sinh. +These special names generally should not be assigned a value in order +for some library routines to work properly. +Included in the report is an indication of which parts of Maple use +the system-defined names. + +.ti -0.4i +Dubious global name in a procedure +.br +A global name is used within a procedure. A global name is +a name which is not a parameter, a local name, a system-defined name, or +a catenated name. +A quoted name used as an argument to the routines lprint, print, and +ERROR is probably used just for output and is not considered a name. +Global names used as procedure +names in a function call are not considered errors. +Also excluded are names of files in the Maple library, e.g., +`convert/ratpoly`. +All remaining names are considered as global names. +By convention, global names used in a package of routines should +begin with the `_` (underscore) character. +Those that do not are considered dubious and are reported here. + +.ti -0.4i +Library file name overwritten +.br +The name of a library file, e.g., `convert/ratpoly`, is assigned +a value. It is usual for the name of a library file to also be +the name of a library function. Hence, the library function +`convert/ratpoly` is no longer accessible. +(The \fB\-l\fP (library file) option will downgrade these messages +from a serious error to a report.) + +.ti -0.4i +Unused parameter in a procedure +.br +A name specified in the parameter list of a procedure is +never used in the procedure. This is considered a serious +error if `args' is never used in the procedure either. +If args is used in the procedure, then it's possible that +the parameter may be accessed through a construct using `arg' +and this error is downgraded to a warning. + +.ti -0.4i +Wrong argument count in a procedure call +.br +The number of arguments passed in a procedure call doesn't match the +number of formal arguments in the definition of a procedure of the +same name recorded in the library database file. +A library database file (cf. \fBDATABASE FILES\fP) contains information +about the minimum number of arguments expected for a procedure, the +maximum number of arguments, whether `nargs' is used in the procedure +body, and the name of the file in which the procedure is defined. +If the number of actual arguments passed is either less than the +minimum arguments expected or more than the maximum number expected +\fIand\fP `nargs' is not used in the procedure body, then a warning is +generated. +This warning is suppressed if one of the arguments passed is `args'. +It is a common practice for a procedure to take its argument list, +contained in the expression sequence `args', and pass that on to +other procedures. +What appears to \fImint\fP as one argument is in reality a sequence +of arguments. +.ti -0.8i + +\fBWARNING\fP + +.ti -0.4i +Equation used as a statement +.br +This may be intentional. On the other hand, it's common +for many Fortran and C programmers to mistype '=' for +the assignment operator which is ':=' in Maple. + +.ti -0.4i +Unused parameter in a procedure +.br +See similar entry under serious errors. + +.ti -0.4i +Global name used +.br +A global name which may or may not start with '_' is used within +this procedure. + +.ti -0.4i +Catenated name used +.br +A name is formed through the catenation operator. + +.in -0.8i +\fBOTHER REPORTS\fP +.sp +If \fIinfo_level\fP is 4, then a usage report is given for each procedure +as well as global statements within the file. +Each usage report shows how parameters, local variables, global variables, +system-defined names and catenated names are used. +As well can easily be done, the following information about how a +variable is used may be provided: +.nf + + 1. Used as a value + 2. Used as a table or list element + 3. Used as a call-by-value parameter + 4. Used as a call-by-name parameter (a quoted parameter) + 5. Called as a function + 6. Assigned a procedure + 7. Assigned a list + 8. Assigned a set + 9. Assigned a range + 10. Assigned a value as a table or list element + 11. \kxAssigned a function value + \h'|\nxu'(assigned a value to remember as a function value) + +.fi + +In addition, a list of all the error messages generated is given. + +.SH COMMAND OPTIONS +The \fB\-i\fP (info level) and \fB\-q\fP (quiet) options are explained +above. +The \fB\-l\fP (library file) option will suppress the catenated name +warning and the global name warning if only one of each is used +outside of any procedure. +Typically, a Maple library source file will contain one of each for +use in loading the library file. +This option will also suppress error messages about library file names +being overwritten since one of the purposes of a library file is to +assign a procedure to a library file name. +Moreover, warnings about the assignment of values to the system-defined +names Digits and printlevel are suppressed since this often happens +in a library file. + +.SH INITIALIZATION FILE +If there is a file named .mintrc in your home directory, \fImint\fP +will read this file for command line options. +This file may contain several lines containing command line options or +arguments as you would type them on a command line. +Since \fImint\fP reads this file and then scans the actual command line, +arguments on the actual command line can override arguments in the +initialization file. +A good use of the initialization file may be to enter the name of the +Maple library procedure database file when using the \fB\-d\fP option, +obviating the need to type this each time \fImint\fP is used. + +.SH PROCEDURE DATABASE FILES +A procedure database file contains information about the definition of +procedures which is useful in ensuring that these procedures are +used correctly. +Each line in a database file contains the following: + +.nf + <name> <min\ args> <max\ args> <nargs\ used> <file\ name> +.fi + +where <name> is a legal Maple name without any embedded blanks, +<min\ args> is the minimum number of arguments expected for +<name>, <max\ args> is the maximum number of arguments, <nargs\ used> +is 1 if `nargs' is used in the procedure body for <name> and +0 otherwise, <file\ name> is the name of the file in which <name> +is defined. +The entries on each line are in free format but must be separated +from one another by at least one space character. +The values for <min\ args> and <max\ args> should be numbers in +the range 0 to 999. +If <max\ args> is 999 for an entry, that denotes that the procedure +has no upper limit on the number of arguments. +There may be multiple entries for a particular procedure. +Later entries supercede earlier ones. + +A procedure database file for the entire Maple library is generated +or updated periodically. +This file is +/usr/maple/data/mint.db and contains close to 1200 entries and +it takes \fImint\fP about 7 seconds to read this file. + +A private database file can be generated through the use of +the \fB\-a\fP command line option for \fImint\fP. +A file name must follow \fB\-a\fP on the command line and is taken +to be a procedure database file. +As \fImint\fP scans procedure definitions in the input file, it +will append procedure database entries into the database file. +For information gathered automatically by \fImint\fP about a +procedure, <min\ args> and <max\ args> will both be the number of +formal arguments used in the procedure definition. +You can edit the database file to adjust these values. +Remember that use of `nargs' in a procedure body sets the <nargs seen> +field to 1 in the database entry and that this will turn off +argument count checking for that procedure. + +.SH EXAMPLES + +.ft CW +.nf +mint -d /usr/maple/data/mint.db -a my.db -i 4 rat_poisson +mint -d /usr/maple/data/mint.db -d my.db rat_trap +mint -i 1 -q warfarin +.fi +.ft P + +The first example gives a full report (info_level = 4) for the +Maple source file rat_poisson. +It reads the Maple library database file and uses this to check that +procedures defined in the Maple library are called with the correct +number of arguments. +Information about procedures defined in rat_poisson is \fIappended\fP +to my.db. + +In the second example, both the Maple library database file and +the private database file my.db are used to check number of arguments +used in procedure calls in the file rat_trap. +Entries in my.db supercede entries in the library database file +if the name of a library procedure has been redefined in my.db. + +In the third example, no argument count checking is done. +Since the info_level is set to 1, only severe errors are +reported. +Since the \fB\-q\fP (quiet) option is used, the printing +of the \fImint\fP leaf logo is suppressed in the output. + +.SH FILES USED +\&.mintrc \- Mint initialization file +/usr/maple/data/mint.db \- \kxMaple library procedure database +\h'|\nxu'(The location of the database may be different for each site) +.SH SEE ALSO +maple + +.SH STATUS +\fIMint\fP will return an exit status of 1, 2, or 3 if the +worst error it detects is a warning, serious error, or severe +error, respectively. An exit status of 0 is returned if no +errors or warnings are found. + |