libfossil
fossil-cli.h File Reference
#include "fossil-scm/fossil.h"
#include <assert.h>
#include <stdlib.h>

Go to the source code of this file.

Data Structures

struct  fcli_help_arg_t
 Describes help text for an application flag. More...
 
struct  fcli_help_t
 Structure for holding app-level –help info. More...
 
struct  fcli_t
 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...
 
struct  FossilCommand
 Describes a named callback command. More...
 

Macros

#define f_out   fcli_printf
 f_out() is a shorthand for fcli_printf(). More...
 
#define fcli_err_report(CLEAR)   fcli_err_report2((CLEAR), __FILE__, __LINE__)
 Convenience macro for using fcli_err_report2(). More...
 
#define FCLI_V(pfexp)   FCLI_VN(1,pfexp)
 Convenience form of FCLI_VN for level-1 verbosity. More...
 
#define FCLI_V2(pfexp)   FCLI_VN(2,pfexp)
 Convenience form of FCLI_VN for level-2 verbosity. More...
 
#define FCLI_VN(N, pfexp)
 Ouputs the given printf-type expression (2nd arg) to fcli_printf() if fcli.verbose>=N, else it does nothing. More...
 

Typedefs

typedef struct fcli_help_arg_t fcli_help_arg_t
 
typedef struct fcli_help_t fcli_help_t
 
typedef struct fcli_t fcli_t
 
typedef struct FossilCommand FossilCommand
 
typedef int(* FossilCommand_f) ()
 Typedef for general-purpose fcli call-by-name commands. More...
 

Functions

FSL_EXPORT fsl_cxfcli_cx ()
 Returns the libfossil context associated with the fcli API. More...
 
FSL_EXPORT int fcli_dispatch_commands (FossilCommand const *cmdList, char reportErrors)
 Expects an array of FossilCommands which contain a trailing sentry entry with a NULL name and callback. More...
 
FSL_EXPORT int fcli_end_of_main (int mainRc)
 A minor helper function intended to be passed the pending result code of the main() routine. More...
 
FSL_EXPORT int fcli_err_report2 (char clear, char const *file, int line)
 If fcli has any error state, this outputs it and returns the error code, else returns 0. More...
 
FSL_EXPORT void fcli_err_reset ()
 Clears any error state in fcli.f. More...
 
FSL_EXPORT int fcli_err_set (int code, char const *fmt,...)
 Sets fcli.f's error state, analog to fsl_cx_err_set(). More...
 
FSL_EXPORT fsl_errorfcli_error ()
 Returns the internally-used fsl_error instance which is used for propagating errors. More...
 
FSL_EXPORT char fcli_flag (char const *opt, char **value)
 Searches fcli.argv for the given flag (pass it without leading dashes). More...
 
FSL_EXPORT char fcli_flag2 (char const *opt1, char const *opt2, char **value)
 Works like fcli_flag() but tries two argument forms, in order. More...
 
FSL_EXPORT char fcli_flag_or_arg (char const *opt1, char const *opt2, char **value)
 Works similarly to fcli_flag2(), but if no flag is found and value is not NULL then *value is assigned to the return value of fcli_next_arg(1). More...
 
FSL_EXPORT char fcli_has_unused_flags (char outputError)
 If fcli.argv contains what looks like any flag arguments, this updates the fossil error state and returns true, else returns false. More...
 
FSL_EXPORT void fcli_help ()
 Calls fcli_local_help() then displays global help options to stdout. More...
 
FSL_EXPORT int fcli_is_verbose ()
 Returns the verbosity level set via CLI args. More...
 
FSL_EXPORT char * fcli_next_arg (char take)
 Peeks at or takes the next argument from the CLI args. More...
 
FSL_EXPORT void fcli_printf (char const *fmt,...)
 Works like printf() but sends its output to fsl_outputf() using the fcli.f fossil conext (if set) or fsl_fprintf() (to stdout). More...
 
FSL_EXPORT int fcli_setup (int argc, char *const *argv)
 Should be called early on in main(), passed the arguments passed to main(). More...
 

Variables

FSL_EXPORT fcli_t fcli
 This fcli_t instance is intended to act as a singleton. More...
 

Macro Definition Documentation

#define f_out   fcli_printf

f_out() is a shorthand for fcli_printf().

Definition at line 361 of file fossil-cli.h.

#define fcli_err_report (   CLEAR)    fcli_err_report2((CLEAR), __FILE__, __LINE__)

Convenience macro for using fcli_err_report2().

Definition at line 473 of file fossil-cli.h.

#define FCLI_V (   pfexp)    FCLI_VN(1,pfexp)

Convenience form of FCLI_VN for level-1 verbosity.

Levels 1 and 2 are intended for application-level use.

Definition at line 97 of file fossil-cli.h.

#define FCLI_V2 (   pfexp)    FCLI_VN(2,pfexp)

Convenience form of FCLI_VN for level-2 verbosity.

Definition at line 91 of file fossil-cli.h.

#define FCLI_VN (   N,
  pfexp 
)
Value:
if(fcli.verbose>=(N)) do { \
fcli_printf("VERBOSE %d: ", (int)(N)); \
fcli_printf pfexp; \
} while(0)
FSL_EXPORT void fcli_printf(char const *fmt,...)
Works like printf() but sends its output to fsl_outputf() using the fcli.f fossil conext (if set) or ...
int verbose
A verbosity level counter.
Definition: fossil-cli.h:194
FSL_EXPORT fcli_t fcli
This fcli_t instance is intended to act as a singleton.
Definition: fossil-cli.h:308

Ouputs the given printf-type expression (2nd arg) to fcli_printf() if fcli.verbose>=N, else it does nothing.

Reminder: this uses a while(0) look so that the macro can end with a semicolon without triggering a warning.

Definition at line 82 of file fossil-cli.h.

Typedef Documentation

Definition at line 127 of file fossil-cli.h.

typedef struct fcli_help_t fcli_help_t

Definition at line 151 of file fossil-cli.h.

typedef struct fcli_t fcli_t

Definition at line 278 of file fossil-cli.h.

typedef struct FossilCommand FossilCommand

Definition at line 510 of file fossil-cli.h.

typedef int(* FossilCommand_f) ()

Typedef for general-purpose fcli call-by-name commands.

See also
fcli_dispatch_commands()

Definition at line 497 of file fossil-cli.h.

Function Documentation

FSL_EXPORT fsl_cx* fcli_cx ( )

Returns the libfossil context associated with the fcli API.

FSL_EXPORT int fcli_dispatch_commands ( FossilCommand const *  cmdList,
char  reportErrors 
)

Expects an array of FossilCommands which contain a trailing sentry entry with a NULL name and callback.

It searches the list for a command matching fcli_next_arg(). If found, it removes that argument from the list, calls the callback, and returns its result. If no command is found FSL_RC_NOT_FOUND is returned, the argument list is not modified, and the error state is updated with a description of the problem and a list of all command names in cmdList.

If reportErrors is true then on error this function outputs the error result but it keeps the error state in place for the downstream use.

FSL_EXPORT int fcli_end_of_main ( int  mainRc)

A minor helper function intended to be passed the pending result code of the main() routine.

This function outputs any pending error state in fcli. Returns one of EXIT_SUCCESS if mainRc is 0 and fcli had no pending error report, otherwise it returns EXIT_FAILURE. This function does not clean up fcli - that is handled via an atexit() handler.

It is intended to be called once at the very end of main:

1 int main(){
2 int rc;
3 
4 ...set up fcli...assign rc...
5 
6 return fcli_end_of_main(rc);
7 }
See also
fcli_error()
fcli_err_set()
fcli_err_report()
fcli_err_reset()
FSL_EXPORT int fcli_err_report2 ( char  clear,
char const *  file,
int  line 
)

If fcli has any error state, this outputs it and returns the error code, else returns 0.

If clear is true the error state is cleared/reset, otherwise it is left in place. Returns 0 if fcli has not been initialized. The 2nd and 3rd arguments are assumed to be the __FILE__ and __LINE__ macro values of the call point. See fcli_err_report() for a convenience form of this function.

The format of the output depends partially on fcli_is_verbose(). In verbose mode, the file/line info is included, otherwise it is elided.

See also
fcli_err_report()
FSL_EXPORT void fcli_err_reset ( )

Clears any error state in fcli.f.

FSL_EXPORT int fcli_err_set ( int  code,
char const *  fmt,
  ... 
)

Sets fcli.f's error state, analog to fsl_cx_err_set().

Returns the code argument on success, some other non-0 value on a more serious error (e.g. FSL_RC_OOM when formatting the string).

FSL_EXPORT fsl_error* fcli_error ( )

Returns the internally-used fsl_error instance which is used for propagating errors.

The object is owned by fcli and MUST NOT be freed or otherwise abused by clients. It may, however, be passed to routines which take a fsl_error parameter to report errors (e.g. fsl_deck_output().

Returns NULL if fcli_setup() has not yet been called or after fcli has been cleaned up (post-main()).

FSL_EXPORT char fcli_flag ( char const *  opt,
char **  value 
)

Searches fcli.argv for the given flag (pass it without leading dashes).

If found, this function returns true, else it returns false. If value is not NULL then the flag, if found, is assumed to have a value, otherwise the flag is assumed to be a boolean. A flag with a value may take either one of these forms:

-flag=value -flag value

value gets assigned to a COPY OF value part of the first form or a COPY OF the subsequent argument for the second form (copies are required in order to avoid trickier memory management here). On success it removes the flag (and its value, if any) from fcli.argv. Thus by removing all flags early on, the CLI arguments are left only with non-flag arguments to sift through.

If it returns a string, the caller must eventually free it with fsl_free().

Flags may start with either one or two dashes - they are equivalent.

FSL_EXPORT char fcli_flag2 ( char const *  opt1,
char const *  opt2,
char **  value 
)

Works like fcli_flag() but tries two argument forms, in order.

It is intended to be passed short and long forms, but can be passed two aliases or similar.

1 char * v = NULL;
2 fcli_flag2("n", "limit", &v);
3 if(v) { ...; fsl_free(v); }
FSL_EXPORT char fcli_flag_or_arg ( char const *  opt1,
char const *  opt2,
char **  value 
)

Works similarly to fcli_flag2(), but if no flag is found and value is not NULL then *value is assigned to the return value of fcli_next_arg(1).

In that case:

  • The return value will specify whether or not fcli_next_arg() returned a value or not.
  • If it returns true then *value is owned by the caller and it must eventually be freed using fsl_free().
  • If it returns false, *value is not modified.

The opt2 parameter may be NULL, but op1 may not.

FSL_EXPORT char fcli_has_unused_flags ( char  outputError)

If fcli.argv contains what looks like any flag arguments, this updates the fossil error state and returns true, else returns false.

If outputError is true and an unused flag is found then the error state is immediately output (but not cleared).

FSL_EXPORT void fcli_help ( )

Calls fcli_local_help() then displays global help options to stdout.

FSL_EXPORT int fcli_is_verbose ( )

Returns the verbosity level set via CLI args.

0 is no verbosity.

FSL_EXPORT char* fcli_next_arg ( char  take)

Peeks at or takes the next argument from the CLI args.

If take is true, it is removed from the args list and transfered to the caller (who must fsl_free() it), else ownership is not modified.

FSL_EXPORT void fcli_printf ( char const *  fmt,
  ... 
)

Works like printf() but sends its output to fsl_outputf() using the fcli.f fossil conext (if set) or fsl_fprintf() (to stdout).

FSL_EXPORT int fcli_setup ( int  argc,
char *const *  argv 
)

Should be called early on in main(), passed the arguments passed to main().

Returns 0 on success. Sets up the fcli instance and opens a checkout in the current dir by default.

MUST BE CALLED BEFORE fsl_malloc() and friends are used, as this swaps out the allocator with one which aborts on OOM.

If argument processing finds either of the (–help, -?) flags, or the first non-flag argument is "help", it sets fcli.transient.helpRequested to a true value, calls fcli_help(), and returns FSL_RC_BREAK, in which case the application should exit/return from main with code 0 immediately. fcli.transient.helpRequested is set to 1 if –help or -? are seen, 2 if "help" is the first non-flag argument, so clients can (if they care to) further distinguish between the two, e.g. by checking for a command after "help" in the latter case and showing command-specific help.

Returns 0 on success. Errors other than FSL_RC_BREAK should be treated as fatal to the app, and fcli.f's error state _might_ contain info about the error.

Variable Documentation

fcli

This fcli_t instance is intended to act as a singleton.

It holds all fcli-related global state. It gets initialized with default/empty state at app startup and gets fully initialized via fcli_setup().

Application startup with this API typically looks like:

1 // from early on in main():
2 int rc;
3 fcli.appHelp = fcli_local_help;
4 rc = fcli_setup(argv, argc);
5 if(FSL_RC_BREAK==rc) return 0; // --help|-?|help
6 else if(rc) goto end;
7 
8 // Else proceed. At the end do:
9 
10 end:
11 return (fcli_err_report(0)||rc) ? EXIT_FAILURE : EXIT_SUCCESS;

fcli.f holds the API's fsl_cx instance. It will be non-NULL (but might not have an opened checkout/repository) if fsl_setup() succeeds.

Definition at line 308 of file fossil-cli.h.