Mod Manager Directives - Technical

General

We assume you are on this page because you want a better technical understanding of Mod Manager and how it works. If you need even more information, please read the code.

Mod Manager is forgiving of trivial errors. White space mismatches between cfg target and target file code will not generate bad target errors.

The six code manipulation directives have been made more logical.

When processing mod configuration (cfg) files and TNG target files Mod Manager copies their content into a buffer and standardizes line endings to CRLF (\r\n) characters to eliminate disparities introduced by different platforms.

Operational Directives

Operational directives tell Mod Manager how to process targeted code or files. This summary explains how they are technically implemented in Mod Manager for TNG 10.1 and above. Mod developers should understand how they work when creating their mods.

Operational Directives For Code Manipulation

There are six operational directives that manipulate code -- three for block insertions or replacement and three for inline insertions or replacement.

Mod Manager consists of a number of class objects, three of which deal with op directives -- modlister, modinstaller and modremover -- each using op directives in a different way depending on their purpose. For each mod:

modlister determines if the new code has already been installed and, if not, if the targeted code can be located (OK to install) -- status is reported accordingly.

modinstaller places new code into the targeted script according to the mod's operational directives.

modremover uses op directives to find and remove any code in the targeted script installed by the mod.

Block Directives

A block consists of one or more complete lines of code that may include leading and trailing spaces and tabs used to format it.

A block contains every character, including spaces and tabs, starting at the extreme left margin of the first line and ending at the extreme right margin of the last line.

Leading and trailing white space is automatically "matched" with the target file for block operations. White space is not considered when determining the "uniqueness" of target code.

Blocks are handled differently depending on the op directive and functional purpose (list, install, remove.)

Block operations will not insert or replace code in the middle of any line of target code. If that is your intention, you must use one of the inline directives described in the next section.

Any unique code (block or fragment) can be used as a target for block inserts.

For %insert:before% the whole line(s) containing the target is pushed down to make room for the insertion.

For %insert:after% Mod Manger pushes all the lines following the last line of target code down to make room for the insertion.

Mod Manager will not break a line of target code for a block insertion. If an insertion is needed in the interior of a line, you must use one of the inline ops (see below.)

The target for %replace:% must be a block -- no fragments allowed here or Mod Manager will generate an error. Leading white space is automatically matched and the entire block is replaced.

The following shows how search or replacement strings are constructed and used. Target_code (%location:%) and new_code both come from the cfg file.

• %insert:before%

list: search for trimmed new_code+CRLF (installed)
      search for trimmed target_code (OK to install)
      (Bad Target if neither found)

install: insert new_code+CRLF before first line of target code

remove: delete new_code+CRLF

• %insert:after%

list: search for trimmed CRLF+new_code (installed) 
      search for trimmed target_code_trimmed (OK to install)
      (Bad Target if neither found)

install: insert CRLF+new_code after last line of target_code

remove: delete CRLF+new_code

• %replace:%

list: search for trimmed new_code (installed) 
      search for trimmed target_code (OK to install) 
      (Bad Target if neither found)

install: mark beginning of target block -- first line, left margin 
         mark end of target block -- last line, right margin
         replace everything in between with new_code

remove: replace new_code with target_code (from cfg)

Inline Directives

Inline describes partial lines (fragments) of code. Inline directives let us insert or replace pieces of a line(s) of target code.

Inline directives can accept a unique block or a fragment of code as a target, but will always handle them as a fragment.

Inline directives do not auto-match white space -- any leading or trailing white space included in the cfg target_code must exactly match that in the target file.

Inline directives do not add blank lines to separate new_code from target_code (naturally.) New_code is concatenated to target_code or else it replaces it.

• %triminsert:before%

list: search for new_code+target_code (installed) 
      search for target_code(OK to install)
      (Bad Target if neither found)

install: set insertion point before target_code
         insert new_code

remove: replace new_code+target_code with target_code (from cfg)

• %triminsert:after%

list: search for target_code+new_code (installed) 
      search for target_code (OK to install)
      (Bad Target if neither found)

install: set insertion point after target_code
         insert new_code
    
remove: replace target_code+new code with target_code (from cfg)

• %trimreplace:%

list: search for new_code (installed) 
      search for target_code(OK to install)
      (Bad Target if neither found)

install: replace target_code with new_code
    
remove: replace new_code with target_code (from cfg)

Simulate Block Directives

The purpose here is not to show developers how to end-run a block directive, but to provide a deeper insight into the differences between block and inline operations. It will also explain how the wrong directive will sometimes work if all the criteria for it are in place.

Use %triminsert:before% as a Block Op

For this to work, the following two criteria must be satisfied:

1. target must be a complete line(s) of code
2. cfg and target leading and trailing white space must exactly match

Because %insert:before% adds a blank line *after* the inserted code, your %triminsert:before% must explicitly provide one in the cfg code. In other words, the last line of the cfg code must be a blank line to separate it from the target code.

• Benefit: none.
• Risk: bad target errors if white space does not exactly match.

Use %trimreplace:% as a Block Op

For this to work, the target code must meet the following criteria:

1. target must be a complete line(s) of code
2. leading and trailing white space must exactly match

• Benefit: none.
• Risk: bad target errors if white space does not exactly match.

Operational Directives For File Manipulation

There are three operational directives used for manipulating files.

• %copyfile
• %copyfile2
• %newfile

Starting with TNG 10.1, the optional file parameter @ for %copyfile or %copyfile2 also allows files that cannot be removed because they are in use on Windows environments to not generate an error. Likewise if the mod contains the @optional file parameter and the file exists, it will not be counted as already installed in the status, allowing the mod to be re-installed.

Mod Manager looks for the @sign prepended to the first file name listed in the directive:

%copyfile2:@{source_file_path}:{destination_file_path}%

File operations with the @ sign are always treated as optional and no errors are generated if they fail to copy for whatever reason.

File copy directives are processed whenever and wherever encountered in the mod config file. For convenience file copies can all be placed together in a section headed %target:files% and terminated with an %end:% tag.

copyfile

%copyfile:{file_path}% has one argument -- the source file. It will copy the file identified by file_path to the TNG root directory. In practice the file to be copied will reside in a folder placed inside the mods folder and the directive will look something like this:

%copyfile:censusplus_v10103/admin_censusplus.php%

Mod Manager constructs the complete file source path using the $rootpath and $modspath from the TNG config file: rootpath+modspath+file_path. Thus the file_path given as an argument to copyfile must always be relative to the TNG mods folder. To copy a file from the extensions folder the argument would have to be: ../extensions/file_name.

copyfile2

%copyfile2:{source_file_path}:{destination_file_path}% has two arguments source and destination files. Whereas %copyfile:% only copies files to the TNG root, %copyfile2% copies the file to any valid location. Prepending the @ sign will bypass the command if the destination file path does not exist.

%copyfile2:gmaps_add_4_placelevels/058.png:img/058.png%
%copyfile2:@censusplus_v10103/cp_text.php:languages/Dutch-UTF8/cp_text.php%

In the second (fictional) example above, if the user does not have a Dutch-UTF8 language folder on his TNG site, only a notice is issued and the mod continues to install its other components.

Note that the optional file directive on a copyfile, the @ at sign, can also be used to tell the Mod Manager not to raise an error if the file is already installed or cannot be removed. This is useful for font files on a local WampServer where Windows does not allow the file to be deleted on an Uninstall, such as in the Google Maps - More Place Levels Mod as shown below

%copyfile2:@gmaps_add_4_placelevels/LiberationSans-Regular.ttf:LiberationSans-Regular.ttf%

Related Links

Mod Manager

• Overview
• Why Use It ?
• Installing Config Files
• Batch Updates
• Interpreting Status
• Editing Parameters
• Deleting Mods

Mod Manager Controls

• Mod Manager Options

For Mod Developers

• Mod Guidelines
• Mod Manager Syntax
• Creating Config Files
• Config File Creation Example
• Avoiding Mod Conflicts
• Using the TNG File Analyzer
• Mod_Manager_Enhancements_TNG_v12

Technical

• Technical Overview
• Technical Directives
• Quick Reference
• Inside Mod Manager v12

Developer Tools

• Notepad++ Mod Manager Language

Example Mods

• Managing Configuration Files
• Managing Stylesheet Overrides