6.4.3 Filename merge with MD5 protected block

To preserve hand-made changes in an output file use the following template:

filename ...FILENAME... merge
   ...
   md5id ...ID... md5block
      ...BODY...
   md5sum
   ...
close

The generated output on file ...NAME... will be:

...
/* MEPMD5 ...ID... */
...BODY...
/* MEPMD5 1234567890abcdef1234567890abcdef */
...

This output will be merged with the file ...NAME... on disk. A block in the generator output will be replaced by the block on the disk if its ...ID... is the same and the body of the disk block has been edited. The generator knows this because its MD5 checksum will not match the checksum on disk.

Notes:

The start and stop tokens, /* MEPMD5 ... */, must be unique in the file. The start and stop tokens are used by MetaEdit+ to parse the file: look for a start token, read up to a stop token to get the ID, read up to the next start token to get the BODY, and read up to the next stop token to get the MD5 checksum. The start and stop tokens thus must not be empty, MD5 blocks may not be nested, and there are some restrictions on where the start and stop tokens may appear elsewhere in the file content. The start token, by default '/* MEPMD5 ', must not appear in the file other than at the start and end of an MD5 block. The stop token, by default ' */' newline, must not be found in the ID or MD5 checksum. Since comment characters are different in different file types, the default tokens can be changed for a file using the md5start and md5stop keywords:

filename 'foo.txt' 
   [md5start '/* MEPMD5 ' ...] 
 [md5stop ' */' newline ...]
(merge|write|append)
   ...
close

If they are not explicitly declared, then they default to the values above, even if there is no enclosing file stream.

	The body is converted to UTF-8 when calculating MD5. This is standard practicefor MD5, to prevent missing differences between things like x (0078 hex) and Y umlaut (0178 hex).
	The MD5 checksum is output as 32 lowercase hex digits, as in the RFC1321 test suite. It is compared as a string, not a number, and the extra spaces at the start and end are stripped first.
	A block in a file counts as edited (and hence should be preserved) if it has a non-empty MD5 string, and that does not match the MD5 string calculated for the block. This allows you to:

	edit just the MD5 string, e.g. to 0, to protect the current block
	edit the contents of a block, and have that edit preserved
	delete the MD5 part (or better, replace it with spaces, since normally there will be two spaces anyway: /* MEPMD5 */) to mark that you no longer want that block to be preserved, and the next generator run should overwrite it.

	Only the `merge` variant of `filename...close` actually causes a merge, and is based purely on the contents of its output stream and that on the disk, not on whether any MD5 commands were run directly in it.
	The output tool shows the status 'written' if the file did not exist before, 'unchanged' if the file existed but would be unchanged by the merge result, and 'merged' if the file existed beforehand and was written now (whether or not any blocks were preserved).
	The output tool entry's contents are what was written to disk, i.e. the mixture of model output and disk contents.