path: root/libpatch.h

/* See LICENSE file for copyright and license details. */
#ifndef LIBPATCH_H
#define LIBPATCH_H

#include <sys/stat.h>
#include <limits.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <time.h>


/**
 * Patch file format
 */
enum libpatch_style {
	/**
	 * Style could not be determined
	 * 
	 * Always invalid as function input
	 * (EINVAL error)
	 */
	LIBPATCH_STYLE_GARBAGE,

	/**
	 * “Normal” format
	 * 
	 * See “Diff Default Output Format”
	 * in diff(1p) for details
	 * 
	 * If nonstandard syntax is enabled, context
	 * will be printed with a “  ”-prefix
	 * 
	 * As a common extension to the format,
	 * if a file does not end with a <newline>,
	 * “\” followed by some text will be printed
	 * after that line is included in the patch
	 */
	LIBPATCH_STYLE_NORMAL,

	/**
	 * “Copied” format
	 * 
	 * See “Diff -c or -C Output Format”
	 * in diff(1p) for details
	 * 
	 * As a common extension to the format,
	 * if a file does not end with a <newline>,
	 * “\” followed by some text will be printed
	 * after that line is included in the patch
	 */
	LIBPATCH_STYLE_COPIED,

	/**
	 * “Unified” format
	 * 
	 * See “Diff -u or -U Output Format”
	 * in diff(1p) for details
	 * 
	 * As a common extension to the format,
	 * if a file does not end with a <newline>,
	 * “\” followed by some text will be printed
	 * after that line is included in the patch
	 */
	LIBPATCH_STYLE_UNIFIED,

	/**
	 * ed(1) format
	 * 
	 * See “Diff -e Output Format”
	 * in diff(1p) for details
	 */
	LIBPATCH_STYLE_ED,

	/**
	 * Alternative ed(1) format
	 * 
	 * See “Diff -f Output Format”
	 * in diff(1p) for details
	 * 
	 * Diff scripts in this format are usually
	 * ambiguous and can therefore not be parsed
	 */
	LIBPATCH_STYLE_ED_ALTERNATIVE,

	/**
	 * RCS format
	 * 
	 * This is a non-POSIX format
	 */
	LIBPATCH_STYLE_RCS
};


/**
 * How a file label shall be formatted
 */
enum libpatch_label_format {
	/**
	 * An error occured
	 */
	LIBPATCH_LABEL_ERROR = -1,

	/**
	 * The patch format does not support file labels
	 */
	LIBPATCH_LABEL_NONE,

	/**
	 * The patch format file label shall
	 * just be the filepath
	 */
	LIBPATCH_LABEL_FILE_ONLY,

	/**
	 * The patch format file label shall
	 * be the filepath followed by a regular
	 * space, followed by the file's mtime
	 */
	LIBPATCH_LABEL_FILE_SPACE_MTIME,

	/**
	 * The patch format file label shall
	 * be the filepath followed by a regular
	 * space, followed by the file's mtime
	 */
	LIBPATCH_LABEL_FILE_TAB_MTIME
};


/**
 * Partial text comparision
 */
struct libpatch_diff2 {
	/**
	 * Which files are changed, or if
	 * the text included as context?
	 */
	enum {
		/**
		 * Text appears in both file
		 */
		LIBPATCH_DIFF2_SKIP = 0x00,

		/**
		 * Text only appears in file 1 (removed)
		 */
		LIBPATCH_DIFF2_FILE1_ONLY = 0x01,

		/**
		 * Text only appears in file 2 (added)
		 */
		LIBPATCH_DIFF2_FILE2_ONLY = 0x02,

		/**
		 * Text is different between file 1 and file 2
		 */
		LIBPATCH_DIFF2_TWO_FILE_CHANGE = 0x03,

		/**
		 * Same as `LIBPATCH_DIFF2_SKIP` except
		 * the text shall be included as context
		 * for a change
		 */
		LIBPATCH_DIFF2_CONTEXT = 1 << 2
	} change : CHAR_BIT;

	/**
	 * The number of consecutive units of
	 * text that `.change` apply to
	 */
	unsigned int repetition : sizeof(int) * CHAR_BIT - CHAR_BIT;
};


/**
 * Specifications for how a diff string shall be organised
 */
struct libpatch_diff2_spec {
	/**
	 * The number of units of text that shall
	 * be included as context before for a change
	 */
	size_t context_before;
	
	/**
	 * If there are up to (inclusive) this number
	 * of units of texts between two changes, the
	 * two changes shall be included as one hunk
	 * 
	 * If `.context_after + .context_before > .context_between`,
	 * `.context_after + .context_before` is effective
	 * used for `.context_between`
	 */
	size_t context_between;
	
	/**
	 * The number of units of text that shall
	 * be included as context after for a change
	 */
	size_t context_after;

	/**
	 * Whether to include all unchanged code as
	 * context. This is the same as setting
	 * `.context_before` and `.context_after`
	 * to `SIZE_MAX`, except that if there are
	 * no changes, the entire file is still used
	 * as context
	 */
	unsigned full_context : 1;

	/**
	 * If 0, keep each `LIBPATCH_DIFF2_FILE1_ONLY`
	 * and `LIBPATCH_DIFF2_FILE2_ONLY`. If 1,
	 * replace each pair of `LIBPATCH_DIFF2_FILE1_ONLY`
	 * and `LIBPATCH_DIFF2_FILE2_ONLY`, that appear
	 * in a consecutive group of changes, with a
	 * `LIBPATCH_DIFF2_TWO_FILE_CHANGE`
	 *
	 * Has no effect if `.two_file_change_order` is
	 * `LIBPATCH_DIFF2_NO_TWO_FILE_CHANGES` or
	 * `LIBPATCH_DIFF2_NO_TWO_FILE_CHANGES_INTERLEAVE`
	 */
	unsigned keep_split_changes : 1;

	enum {
		/**
		 * Text that only appear in file 1
		 * shall be included in the patch before
		 * any text that appears in file 2
		 * (that is not indentical in file 1)
		 */
		LIBPATCH_DIFF2_FILE1_ONLY_FIRST,

		/**
		 * Text that only appear in file 2
		 * shall be included in the patch before
		 * any text that appears in file 1
		 * (that is not indentical in file 2)
		 */
		LIBPATCH_DIFF2_FILE2_ONLY_FIRST
	} single_file_change_order : 1;

	enum {
		/**
		 * Each `LIBPATCH_DIFF2_TWO_FILE_CHANGE` shall
		 * be rewritten as `LIBPATCH_DIFF2_FILE1_ONLY`
		 * and `LIBPATCH_DIFF2_FILE2_ONLY` (doubling the
		 * number of reported changes). Each group of
		 * `LIBPATCH_DIFF2_FILE1_ONLY` and
		 * `LIBPATCH_DIFF2_FILE2_ONLY` shall be sorted
		 * according to `.single_file_change_order`
		 */
		LIBPATCH_DIFF2_NO_TWO_FILE_CHANGES,

		/**
		 * Same as `LIBPATCH_DIFF2_NO_TWO_FILE_CHANGES_INTERLEAVE`
		 * except that, to the extent possible, there shall be
		 * and alternation between `LIBPATCH_DIFF2_FILE1_ONLY`
		 * and `LIBPATCH_DIFF2_FILE2_ONLY`
		 */
		LIBPATCH_DIFF2_NO_TWO_FILE_CHANGES_INTERLEAVE,

		/**
		 * In consecutive changes, all
		 * `LIBPATCH_DIFF2_TWO_FILE_CHANGE`s shall
		 * be put in the front
		 */
		LIBPATCH_DIFF2_TWO_FILE_CHANGES_BEFORE_SINGLE_FILE,

		/**
		 * In consecutive changes, all
		 * `LIBPATCH_DIFF2_TWO_FILE_CHANGE`s shall
		 * be put after all of whichever shall appear
		 * first of `LIBPATCH_DIFF2_FILE1_ONLY` and
		 * `LIBPATCH_DIFF2_FILE2_ONLY`, but before
		 * the other ones
		 */
		LIBPATCH_DIFF2_TWO_FILE_CHANGES_BETWEEN_SINGLE_FILE,

		/**
		 * In consecutive changes, all
		 * `LIBPATCH_DIFF2_TWO_FILE_CHANGE`s shall
		 * be put in the back
		 */
		LIBPATCH_DIFF2_TWO_FILE_CHANGES_AFTER_SINGLE_FILE
	} two_file_change_order : 3;
};


/**
 * A line from a patch file
 */
struct libpatch_patch {
	/**
	 * What the line represents
	 */
	enum {
		/**
		 * The line does not mean anything and
		 * should be ignored if at an appropriate
		 * location
		 */
		LIBPATCH_PATCH_GARBAGE,

		/**
		 * The line is simply require by the
		 * patch format and can be ignored
		 */
		LIBPATCH_PATCH_SYNTACTICAL,

		/**
		 * Line describing what files are compared
		 * and how (used in multi-file patchsets)
		 * 
		 * The line's non-syntactical text is the
		 * command line arguments after "diff"
		 */
		LIBPATCH_PATCH_DIFF_LINE,

		/**
		 * The line's non-syntactical text is the first
		 * file's label (see `libpatch_get_label_format`)
		 */
		LIBPATCH_PATCH_FILE1_LABEL,

		/**
		 * The line's non-syntactical text is the second
		 * file's label (see `libpatch_get_label_format`)
		 */
		LIBPATCH_PATCH_FILE2_LABEL,

		/**
		 * Beginning of a hunk, `.first_line` and
		 * `.line_count` are set to indicate
		 * required deletion
		 * 
		 * The line's non-syntactical text is context
		 * for the hunk intended for human reading
		 */
		LIBPATCH_PATCH_HUNK_WITH_DELETION,

		/**
		 * Beginning of a hunk
		 * 
		 * The line's non-syntactical text is context
		 * for the hunk intended for human reading
		 */
		LIBPATCH_PATCH_HUNK,

		/**
		 * Beginning of text deletions in a hunk
		 * 
		 * The line's non-syntactical text is context
		 * for the hunk intended for human reading
		 */
		LIBPATCH_PATCH_HUNK_FILE1,

		/**
		 * Beginning of text insertions in a hunk
		 * 
		 * The line's non-syntactical text is context
		 * for the hunk intended for human reading
		 */
		LIBPATCH_PATCH_HUNK_FILE2,

		/**
		 * The line's non-syntactical text is
		 * context for an hunk
		 */
		LIBPATCH_PATCH_CONTEXT,

		/**
		 * The line's non-syntactical text is
		 * context for text deletion
		 */
		LIBPATCH_PATCH_FILE1_CONTEXT,

		/**
		 * The line's non-syntactical text is
		 * context for text insertion
		 */
		LIBPATCH_PATCH_FILE2_CONTEXT,

		/**
		 * The line's non-syntactical text is
		 * a line of text to delete
		 */
		LIBPATCH_PATCH_FILE1_ONLY,

		/**
		 * The line's non-syntactical text is
		 * a line of text to insert
		 */
		LIBPATCH_PATCH_FILE2_ONLY,

		/**
		 * The line's non-syntactical text is
		 * a line of text to delete for which
		 * there also is an insertion
		 */
		LIBPATCH_PATCH_PRECHANGE,

		/**
		 * The line's non-syntactical text is
		 * a line of text to insertion for which
		 * there also is an deletion
		 */
		LIBPATCH_PATCH_POSTCHANGE
	} type : 7;

	/**
	 * Usually 1, but if the text line shall
	 * not be <newline>-terminated, it is 0
	 */
	unsigned lf_terminated : 1;

	/**
	 * The byte in the patch file where
	 * the line's non-syntactical text begins
	 */
	size_t text_offset;

	/**
	 * The length of the line's non-syntactical text
	 */
	size_t text_length;

	/**
	 * The first line (counted from 1) to
	 * delete from the first line, or 0 if
	 * not applicable
	 */
	size_t first_line;

	/**
	 * The number of lines to delete from
	 * the first file
	 */
	size_t line_count;

	/**
	 * The line number (counted from 1) in the
	 * first file, or 0 if not applicable
	 */
	size_t file1_lineno;

	/**
	 * The line number (counted from 1) in the
	 * second file, or 0 if not applicable
	 */
	size_t file2_lineno;
};


/**
 * A line of text
 */
struct libpatch_line {
	/**
	 * The number of bytes in the text
	 */
	size_t len;

	/**
	 * The text
	 */
	char text[];
};


/**
 * Description of a compared file
 */
struct libpatch_file {
	/**
	 * The file's label (see `libpatch_get_label_format`)
	 */
	const char *label;

	/**
	 * Whether the file ends with a <newline>
	 */
	unsigned lf_terminated;

	/**
	 * The number of lines in the file
	 */
	size_t nlines;

	/**
	 * Each line in the file, these are not <newline> terminated
	 */
	struct libpatch_line **lines;
};


/**
 * How a diff should be printed
 */
struct libpatch_diff2_printer {
	/* TODO doc */
	void (*put_end_of_change)(struct libpatch_diff2_printer *this, const char *text);
	void (*put_syntactical_escape)(struct libpatch_diff2_printer *this, const char *text);
	void (*put_syntactical_garbage)(struct libpatch_diff2_printer *this, const char *text);
	void (*put_hunk_head_prefix)(struct libpatch_diff2_printer *this, const char *text, int file /* 0 if both */);
	void (*put_hunk_head_suffix)(struct libpatch_diff2_printer *this, const char *text, int file /* 0 if both */);
	void (*put_hunk_start)(struct libpatch_diff2_printer *this, const char *prefix, size_t value, int file /* 1 or 2 */);
	void (*put_hunk_end)(struct libpatch_diff2_printer *this, const char *prefix, size_t value, int file /* 1 or 2 */);
	void (*put_hunk_length)(struct libpatch_diff2_printer *this, const char *prefix, size_t value, int file /* 1 or 2 */);
	void (*put_hunk_operation)(struct libpatch_diff2_printer *this, const char *text, int file1, int file2);
	void (*put_label_prefix)(struct libpatch_diff2_printer *this, const char *prefix, int file /* 1 or 2 */);
	void (*put_label)(struct libpatch_diff2_printer *this, const char *label, int file /* 1 or 2 */);
	void (*put_context_prefix)(struct libpatch_diff2_printer *this, const char *prefix,
	                           int file1, int file2, size_t lineno);
	void (*put_change_prefix)(struct libpatch_diff2_printer *this, const char *prefix,
	                          int file /* 1 or 2 */, int two_file_change, size_t lineno);

	/**
	 * Output text from a compared file
	 * 
	 * Fill be preceeded by one `.put_context_prefix` or
	 * one `.put_change_prefix`, even if the prefix text
	 * is empty, followed by any number of `.put_whitespace`
	 * 
	 * @param  this  The container of this member function
	 * @param  line  The text to output
	 */
	void (*put_line)(struct libpatch_diff2_printer *this, struct libpatch_line *line);

	/**
	 * Called any time syntactical whitespace shall be
	 * output
	 * 
	 * @param  this  The container of this member function
	 * @param  text  The text to output
	 */
	void (*put_whitespace)(struct libpatch_diff2_printer *this, const char *text);

	/**
	 * Called any time <newline> should be output
	 * 
	 * @param  this  The container of this member function
	 */
	void (*put_newline)(struct libpatch_diff2_printer *this);

	/**
	 * Output a text that is used to mark that a line
	 * is not properly terminated with a <newline>
	 * 
	 * @param  this  The container of this member function
	 * @param  text  The text to output
	 */
	void (*put_no_newline)(struct libpatch_diff2_printer *this, const char *text);

	/**
	 * If 1, patches with “unified” format shall will
	 * use text from the second file for context
	 * 
	 * If 0, patches with “unified” format shall will
	 * use text from the first file for context
	 */
	unsigned use_file2_when_common : 1;

	/**
	 * If 0, the output shall be as portable as possible
	 * (changes that cannot be describe in standard format
	 * or would safely enough be interpreted as garbage
	 * and is very rare will still be included.)
	 * 
	 * If 1, patches in “normal” format can include
	 * context, if 0, such context would be printed
	 * as changes (that don't actually change anything)
	 */
	unsigned use_nonstandard_syntax : 1;

	/**
	 * If an error is encountered, the errno(3) value is stored here
	 */
	int error;

	/**
	 * User-defined data (implementation-definied if set by the library)
	 */
	void *user_data;
};


/**
 * Create a `struct libpatch_diff2_printer` to
 * print a patch file that is parsable by patch(1)
 * (that is, without any colours or other additions
 * to aid human reading)
 *
 * @param   output  The file stream to print to
 * @return          The printer, `NULL` on failure; deallocate with free(3)
 * @throws  ENOMEM  Failed to allocate enough memory
 */
struct libpatch_diff2_printer *libpatch_plain_stream_diff2_printer(FILE *output);

/**
 * Create a `struct libpatch_diff2_printer` to
 * print a patch file that is parsable by patch(1)
 * (that is, without any colours or other additions
 * to aid human reading)
 *
 * @param   output  The file descriptor to print to
 * @return          The printer, `NULL` on failure; deallocate with free(3)
 * @throws  ENOMEM  Failed to allocate enough memory
 */
struct libpatch_diff2_printer *libpatch_plain_fd_diff2_printer(int output);

/**
 * Create file timestamp for diff header
 * 
 * @param   buf                  Output buffer for the time stamp; will be NUL-terminated
 *                               provided that the function returns a value that is no
 *                               greater than `bufsize` (may or may not be NUL-terminated
 *                               otherwise)
 * @param   bufsize              The size of `buf`
 * @param   tm                   The time to use in the timestamp
 * @param   subseconds           The subseconds in the timestamp
 * @param   subseconds_decimals  The number of decimals in the subseconds
 * @param   frac                 The number of subsecond decimals to include in the
 *                               timestamp (of allowed), at most (the function may choose
 *                               to include less)
 * @param   zone                 Whether to include the timezone (ignored unless optional)
 * @param   style                The diff style the timestamp shall be generated for
 * @return                       The length of the time stamp, including terminal NUL byte, 0 on
 *                               failure. This value will exceed `bufsize` if `buf` is to small.
 *                               It is possible that if `bufsize` is too small, an overly large
 *                               value is returned.
 * @throws  EINVAL               `style` is not a style that uses a diff header with timestamps
 */
size_t libpatch_create_timestamp(char *buf, size_t bufsize, const struct tm *tm,
                                 uintmax_t subseconds, unsigned subseconds_decimals, 
                                 unsigned frac, int zone, enum libpatch_style style);

/**
 * Create file timestamp for diff header
 * 
 * @param   buf      Output buffer for the time stamp; will be NUL-terminated
 *                   provided that the function returns a value that is no
 *                   greater than `bufsize` (may or may not be NUL-terminated
 *                   otherwise)
 * @param   bufsize  The size of `buf`
 * @param   tm       The time to use in the timestamp
 * @param   frac     `NULL` or the string of subsecond decimals (any non-digit
 *                   character is interpreted as a string termination)
 * @param   zone     Whether to include the timezone (ignored unless optional)
 * @param   style    The diff style the timestamp shall be generated for
 * @return           The length of the time stamp, including terminal NUL byte, 0 on
 *                   failure. This value will exceed `bufsize` if `buf` is to small.
 *                   It is possible that if `bufsize` is too small, an overly large
 *                   value is returned.
 * @throws  EINVAL   `style` is not a style that uses a diff header with timestamps
 */
size_t libpatch_create_timestamp_frac_string(char *buf, size_t bufsize, const struct tm *tm,
                                             const char *frac, int zone, enum libpatch_style style);

/**
 * Create file timestamp for diff header
 * 
 * @param   buf      Output buffer for the time stamp; will be NUL-terminated
 *                   provided that the function returns a value that is no
 *                   greater than `bufsize` (may or may not be NUL-terminated
 *                   otherwise)
 * @param   bufsize  The size of `buf`
 * @param   tm       The time to use in the timestamp
 * @param   zone     Whether to include the timezone (ignored unless optional)
 * @param   style    The diff style the timestamp shall be generated for
 * @return           The length of the time stamp, including terminal NUL byte, 0 on
 *                   failure. This value will exceed `bufsize` if `buf` is to small.
 *                   It is possible that if `bufsize` is too small, an overly large
 *                   value is returned.
 * @throws  EINVAL   `style` is not a style that uses a diff header with timestamps
 */
inline size_t
libpatch_create_timestamp_tm(char *buf, size_t bufsize, const struct tm *tm,
                             int zone, enum libpatch_style style)
{
	return libpatch_create_timestamp(buf, bufsize, tm, 0, 0, 0, zone, style);
}

/**
 * Create file timestamp for diff header
 * 
 * @param   buf      Output buffer for the time stamp; will be NUL-terminated
 *                   provided that the function returns a value that is no
 *                   greater than `bufsize` (may or may not be NUL-terminated
 *                   otherwise)
 * @param   bufsize  The size of `buf`
 * @param   ts       The time to use in the timestamp
 * @param   frac     The number of subsecond decimals to include in the
 *                   timestamp (of allowed), at most (the function may choose
 *                   to include less)
 * @param   zone     Whether to include the timezone (ignored unless optional)
 * @param   style    The diff style the timestamp shall be generated for
 * @return           The length of the time stamp, including terminal NUL byte, 0 on
 *                   failure. This value will exceed `bufsize` if `buf` is to small.
 *                   It is possible that if `bufsize` is too small, an overly large
 *                   value is returned.
 * @throws  EINVAL   `style` is not a style that uses a diff header with timestamps
 * @throws           Any error from localtime(3)
 */
inline size_t
libpatch_create_timestamp_ts(char *buf, size_t bufsize, const struct timespec *ts,
                             unsigned frac, int zone, enum libpatch_style style)
{
	struct tm *tm, tmbuf;
	tm = localtime_r(&ts->tv_sec, &tmbuf);
	return tm ? libpatch_create_timestamp(buf, bufsize, tm, (uintmax_t)ts->tv_nsec, 9, frac, zone, style) : 0;
}

/**
 * Create file timestamp for diff header
 * 
 * @param   buf      Output buffer for the time stamp; will be NUL-terminated
 *                   provided that the function returns a value that is no
 *                   greater than `bufsize` (may or may not be NUL-terminated
 *                   otherwise)
 * @param   bufsize  The size of `buf`
 * @param   tv       The time to use in the timestamp
 * @param   frac     The number of subsecond decimals to include in the
 *                   timestamp (of allowed), at most (the function may choose
 *                   to include less)
 * @param   zone     Whether to include the timezone (ignored unless optional)
 * @param   style    The diff style the timestamp shall be generated for
 * @return           The length of the time stamp, including terminal NUL byte, 0 on
 *                   failure. This value will exceed `bufsize` if `buf` is to small.
 *                   It is possible that if `bufsize` is too small, an overly large
 *                   value is returned.
 * @throws  EINVAL   `style` is not a style that uses a diff header with timestamps
 * @throws           Any error from localtime(3)
 */
inline size_t
libpatch_create_timestamp_tv(char *buf, size_t bufsize, const struct timeval *tv,
                             unsigned frac, int zone, enum libpatch_style style)
{
	struct tm *tm, tmbuf;
	tm = localtime_r(&tv->tv_sec, &tmbuf);
	return tm ? libpatch_create_timestamp(buf, bufsize, tm, (uintmax_t)tv->tv_usec, 6, frac, zone, style) : 0;
}

/**
 * Create file timestamp for diff header
 * 
 * @param   buf      Output buffer for the time stamp; will be NUL-terminated
 *                   provided that the function returns a value that is no
 *                   greater than `bufsize` (may or may not be NUL-terminated
 *                   otherwise)
 * @param   bufsize  The size of `buf`
 * @param   secs     The time to use in the timestamp
 * @param   zone     Whether to include the timezone (ignored unless optional)
 * @param   style    The diff style the timestamp shall be generated for
 * @return           The length of the time stamp, including terminal NUL byte, 0 on
 *                   failure. This value will exceed `bufsize` if `buf` is to small.
 *                   It is possible that if `bufsize` is too small, an overly large
 *                   value is returned.
 * @throws  EINVAL   `style` is not a style that uses a diff header with timestamps
 * @throws           Any error from localtime(3)
 */
inline size_t
libpatch_create_timestamp_secs(char *buf, size_t bufsize, time_t secs,
                               int zone, enum libpatch_style style)
{
	struct tm *tm, tmbuf;
	tm = localtime_r(&secs, &tmbuf);
	return tm ? libpatch_create_timestamp(buf, bufsize, tm, 0, 0, 0, zone, style) : 0;
}

/**
 * Create file timestamp, from file status, for diff header
 * 
 * @param   buf      Output buffer for the time stamp; will be NUL-terminated
 *                   provided that the function returns a value that is no
 *                   greater than `bufsize` (may or may not be NUL-terminated
 *                   otherwise)
 * @param   bufsize  The size of `buf`
 * @param   st       The file's status (mtime will be used)
 * @param   frac     The number of subsecond decimals to include in the
 *                   timestamp (of allowed), at most (the function may choose
 *                   to include less)
 * @param   zone     Whether to include the timezone (ignored unless optional)
 * @param   style    The diff style the timestamp shall be generated for
 * @return           The length of the time stamp, including terminal NUL byte, 0 on
 *                   failure. This value will exceed `bufsize` if `buf` is to small.
 *                   It is possible that if `bufsize` is too small, an overly large
 *                   value is returned.
 * @throws  EINVAL   `style` is not a style that uses a diff header with timestamps
 * @throws           Any error from localtime(3)
 */
inline size_t
libpatch_create_timestamp_stat(char *buf, size_t bufsize, const struct stat *st,
                               unsigned frac, int zone, enum libpatch_style style)
{
#ifdef st_mtime /* = st_mtim.tv_sec, infers existance of st->st_mtim */
	return libpatch_create_timestamp_ts(buf, bufsize, &st->st_mtim, frac, zone, style);
#else
	return libpatch_create_timestamp_secs(buf, bufsize, &st->st_mtime, zone, style);
#endif
}

/**
 * Create file timestamp, from a file descriptor, for diff header
 * 
 * @param   buf      Output buffer for the time stamp; will be NUL-terminated
 *                   provided that the function returns a value that is no
 *                   greater than `bufsize` (may or may not be NUL-terminated
 *                   otherwise)
 * @param   bufsize  The size of `buf`
 * @param   fd       The file descriptor (mtime will be used)
 * @param   frac     The number of subsecond decimals to include in the
 *                   timestamp (of allowed), at most (the function may choose
 *                   to include less)
 * @param   zone     Whether to include the timezone (ignored unless optional)
 * @param   style    The diff style the timestamp shall be generated for
 * @return           The length of the time stamp, including terminal NUL byte, 0 on
 *                   failure. This value will exceed `bufsize` if `buf` is to small.
 *                   It is possible that if `bufsize` is too small, an overly large
 *                   value is returned.
 * @throws  EINVAL   `style` is not a style that uses a diff header with timestamps
 * @throws           Any error from localtime(3) or fstat(3)
 */
inline size_t
libpatch_create_timestamp_fd(char *buf, size_t bufsize, int fd,
                             unsigned frac, int zone, enum libpatch_style style)
{
	struct stat st;
	return fstat(fd, &st) ? 0 : libpatch_create_timestamp_stat(buf, bufsize, &st, frac, zone, style);
}

/**
 * Create file timestamp, from the current time, for diff header
 *
 * According to POSIX, diff(1) shall (not explicitly a strict requirement)
 * use the current time in the timestamp if the file is standard input.
 * GNU diff uses the current time where the "-" operand is specified.
 * On Linux, pipes have timestamps so you would automatically get the
 * current time if standard input is a pipe.
 * 
 * @param   buf      Output buffer for the time stamp; will be NUL-terminated
 *                   provided that the function returns a value that is no
 *                   greater than `bufsize` (may or may not be NUL-terminated
 *                   otherwise)
 * @param   bufsize  The size of `buf`
 * @param   frac     The number of subsecond decimals to include in the
 *                   timestamp (of allowed), at most (the function may choose
 *                   to include less); -1 for autoselection
 * @param   zone     Whether to include the timezone (ignored unless optional)
 * @param   style    The diff style the timestamp shall be generated for
 * @return           The length of the time stamp, including terminal NUL byte, 0 on
 *                   failure. This value will exceed `bufsize` if `buf` is to small.
 *                   It is possible that if `bufsize` is too small, an overly large
 *                   value is returned.
 * @throws  EINVAL   `style` is not a style that uses a diff header with timestamps
 * @throws           Any error from localtime(3)
 */
size_t libpatch_create_timestamp_now(char *buf, size_t bufsize, signed frac, int zone,
                                     enum libpatch_style style);

/**
 * Parse a timestamp from a diff header
 * 
 * @param   text          The timestamp to parse (the mtime for a file)
 * @param   time_out      Output parameter for the timestamp (second-resolution);
 *                        `time_out->tm_isdst` and `time_out->tm_zone` will be undefined
 * @param   frac_out      Output parameter for the pointer to where in `text`
 *                        the fractions of the second start. If there are not
 *                        fractions of the second in the timestamp, `NULL` will
 *                        be stored in `*frac_out`.
 * @param   has_zone_out  Output parameter for whether the timestamp contained a
 *                        time zone
 * @param   style         The diff style the timestamp is assumed to use
 * @return                Pointer to pass the last parsed character in `text`, or
 *                        `NULL` on failure
 * @throws  EINVAL        `style` is not a style that uses a diff header with timestamps
 * @throws                Any error from strptime(3)
 */
const char *libpatch_parse_timestamp(const char *text, struct tm *time_out, const char **frac_out,
                                     int *has_zone_out, enum libpatch_style style);

/**
 * Get how a file label shall be formatted
 * 
 * @param   style   The diff style
 * @return          How file labels shall be formatted,
 *                  `LIBPATCH_LABEL_ERROR` on failure
 * @throws  EINVAL  `style` is not a recognised style
 */
enum libpatch_label_format libpatch_get_label_format(enum libpatch_style style);

/**
 * Rewrite a diff string
 * 
 * @param   diff     The output string, will be updated
 * @param   difflen  The string length, may be updated
 * @param   spec     Specification for desired diff string
 * @return           0 on success, -1 on failure
 * @throws  ENOMEM   Failed to allocate enough memory
 * 
 * Update to `*diff` may be incomplete on failure (causing corruption)
 */
int libpatch_rewrite_diff2(struct libpatch_diff2 **diff, size_t *difflen, const struct libpatch_diff2_spec *spec);

/**
 * Check what properties a file's content must have
 * 
 * Support for non-text files may be an extension of the standard
 * 
 * @param   style      The diff style
 * @param   multifile  Whether the created patchset may contain multiple diff scripts
 * @return             Bitmask of text properties the diff style requires:
 *                     * 0x01:  File must be LF-terminated
 *                     (subject to additional bits in future version)
 *                     -1 on failure; if 0, there no restrictions on the file
 * @throws  EINVAL     `style` is not a recognised style
 */
int libpatch_style_requires_text(enum libpatch_style style, int multifile);
#define LIBPATCH_STYLE_REQUIRES_LF_TERMINATION 0x01

/**
 * Check that a diff style supports a file's content
 * 
 * @param   file       The file
 * @param   style      The diff style
 * @param   multifile  Whether the created patchset may contain multiple diff scripts
 * @return             0 if the file is supported, positive if otherwise,
 *                     and -1 on failure; if the value is positive, the
 *                     bits as returned by `libpatch_style_requires_text`
 *                     that denote a property that is not satisfied as set
 *                     (bits for satisfied properties are cleared)
 * @throws  EINVAL     `style` is not a recognised style
 */
int libpatch_check_file(struct libpatch_file *file, enum libpatch_style style, int multifile);

/**
 * Check if a file descriptor refers to /dev/null
 *
 * Since diff(1) can be used to find whether a file
 * is identical or not to another file, diff(1) is
 * often piped to /dev/null to discard the diff output
 * (piping to /dev/zero has the same effect, but is
 * not common practice, and could be useful for
 * benchmarking). Therefore it can be a good idea to
 * check if standard out is /dev/null, and if so,
 * check whether the files are identical or not,
 * rather than doing the expensive work of creating
 * a patch file.
 * 
 * @param   fd  The file descriptor
 * @return      0 if the file descriptor is not /dev/null,
 *              1 if the file descriptor is /dev/null,
 *              -1 on failure
 * @throws      Any error for fstat(3) or stat(3)
 */
int libpatch_is_devnull(int fd);

/**
 * Get the next hunk in a patch
 * 
 * @param   diff          The diff string for the patch
 * @param   difflen       The length of `diff`
 * @param   position      The current position in `diff`, will be updated, start at 0
 * @param   ai            The current position in the first file, will be updated, start at 0
 * @param   bi            The current position in the second file, will be updated, start at 0
 * @param   an_out        Output parameter for the number of lines in the first file within
 *                        the hunk; before calling again, add this value to `*ai`
 * @param   bn_out        Output parameter for the number of lines in the second file within
 *                        the hunk; before calling again, add this value to `*bi`
 * @param   skip_context  If 0, include `LIBPATCH_DIFF2_CONTEXT` lines, exclude them otherwise
 * @return                The number of elements in `diff` that the hunk uses,
 *                        0 if there are no more hunks in the patch;
 *                        before calling again, add this value to `*position`
 */
size_t libpatch_next_hunk(struct libpatch_diff2 *diff, size_t difflen, size_t *position,
                          size_t *ai, size_t *bi, size_t *an_out, size_t *bn_out, int skip_context);

/**
 * Get the previous hunk in a patch
 * 
 * @param   diff          The diff string for the patch
 * @param   position      The position in `diff` where the current hunk ends, will be
 *                        updated; the initial value shall be the number of elements in `diff`
 * @param   ai            The current position in the first file, will be updated;
 *                        the initial value shall be the number of lines in the first file
 * @param   bi            The current position in the second file, will be updated;
 *                        the initial value shall be the number of lines in the second file
 * @param   an_out        Output parameter for the number of lines in the first file within
 *                        the hunk (do _not_ use this value to modify `*ai`)
 * @param   bn_out        Output parameter for the number of lines in the second file within
 *                        the hunk (do _not_ use this value to modify `*bi`)
 * @param   skip_context  If 0, include `LIBPATCH_DIFF2_CONTEXT` lines, exclude them otherwise
 * @return                The number of elements in `diff` that the hunk uses,
 *                        0 if there are no more hunks in the patch;
 *                        (do _not_ use this value to modify `*position`)
 */
size_t libpatch_previous_hunk(struct libpatch_diff2 *diff, size_t *position,
                              size_t *ai, size_t *bi, size_t *an_out, size_t *bn_out, int skip_context);

/**
 * Print a patch in “unified” format
 * 
 * @param   printer  Patch printer
 * @param   diff     The diff string for the patch
 * @param   difflen  The number of elements in `diff`
 * @param   file1    The first file
 * @param   file2    The second file
 * @return           0 on success, -1 on failure (always successful in the current implementation)
 */
int libpatch_format_unified_patch(struct libpatch_diff2_printer *printer, struct libpatch_diff2 *diff, size_t difflen,
                                  const struct libpatch_file *file1, const struct libpatch_file *file2);

/**
 * Print a patch in “copied” format
 * 
 * @param   printer  Patch printer
 * @param   diff     The diff string for the patch
 * @param   difflen  The number of elements in `diff`
 * @param   file1    The first file
 * @param   file2    The second file
 * @return           0 on success, -1 on failure (always successful in the current implementation)
 */
int libpatch_format_copied_patch(struct libpatch_diff2_printer *printer, struct libpatch_diff2 *diff, size_t difflen,
                                 const struct libpatch_file *file1, const struct libpatch_file *file2);

/**
 * Print a patch in “normal” format
 * 
 * @param   printer  Patch printer
 * @param   diff     The diff string for the patch
 * @param   difflen  The number of elements in `diff`
 * @param   file1    The first file
 * @param   file2    The second file
 * @return           0 on success, -1 on failure (always successful in the current implementation)
 */
int libpatch_format_normal_patch(struct libpatch_diff2_printer *printer, struct libpatch_diff2 *diff, size_t difflen,
                                 const struct libpatch_file *file1, const struct libpatch_file *file2);

/**
 * Print a patch in “alternative ed” format
 * 
 * @param   printer  Patch printer
 * @param   diff     The diff string for the patch
 * @param   difflen  The number of elements in `diff`
 * @param   file1    The first file
 * @param   file2    The second file
 * @return           0 on success, -1 on failure
 * @throws  ENOMEM   If enough memory cannot be allocated
 */
int libpatch_format_ed_alternative_patch(struct libpatch_diff2_printer *printer, struct libpatch_diff2 *diff, size_t difflen,
                                         const struct libpatch_file *file1, const struct libpatch_file *file2);

/**
 * Print a patch in ed(1) format
 * 
 * @param   printer  Patch printer
 * @param   diff     The diff string for the patch
 * @param   difflen  The number of elements in `diff`
 * @param   file1    The first file
 * @param   file2    The second file
 * @return           0 on success, -1 on failure
 * @throws  ENOMEM   If enough memory cannot be allocated
 */
int libpatch_format_ed_patch(struct libpatch_diff2_printer *printer, struct libpatch_diff2 *diff, size_t difflen,
                             const struct libpatch_file *file1, const struct libpatch_file *file2);

/**
 * Print a patch in RCS format
 * 
 * @param   printer  Patch printer
 * @param   diff     The diff string for the patch
 * @param   difflen  The number of elements in `diff`
 * @param   file1    The first file
 * @param   file2    The second file
 * @return           0 on success, -1 on failure
 * @throws  ENOMEM   If enough memory cannot be allocated
 */
int libpatch_format_rcs_patch(struct libpatch_diff2_printer *printer, struct libpatch_diff2 *diff, size_t difflen,
                              const struct libpatch_file *file1, const struct libpatch_file *file2);

/**
 * Print a patch
 * 
 * @param   printer  Patch printer
 * @param   diff     The diff string for the patch
 * @param   difflen  The number of elements in `diff`
 * @param   file1    The first file
 * @param   file2    The second file
 * @param   style    The format the patch file should use
 * @return           0 on success, -1 on failure
 * @throws  ENOMEM   If enough memory cannot be allocated
 * @throws  EINVAL   `style` is not a recognised style
 */
int libpatch_format_patch(struct libpatch_diff2_printer *printer, struct libpatch_diff2 *diff, size_t difflen,
                          const struct libpatch_file *file1, const struct libpatch_file *file2, enum libpatch_style style);

/**
 * Parse a patch file in “unified” format
 * 
 * @param   text          The content of the patch file
 * @param   textlen       The size of the patch file
 * @parma   textend_out   Unless `NULL`, parsing will at the end of the first patch
 *                        in the file and the number of bytes included in the patch
 *                        is stored to `*textend_out`
 * @param   patch_out     Output parameter for the description of patch
 * @param   patchlen_out  Output parameter for the number of eleemnts in `*patch_out`
 * @return                0 on success, -1 on failure
 * @throws  ENOMEM        If enough memory cannot be allocated
 */
int libpatch_parse_unified_patch(const char *text, size_t textlen, size_t *textend_out,
                                 struct libpatch_patch **patch_out, size_t *patchlen_out);

/**
 * Parse a patch file in “copied” format
 * 
 * @param   text          The content of the patch file
 * @param   textlen       The size of the patch file
 * @parma   textend_out   Unless `NULL`, parsing will at the end of the first patch
 *                        in the file and the number of bytes included in the patch
 *                        is stored to `*textend_out`
 * @param   patch_out     Output parameter for the description of patch
 * @param   patchlen_out  Output parameter for the number of eleemnts in `*patch_out`
 * @return                0 on success, -1 on failure
 * @throws  ENOMEM        If enough memory cannot be allocated
 */
int libpatch_parse_copied_patch(const char *text, size_t textlen, size_t *textend_out,
                                struct libpatch_patch **patch_out, size_t *patchlen_out);

/**
 * Parse a patch file in “normal” format
 * 
 * @param   text          The content of the patch file
 * @param   textlen       The size of the patch file
 * @parma   textend_out   Unless `NULL`, parsing will at the end of the first patch
 *                        in the file and the number of bytes included in the patch
 *                        is stored to `*textend_out`
 * @param   patch_out     Output parameter for the description of patch
 * @param   patchlen_out  Output parameter for the number of eleemnts in `*patch_out`
 * @return                0 on success, -1 on failure
 * @throws  ENOMEM        If enough memory cannot be allocated
 */
int libpatch_parse_normal_patch(const char *text, size_t textlen, size_t *textend_out,
                                struct libpatch_patch **patch_out, size_t *patchlen_out);

/**
 * Parse a patch file in ed(1) format
 * 
 * @param   text          The content of the patch file
 * @param   textlen       The size of the patch file
 * @parma   textend_out   Unless `NULL`, parsing will at the end of the first patch
 *                        in the file and the number of bytes included in the patch
 *                        is stored to `*textend_out`
 * @param   patch_out     Output parameter for the description of patch
 * @param   patchlen_out  Output parameter for the number of eleemnts in `*patch_out`
 * @return                0 on success, -1 on failure
 * @throws  ENOMEM        If enough memory cannot be allocated
 */
int libpatch_parse_ed_patch(const char *text, size_t textlen, size_t *textend_out,
                            struct libpatch_patch **patch_out, size_t *patchlen_out);

/**
 * Parse a patch file in RCS format
 * 
 * @param   text          The content of the patch file
 * @param   textlen       The size of the patch file
 * @parma   textend_out   Unless `NULL`, parsing will at the end of the first patch
 *                        in the file and the number of bytes included in the patch
 *                        is stored to `*textend_out`
 * @param   patch_out     Output parameter for the description of patch
 * @param   patchlen_out  Output parameter for the number of eleemnts in `*patch_out`
 * @return                0 on success, -1 on failure
 * @throws  ENOMEM        If enough memory cannot be allocated
 */
int libpatch_parse_rcs_patch(const char *text, size_t textlen, size_t *textend_out,
                             struct libpatch_patch **patch_out, size_t *patchlen_out);

/**
 * Parse a patch file
 * 
 * @param   text          The content of the patch file
 * @param   textlen       The size of the patch file
 * @parma   textend_out   Unless `NULL`, parsing will at the end of the first patch
 *                        in the file and the number of bytes included in the patch
 *                        is stored to `*textend_out`
 * @param   patch_out     Output parameter for the description of patch
 * @param   patchlen_out  Output parameter for the number of eleemnts in `*patch_out`
 * @param   style         The format the patch file is in
 * @return                0 on success, -1 on failure
 * @throws  ENOMEM        If enough memory cannot be allocated
 * @throws  EINVAL        `style` is not a recognised style
 * @throws  EINVAL        `style` is LIBPATCH_STYLE_ED_ALTERNATIVE
 */
int libpatch_parse_patch(const char *text, size_t textlen, size_t *textend_out,
                         struct libpatch_patch **patch_out, size_t *patchlen_out,
                         enum libpatch_style style);

/**
 * Determine how a patch file is formatted
 * 
 * If the file does not contain any diff content,
 * `LIBPATCH_STYLE_GARBAGE` will be returned, but
 * it can still contain useful information that
 * can be parsed by arbitrary parsing function.
 * If `LIBPATCH_STYLE_GARBAGE` is returned, there
 * is no point in calling the function again.
 * 
 * @param   text     The content of the patch file
 * @param   textlen  The size of the patch file
 * @param   offset   Offset for where the function shall start
 *                   reading the patch file to determine the
 *                   format. Shall be 0 on the first. The function
 *                   will update the value so that it is set
 *                   appropriately for calling the function again
 *                   to make a new guess. (This value shall not
 *                   be used as an offset for parsing.)
 * @return           The style the patch file appears to use,
 *                   or `LIBPATCH_STYLE_GARBAGE` if it couldn't
 *                   be determined
 */
enum libpatch_style libpatch_guess_format(const char *text, size_t textlen, size_t *offset);

/**
 * Reverse the direction of a diff script
 * 
 * @param  diff     The diff string, will be modified in-place
 * @param  difflen  The number of elements in `diff`
 */
void libpatch_reverse_diff2(struct libpatch_diff2 *diff, size_t difflen);


#endif