libfossil
fsl_dibu Struct Reference

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"

Collaboration diagram for fsl_dibu:

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.

Detailed Description

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().

Definition at line 4190 of file util.h.

Field Documentation

◆ chunkHeader

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:

@@ -A,B +C,D @@

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.

Definition at line 4257 of file util.h.

◆ common

int(* fsl_dibu::common) (fsl_dibu *, fsl_dline const *line)

Tells the builder that the given line represents one line of common output.

Must return 0 on success, non-0 on error.

Typical common implementation details:

  • Increment both this->lnLHS and this->lnRHS by 1.

Definition at line 4279 of file util.h.

◆ deletion

int(* fsl_dibu::deletion) (fsl_dibu *, fsl_dline const *line)

Tells the builder that the given line represents a "deletion" - a line removed from the LHS.

Must return 0 on success, non-0 on error.

Typical common implementation details:

  • Increment this->lnLHS by 1.

Definition at line 4298 of file util.h.

◆ deletions

uint32_t fsl_dibu::deletions

Number of lines deleted so far.

Definition at line 4447 of file util.h.

◆ edit

int(* fsl_dibu::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.

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:

  • Increment both this->lnLHS and this->lnRHS by 1.

Definition at line 4328 of file util.h.

◆ edits

uint32_t fsl_dibu::edits

Number of line-level edits performed so far.

Definition at line 4449 of file util.h.

◆ fileCount

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.

Definition at line 4417 of file util.h.

◆ finalize

void(* fsl_dibu::finalize) (fsl_dibu *)

Must free any state owned by this builder, including the builder object.

It must not generate any output.

Definition at line 4369 of file util.h.

◆ finally

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.

Definition at line 4364 of file util.h.

◆ finish

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.

Definition at line 4351 of file util.h.

◆ implFlags

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.

Definition at line 4403 of file util.h.

◆ insertion

int(* fsl_dibu::insertion) (fsl_dibu *, fsl_dline const *line)

Tells the builder that the given line represents an "insert" into the RHS.

Must return 0 on success, non-0 on error.

Typical common implementation details:

  • Increment this->lnRHS by 1.

Definition at line 4288 of file util.h.

◆ insertions

uint32_t fsl_dibu::insertions

Number of lines inserted performed so far.

Definition at line 4445 of file util.h.

◆ lnLHS

uint32_t fsl_dibu::lnLHS

Number of lines seen of the LHS content.

It is up to the concrete builder impl to update this if it's needed. The core diff driver sets this to 0 before calling this->start().

Definition at line 4423 of file util.h.

◆ lnRHS

uint32_t fsl_dibu::lnRHS

Number of lines seen of the RHS content.

It is up to the concrete builder impl to update this if it's needed. The core diff driver sets this to 0 before calling this->start().

Definition at line 4429 of file util.h.

◆ [struct]

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.

◆ opt

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).)

Definition at line 4203 of file util.h.

◆ passNumber

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.

Definition at line 4384 of file util.h.

◆ pimpl

void* fsl_dibu::pimpl

Impl-specific diff-generation state.

If it is owned by this instance then this->finalize() must clean it up.

Definition at line 4389 of file util.h.

◆ pimplFlags

unsigned int fsl_dibu::pimplFlags

Space for private, implementation-specific flags, e.g.

for tracking basic output state, e.g. of opening/closing tags. This must not be modified by clients.

Definition at line 4395 of file util.h.

◆ replacement

int(* fsl_dibu::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.

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:

  • Increment both this->lnLHS and this->lnRHS by 1.

Definition at line 4312 of file util.h.

◆ replacements

uint32_t fsl_dibu::replacements

Number of line replacements performed so far.

These are different from edits in that the whole line differs in the LHS/RHS.

Definition at line 4453 of file util.h.

◆ skip

int(* fsl_dibu::skip) (fsl_dibu *, uint32_t n)

Tells the builder that n lines of common output are to be skipped.

How it represents this is up to the impl. Must return 0 on success, non-0 on error.

Typical common implementation details:

  • Increment both this->lnLHS and this->lnRHS by n.

Definition at line 4270 of file util.h.

◆ start

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.

Definition at line 4232 of file util.h.

◆ twoPass

bool fsl_dibu::twoPass

If true, this builder gets passed through the diff generation process twice.

See this->passNumber for details.

Definition at line 4374 of file util.h.

◆ typeID

void const* fsl_dibu::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.

Definition at line 4209 of file util.h.


The documentation for this struct was generated from the following file: