libfossil
fcli_t Struct Reference

The fcli_t type, accessed by clients via the fcli global instance, contains various data for managing a basic Fossil SCM application build using libfossil. More...

#include "cli.h"

Collaboration diagram for fcli_t:

Data Fields

char const * appName
 Application's name.
int argc
 Current number of items in this->argv.
char ** argv
 The current list of CLI arguments.
struct { 
   fcli_help_info const *   appHelp 
 If not NULL, it must be a pointer to fcli_help_info holding help info for the app. More...
   char const *   checkoutDir 
 If not NULL then fcli_setup() will attempt to open the checkout for the given dir, including its associated repo db. More...
   const fcli_cliflag *   cliFlags 
 May be set to an array of CLI flag objects, which fcli_setup() will use for parsing the CLI flags. More...
   fsl_msg_listener   listener 
 Listener for fsl_msg-published messages. More...
   fsl_outputer   outputer 
 This output channel is used when initializing the context object. More...
   int   traceSql 
 Whether or not to enable fossil's SQL tracing. More...
   unsigned short   verbose 
 A verbosity level counter. More...
} config
 The flags in this struct are "public," meaning that client applications may query and safely manipulate them directly if they know what they're doing.
fsl_error err
 For holding pre-this->f-init error state.
fsl_cx * f
 The shared fsl_cx instance.
struct { 
   fsl_pathfinder   bins 
 Search object for binaries. More...
} paths
 Search paths.
struct { 
   const char *   key 
 Key passed to the –see-key CLI flag. More...
   unsigned int   nKey 
 Key len. More...
   enum fsl_see_keytype_e   type 
 Key type. More...
} see
struct { 
   short   helpRequested 
 Incremented if fcli_setup() detects -? More...
   const char *   repoDbArg 
 repo db name string from -R/–repo CLI flag. More...
   const char *   userArg 
 User name from the –user CLI flag. More...
   bool   versionRequested 
 True if the –lib-version CLI flag was used. More...
} transient
 Transient settings and flags.

Detailed Description

The fcli_t type, accessed by clients via the fcli global instance, contains various data for managing a basic Fossil SCM application build using libfossil.

Usage notes:

  • All non-const pointer members are owned and managed by the fcli API. Clients may reference them but must be aware of lifetimes if they plan to hold the reference for long.

Definition at line 368 of file cli.h.

Field Documentation

◆ appHelp

fcli_help_info const* fcli_t::appHelp

If not NULL, it must be a pointer to fcli_help_info holding help info for the app.

It will be formated and output when –help is triggered.

Should be set by client applications BEFORE calling fcli_setup() so that the fcli help subsystem can integrate the app. fcli.appName will be set by the time this is used.

Definition at line 409 of file cli.h.

◆ appName

char const* fcli_t::appName

Application's name.

Currently argv[0] but needs to be adjusted for Windows platforms.

Definition at line 390 of file cli.h.

◆ argc

int fcli_t::argc

Current number of items in this->argv.

Definition at line 385 of file cli.h.

◆ argv

char** fcli_t::argv

The current list of CLI arguments.

This list gets modified by fcli_flag() and friends. Its memory is owned by fcli.

Definition at line 381 of file cli.h.

◆ bins

fsl_pathfinder fcli_t::bins

Search object for binaries.

Definition at line 516 of file cli.h.

◆ checkoutDir

char const* fcli_t::checkoutDir

If not NULL then fcli_setup() will attempt to open the checkout for the given dir, including its associated repo db.

By default this is "." (the current directory).

Applications can set this to NULL before calling fcli_setup() in order to disable the automatic attemp to open a checkout under the current directory. Doing so is equivalent to using the –no-checkout flag. The global –checkout-dir flag will trump that setting, though.

Definition at line 456 of file cli.h.

◆ cliFlags

const fcli_cliflag* fcli_t::cliFlags

May be set to an array of CLI flag objects, which fcli_setup() will use for parsing the CLI flags.

The array MUST end with an entry which has NULL values for its (flagShort, flagLong) members. When creating the array it is simplest to use fcli_cliflag_empty_m as the initializer for that sentinel entry.

The elements in this array are traversed in the order they are provided, and any which have a callback which returns FCLI_RC_FLAG_AGAIN will be traversed repeatedly before moving on to the next flag. This ordering may have side-effects on how the app sets up its flag handling. In particular, this arrangement makes the common cases easy to implement but makes certain more complicated situations effectively impossible to implement. For example:

-x=1 -y=2 -x=3 -y=4

Assuming the definition of the -y flag is first in this array and has a callback which returns FCLI_RC_FLAG_AGAIN, the two -x flags will be processed before either of the -y flags. Thus it is impossible (using this method of traversal) to change the behavior of the -y flags based on the left-closest -x value.

We "could," but probably never will, instead walk the input argv looking for things which look like flags, then looking back into this list for a match, rather than the other way around. That would require a new args processing implementation, though, for relatively little benefit.

Definition at line 443 of file cli.h.

◆ [struct]

struct { ... } fcli_t::config

The flags in this struct are "public," meaning that client applications may query and safely manipulate them directly if they know what they're doing.

However, some of this state is only be legally modified before calling fcli_setup() (or equivalent).

◆ err

fsl_error fcli_t::err

For holding pre-this->f-init error state.

Once this->f is initialized, all errors reported via fcli_err_set() are stored in that object's error state.

Definition at line 523 of file cli.h.

◆ f

fsl_cx* fcli_t::f

The shared fsl_cx instance.

It gets initialized by fcli_setup() and cleaned up post-main().

this->f is owned by this object and will be cleaned up at app shutdown (post-main).

Definition at line 376 of file cli.h.

◆ helpRequested

short fcli_t::helpRequested

Incremented if fcli_setup() detects -?

or –help in the argument list, or if the first non-flag argument is "help". This is an int, rather than a bool, to support multiple levels of help verbosity via multiple –help flags.

Definition at line 504 of file cli.h.

◆ key

const char* fcli_t::key

Key passed to the –see-key CLI flag.

Definition at line 528 of file cli.h.

◆ listener

fsl_msg_listener fcli_t::listener

Listener for fsl_msg-published messages.

Definition at line 481 of file cli.h.

◆ nKey

unsigned int fcli_t::nKey

Key len.

Definition at line 531 of file cli.h.

◆ outputer

fsl_outputer fcli_t::outputer

This output channel is used when initializing the context object.

The default implementation uses fsl_outputer_FILE to output to stdout.

Definition at line 476 of file cli.h.

◆ [struct]

struct { ... } fcli_t::paths

Search paths.

◆ repoDbArg

const char* fcli_t::repoDbArg

repo db name string from -R/–repo CLI flag.

Definition at line 493 of file cli.h.

◆ [struct]

struct { ... } fcli_t::see

◆ traceSql

int fcli_t::traceSql

Whether or not to enable fossil's SQL tracing.

This should start with a negative value, which helps fcli_setup() process it. Setting this after initialization has no effect.

Definition at line 470 of file cli.h.

◆ [struct]

struct { ... } fcli_t::transient

Transient settings and flags.

These are bits which are used during (or very shortly after) fcli_setup() but have no effect if modified after that.

◆ type

enum fsl_see_keytype_e fcli_t::type

Key type.

Definition at line 535 of file cli.h.

◆ userArg

const char* fcli_t::userArg

User name from the –user CLI flag.

Definition at line 497 of file cli.h.

◆ verbose

unsigned short fcli_t::verbose

A verbosity level counter.

Starts at 0 (no verbosity) and goes up for higher verbosity levels. Currently levels 1 and 2 are intended for app-level use and level 3 for library-level use.

Definition at line 463 of file cli.h.

◆ versionRequested

bool fcli_t::versionRequested

True if the –lib-version CLI flag was used.

This causes fcli setup to exit as if –help had been invoked.

Definition at line 509 of file cli.h.


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