![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mint.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / mana|
Return to mint.1 CVS log | Up to [Research Unix] / researchv10dc / man / mana |
1.1 root 1: .TH MINT 1 "02 June 1987" "University of Waterloo"
2: .ds ]W "Symbolic Comp. Group
3: .SH NAME
4: mint \- produce usage report from a maple program
5: .SH SYNOPSIS
6: .B mint
7: [
8: .B \-i
9: info_level
10: ]
11: [
12: .B \-l
13: ]
14: [
15: .B \-d
16: library_database
17: ]
18: [
19: .B \-a
20: database_file
21: ]
22: [
23: .B \-q
24: ]
25: [ file ]
26: .SH DESCRIPTION
27: \fIMint\fP produces a report about possible errors in a Maple source file
28: and also reports about how variables are used in the file.
29: If \fIfile\fP is not given, then the standard input file is used to
30: read Maple source statements.
31: Unlike \fImaple\fP, \fImint\fP is not terminated when it reads a
32: quit statement.
33: It is terminated when it reaches the end of file.
34: When started, \fImint\fP normally produces a mint leaf logo.
35: This can be suppressed by the use of the \fB\-q\fP (quiet) option.
36:
37: The amount of information to be produced by \fImint\fP is specified by the
38: \fIinfo_level\fP argument.
39: The values allowed for this argument are:
40: .nf
41:
42: 0 \- Display no information.
43: 1 \- Display only severe errors
44: 2 \- Display severe and serious errors
45: 3 \- Display warnings as well as severe and serious errors
46: 4 \- \kxGive a full report on variable usage as well as
47: \h'|\nxu'displaying errors and warnings
48:
49: .fi
50: A report for each procedure in the file is displayed
51: separately followed by a global report for statements not contained
52: within any procedure.
53: If the severity of errors found within a procedure is less than
54: what \fIinfo_level\fP specifies, then no report is produced for
55: that procedure.
56: In all cases, the most severe error found in the file will be used
57: to set the exit status for \fImint\fP.
58: Thus, by using an \fIinfo_level\fP of 0, \fImint\fP can be used to
59: determine the severity of errors in a file without actually producing
60: any output at all.
61: If no value is given for \fIinfo_level\fP on the command line, a default
62: value of 2 (severe and serious errors) is used.
63:
64: The types of errors and warnings found are classified as severe,
65: serious, and warning. A severe error is an undisputable error.
66: A serious error
67: is almost certainly an error. However, persons defining procedures
68: for addition to the Maple library may choose to ignore these ``errors''.
69: Warnings are possible errors.
70: They point to constructs that may be correct in some contexts, but
71: probable errors in other contexts.
72: The types of errors and warnings produced are:
73: .in +0.8i
74: .ti -0.8i
75:
76: \fBSEVERE\fP
77:
78: .ti -0.4i
79: Syntax errors
80: .br
81: A caret symbol will point to the token
82: that is being read when the error occurred.
83:
84: .ti -0.4i
85: Duplicated parameter
86: .br
87: A name appears more than once in a parameter list for a
88: procedure.
89:
90: .ti -0.4i
91: Duplicated local
92: .br
93: A name is declared more than once in the list of local
94: variables for a procedure.
95:
96: .ti -0.4i
97: Local variable and parameter conflict
98: .br
99: A name is used both as a parameter and a local
100: variable within a procedure. In further analysis,
101: the name is treated as a parameter.
102:
103: .ti -0.4i
104: Local variable and system-defined name conflict
105: .br
106: The name of a local variable is also used by Maple as a
107: system-defined name.
108:
109: .ti -0.4i
110: Parameter and system-defined name conflict
111: .br
112: The name of a parameter is also used by Maple as a
113: system-defined name.
114:
115: .ti -0.4i
116: Duplicated loop name
117: .br
118: A loop nested within another loop uses as its loop
119: control variable the same name that the outer loop uses.
120:
121: .ti -0.4i
122: Break or next statement outside of a loop
123: .br
124: A break or a next statement occurs outside of any loop.
125: (Break or next may still be used as names within an
126: expression outside of a loop.)
127:
128: .ti -0.4i
129: RETURN or ERROR function call outside of a procedure
130: .br
131: A function call to RETURN or ERROR occurs outside of
132: a procedure body. (RETURN or ERROR may still be used
133: as names if they are not invoked as functions.)
134:
135: .ti -0.4i
136: Unreachable code
137: .br
138: There are statements which follow directly after a goto type
139: of statement. These statements are unreachable and will never
140: be executed. A goto statement is a next statement, a break
141: statement, a quit, stop, or done statement, a RETURN() call,
142: an ERROR() call.
143: An if statement all branches of which end in a goto statement
144: is also considered a goto statement.
145:
146: .ti -0.8i
147: \fBSERIOUS\fP
148:
149: .ti -0.4i
150: Overly long name
151: .br
152: A name whose length is too long is used. The length of
153: the name is truncated to the maximum allowed.
154:
155: .ti -0.4i
156: Unused local variable
157: .br
158: A local variable is declared for a procedure but never
159: used within the procedure body.
160:
161: .ti -0.4i
162: Local variable assigned a value but not used otherwise
163: .br
164: A local variable is assigned a value within a procedure but
165: is not otherwise used.
166:
167: .ti -0.4i
168: Local variable never assigned a value but used as a value
169: .br
170: A local variable was never assigned a value in a procedure but
171: within the procedure its value is used in an expression.
172: Such an expression would contain a pointer to a non-existent
173: local variable if the expression were returned or assigned to
174: a global variable.
175:
176: .ti -0.4i
177: System-defined name is overwritten
178: .br
179: A name which is treated as a system-defined name by Maple
180: is assigned a value.
181: The class of system-defined names includes names which are
182: special names for the Maple kernel, e.g., true and Digits,
183: names of built-in functions, e.g., anames and lprint,
184: names of functions which are automatically readlib-defined, e.g.,
185: cat or help.
186: Also included are names that are special to routines for evalf,
187: diff, expand, etc.
188: Examples of these are Pi and sinh.
189: These special names generally should not be assigned a value in order
190: for some library routines to work properly.
191: Included in the report is an indication of which parts of Maple use
192: the system-defined names.
193:
194: .ti -0.4i
195: Dubious global name in a procedure
196: .br
197: A global name is used within a procedure. A global name is
198: a name which is not a parameter, a local name, a system-defined name, or
199: a catenated name.
200: A quoted name used as an argument to the routines lprint, print, and
201: ERROR is probably used just for output and is not considered a name.
202: Global names used as procedure
203: names in a function call are not considered errors.
204: Also excluded are names of files in the Maple library, e.g.,
205: `convert/ratpoly`.
206: All remaining names are considered as global names.
207: By convention, global names used in a package of routines should
208: begin with the `_` (underscore) character.
209: Those that do not are considered dubious and are reported here.
210:
211: .ti -0.4i
212: Library file name overwritten
213: .br
214: The name of a library file, e.g., `convert/ratpoly`, is assigned
215: a value. It is usual for the name of a library file to also be
216: the name of a library function. Hence, the library function
217: `convert/ratpoly` is no longer accessible.
218: (The \fB\-l\fP (library file) option will downgrade these messages
219: from a serious error to a report.)
220:
221: .ti -0.4i
222: Unused parameter in a procedure
223: .br
224: A name specified in the parameter list of a procedure is
225: never used in the procedure. This is considered a serious
226: error if `args' is never used in the procedure either.
227: If args is used in the procedure, then it's possible that
228: the parameter may be accessed through a construct using `arg'
229: and this error is downgraded to a warning.
230:
231: .ti -0.4i
232: Wrong argument count in a procedure call
233: .br
234: The number of arguments passed in a procedure call doesn't match the
235: number of formal arguments in the definition of a procedure of the
236: same name recorded in the library database file.
237: A library database file (cf. \fBDATABASE FILES\fP) contains information
238: about the minimum number of arguments expected for a procedure, the
239: maximum number of arguments, whether `nargs' is used in the procedure
240: body, and the name of the file in which the procedure is defined.
241: If the number of actual arguments passed is either less than the
242: minimum arguments expected or more than the maximum number expected
243: \fIand\fP `nargs' is not used in the procedure body, then a warning is
244: generated.
245: This warning is suppressed if one of the arguments passed is `args'.
246: It is a common practice for a procedure to take its argument list,
247: contained in the expression sequence `args', and pass that on to
248: other procedures.
249: What appears to \fImint\fP as one argument is in reality a sequence
250: of arguments.
251: .ti -0.8i
252:
253: \fBWARNING\fP
254:
255: .ti -0.4i
256: Equation used as a statement
257: .br
258: This may be intentional. On the other hand, it's common
259: for many Fortran and C programmers to mistype '=' for
260: the assignment operator which is ':=' in Maple.
261:
262: .ti -0.4i
263: Unused parameter in a procedure
264: .br
265: See similar entry under serious errors.
266:
267: .ti -0.4i
268: Global name used
269: .br
270: A global name which may or may not start with '_' is used within
271: this procedure.
272:
273: .ti -0.4i
274: Catenated name used
275: .br
276: A name is formed through the catenation operator.
277:
278: .in -0.8i
279: \fBOTHER REPORTS\fP
280: .sp
281: If \fIinfo_level\fP is 4, then a usage report is given for each procedure
282: as well as global statements within the file.
283: Each usage report shows how parameters, local variables, global variables,
284: system-defined names and catenated names are used.
285: As well can easily be done, the following information about how a
286: variable is used may be provided:
287: .nf
288:
289: 1. Used as a value
290: 2. Used as a table or list element
291: 3. Used as a call-by-value parameter
292: 4. Used as a call-by-name parameter (a quoted parameter)
293: 5. Called as a function
294: 6. Assigned a procedure
295: 7. Assigned a list
296: 8. Assigned a set
297: 9. Assigned a range
298: 10. Assigned a value as a table or list element
299: 11. \kxAssigned a function value
300: \h'|\nxu'(assigned a value to remember as a function value)
301:
302: .fi
303:
304: In addition, a list of all the error messages generated is given.
305:
306: .SH COMMAND OPTIONS
307: The \fB\-i\fP (info level) and \fB\-q\fP (quiet) options are explained
308: above.
309: The \fB\-l\fP (library file) option will suppress the catenated name
310: warning and the global name warning if only one of each is used
311: outside of any procedure.
312: Typically, a Maple library source file will contain one of each for
313: use in loading the library file.
314: This option will also suppress error messages about library file names
315: being overwritten since one of the purposes of a library file is to
316: assign a procedure to a library file name.
317: Moreover, warnings about the assignment of values to the system-defined
318: names Digits and printlevel are suppressed since this often happens
319: in a library file.
320:
321: .SH INITIALIZATION FILE
322: If there is a file named .mintrc in your home directory, \fImint\fP
323: will read this file for command line options.
324: This file may contain several lines containing command line options or
325: arguments as you would type them on a command line.
326: Since \fImint\fP reads this file and then scans the actual command line,
327: arguments on the actual command line can override arguments in the
328: initialization file.
329: A good use of the initialization file may be to enter the name of the
330: Maple library procedure database file when using the \fB\-d\fP option,
331: obviating the need to type this each time \fImint\fP is used.
332:
333: .SH PROCEDURE DATABASE FILES
334: A procedure database file contains information about the definition of
335: procedures which is useful in ensuring that these procedures are
336: used correctly.
337: Each line in a database file contains the following:
338:
339: .nf
340: <name> <min\ args> <max\ args> <nargs\ used> <file\ name>
341: .fi
342:
343: where <name> is a legal Maple name without any embedded blanks,
344: <min\ args> is the minimum number of arguments expected for
345: <name>, <max\ args> is the maximum number of arguments, <nargs\ used>
346: is 1 if `nargs' is used in the procedure body for <name> and
347: 0 otherwise, <file\ name> is the name of the file in which <name>
348: is defined.
349: The entries on each line are in free format but must be separated
350: from one another by at least one space character.
351: The values for <min\ args> and <max\ args> should be numbers in
352: the range 0 to 999.
353: If <max\ args> is 999 for an entry, that denotes that the procedure
354: has no upper limit on the number of arguments.
355: There may be multiple entries for a particular procedure.
356: Later entries supercede earlier ones.
357:
358: A procedure database file for the entire Maple library is generated
359: or updated periodically.
360: This file is
361: /usr/maple/data/mint.db and contains close to 1200 entries and
362: it takes \fImint\fP about 7 seconds to read this file.
363:
364: A private database file can be generated through the use of
365: the \fB\-a\fP command line option for \fImint\fP.
366: A file name must follow \fB\-a\fP on the command line and is taken
367: to be a procedure database file.
368: As \fImint\fP scans procedure definitions in the input file, it
369: will append procedure database entries into the database file.
370: For information gathered automatically by \fImint\fP about a
371: procedure, <min\ args> and <max\ args> will both be the number of
372: formal arguments used in the procedure definition.
373: You can edit the database file to adjust these values.
374: Remember that use of `nargs' in a procedure body sets the <nargs seen>
375: field to 1 in the database entry and that this will turn off
376: argument count checking for that procedure.
377:
378: .SH EXAMPLES
379:
380: .ft CW
381: .nf
382: mint -d /usr/maple/data/mint.db -a my.db -i 4 rat_poisson
383: mint -d /usr/maple/data/mint.db -d my.db rat_trap
384: mint -i 1 -q warfarin
385: .fi
386: .ft P
387:
388: The first example gives a full report (info_level = 4) for the
389: Maple source file rat_poisson.
390: It reads the Maple library database file and uses this to check that
391: procedures defined in the Maple library are called with the correct
392: number of arguments.
393: Information about procedures defined in rat_poisson is \fIappended\fP
394: to my.db.
395:
396: In the second example, both the Maple library database file and
397: the private database file my.db are used to check number of arguments
398: used in procedure calls in the file rat_trap.
399: Entries in my.db supercede entries in the library database file
400: if the name of a library procedure has been redefined in my.db.
401:
402: In the third example, no argument count checking is done.
403: Since the info_level is set to 1, only severe errors are
404: reported.
405: Since the \fB\-q\fP (quiet) option is used, the printing
406: of the \fImint\fP leaf logo is suppressed in the output.
407:
408: .SH FILES USED
409: \&.mintrc \- Mint initialization file
410: /usr/maple/data/mint.db \- \kxMaple library procedure database
411: \h'|\nxu'(The location of the database may be different for each site)
412: .SH SEE ALSO
413: maple
414:
415: .SH STATUS
416: \fIMint\fP will return an exit status of 1, 2, or 3 if the
417: worst error it detects is a warning, serious error, or severe
418: error, respectively. An exit status of 0 is returned if no
419: errors or warnings are found.
420:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.