libfossil
fsl_deck Struct Reference

A "deck" stores (predictably enough) a collection of "cards." Cards are constructs embedded within Fossil's Control Artifacts to denote various sorts of changes in a Fossil repository, and a Deck encapsulates the cards for a single Control Artifact of an arbitrary type, e.g. More...

#include "fossil-content.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 event or UUID of ticket or wiki page to which the attachment applies. More...
 
A
 The 'A' (attachment) card. More...
 
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). More...
 
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. More...
 
fsl_buffer content
 This is part of an optimization used when parsing fsl_deck instances from source text. More...
 
fsl_double_t D
 The 'D' (date) card, in Julian format. More...
 
struct {
   fsl_double_t   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. More...
 
fsl_error error
 For propagating error state through certain parts of the API. More...
 
fsl_cxf
 The Fossil context responsible for this deck. More...
 
struct {
   fsl_int_t   cursor
 An internal cursor into this->list, used primarily for properly traversing the file list in delta manifests. More...
 
   fsl_list   list
 A list of 'F' (file) cards. More...
 
F
 The 'F' (file) card container. More...
 
fsl_list J
 The 'J' card specifies changes to "value" of "fields" in tickets (FSL_CATYPE_TICKET). More...
 
fsl_uuid_str K
 UUID for the 'K' (ticket) card. More...
 
char * L
 The 'L' (wiki name/title) card. More...
 
fsl_list M
 List of UUIDs (fsl_uuid_str) in a cluster ('M' cards). More...
 
char * N
 The 'N' (content mime type) card. More...
 
fsl_decknext
 To be used for a manifest cache. More...
 
fsl_list P
 List of UUIDs of parents ('P' cards). More...
 
fsl_list Q
 'Q' (cherry pick) cards. More...
 
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. More...
 
fsl_id_t rid
 DB repo.blob.rid value. More...
 
fsl_list T
 List of 'T' (tag) cards. More...
 
fsl_catype_t type
 Specifies the the type (or eventual type) of this artifact. More...
 
char * U
 The U (user) card. More...
 
fsl_uuid_str uuid
 Gets set by fsl_deck_parse() to the hash/UUID of the manifest it parsed. More...
 
fsl_buffer W
 The W (wiki content) card. More...
 

Detailed Description

A "deck" stores (predictably enough) a collection of "cards." Cards are constructs embedded within Fossil's Control Artifacts to denote various sorts of changes in a Fossil repository, and a Deck encapsulates the cards for a single Control 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:

http://fossil-scm.org/index.html/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 Control Artifact type, so that they can fail long before the user gets a chance to add a malformed Control 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(). Adding the Z card to this class would require that fsl_deck_output() and friends take a non-const deck object (because Z is calculated incrementally during output of the artifact), which just seems philosophically wrong for an output operation. It might be useful to expand fsl_deck_output() to write the Z card's result to an optional output parameter.

Maintenance reminder: please keep the card members alpha sorted to simplify eyeball-searching through their docs.

See also
fsl_deck_malloc()
fsl_deck_init()
fsl_deck_parse()
fsl_deck_load_rid()
fsl_deck_finalize()
fsl_deck_clean()
fsl_deck_save()
fsl_deck_A_set()
fsl_deck_B_set()
fsl_deck_D_set()
fsl_deck_E_set()
fsl_deck_F_add()
fsl_deck_J_add()
fsl_deck_K_set()
fsl_deck_L_set()
fsl_deck_M_add()
fsl_deck_N_set()
fsl_deck_P_add()
fsl_deck_Q_add()
fsl_deck_R_set()
fsl_deck_T_add()
fsl_deck_U_set()
fsl_deck_W_set()

Definition at line 221 of file fossil-content.h.

Field Documentation

struct { ... } fsl_deck::A

The 'A' (attachment) card.

Only used by FSL_CATYPE_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).

Definition at line 428 of file fossil-content.h.

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 (recursively) when this instance is cleaned up (when the containing deck is cleaned up).

Definition at line 292 of file fossil-content.h.

char* fsl_deck::C

The 'C' (comment) card.

Definition at line 297 of file fossil-content.h.

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 allocate the memory for that bit.

Definition at line 415 of file fossil-content.h.

fsl_int_t fsl_deck::cursor

An internal cursor into this->list, used primarily for properly traversing the file list in delta manifests.

Maintenance note: internal updates to this member are the only reason some of the deck APIs require a non-const deck.

Definition at line 335 of file fossil-content.h.

fsl_double_t fsl_deck::D

The 'D' (date) card, in Julian format.

Definition at line 302 of file fossil-content.h.

struct { ... } fsl_deck::E

The 'E' (event) card.

fsl_error fsl_deck::error

For propagating error state through certain parts of the API.

Definition at line 403 of file fossil-content.h.

fsl_cx* fsl_deck::f

The Fossil context responsible for this deck.

We store this so that some API routines to not require the caller to explicitly pass around the context. Relatively few deck operations make use of this.

Definition at line 248 of file fossil-content.h.

struct { ... } fsl_deck::F

The 'F' (file) card container.

fsl_list fsl_deck::J

The 'J' card specifies changes to "value" of "fields" in tickets (FSL_CATYPE_TICKET).

Holds (fsl_card_J*) entries.

Definition at line 344 of file fossil-content.h.

fsl_double_t fsl_deck::julian

The 'E' card's date in Julian Day format.

Definition at line 311 of file fossil-content.h.

fsl_uuid_str fsl_deck::K

UUID for the 'K' (ticket) card.

Definition at line 354 of file fossil-content.h.

char* fsl_deck::L

The 'L' (wiki name/title) card.

Definition at line 349 of file fossil-content.h.

fsl_list fsl_deck::list

A list of 'F' (file) cards.

Contains (fsl_card_F*) entries.

Definition at line 327 of file fossil-content.h.

fsl_list fsl_deck::M

List of UUIDs (fsl_uuid_str) in a cluster ('M' cards).

Definition at line 359 of file fossil-content.h.

char* fsl_deck::N

The 'N' (content mime type) card.

Definition at line 364 of file fossil-content.h.

char* fsl_deck::name

Filename of the A-card.

Definition at line 259 of file fossil-content.h.

fsl_deck* fsl_deck::next

To be used for a manifest cache.

Definition at line 420 of file fossil-content.h.

fsl_list fsl_deck::P

List of UUIDs of parents ('P' cards).

Entries are of type (fsl_uuid_str).

Definition at line 370 of file fossil-content.h.

fsl_list fsl_deck::Q

'Q' (cherry pick) cards.

Holds (fsl_card_Q*) entries.

Definition at line 375 of file fossil-content.h.

char* fsl_deck::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.

See the class-level docs for a link to a page which describes how this is calculated.

Definition at line 383 of file fossil-content.h.

fsl_id_t fsl_deck::rid

DB repo.blob.rid value.

Normally set by fsl_deck_parse().

Definition at line 234 of file fossil-content.h.

fsl_uuid_str fsl_deck::src

UUID of the file being attached via the A-card.

Definition at line 271 of file fossil-content.h.

fsl_list fsl_deck::T

List of 'T' (tag) cards.

Holds (fsl_card_T*) instances.

Definition at line 388 of file fossil-content.h.

char* fsl_deck::tgt

Name of event or UUID of ticket or wiki page to which the attachment applies.

For tickets/events, the "name" is its UUID.

Definition at line 266 of file fossil-content.h.

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

Definition at line 229 of file fossil-content.h.

char* fsl_deck::U

The U (user) card.

Definition at line 393 of file fossil-content.h.

fsl_uuid_str fsl_deck::uuid

Gets set by fsl_deck_parse() to the hash/UUID of the manifest it parsed.

The 'E' card's UUID.

The 'B' (baseline) card holds the UUID of baseline manifest.

Normally set by fsl_deck_parse().

This is empty for baseline manifests and holds the UUID of the parent for delta manifests.

Definition at line 240 of file fossil-content.h.

fsl_buffer fsl_deck::W

The W (wiki content) card.

Definition at line 398 of file fossil-content.h.


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