Inside Mod Manager v14 Errors
Error Handling
Mod Manager provides abundant error messaging for screen display and log entries.
There are two categories of errors: 1) Parser Errors (MM syntax) and 2) Installation errors.
Parser errors are generated by Modparser while digesting the content of mod configuration files and are always fatal.
Installation status and errors are generated by Modvalidator, as it checks the mod environment to ensure that all the elements are either in place and ready to be installed, or have already been installed. Modinstaller and Modremover can also generate errors on the fly. For example, installing a mod which has a provisional target file -- the Modvalidator will okay it, but if Modinstaller does not find the provisional file at runtime, it will log an error.
E### Designators
To help identify and resolving Mod Manager errors, many error messages now contain an E number, for example, "Validator E151" which refers to the line number in the Modvalidator which threw the error. If the error is in the log for a mod installaton, Modinstaller will have generated it. The purpose is to allow mod developers and MM maintainers quickly pinpoint the source of the error in the code, the use debugging techniques to isolate the cause.
Almost all MM errors are seen by mod developers as they work their way through mod creation. If am end-user sees an error while working with a mod, he will often contact the developer. If he includes the E number in his report, it help the developer zero in and quickly resolve it.
If the "E" designation is found in a logged error, then the number refers to a line in the MM class which performed the operation -- Modinstaller, for example, if MM was attempting to install a mod when the error was logged.
Since most of the highest level MM classes use (extend) Modparser, a parsing error will be specifically identified to avoid confusion -- "Parser E698", for example.
In many cases, commentary in the code at that error location will add detail as to the cause and perhaps suggest possible fixes for a developer to investigate. We hope to expand the commentary detail as we gain more experience with different mods.
Parser Errors - Errorpacks
The Modparser main external function is $oParser->parse(). All MM extending classes have access to this function. To list the mods, for example, Modlister calls function $this->parse(), which is part of itself now by virtue of extending Modparser.
Modparser checks for Mod Manager syntax errors. For example, it verifies that:
- mod directives have been properly terminated
- required directive values are present (e.g., mod name, mod version)
- all mod directive names are valid MM
- conditional jump labels exist
- required directive arguments are present and valid
- dependent directives are present and valid
When Modparser detects a syntax error it generates an Errorpack ($this->parse_error[]) in it's data store:
$this->parse_error['line'] = $dirpack['line'];
$this->parse_error['tag'] = "- label \"$label\"";
$this->parse_error['text'] = self::MISSING;An Errorpack contains three elements:
1) the line number ['line'] in the Mod config file where the faulty directive is found;
2) a text element ['tag'] which can contain any text; and
3) a language support ['text'] which contains the index into $admtext[] array for the error message.
- The line number can generally be taken from the $tokens table.
- The ['tag'] text is created to show the directive name and perhaps an error E-number.
- The text index into $this->admtext[] is self explanatory. In the example above, the index is contained in a constant (MISSING) predefined in Modbase.php. Not all indexes are predefined, so the actual index may be used (for example, 'errors').
Since parse errors are fatal, Modparser stops processing and returns whatever parse table has already been created to the calling object. When the caller, for example a Modlister, gets the parse table back, it checks to see if an Errorpack has been created. If it has, it breaks out of the processing loop, publishes the "Cannot install" error and bails out on that particular mod.
Error Message Construction
If it is Modlister, the last function called is $this->display_modline(), which assembles elements from the Error pack into a standard sequence:
['line']: ['tag'] ['text']
Error styling is applied to the last element.
Don't be confused; the 'tag' contains the text and the 'text' contains the index into $this->admtext. The 'tag' text can contain an E-number to show where in MM the error was thrown. Backward compatibility.
The error string is then added to the mod's $this->status_string and the entire string is displayed in the Modlister status area.
A similar process occurs with logged entries, only they are written instead of displayed.
Installation Errors
Inside Mod Manager v14 Directory
| TOC |
|---|
