|
libfossil
|
A "deck" stores (predictably enough) a collection of "cards." Cards are constructs embedded within Fossil's Structural Artifacts to denote various sorts of changes in a Fossil repository, and a Deck encapsulates the cards for a single Structural Artifact of an arbitrary type, e.g. More...
#include "repo.h"
Data Fields | |
| struct { | |
| char * name | |
| Filename of the A-card. More... | |
| fsl_uuid_str src | |
| UUID of the file being attached via the A-card. More... | |
| char * tgt | |
| Name of wiki page, or UUID of ticket or event (technote), to which the attachment applies. More... | |
| } | A |
| The 'A' (attachment) card. | |
| void const * | allocStamp |
| A marker which tells fsl_deck_finalize() whether or not fsl_deck_malloc() allocated this instance (in which case fsl_deck_finalize() will fsl_free() it) or not (in which case it does not fsl_free() it). | |
| struct { | |
| fsl_deck * baseline | |
| Baseline manifest corresponding to this->B. More... | |
| fsl_uuid_str uuid | |
| The 'B' (baseline) card holds the UUID of baseline manifest. More... | |
| } | B |
| char * | C |
| The 'C' (comment) card. | |
| fsl_buffer | content |
| This is part of an optimization used when parsing fsl_deck instances from source text. | |
| double | D |
| The 'D' (date) card, in Julian format. | |
| struct { | |
| double julian | |
| The 'E' card's date in Julian Day format. More... | |
| fsl_uuid_str uuid | |
| The 'E' card's UUID. More... | |
| } | E |
| The 'E' (event) card. | |
| fsl_card_F_list | F |
| The 'F' (file) card container. | |
| fsl_cx * | f |
| The Fossil context responsible for this deck. | |
| fsl_uuid_str | G |
| UUID for the 'G' (forum thread-root) card. | |
| char * | H |
| The H (forum title) card. | |
| fsl_uuid_str | I |
| UUID for the 'I' (forum in-response-to) card. | |
| fsl_list | J |
| The 'J' card specifies changes to "value" of "fields" in tickets (FSL_SATYPE_TICKET). | |
| fsl_uuid_str | K |
| UUID for the 'K' (ticket) card. | |
| char * | L |
| The 'L' (wiki name/title) card. | |
| fsl_list | M |
| List of UUIDs (fsl_uuid_str) in a cluster ('M' cards). | |
| char * | N |
| The 'N' (comment mime type) card. | |
| fsl_deck * | next |
| To potentially be used for a manifest cache. | |
| fsl_list | P |
| List of UUIDs of parents ('P' cards). | |
| fsl_list | Q |
| 'Q' (cherry pick) cards. | |
| char * | R |
| The R-card holds an MD5 hash which is calculated based on the names, sizes, and contents of the files included in a manifest. | |
| fsl_id_t | rid |
| DB repo.blob.rid value. | |
| fsl_list | T |
| List of 'T' (tag) cards. | |
| fsl_satype_e | type |
| Specifies the the type (or eventual type) of this artifact. | |
| char * | U |
| The U (user) card. | |
| fsl_buffer | W |
| The W (wiki content) card. | |
A "deck" stores (predictably enough) a collection of "cards." Cards are constructs embedded within Fossil's Structural Artifacts to denote various sorts of changes in a Fossil repository, and a Deck encapsulates the cards for a single Structural Artifact of an arbitrary type, e.g.
Manifest (a.k.a. "checkin") or Cluster. A card is basically a command with a single-letter name and a well-defined signature for its arguments. Each card is represented by a member of this struct whose name is the same as the card type (e.g. fsl_card::C holds a C-card and fsl_card::F holds a list of F-card). Each type of artifact only allows certain types of card. The complete list of valid card/construct combinations can be found here:
https://fossil-scm.org/home/doc/trunk/www/fileformat.wiki#summary
fsl_card_is_legal() can be used determine if a given card type is legal (per the above chart) with a given Control Artifiact type (as stored in the fsl_deck::type member).
The type member is used by some algorithms to determine which operations are legal on a given artifact type, so that they can fail long before the user gets a chance to add a malformed artifact to the database. Clients who bypass the fsl_deck APIs and manipulate the deck's members "by hand" (so to say) effectively invoke undefined behaviour.
The various routines to add/set cards in the deck are named fsl_deck_CARDNAME_add() resp. fsl_deck_CARDNAME_set(). The "add" functions represent cards which may appear multiple times (e.g. the 'F' card) or have multiple values (the 'P' card), and those named "set" represent unique or optional cards. The R-card is the outlier, with fsl_deck_R_calc(). NEVER EVER EVER directly modify a member of this struct - always use the APIs. The library performs some optimizations which can lead to corrupt memory and invalid free()s if certain members' values are directly replaced by the client (as opposed to via the APIs).
Note that the 'Z' card is not in this structure because it is a hash of the other inputs and is calculated incrementally and appended automatically by fsl_deck_output().
All non-const pointer members of this structure are owned by the structure instance unless noted otherwise (the fsl_deck::f member being the notable exception).
Maintenance reminder: please keep the card members alpha sorted to simplify eyeball-searching through their docs.
| struct { ... } fsl_deck::A |
The 'A' (attachment) card.
Only used by FSL_SATYPE_ATTACHMENT decks. The spec currently specifies only 1 A-card per manifest, but conceptually this could/should be a list.
| void const* fsl_deck::allocStamp |
A marker which tells fsl_deck_finalize() whether or not fsl_deck_malloc() allocated this instance (in which case fsl_deck_finalize() will fsl_free() it) or not (in which case it does not fsl_free() it).
| struct { ... } fsl_deck::B |
| fsl_deck* fsl_deck::baseline |
Baseline manifest corresponding to this->B.
It is loaded on demand by routines which need it, typically by calling fsl_deck_F_rewind() (unintuitively enough!). The parent/child relationship in Fossil is the reverse of conventional - children own their parents, not the other way around. i.e. this->baseline will get cleaned up when the child part of that relationship is cleaned up.
| fsl_buffer fsl_deck::content |
This is part of an optimization used when parsing fsl_deck instances from source text.
For most types of card we re-use string values in the raw source text rather than duplicate them, and that requires storing the original text (as passed to fsl_deck_parse()). This requires that clients never tinker directly with values in a fsl_deck, in particular never assign over them or assume they know who allocated the memory for that bit.
| struct { ... } fsl_deck::E |
The 'E' (event) card.
| fsl_card_F_list fsl_deck::F |
| fsl_cx* fsl_deck::f |
The Fossil context responsible for this deck.
Though this data type is normally, at least conceptually, free of any given fossil context, many related algorithms need a context in order to perform db- or caching-related work, as well as to simplify error message propagation. We store this as a struct member to keep all such algorithms from redundantly requiring both pieces of information as arguments.
This object does not own the context and the context object must outlive this deck instance.
| fsl_uuid_str fsl_deck::G |
| fsl_uuid_str fsl_deck::I |
| fsl_list fsl_deck::J |
| double fsl_deck::julian |
| fsl_uuid_str fsl_deck::K |
| fsl_list fsl_deck::M |
List of UUIDs (fsl_uuid_str) in a cluster ('M' cards).
| char* fsl_deck::N |
| fsl_deck* fsl_deck::next |
| fsl_list fsl_deck::P |
List of UUIDs of parents ('P' cards).
Entries are of type (fsl_uuid_str).
| fsl_list fsl_deck::Q |
| char* fsl_deck::R |
| fsl_id_t fsl_deck::rid |
| fsl_uuid_str fsl_deck::src |
| fsl_list fsl_deck::T |
| char* fsl_deck::tgt |
| fsl_satype_e fsl_deck::type |
Specifies the the type (or eventual type) of this artifact.
The function fsl_card_is_legal() can be used to determined if a given card type is legal for a given value of this member. APIs which add/set cards use that to determine if the operation requested by the client is semantically legal.
| fsl_uuid_str fsl_deck::uuid |
| fsl_buffer fsl_deck::W |