6.23.3.2. Requirements

The function 'compare_files' shall return 1 if two text files have the same contents, and 0 otherwise. The comparison may ignore whitespace at the end of lines but is not required to. The compare files function shall return 1 if the files are exactly equal, in particular if the same file is given as both arguments.

The function 'compare_code_files' is the same as 'compare_files' except it may accept keyword arguments specifying the language of the source code. If such arguments are supplied the function may perform a semantic comparison of the code, and return 1 if the codes are equivalent. The purpose of the function is primarily to avoid rebuilding files differing only in comments, blank lines, etc.

The function 'diff_files' compares two text files, the original file and an upgraded file, and returns a string describing the differences. The string may be in any format, but it must be possible for the patch_file function to modify the original file using this string, and produce an upgraded file which compares equal using the compare files function.

The function 'diff_strings' compares two strings, returning a context diff as a string.

The function 'diff_lines' compares two sequences of strings, returning a diff descriptor as follows (code, left, right). Code may be 'c' for change or 's' for common, left and right are line counts.

The function 'patch_file' takes a string and an original file, and the name of an upgraded file, and produces an upgraded file which has been modified by the patch string in such a way that the compare_files function will report the files are equal. In addition, the function shall accept an empty patch string signifying no differences between the original and upgraded files.

This function is not required to operate correctly if the orginal file has been modified since the patch string was produced by diff_files.

The names of the argument files shall not denote the same file.

The function shall return a result

The function 'posix_patch' is optional. If this function is present, it will take a patch string produced by the standard posix context diff and patch the file. The purpose of this function is to facilitate use of posix context diff as an Internet standard method of transporting source code patches.

The specification of this function is defined as the result of calling diff with the -C option on a system compliant with the ISO Posix standard.