|
libfossil
|
This class is the basis of libfossil's port of the diff engine added to fossil(1) in 2021-09, colloquially known as the "diff builder. More...
#include "util.h"
Data Fields | |
| int(* | chunkHeader )(fsl_dibu *, uint32_t A, uint32_t B, uint32_t C, uint32_t D) |
| If this is not NULL, it is called one time at the start of each chunk of diff for a given file and is passed the line number of each half of the diff and the number of lines in that chunk for that half (including insertions and deletions). | |
| int(* | common )(fsl_dibu *, fsl_dline const *line) |
| Tells the builder that the given line represents one line of common output. | |
| int(* | deletion )(fsl_dibu *, fsl_dline const *line) |
| Tells the builder that the given line represents a "deletion" - a line removed from the LHS. | |
| int(* | edit )(fsl_dibu *, fsl_dline const *lineLhs, fsl_dline const *lineRhs) |
| Tells the builder that the given line represents an "edit" from the LHS to the RHS. | |
| uint32_t | fileCount |
| A place to store the number of files seen by this builder so far, for builders which need to distinguish that somehow (e.g. | |
| void(* | finalize )(fsl_dibu *) |
| Must free any state owned by this builder, including the builder object. | |
| int(* | finally )(fsl_dibu *b) |
| This optional method is similar to this->finish() but it is not called by the library. | |
| int(* | finish )(fsl_dibu *b) |
| Must "finish" the diff process. | |
| unsigned int | implFlags |
| Space for implementation-specific flags which clients may set to modify the dibu's behaviour. | |
| int(* | insertion )(fsl_dibu *, fsl_dline const *line) |
| Tells the builder that the given line represents an "insert" into the RHS. | |
| uint32_t | lnLHS |
| Number of lines seen of the LHS content. | |
| uint32_t | lnRHS |
| Number of lines seen of the RHS content. | |
| struct { | |
| uint32_t deletions | |
| Number of lines deleted so far. More... | |
| uint32_t edits | |
| Number of line-level edits performed so far. More... | |
| uint32_t insertions | |
| Number of lines inserted performed so far. More... | |
| uint32_t replacements | |
| Number of line replacements performed so far. More... | |
| } | metrics |
| Metrics maintained by the core diff algorithm. | |
| fsl_dibu_opt const * | opt |
| Config info, owned by higher-level routines. | |
| unsigned short | passNumber |
| Gets set to the "pass number" immediately before this->start() is called, starting with pass number 1. | |
| void * | pimpl |
| Impl-specific diff-generation state. | |
| unsigned int | pimplFlags |
| Space for private, implementation-specific flags, e.g. | |
| int(* | replacement )(fsl_dibu *, fsl_dline const *lineLhs, fsl_dline const *lineRhs) |
| Tells the builder that the given line represents a replacement from the LHS to the RHS. | |
| int(* | skip )(fsl_dibu *, uint32_t n) |
| Tells the builder that n lines of common output are to be skipped. | |
| int(* | start )(fsl_dibu *b) |
| If not NULL, this is called once per pass per diff to give the builder a chance to perform any bootstrapping initialization or header output. | |
| bool | twoPass |
| If true, this builder gets passed through the diff generation process twice. | |
| void const * | typeID |
| Can optionally be set by factory functions to some internal opaque value, so that non-member routines specific to that type can determine whether any given builder is of the proper type. | |
This class is the basis of libfossil's port of the diff engine added to fossil(1) in 2021-09, colloquially known as the "diff builder.
"
A diff builder is an object responsible for formatting low-level diff info another form, typically for human readability but also for machine readability (patches). The library generates a low-level diff then feeds that through an algorithm which determines which methods of this class to call, delegating all rendering of the diff to an instance of this class.
The internal APIs which drive each instance of this class guaranty that if any method of this class returns non-0 (an error code) then no futher methods will be called except for finalize().
| int(* fsl_dibu::chunkHeader) (fsl_dibu *, uint32_t A, uint32_t B, uint32_t C, uint32_t D) |
If this is not NULL, it is called one time at the start of each chunk of diff for a given file and is passed the line number of each half of the diff and the number of lines in that chunk for that half (including insertions and deletions).
This is primarily intended for generating conventional unified diff chunk headers in the form:
The inclusion of this method in an object might preclude certain other diff formatting changes which might otherwise apply. Notably, if the span between two diff chunks is smaller than the context lines count, the diff builder driver prefers to merge those two chunks together. That "readability optimization" is skipped when this method is set because this method may otherwise report that lines are being skipped which then subsequently get output by the driver.
Must return 0 on success, non-0 on error.
| uint32_t fsl_dibu::deletions |
Tells the builder that the given line represents an "edit" from the LHS to the RHS.
Must return 0 on success, non-0 on error. Builders are free, syntax permitting, to use the fsl_dline_change_spans() API to elaborate on edits for display purposes, to treat it identically to this->replacement(), or to treat this as a single pair of calls to this->deletion() and this->insertion(). In the latter case they simply need to pass lineLhs to this->deletion() and lineRhs to this->insertion().
Typical common implementation details:
| uint32_t fsl_dibu::edits |
| uint32_t fsl_dibu::fileCount |
A place to store the number of files seen by this builder so far, for builders which need to distinguish that somehow (e.g.
adding a separator before each file after the first). Implementations which use this should increment it in their start() method.
Maintenance reminder/TODO: we can't increment this from the main diff driver because... we possibly could, but we'd need to patch the various diff builders which currently do this themselves. The main diff driver doesn't have enough info to know when to set it, though. That "could" be done in this->finally() but that method is optional.
| void(* fsl_dibu::finalize) (fsl_dibu *) |
| int(* fsl_dibu::finally) (fsl_dibu *b) |
This optional method is similar to this->finish() but it is not called by the library.
It is intended to be called, if it's not NULL, by the client after they are done, e.g., looping over a series of diffs with the same builder. Some builders can use this to flush any final state, e.g. dumping out change count totals or some such.
As an example, the TCL/TK-based builder, when the FSL_DIBU_TCL_TK flag is set on this->implFlag, embeds a TK script in the output from this method.
| int(* fsl_dibu::finish) (fsl_dibu *b) |
Must "finish" the diff process.
Depending on the diff impl, this might flush any pending output or may be a no-op. This is only called if the rest of the diff was generated without producing an error result.
This member may be NULL.
Implementations are free to collect all of their output in an internal representation and delay flushing it until this routine is called.
Must return 0 on success, non-0 on error (e.g. output flushing fails).
Minor achtung: for a multi-file diff run, this gets called after each file. The library does not have enough information to know when a builder is "done for good" and if a custom builder requires, e.g., extra post-diff-loop processing, the client will have to take care of that themselves.
| unsigned int fsl_dibu::implFlags |
Space for implementation-specific flags which clients may set to modify the dibu's behaviour.
This is different from fsl_dibu_opt::diffFlags in that these flags are specific to a given dibu type. See the fsl_dibu_impl_flags_e enum for the list of flags for the library-provided diff builders.
| uint32_t fsl_dibu::insertions |
| uint32_t fsl_dibu::lnLHS |
| uint32_t fsl_dibu::lnRHS |
| struct { ... } fsl_dibu::metrics |
Metrics maintained by the core diff algorithm.
These are updated during the first pass through a given fsl_diff_v2() run. They are NEVER reset by the builder algo because it cannot know if the user wants a running total or a per-file total. Clients running diffs in a loop may want to reset them on each loop. The simplest way is to cop fsl_dibu_empty.metrics over them. It is legal for a given builder to reset these in their start(), finish(), or finally() methods, depending on how the builder is used.
Note that all metrics apply to the RHS version, not the LHS.
| fsl_dibu_opt const* fsl_dibu::opt |
Config info, owned by higher-level routines.
Every diff builder requires one of these but not all options are relevant for all builders.
Note that the diff driver may make a bitwise copy of this object and use that one for the actual diff generation. That is, methods of this class must never assume that this member's pointer refers to a specific object. (This leeway is necessary in order to implement diff inversion (swapping the LHS/RHS of a diff).)
| unsigned short fsl_dibu::passNumber |
Gets set to the "pass number" immediately before this->start() is called, starting with pass number 1.
This value is only relevant for two-pass builders, which can use this to control their mode of operation, e.g. data collection in pass 1 and actual work in pass 2. Note that all of the diff-building API methods are called for both passes, including start() and finish(). Only finalize() and finally() are not affected by this.
| void* fsl_dibu::pimpl |
Impl-specific diff-generation state.
If it is owned by this instance then this->finalize() must clean it up.
| unsigned int fsl_dibu::pimplFlags |
Tells the builder that the given line represents a replacement from the LHS to the RHS.
Must return 0 on success, non-0 on error. This differs from an "edit" in that the line being replaced seems to have on relationship to the replacement. Even so, builders are free to represent replacements and edits identically, and are free to represent either or both as a pair of deletion/insertion operations.
Typical common implementation details:
| uint32_t fsl_dibu::replacements |
| int(* fsl_dibu::skip) (fsl_dibu *, uint32_t n) |
| int(* fsl_dibu::start) (fsl_dibu *b) |
If not NULL, this is called once per pass per diff to give the builder a chance to perform any bootstrapping initialization or header output.
At the point this is called, this->cfg is assumed to have been filled out properly. Diff builder implementations which require dynamic resource allocation may perform it here or in their factory routine(s).
b->lnLHS and b->lnRHS will be set to 0 before each call.
This method should also reset any dynamic state of a builder so that it may be reused for subsequent diffs. This enables the API to use a single builder for a collection of logically grouped files without having to destroy and reallocate the builder.
Must return 0 on success, non-0 on error. If it returns non-0, the only other method of the instance which may be legally called is finalize().
The diff driver sets this->lnLHS and this->lnRHS to 0 before calling this.
| bool fsl_dibu::twoPass |
| void const* fsl_dibu::typeID |