libfossil
cli.h
Go to the documentation of this file.
1/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* vim: set ts=2 et sw=2 tw=80: */
3#if !defined(_ORG_FOSSIL_SCM_FCLI_H_INCLUDED_)
4#define _ORG_FOSSIL_SCM_FCLI_H_INCLUDED_
5/*
6 Copyright 2013-2021 The Libfossil Authors, see LICENSES/BSD-2-Clause.txt
7
8 SPDX-License-Identifier: BSD-2-Clause-FreeBSD
9 SPDX-FileCopyrightText: 2021 The Libfossil Authors
10 SPDX-FileType: Code
11
12 Heavily indebted to the Fossil SCM project (https://fossil-scm.org).
13
14 *****************************************************************************
15 This file provides a basis for basic libfossil-using apps. It
16 attempts to provide basic services required by a wide variety of
17 fossil-using apps, with the intent of simplifying their creation.
18*/
19
20#include "core.h"
21#include <stdlib.h> /* EXIT_SUCCESS and friends */
22#include <assert.h>
23
24/** @page page_fcli fcli (formerly FossilApp)
25
26 ::fcli (formerly FossilApp) provides a small framework for
27 bootstrapping simple libfossil applications which only need a
28 single fsl_cx instance managing a single checkout and/or
29 repository. It is primarily intended for use with CLI apps
30 implementing features similar to those in fossil(1), but can also
31 be used with GUI apps. It provides the following basic services to
32 applications:
33
34 - The global ::fcli struct holds global state.
35
36 - fcli_setup_v2() bootstraps the environment. This must be the
37 first call made into the API, as this replaces the libfossil
38 memory allocator with a fail-fast variant to simplify app-level
39 code a bit (by removing the need to check for OOM errors). This
40 also registers an atexit(3) handler to clean up fcli-owned
41 resources at app shutdown.
42
43 - Automatically tries to open a checkout (and its associated
44 repository) under the current directory, but not finding one
45 is not an error (the app needs to check for this if it should
46 be an error: use fsl_cx_db_repo() and fsl_cx_db_ckout()).
47
48 - fcli_flag(), fcli_next_arg(), and friends provide uniform access
49 to CLI arguments.
50
51 - A (very) basic help subsystem, triggered by the --help or -? CLI
52 flags, or if the first non-flag argument is "help". Applications
53 may optionally assign fcli.appHelp to a function which outputs
54 app-specific help.
55
56 - Basic error reporting mechanism. See fcli_err_report().
57
58 The source tree contains several examples of using fcli
59 in the files named f-*.c.
60*/
61
62/**
63 Outputs the given fsl_appendf()-compatible formatting expression
64 (2nd arg) to fcli_printf() if fcli.verbose>=N, else it does
65 nothing.
66
67 Reminder: this uses a while(0) loop so that the macro can end
68 with a semicolon without triggering a warning.
69*/
70#define FCLI_VN(N,pfexp) \
71 if(fcli.config.verbose>=(N)) do { \
72 fcli_printf("VERBOSE %d: ", (int)(N)); \
73 fcli_printf pfexp; \
74 } while(0)
75
76/**
77 Convenience form of FCLI_VN for level-2 verbosity.
78*/
79#define FCLI_V2(pfexp) FCLI_VN(2,pfexp)
80
81/**
82 Convenience form of FCLI_VN for level-1 verbosity. Levels 1 and 2
83 are intended for application-level use. Levels 3+ are intended for
84 fcli use.
85*/
86#define FCLI_V(pfexp) FCLI_VN(1,pfexp)
87
88#if defined(__cplusplus)
89extern "C" {
90#endif
91
92/**
93 Result codes specific to the fcli API.
94*/
96/**
97 For use with fcli_flag_callback_f() implementations to indicate
98 that the flag processor should check for that flag again.
99*/
100FCLI_RC_FLAG_AGAIN = FSL_RC_end + 1,
101/**
102 Returned from fcli_dispatch_commands() when the string returned
103 from fcli_next_arg() does not match any fcli_command in the list.
104*/
106/**
107 Returned from fcli_setup() if flag processing invokes the help
108 system. This is an indication that the app should exit immediately
109 with a 0 result code.
110*/
112};
113/**
114 Types for use with the fcli_cliflag::flagType field. The value of
115 that field determines how the CLI flag handling interprets the
116 fcli_cliflag::flagValue void pointer.
117*/
119/** Sentinel placeholder. */
121/** Represents bool. */
123/** Represents bool, but gets set to false if the flag is set. */
125/** Represents int32_t. */
127/** Represents int64_t. */
129/** Represents fsl_id_t, which might be either int32_t or int64_t. */
131/** Represents double. */
133/** Represents (char const *). */
135};
136
138/**
139 Callback handler for CLI flag handling. It is passed the flag in
140 question, containing its state after fcli has processed its
141 flagValue part.
142
143 If the callback returns FCLI_RC_FLAG_AGAIN, the flag handler will
144 check for that flag again (for as long as the handler keeps
145 returning that value and as long as the flag repeats in the
146 argument list). This can be used to implement repeatable flags.
147
148 If it returns any other non-0 value, fcli_setup()
149 resp. fcli_process_flags() will fail with that result code.
150
151 Achtung: during fcli_setup(), at the time these are processed, fcli
152 will not yet have opened up a repository or checkout, so the
153 callback will not have access to things like symbolic-name-to-UUID
154 conversion at this level. Apps which need to do such work on their
155 arguments must first queue up the input and process it after
156 fcli_setup() returns. Apps which process the flags using
157 fcli_process_flags() after setup is complete will have access to
158 such features.
159*/
160typedef int (*fcli_flag_callback_f)(fcli_cliflag const *);
161
162/**
163 Models a single CLI flag. Its relative complexity is largely to
164 support generation of help text.
165
166 @see fcli_process_flags()
167*/
169 /**
170 "Short-form" for this flag, noting that there's no restriction on
171 its length. Either of flagShort and flagLong, but not both, may be
172 NULL.
173 */
174 const char * flagShort;
175 /**
176 "Long-form" for this flag, noting that there's no restriction on
177 its length.
178 */
179 const char * flagLong;
180
181 /**
182 Specifies how to interpret the data pointed to by
183 this->flagValue. See that member for details.
184 */
186
187 /**
188 If not NULL, the member is the target of the flag's value.
189 Its exact interpretation depends on the value of this->flagType:
190
191 - FCLI_FLAG_TYPE_BOOL: a pointer to a bool. Existence
192 of the flag causes it to be set to true.
193
194 - FCLI_FLAG_TYPE_BOOL_INVERT: a pointer to a bool, but
195 existence of the flag causes it to be set to false.
196
197 - FCLI_FLAG_TYPE_INT32: a pointer to an int32_t. The flag
198 will be converted from string to int using atoi().
199
200 - FCLI_FLAG_TYPE_INT64: a pointer to an int64_t. The flag
201 will be converted from string to int using atoll().
202
203 - FCLI_FLAG_TYPE_ID: a pointer to a fsl_id_t, which
204 can be either int32_t or int64_t.
205
206 - FCLI_FLAG_TYPE_DOUBLE: a pointer to a double. The flag
207 will be converted from string to int using strtod().
208
209 - FCLI_FLAG_TYPE_CSTR: a pointer to a (const char *). The flag's
210 value will be assigned on without further interpretation.
211
212 If this member is not NULL: If the flag is set, this value will
213 be assigned to. If the flag is not set in the CLI args, this
214 value is not written to.
215
216 If this member is NULL then fcli_process_flags() will simply skip
217 over it, but the help-text generator will process it. This can be
218 used to set up flags which will appear in the --help text but
219 which are processed separately (or outright ignored) by the app.
220
221 The underlying flag value's string memory is owned by fcli and is
222 valid until the app exits.
223 */
224 void * flagValue;
225
226 /**
227 Optional descriptive label to be used when rendering help text:
228
229 -x|--x-flag=ABCD
230
231 If it is NULL, the --help text generator will choose a value of
232 the ABCD part which depends on this->flagType.
233
234 This is only used if this->flagType is not one of
235 (FCLI_FLAG_TYPE_BOOL, FCLI_FLAG_TYPE_BOOL_INVERT). For those
236 types (which have no client-given values), this member is
237 ignored when generating help text.
238 */
239 const char * flagValueLabel;
240
241 /**
242 Optional callback which gets passed the flag, if it is set, after
243 fcli has assigned the flagValue entry (if it is not NULL).
244 See this data type's docs for more details.
245 */
247
248 /**
249 Help text for the flag. Intended to be displayed in the context
250 of a --help listing of flags.
251 */
252 const char * helpText;
253};
254#define fcli_cliflag_empty_m {\
255 0/*flagShort*/,0/*flagLong*/,\
256 FCLI_FLAG_TYPE_INVALID/*flagType*/,\
257 NULL/*flagValue*/,\
258 NULL/*flagValueLabel*/,NULL/*callback*/,NULL/*helpText*/}
259/** Non-const-copyable counterpart of fcli_cliflag_empty_m. */
261
262/** @def FCLI_FLAG_xxx
263
264 The various FCLI_FLAG_xxx macros are convenience-form initializers
265 for fcli_cliflag instances for use in initializing a fcli_cliflag
266 array. Example usage:
267
268 ```
269 bool flag1 = true, flag2 = false;
270 int32_t flag3 = 0;
271 const char * flag4 = 0;
272 const fcli_cliflag cliFlags[] = {
273 FCLI_FLAG_BOOL("x","xyz",&flag1,"Flag 1."),
274 FCLI_FLAG_BOOL_INVERT(NULL,"yzx",&flag2,"Flag 2."),
275 FCLI_FLAG_INT32("z",NULL,"value",&flag3,"Flag 3"),
276 FCLI_FLAG("f","file","filename",&flag4,
277 "Input file. May optionally be passed as the first "
278 "non-flag argument."),
279 fcli_cliflag_empty_m // list MUST end with this (or equivalent)
280 };
281 fcli_help_info const appHelp = {...};
282
283 int rc = fcli_setup_v2(argc, argv, cliFlags, &appHelp);
284 ```
285
286 BE CAREFUL with the data types, as we're using (void*) to access
287 data of an arbitrary type, the type being defined by a separate
288 field in the fcli_cliflag object.
289*/
290#define FCLI_FLAG_xxx /* for doc purposes only */
291//Members:
292//{short, long, type, tgt, valueDescr., callback, help}
293/** Bool-type flag. */
294#define FCLI_FLAG_BOOL(S,L,TGT,HELP) \
295 {S,L,FCLI_FLAG_TYPE_BOOL,TGT,NULL,NULL,HELP}
296/** Bool-type flag, but set to false if flag is set. */
297#define FCLI_FLAG_BOOL_INVERT(S,L,TGT,HELP) \
298 {S,L,FCLI_FLAG_TYPE_BOOL_INVERT,TGT,NULL,NULL,HELP}
299/** Bool-type flag with a callback. */
300#define FCLI_FLAG_BOOL_X(S,L,TGT,CALLBACK,HELP) \
301 {S,L,FCLI_FLAG_TYPE_BOOL,TGT,NULL,CALLBACK,HELP}
302/** Bool-type flag with a callback, but set to false if the flag is set. */
303#define FCLI_FLAG_BOOL_INVERT_X(S,L,TGT,CALLBACK,HELP) \
304 {S,L,FCLI_FLAG_TYPE_BOOL_INVERT,TGT,NULL,CALLBACK,HELP}
305/** String-type flag. */
306#define FCLI_FLAG_CSTR(S,L,LBL,TGT,HELP) \
307 {S,L,FCLI_FLAG_TYPE_CSTR,TGT,LBL,NULL,HELP}
308#define FCLI_FLAG FCLI_FLAG_CSTR
309/** String-type flag with a callback. */
310#define FCLI_FLAG_CSTR_X(S,L,LBL,TGT,CALLBACK,HELP) \
311 {S,L,FCLI_FLAG_TYPE_CSTR,TGT,LBL,CALLBACK,HELP}
312#define FCLI_FLAG_X FCLI_FLAG_CSTR_X
313/** int32-type flag. */
314#define FCLI_FLAG_I32(S,L,LBL,TGT,HELP) \
315 {S,L,FCLI_FLAG_TYPE_INT32,TGT,LBL,NULL,HELP}
316/** int32-type flag with a callback. */
317#define FCLI_FLAG_I32_X(S,L,LBL,TGT,CALLBACK,HELP) \
318 {S,L,FCLI_FLAG_TYPE_INT32,TGT,LBL,CALLBACK,HELP}
319/** int64-type flag. */
320#define FCLI_FLAG_I64(S,L,LBL,TGT,HELP) \
321 {S,L,FCLI_FLAG_TYPE_INT64,TGT,LBL,NULL,HELP}
322/** int64-type flag with a callback. */
323#define FCLI_FLAG_I64_X(S,L,LBL,TGT,CALLBACK,HELP) \
324 {S,L,FCLI_FLAG_TYPE_INT64,TGT,LBL,CALLBACK,HELP}
325/** fsl_id_t-type flag. */
326#define FCLI_FLAG_ID(S,L,LBL,TGT,HELP) \
327 {S,L,FCLI_FLAG_TYPE_ID,TGT,LBL,NULL,HELP}
328/** fsl_id_t-type flag with a callback. */
329#define FCLI_FLAG_ID_X(S,L,LBL,TGT,CALLBACK,HELP) \
330 {S,L,FCLI_FLAG_TYPE_ID,TGT,LBL,CALLBACK,HELP}
331/** double-type flag. */
332#define FCLI_FLAG_DBL(S,L,LBL,TGT,HELP) \
333 {S,L,FCLI_FLAG_TYPE_DOUBLE,TGT,LBL,NULL,HELP}
334/** double-type flag with a callback. */
335#define FCLI_FLAG_DBL_X(S,L,LBL,TGT,CALLBACK,HELP) \
336 {S,L,FCLI_FLAG_TYPE_DOUBLE,TGT,LBL,CALLBACK,HELP}
337
338/**
339 Structure for holding app-level --help info.
340*/
342 /** Brief description of what the app does. */
343 char const * briefDescription;
344 /** Brief usage text. It will be prefixed by the app's name and
345 "[options]". e.g. "file1 ... fileN".
346 */
347 char const * briefUsage;
348 /**
349 If not 0 then this is called after outputing any flags' help.
350 It should output any additional help text using f_out().
351 */
352 void (*callback)(void);
353};
355
356/**
357 The fcli_t type, accessed by clients via the ::fcli
358 global instance, contains various data for managing a basic
359 Fossil SCM application build using libfossil.
360
361 Usage notes:
362
363 - All non-const pointer members are owned and managed by the
364 fcli API. Clients may reference them but must be aware of
365 lifetimes if they plan to hold the reference for long.
366
367*/
368struct fcli_t {
369 /**
370 The shared fsl_cx instance. It gets initialized by
371 fcli_setup() and cleaned up post-main().
372
373 this->f is owned by this object and will be cleaned up at app
374 shutdown (post-main).
375 */
377 /**
378 The current list of CLI arguments. This list gets modified by
379 fcli_flag() and friends. Its memory is owned by fcli.
380 */
381 char ** argv;
382 /**
383 Current number of items in this->argv.
384 */
385 int argc;
386 /**
387 Application's name. Currently argv[0] but needs to be
388 adjusted for Windows platforms.
389 */
390 char const * appName;
391 /**
392 The flags in this struct are "public," meaning that client
393 applications may query and safely manipulate them directly if
394 they know what they're doing.
395
396 However, some of this state is only be legally modified
397 _before_ calling fcli_setup() (or equivalent).
398 */
399 struct {
400 /**
401 If not NULL, it must be a pointer to fcli_help_info holding help
402 info for the app. It will be formated and output when --help
403 is triggered.
404
405 Should be set by client applications BEFORE calling fcli_setup()
406 so that the ::fcli help subsystem can integrate the
407 app. fcli.appName will be set by the time this is used.
408 */
410
411 /**
412 May be set to an array of CLI flag objects, which fcli_setup()
413 will use for parsing the CLI flags. The array MUST end with an
414 entry which has NULL values for its (flagShort, flagLong)
415 members. When creating the array it is simplest to use
416 fcli_cliflag_empty_m as the initializer for that sentinel entry.
417
418 The elements in this array are traversed in the order they are
419 provided, and any which have a callback which returns
420 FCLI_RC_FLAG_AGAIN will be traversed repeatedly before moving on
421 to the next flag. This ordering may have side-effects on how the
422 app sets up its flag handling. In particular, this arrangement
423 makes the common cases easy to implement but makes certain more
424 complicated situations effectively impossible to implement. For
425 example:
426
427 ```
428 -x=1 -y=2 -x=3 -y=4
429 ```
430
431 Assuming the definition of the -y flag is first in this array and
432 has a callback which returns FCLI_RC_FLAG_AGAIN, the two -x flags
433 will be processed before either of the -y flags. Thus it is
434 impossible (using this method of traversal) to change the
435 behavior of the -y flags based on the left-closest -x value.
436
437 We "could," but probably never will, instead walk the input argv
438 looking for things which look like flags, then looking back into
439 this list for a match, rather than the other way around. That
440 would require a new args processing implementation, though, for
441 relatively little benefit.
442 */
444
445 /**
446 If not NULL then fcli_setup() will attempt to open the
447 checkout for the given dir, including its associated repo
448 db. By default this is "." (the current directory).
449
450 Applications can set this to NULL _before_ calling
451 fcli_setup() in order to disable the automatic attemp to
452 open a checkout under the current directory. Doing so is
453 equivalent to using the --no-checkout flag. The global
454 --checkout-dir flag will trump that setting, though.
455 */
456 char const * checkoutDir;
457
458 /**
459 A verbosity level counter. Starts at 0 (no verbosity) and goes
460 up for higher verbosity levels. Currently levels 1 and 2 are
461 intended for app-level use and level 3 for library-level use.
462 */
463 unsigned short verbose;
464
465 /**
466 Whether or not to enable fossil's SQL tracing. This should
467 start with a negative value, which helps fcli_setup() process
468 it. Setting this after initialization has no effect.
469 */
471 /**
472 This output channel is used when initializing the context
473 object. The default implementation uses fsl_outputer_FILE to
474 output to stdout.
475 */
477
478 /**
479 Listener for fsl_msg-published messages.
480 */
483
484 /**
485 Transient settings and flags. These are bits which are used
486 during (or very shortly after) fcli_setup() but have no effect
487 if modified after that.
488 */
489 struct {
490 /**
491 repo db name string from -R/--repo CLI flag.
492 */
493 const char * repoDbArg;
494 /**
495 User name from the --user CLI flag.
496 */
497 const char * userArg;
498 /**
499 Incremented if fcli_setup() detects -? or --help in the
500 argument list, or if the first non-flag argument is "help".
501 This is an int, rather than a bool, to support multiple levels
502 of help verbosity via multiple --help flags.
503 */
505 /**
506 True if the --lib-version CLI flag was used. This causes
507 fcli setup to exit as if --help had been invoked.
508 */
511 /**
512 Search paths.
513 */
514 struct {
515 /** Search object for binaries. */
518 /**
519 For holding pre-this->f-init error state. Once this->f is
520 initialized, all errors reported via fcli_err_set() are stored in
521 that object's error state.
522 */
524 struct {
525 /**
526 Key passed to the --see-key CLI flag.
527 */
528 const char * key;
529
530 /** Key len. */
531 unsigned int nKey;
532 /**
533 Key type.
534 */
537};
538typedef struct fcli_t fcli_t;
539
540/** @var fcli
541
542 This fcli_t instance is intended to act as a singleton. It holds
543 all fcli-related global state. It gets initialized with
544 default/empty state at app startup and gets fully initialized via
545 fcli_setup(). See that routine for an example of how it is
546 typically initialized.
547
548 fcli_cx() returns the API's fsl_cx instance. It will be non-NULL
549 (but might not have an opened checkout/repository) if fsl_setup()
550 succeeds.
551*/
553
554/**
555 Initializes fcli's state and CLI flags processing.
556
557 MUST BE CALLED BEFORE fsl_malloc() and friends are used, as this
558 swaps out the allocator with one which aborts on OOM. (But see
559 fcli_pre_setup() for a workaround for that.)
560
561 Should be called early on in main(), passed the arguments passed to
562 main(). Returns 0 on success. This sets up the ::fcli instance and
563 opens any checkout found in/above the current dir by default. To
564 disable the automatic search for a checkout, assign
565 `fcli.config.checkoutDir` to `NULL` before calling this.
566
567 If the 3rd argument is not NULL, this sets `fcli.config.cliFlags` to its
568 value. If the 4th argument is not NULL, this sets `fcli.config.appHelp` to
569 that value.
570
571 If argument processing finds either of the (`--help`, `-?`) flags,
572 or the first non-flag argument is "help", it sets
573 fcli.transient.helpRequested to a true value, calls fcli_help(),
574 and returns FCLI_RC_HELP, in which case the application should
575 exit/return from main with code 0 immediately. It behaves similar
576 when it finds the `--lib-version` flag.
577
578 This function behaves significantly differently if its 3rd argument
579 is not NULL or if fcli.config.cliFlags has been set before it is
580 called. In that case, it parses the CLI flags using that type's
581 rules and sets up fcli_help() to use those flags for generating the
582 help. It parses the global flags first, then the app-specific flags
583 (this means that global flags will be consumed from the argv array
584 before app-specific flags with the same names).
585
586 Returns 0 on success. Results other than FCLI_RC_HELP should be
587 treated as fatal to the app, and fcli.f's error state _might_
588 contain info about the error. If this function returns non-0, the
589 convention is that the app immediately returns the result of
590 fcli_end_of_main(THE_RESULT_CODE) from main(). That function will
591 treat FCLI_RC_HELP as a non-error and will report any error state
592 pending in the fcli_cx() object.
593
594 Example of intended basic usage:
595
596 ```
597 int main(int argc, char const * const * argv){
598 ...
599 // Optional fcli_cliflag setup:
600 fcli_cliflag const cliFlags[] = {
601 ...,
602 fcli_cliflag_empty_m
603 };
604 // Optional fcli_help_info setup:
605 fcli_help_info const help = {
606 "Fnoobs the borts and rustles the feathers.",
607 "file1 [... fileN]",
608 NULL // optional callback to display extra help
609 };
610 // Initialize...
611 int rc = fcli_setup_v2(argc, argv, cliFlags, &help);
612 if(rc) goto end;
613
614 ... app logic ...
615
616 end:
617 return fcli_end_of_main(rc);
618 }
619 ```
620
621 @see fcli_pre_setup()
622 @see fcli_setup()
623 @see fcli_end_of_main()
624*/
625FSL_EXPORT int fcli_setup_v2(int argc, char const * const * argv,
626 fcli_cliflag const * const cliFlags,
627 fcli_help_info const * const helpInfo );
628
629/**
630 The first time this is called, it swaps out libfossil's default
631 allocator with a fail-fast one which abort()s on allocation
632 error. This is normally called by fcli_setup(), but that also means
633 that it's illegal to use fsl_malloc() and friends before calling
634 that routine. If an application really needs to use fsl_malloc()
635 before calling fcli_setup(), it must call this first in order to
636 get the allocator initialization out of the way.
637
638 Calls after the first are no-ops, but the check for that is not
639 thread-safe. Neither is fcli, though, so that's okay.
640*/
642
643/**
644 Returns the libfossil context associated with the fcli API.
645 This will be NULL until fcli_setup() is called.
646*/
648
649/**
650 Works like printf() but sends its output to fsl_outputf() using
651 the fcli.f fossil conext (if set) or fsl_fprintf() (to
652 stdout).
653*/
654FSL_EXPORT void fcli_printf(char const * fmt, ...)
655#if 0
656/* Would be nice, but complains about our custom format options: */
657 __attribute__ ((__format__ (__printf__, 1, 2)))
658#endif
659 ;
660
661/**
662 f_out() is a shorthand for fcli_printf().
663*/
664#define f_out fcli_printf
665
666/**
667 Returns the verbosity level set via CLI args. 0 is no verbosity,
668 and one level is added each time the --verbose/-V CLI flag is
669 encountered by fcli_setup().
670*/
671FSL_EXPORT unsigned short fcli_is_verbose(void);
672
673/**
674 Searches fcli.argv for the given flag (pass it without leading
675 dashes). If found, this function returns true, else it returns
676 false. If value is not NULL then the flag, if found, is assumed to
677 have a value, otherwise the flag is assumed to be a boolean. A flag
678 with a value may take either one of these forms:
679
680 -flag=value
681 -flag value
682
683 *value gets assigned to a COPY OF the value part of the first form
684 or a COPY OF the subsequent argument for the second form (copies
685 are required in order to avoid trickier memory management
686 here). That copy is owned by fcli and will be cleaned up at app
687 exit. On success it removes the flag (and its value, if any) from
688 fcli.argv. Thus by removing all flags early on, the CLI arguments
689 are left only with non-flag arguments to sift through.
690
691 Flags may start with either one or two dashes - they are
692 equivalent.
693
694 This function may update the fcli error state. Specifically, if
695 passed a non-NULL 2nd argument and the flag is found at the end of
696 the argument list or the value immediately after the flag starts
697 with '-' then the error state will be updated and false will be
698 returned. Apps don't normally need to be quite that picky with
699 their error checking after looking for a flag, but the state is
700 there if needed. It may get reset by any future calls into the API,
701 though. fcli_process_flags() does check this state and will fail if
702 such an error is triggered.
703*/
704FSL_EXPORT bool fcli_flag(char const * opt, const char ** value);
705
706/**
707 Works like fcli_flag() but tries two argument forms, in order. It
708 is intended to be passed short and long forms, but can be passed
709 two aliases or similar. It accepts NULL for either form.
710
711 ```
712 const char * v = NULL;
713 fcli_flag2("n", "limit", &v);
714 if(v) { ... }
715 ```
716*/
717FSL_EXPORT bool fcli_flag2(char const * opt1, char const * opt2,
718 const char ** value);
719
720/**
721 Works similarly to fcli_flag2(), but if no flag is found and
722 value is not NULL then *value is assigned to the return value of
723 fcli_next_arg(true). In that case:
724
725 - The return value will specify whether or not fcli_next_arg()
726 returned a value or not.
727
728 - If it returns true then *value is owned by fcli and will be
729 cleaned up at app exit.
730
731 - If it returns false, *value is not modified.
732
733 The opt2 parameter may be NULL, but op1 may not.
734*/
735FSL_EXPORT bool fcli_flag_or_arg(char const * opt1, char const * opt2,
736 const char ** value);
737
738
739/**
740 Clears any error state in fcli.f.
741*/
743
744/**
745 Sets fcli.f's error state, analog to fsl_cx_err_set().
746 Returns the code argument on success, some other non-0 value on
747 a more serious error (e.g. FSL_RC_OOM when formatting the
748 string).
749*/
750FSL_EXPORT int fcli_err_set(int code, char const * fmt, ...);
751
752/**
753 Returns the internally-used fsl_error instance which is used for
754 propagating errors. The object is owned by ::fcli and MUST NOT
755 be freed or otherwise abused by clients. It may, however, be
756 passed to routines which take a fsl_error parameter to report
757 errors (e.g. fsl_deck_output().
758
759 Returns NULL if fcli_setup() has not yet been called or after
760 fcli has been cleaned up (post-main()).
761
762*/
764
765/**
766 If ::fcli has any error state, this outputs it and returns the
767 error code, else returns 0. If clear is true the error state is
768 cleared/reset, otherwise it is left in place. Returns 0 if
769 ::fcli has not been initialized. The 2nd and 3rd arguments are
770 assumed to be the __FILE__ and __LINE__ macro values of the call
771 point. See fcli_err_report() for a convenience form of this
772 function.
773
774 If fcli_cx() has no error state but fsl_cx_db(fcli_cx()) does,
775 then that error state is moved into the fsl_cx object and
776 reported here.
777
778 The format of the output depends partially on fcli_is_verbose(). In
779 verbose mode, the file/line info is included, otherwise it is
780 elided.
781
782 @see fcli_err_report()
783*/
784FSL_EXPORT int fcli_err_report2(bool clear, char const * file, int line);
785
786/**
787 Convenience macro for using fcli_err_report2().
788*/
789#define fcli_err_report(CLEAR) fcli_err_report2((CLEAR), __FILE__, __LINE__)
790
791/**
792 Peeks at or takes the next argument from the CLI args. If the
793 argument is true, it is removed from the args list. It is owned by
794 fcli and will be freed when the app exits.
795
796 Returns NULL if the args list is empty.
797*/
798FSL_EXPORT const char * fcli_next_arg(bool remove);
799
800/**
801 If fcli.argv contains what looks like any flag arguments, this
802 updates the fossil error state and returns FSL_RC_MISUSE, else
803 returns 0. If outputError is true and an unused flag is found
804 then the error state is immediately output (but not cleared).
805*/
806FSL_EXPORT int fcli_has_unused_flags(bool outputError);
807/**
808 If fcli.argv contains any entries, returns FSL_RC_MISUSE and
809 updates the error state with a message about unusued extra
810 arguments, else returns 0. If outputError is true and an unconsumed
811 argument is found then the error state is immediately output (but
812 not cleared).
813*/
814FSL_EXPORT int fcli_has_unused_args(bool outputError);
815
817/**
818 Typedef for general-purpose fcli call-by-name commands.
819
820 It gets passed its own command definition, primarily for each of
821 access to the flags member for CLI flags processing.
822
823 @see fcli_dispatch_commands()
824*/
825typedef int (*fcli_command_f)(fcli_command const *);
826
827/**
828 Describes a named callback command.
829
830 @see fcli_dispatch_commands()
831*/
833 /** The name of the command. */
834 char const * name;
835 /**
836 NUL-delimited string containing optional aliases of the above command
837 name. This string _must_ be double-NUL terminated (e.g., "alias\0\al\0").
838 */
839 char const * aliases;
840 /** Brief description, for use in generating help text. */
841 char const * briefDescription;
842 /** The callback for this command. */
844 /** Optional usage callback for this command. */
845 void (*usage)(void);
846 /**
847 Must be NULL or an array compatible with fcli_process_flags().
848 Can be used from within this->f for command-specific flag
849 dispatching, as well as help text generation.
850 */
852};
853
854/**
855 Expects an array of fcli_commands which contain a trailing
856 sentry entry with a NULL name and callback. It searches the list
857 for a command matching fcli_next_arg(). If found, it
858 removes that argument from the list, calls the callback, and
859 returns its result. If no command is found FCLI_RC_NO_CMD is
860 returned, the argument list is not modified, and the error state
861 is updated with a description of the problem and a list of all
862 command names in cmdList.
863
864 The distinct FCLI return code aims to help clients distinguish
865 between fcli_dispatch_commands() failure and failures propagated
866 by successfully dispatched fcli_command fcli_command_f callbacks.
867
868 If reportErrors is true then on error this function outputs
869 the error result but it keeps the error state in place
870 for the downstream use.
871
872 As a special case: when a command matches the first argument and
873 that object has a non-NULL flags member, this function checks the
874 _next_ argument, and if it is "help" then this function passes
875 that flags member to fcli_command_help() to output help, then
876 returns 0.
877*/
879 bool reportErrors);
880
881/**
882 Parse cmd->aliases for an alias (i.e., NUL-terminated string semantically
883 equivalent to cmd->name) matching arg. Return 0 if a match is found, else 1.
884 Note that cmd->aliases _must_ be double-NUL terminated.
885*/
886FSL_EXPORT int fcli_cmd_aliascmp( fcli_command const * cmd, char const * arg );
887
888/**
889 A minor helper function intended to be passed the pending result
890 code of the main() routine. This function outputs any pending
891 error state in fcli. Returns one of EXIT_SUCCESS if mainRc is 0
892 and fcli had no pending error report, otherwise it returns
893 EXIT_FAILURE. This function does not clean up fcli - that is
894 handled via an atexit() handler.
895
896 It is intended to be called once at the very end of main:
897
898 ```
899 int main(){
900 int rc;
901
902 ...set up fcli...assign rc...
903
904 return fcli_end_of_main(rc);
905 }
906 ```
907
908 As a special case, if mainRc is FCLI_RC_HELP, it is assumed to
909 be the result of the fcli --help flag handling, and is treated as
910 if it were 0.
911
912 @see fcli_error()
913 @see fcli_err_set()
914 @see fcli_err_report()
915 @see fcli_err_reset()
916*/
918
919/**
920 If mem is not NULL, this routine appends mem to a list of pointers
921 which will be passed to fsl_free() during the atexit() shutdown
922 phase of the app. Because fcli uses a fail-fast allocator, failure
923 to append the entry will itself cause a crash. This is only useful
924 for values for which fsl_free() suffices to clean them up, not
925 complex values like multi-dimensional arrays.
926
927 "fax" is short for "free at exit."
928
929 Results are undefined if the same address or overlapping addresses
930 are queued more than once. Once an entry is in this queue, there is
931 no way to remove it.
932
933 Returns its argument so that it can be used like:
934
935 ```
936 char * x = fcli_fax( fsl_strdup("...") );
937 ```
938*/
939FSL_EXPORT void * fcli_fax(void * mem);
940
941/**
942 Requires an array of fcli_cliflag objects terminated with an
943 instance with NULL values for the (flagShort, flagLong) members
944 (fcli_cliflag_empty_m is an easy way to get that).
945
946 If fcli.config.cliFlags is set before fcli_setup() is called, this routine
947 is called and passed those flags. Thus most apps can simply assign
948 their flags there and let setup() do the work. Apps which have
949 multiple dispatch paths, each with differing flags, may find it
950 easier to use this.
951
952 As a special case, if a given entry has NULL values for both of its
953 (flagValue, callback) members, it is assumed to exist purely for
954 use with the help-generating mechanisms and the flag is NOT
955 processed or consumed by fcli_process_flags(). That can be used
956 when the client needs to process the flag in ways beyond what is
957 capable via this routine. In such cases, add an appropriate entry
958 to the fcli_cliflag array for --help purposes and then process the
959 flag using fcli_flag() (or similar) either before or after calling
960 this.
961
962 Returns 0 on success. Returns non-0 only if a callback() member of
963 one of the entries returns a value other than FCLI_RC_FLAG_AGAIN.
964*/
966
967/**
968 Requires an array of fcli_cliflag objects as described for
969 fcli_process_flags(). This routine outputs their flags
970 and help text in a framework-conventional manner.
971
972 If fcli.config.cliFlags is set before fcli_setup() is called, this
973 routine is called and passed those flags. Thus most apps can simply
974 assign their flags there and let fcli_setup() do the work. Apps
975 which have multiple dispatch paths, each with differing flags, may
976 find it easier to use this.
977
978 Such apps, in order to get the full help listing for all dispatch
979 paths, may need to assign fcli.config.appHelp to a helper which
980 dispatches to an app-local help routine which, in turn, passes each
981 of their separate fcli_cliflag lists to this routine.
982*/
984
985/**
986 Requires that cmd be an array of fcli_command objects with a
987 trailing entry which has a NULL name. This function iterates over
988 them and outputs help text based on each one's (name,
989 briefDescription, flags) members.
990
991 If the 2nd argument is true AND the cmd->usage() callback has been
992 set, it will be called for each object in the cmd array after
993 outputting the cmd->flags help text.
994
995 If the 3rd argument is true, only the help for the single given
996 object is output, not any adjacent array members (if any).
997*/
998FSL_EXPORT void fcli_command_help(fcli_command const * cmd, bool showUsage, bool onlyOne);
999
1000/**
1001 Pretty print fcli_command->aliases like: " (aliases: cmd, com)".
1002*/
1003FSL_EXPORT void fcli_help_show_aliases(char const * aliases);
1004
1005/**
1006 If fcli has a checkout opened, this dumps various info about it
1007 to its output channel. Returns 0 on success, FSL_RC_NOT_A_CKOUT
1008 if no checkout is opened, or some other non-0 code on error.
1009
1010 If the useUtc argument is true, it uses UTC timestamps, else
1011 localtime. (Potential TODO: add an fcli-level CLI flag for that
1012 instead?)
1013*/
1015
1016/**
1017 Given a hash prefix, lists (via f_out()) all blob table entries
1018 which have this prefix. This is intended to be used by apps which
1019 accept a from a user and fsl_sym_to_rid() returns FSL_RC_AMBIGUOUS.
1020
1021 The first argument is an optional output label/header to output.
1022 If it is NULL, a default is used. If it is "" then no header is
1023 output.
1024*/
1025FSL_EXPORT void fcli_list_ambiguous_artifacts(char const * label, char const *prefix);
1026
1027/**
1028 If fcli has an opened checkout, that db handle is returned, else NULL
1029 is returned.
1030*/
1032
1033/**
1034 If fcli has an opened repository, that db handle is returned, else
1035 NULL is returned.
1036*/
1038
1039/**
1040 If fcli has an opened checkout, that db handle is returned, else NULL
1041 is returned and fcli's error state is updated with a description
1042 of the problem.
1043*/
1045
1046/**
1047 If fcli has an opened repository, that db handle is returned, else NULL
1048 is returned and fcli's error state is updated with a description
1049 of the problem.
1050*/
1052
1053/**
1054 Processes all remaining CLI arguments as potential file or directory
1055 names, collects their vfile.id values, and stores them in the given
1056 target bag. It requires an opened checkout.
1057
1058 vid is the vfile.vid value to filter on. If vid<=0 then the current
1059 checkout version is used. (Unless the app has explicitly loaded
1060 another version, that will be the only option available.)
1061
1062 If relativeToCwd is true then each argument is resolved as if
1063 referenced from the current working directory, else each is assumed
1064 to be relative to the top of the checkout directory. (For CLI apps,
1065 a value of true is almost always the right choice.)
1066
1067 If changedFilesOnly is true then only files which are "changed",
1068 according to the vfile table (as opposed to a filesystem check) are
1069 considered for addition. For that to work, vfile must be up to
1070 date, so fsl_vfile_changes_scan() must have been recently called to
1071 update that state. This function does not call it automatically
1072 because it's relatively slow and many apps already have to call it
1073 on their own.
1074
1075 This function matches only vfile.pathname, not vfile.origname,
1076 because it is possible for a given name to be in both fields (in
1077 different records) at the same time.
1078
1079 Returns 0 on success. If there are no more CLI arguments when it is
1080 called then it returns FSL_RC_MISUSE and updates the fcli error
1081 state with a description of the problem. It may return any number
1082 of non-0 codes from the underlying operations.
1083
1084 Sidebar: fsl_filename_to_vfile_ids() requires that directory names
1085 passed to it have no trailing slashes, and this routine strips
1086 trailing slashes from its arguments before passing them on to that
1087 routine, so they may be entered with slashes without ill effect.
1088
1089 @see fsl_filename_to_vfile_ids()
1090*/
1092 fsl_id_t vid,
1093 bool relativeToCwd,
1094 bool changedFilesOnly);
1095
1096/**
1097 Performs a "fingerprint check" on the current checkout/repo
1098 combination, as per fsl_ckout_fingerprint_check(). If the check
1099 fails and reportImmediately is true then an error report is
1100 immediately output. Returns 0 if the fingerprint check is okay,
1101 else a non-0 value as per fsl_ckout_fingerprint_check().
1102
1103 Passing true here may output more information than the underlying
1104 fsl_cx-level error state provides. e.g. it may provide a hint about
1105 how to recover.
1106*/
1107FSL_EXPORT int fcli_fingerprint_check(bool reportImmediately);
1108
1109/**
1110 Returns the "tail" part of the argv[0] string which was passed to
1111 fcli_setup(), or NULL if neither of those have yet been called. The
1112 "tail" part is the part immediately after the final '/' or '\\'
1113 character.
1114*/
1115FSL_EXPORT char const * fcli_progname(void);
1116
1117/**
1118 Searches the `$PATH` for a binary named fossil or fossil.exe. If
1119 found, that string is returned. The bytes are guaranteed to be
1120 alive until either the app ends or someone modifies
1121 fcli.path.bins. If not found, it returns NULL.
1122
1123 If errIfNotFound is true and no binary is found, it will update
1124 fcli's error state with a description of the problem.
1125
1126 If errIfNotFound is false, reportPolicy is ignored, else it is
1127 interpreted as:
1128
1129 - 0 = do not fcli_err_report() any errors and retain error state.
1130 - <0 = report and retain the error state.
1131 - >0 = report and clear error state.
1132*/
1133FSL_EXPORT char const * fcli_fossil_binary(bool errIfNotFound,
1134 int reportPolicy);
1135
1136/**
1137 Color theme IDs for use with fcli_diff_colors.
1138 */
1140/**
1141 Tells fcli_diff_colors() to NULL out the ANSI color state of its
1142 target object.
1143*/
1145/**
1146 Basic red (deletion) and green (insertion) diff colors.
1147*/
1150};
1152
1153/**
1154 Populates the given fsl_dibu_opt::ansiColors state with values
1155 dependend on the second argument.
1156*/
1158 fcli_diff_colors_e theme);
1159
1160
1161/**
1162 Flags for use with fcli_sync().
1163*/
1165/**
1166 Only perform one of the request operations if the fossil config
1167 setting "fcli.autosync" or "autosync" is set, preferring the
1168 former. "autosync" is fossil(1) standard flag for this, but clients
1169 may use "fcli.autosync" to trump that without changing fossil's
1170 behavior.
1171*/
1173/** Perform a pull (read-only) sync. */
1175/** Perform a push (write-only) sync. */
1177/** Perform a full sync. */
1179/** Perform a full sync, but only if autosync is enabled. */
1181/** Redirect all stdout output from the fsl_system() to /dev/null.
1182 This only works on non-Windows platforms. stderr output is
1183 retained. */
1185/**
1186 Works like FCLI_SYNC_NO_STDOUT, but also suppresses
1187 stderr.
1188 */
1190};
1191
1192/**
1193 Uses fcli_fossil_binary() to find the fossil(1) binary and run a
1194 sync operation, optionally either or both of push and pull
1195 operations.
1196
1197 Its argument may be a mask of any values from the fcli_sync_e
1198 enum.
1199
1200 Returns 0 if it does nothing or if fossil exits with a zero code.
1201 Returns FSL_RC_NOT_A_REPO if no repo is opened. If the repo is
1202 opened but has no "syncwith:" entries in its config table, no sync
1203 is attempted and 0 is returned.
1204
1205 If fossil cannot be found, returns FSL_RC_NOT_FOUND, else returns
1206 as documented for fsl_system().
1207
1208 This function will fail with FSL_RC_LOCKED if a transaction is
1209 currently open. Synching cannot succeed if a transaction is opened
1210 because the repo is write-locked during that time.
1211
1212 Though this routine does not generate any console output,
1213 the proxied binary will, which may corrupt screen state of
1214 any hypothetical curses-style libfossil clients.
1215*/
1216//FSL_EXPORT int fcli_sync( bool push, bool pull );
1217
1218FSL_EXPORT int fcli_sync( int ops );
1219
1220
1221/** @internal
1222
1223 This function is intented for use in development of libfossil. It
1224 dumps the current state of cached SQL statements to fcli_printf().
1225
1226 Normally its output detail level is determined by
1227 fcli_is_verbose(), but if forceVerbose is true then it cranks the
1228 detail all the way up.
1229 */
1230FSL_EXPORT void fcli_dump_stmt_cache(bool forceVerbose);
1231
1232/** @internal
1233
1234 This pseudo-internal function causes fcli to dump any
1235 library-level caching metrics it knows about. This function exists
1236 primarily to keep fcli client code from having to access the
1237 related internal members directly. This is a no-op if fcli has
1238 not been initialized.
1239*/
1241
1242/**
1243 A fsl_msg_f() implementation intended for use with CLI apps. It
1244 emits all output via fcli_printf(). This is the default message
1245 listener. Clients may replace the default by setting up
1246 fcli.config.listener before calling fcli_setup_v2(), and simple
1247 client apps may use this for other fsl_cx instances. This
1248 implementation ignores its state argument.
1249*/
1250FSL_EXPORT int fsl_msg_f_fcli(fsl_msg const *msg, void *state);
1251
1252#if defined(__cplusplus)
1253} /*extern "C"*/
1254#endif
1255
1256#endif
1257/* _ORG_FOSSIL_SCM_FCLI_H_INCLUDED_ */
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_EXPORT const char * fcli_next_arg(bool remove)
Peeks at or takes the next argument from the CLI args.
int(* fcli_command_f)(fcli_command const *)
Typedef for general-purpose fcli call-by-name commands.
Definition cli.h:825
fcli_sync_e
Flags for use with fcli_sync().
Definition cli.h:1164
@ FCLI_SYNC_AUTO
Only perform one of the request operations if the fossil config setting "fcli.autosync" or "autosync"...
Definition cli.h:1172
@ FCLI_SYNC_NO_OUTPUT
Works like FCLI_SYNC_NO_STDOUT, but also suppresses stderr.
Definition cli.h:1189
@ FCLI_SYNC_FULLAUTO
Perform a full sync, but only if autosync is enabled.
Definition cli.h:1180
@ FCLI_SYNC_PUSH
Perform a push (write-only) sync.
Definition cli.h:1176
@ FCLI_SYNC_PULL
Perform a pull (read-only) sync.
Definition cli.h:1174
@ FCLI_SYNC_NO_STDOUT
Redirect all stdout output from the fsl_system() to /dev/null.
Definition cli.h:1184
@ FCLI_SYNC_FULL
Perform a full sync.
Definition cli.h:1178
FSL_EXPORT fcli_t fcli
This fcli_t instance is intended to act as a singleton.
Definition cli.h:552
FSL_EXPORT bool fcli_flag_or_arg(char const *opt1, char const *opt2, const char **value)
Works similarly to fcli_flag2(), but if no flag is found and value is not NULL then *value is assigne...
FSL_EXPORT void fcli_command_help(fcli_command const *cmd, bool showUsage, bool onlyOne)
Requires that cmd be an array of fcli_command objects with a trailing entry which has a NULL name.
FSL_EXPORT void fcli_diff_colors(fsl_dibu_opt *const tgt, fcli_diff_colors_e theme)
Populates the given fsl_dibu_opt::ansiColors state with values dependend on the second argument.
FSL_EXPORT int fcli_setup_v2(int argc, char const *const *argv, fcli_cliflag const *const cliFlags, fcli_help_info const *const helpInfo)
Initializes fcli's state and CLI flags processing.
FSL_EXPORT int fcli_err_set(int code, char const *fmt,...)
Sets fcli.f's error state, analog to fsl_cx_err_set().
FSL_EXPORT char const * fcli_progname(void)
Returns the "tail" part of the argv[0] string which was passed to fcli_setup(), or NULL if neither of...
FSL_EXPORT void fcli_dump_stmt_cache(bool forceVerbose)
FSL_EXPORT int fcli_has_unused_args(bool outputError)
If fcli.argv contains any entries, returns FSL_RC_MISUSE and updates the error state with a message a...
FSL_EXPORT int fcli_dispatch_commands(fcli_command const *cmdList, bool reportErrors)
Expects an array of fcli_commands which contain a trailing sentry entry with a NULL name and callback...
FSL_EXPORT int fcli_err_report2(bool clear, char const *file, int line)
If fcli has any error state, this outputs it and returns the error code, else returns 0.
fcli_rc_e
Result codes specific to the fcli API.
Definition cli.h:95
@ FCLI_RC_NO_CMD
Returned from fcli_dispatch_commands() when the string returned from fcli_next_arg() does not match a...
Definition cli.h:105
@ FCLI_RC_HELP
Returned from fcli_setup() if flag processing invokes the help system.
Definition cli.h:111
@ FCLI_RC_FLAG_AGAIN
For use with fcli_flag_callback_f() implementations to indicate that the flag processor should check ...
Definition cli.h:100
FSL_EXPORT void fcli_help_show_aliases(char const *aliases)
Pretty print fcli_command->aliases like: " (aliases: cmd, com)".
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.
FSL_EXPORT fsl_error * fcli_error(void)
Returns the internally-used fsl_error instance which is used for propagating errors.
FSL_EXPORT int fcli_sync(int ops)
Uses fcli_fossil_binary() to find the fossil(1) binary and run a sync operation, optionally either or...
FSL_EXPORT void fcli_err_reset(void)
Clears any error state in fcli.f.
FSL_EXPORT int fcli_fingerprint_check(bool reportImmediately)
Performs a "fingerprint check" on the current checkout/repo combination, as per fsl_ckout_fingerprint...
FSL_EXPORT void * fcli_fax(void *mem)
If mem is not NULL, this routine appends mem to a list of pointers which will be passed to fsl_free()...
FSL_EXPORT bool fcli_flag(char const *opt, const char **value)
Searches fcli.argv for the given flag (pass it without leading dashes).
fcli_cliflag_type_e
Types for use with the fcli_cliflag::flagType field.
Definition cli.h:118
@ FCLI_FLAG_TYPE_INVALID
Sentinel placeholder.
Definition cli.h:120
@ FCLI_FLAG_TYPE_BOOL_INVERT
Represents bool, but gets set to false if the flag is set.
Definition cli.h:124
@ FCLI_FLAG_TYPE_INT32
Represents int32_t.
Definition cli.h:126
@ FCLI_FLAG_TYPE_ID
Represents fsl_id_t, which might be either int32_t or int64_t.
Definition cli.h:130
@ FCLI_FLAG_TYPE_CSTR
Represents (char const *).
Definition cli.h:134
@ FCLI_FLAG_TYPE_BOOL
Represents bool.
Definition cli.h:122
@ FCLI_FLAG_TYPE_INT64
Represents int64_t.
Definition cli.h:128
@ FCLI_FLAG_TYPE_DOUBLE
Represents double.
Definition cli.h:132
FSL_EXPORT fsl_db * fcli_db_ckout(void)
If fcli has an opened checkout, that db handle is returned, else NULL is returned.
FSL_EXPORT fsl_db * fcli_needs_ckout(void)
If fcli has an opened checkout, that db handle is returned, else NULL is returned and fcli's error st...
FSL_EXPORT int fsl_msg_f_fcli(fsl_msg const *msg, void *state)
A fsl_msg_f() implementation intended for use with CLI apps.
FSL_EXPORT int fcli_cmd_aliascmp(fcli_command const *cmd, char const *arg)
Parse cmd->aliases for an alias (i.e., NUL-terminated string semantically equivalent to cmd->name) ma...
int(* fcli_flag_callback_f)(fcli_cliflag const *)
Callback handler for CLI flag handling.
Definition cli.h:160
FSL_EXPORT char const * fcli_fossil_binary(bool errIfNotFound, int reportPolicy)
Searches the $PATH for a binary named fossil or fossil.exe.
FSL_EXPORT unsigned short fcli_is_verbose(void)
Returns the verbosity level set via CLI args.
FSL_EXPORT int fcli_ckout_show_info(bool useUtc)
If fcli has a checkout opened, this dumps various info about it to its output channel.
FSL_EXPORT fsl_cx * fcli_cx(void)
Returns the libfossil context associated with the fcli API.
FSL_EXPORT void fcli_dump_cache_metrics(void)
FSL_EXPORT bool fcli_flag2(char const *opt1, char const *opt2, const char **value)
Works like fcli_flag() but tries two argument forms, in order.
FSL_EXPORT int fcli_args_to_vfile_ids(fsl_id_bag *const tgt, fsl_id_t vid, bool relativeToCwd, bool changedFilesOnly)
Processes all remaining CLI arguments as potential file or directory names, collects their vfile....
fcli_diff_colors_e
Color theme IDs for use with fcli_diff_colors.
Definition cli.h:1139
@ FCLI_DIFF_COLORS_NONE
Tells fcli_diff_colors() to NULL out the ANSI color state of its target object.
Definition cli.h:1144
@ FCLI_DIFF_COLORS_RG
Basic red (deletion) and green (insertion) diff colors.
Definition cli.h:1148
@ FCLI_DIFF_COLORS_DEFAULT
Definition cli.h:1149
FSL_EXPORT int fcli_process_flags(fcli_cliflag const *defs)
Requires an array of fcli_cliflag objects terminated with an instance with NULL values for the (flagS...
FSL_EXPORT fsl_db * fcli_needs_repo(void)
If fcli has an opened repository, that db handle is returned, else NULL is returned and fcli's error ...
FSL_EXPORT void fcli_list_ambiguous_artifacts(char const *label, char const *prefix)
Given a hash prefix, lists (via f_out()) all blob table entries which have this prefix.
FSL_EXPORT const fcli_cliflag fcli_cliflag_empty
Non-const-copyable counterpart of fcli_cliflag_empty_m.
Definition cli.h:260
FSL_EXPORT fsl_db * fcli_db_repo(void)
If fcli has an opened repository, that db handle is returned, else NULL is returned.
FSL_EXPORT void fcli_pre_setup(void)
The first time this is called, it swaps out libfossil's default allocator with a fail-fast one which ...
FSL_EXPORT int fcli_has_unused_flags(bool outputError)
If fcli.argv contains what looks like any flag arguments, this updates the fossil error state and ret...
FSL_EXPORT void fcli_cliflag_help(fcli_cliflag const *defs)
Requires an array of fcli_cliflag objects as described for fcli_process_flags().
int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
Definition config.h:271
#define FSL_EXPORT
Definition config.h:66
This file declares the core SCM-related public APIs.
fsl_see_keytype_e
SQLite Encryption Extension (SEE) key types for use with fsl_see_key_f().
Definition core.h:595
Models a single CLI flag.
Definition cli.h:168
fcli_flag_callback_f callback
Optional callback which gets passed the flag, if it is set, after fcli has assigned the flagValue ent...
Definition cli.h:246
enum fcli_cliflag_type_e flagType
Specifies how to interpret the data pointed to by this->flagValue.
Definition cli.h:185
void * flagValue
If not NULL, the member is the target of the flag's value.
Definition cli.h:224
const char * flagLong
"Long-form" for this flag, noting that there's no restriction on its length.
Definition cli.h:179
const char * flagValueLabel
Optional descriptive label to be used when rendering help text:
Definition cli.h:239
const char * flagShort
"Short-form" for this flag, noting that there's no restriction on its length.
Definition cli.h:174
const char * helpText
Help text for the flag.
Definition cli.h:252
Describes a named callback command.
Definition cli.h:832
fcli_command_f f
The callback for this command.
Definition cli.h:843
void(* usage)(void)
Optional usage callback for this command.
Definition cli.h:845
char const * briefDescription
Brief description, for use in generating help text.
Definition cli.h:841
char const * name
The name of the command.
Definition cli.h:834
fcli_cliflag const * flags
Must be NULL or an array compatible with fcli_process_flags().
Definition cli.h:851
char const * aliases
NUL-delimited string containing optional aliases of the above command name.
Definition cli.h:839
Structure for holding app-level –help info.
Definition cli.h:341
void(* callback)(void)
If not 0 then this is called after outputing any flags' help.
Definition cli.h:352
char const * briefDescription
Brief description of what the app does.
Definition cli.h:343
char const * briefUsage
Brief usage text.
Definition cli.h:347
The fcli_t type, accessed by clients via the fcli global instance, contains various data for managing...
Definition cli.h:368
fsl_msg_listener listener
Listener for fsl_msg-published messages.
Definition cli.h:481
fsl_pathfinder bins
Search object for binaries.
Definition cli.h:516
struct fcli_t::@202107064176066125066352360350102245112274252274 config
The flags in this struct are "public," meaning that client applications may query and safely manipula...
enum fsl_see_keytype_e type
Key type.
Definition cli.h:535
int traceSql
Whether or not to enable fossil's SQL tracing.
Definition cli.h:470
unsigned int nKey
Key len.
Definition cli.h:531
char const * checkoutDir
If not NULL then fcli_setup() will attempt to open the checkout for the given dir,...
Definition cli.h:456
const fcli_cliflag * cliFlags
May be set to an array of CLI flag objects, which fcli_setup() will use for parsing the CLI flags.
Definition cli.h:443
struct fcli_t::@266037043025206162025002275223140110232154337054 see
const char * userArg
User name from the –user CLI flag.
Definition cli.h:497
char const * appName
Application's name.
Definition cli.h:390
char ** argv
The current list of CLI arguments.
Definition cli.h:381
short helpRequested
Incremented if fcli_setup() detects -?
Definition cli.h:504
fcli_help_info const * appHelp
If not NULL, it must be a pointer to fcli_help_info holding help info for the app.
Definition cli.h:409
const char * key
Key passed to the –see-key CLI flag.
Definition cli.h:528
struct fcli_t::@223255154203053366060260163120160074261145270143 paths
Search paths.
struct fcli_t::@325172015216067022331121211371252330115153125361 transient
Transient settings and flags.
fsl_outputer outputer
This output channel is used when initializing the context object.
Definition cli.h:476
int argc
Current number of items in this->argv.
Definition cli.h:385
unsigned short verbose
A verbosity level counter.
Definition cli.h:463
bool versionRequested
True if the –lib-version CLI flag was used.
Definition cli.h:509
fsl_error err
For holding pre-this->f-init error state.
Definition cli.h:523
const char * repoDbArg
repo db name string from -R/–repo CLI flag.
Definition cli.h:493
fsl_cx * f
The shared fsl_cx instance.
Definition cli.h:376
The main Fossil "context" type.
Definition internal.h:400
Db handle wrapper class.
Definition db.h:313
An instance of this class is used to convey certain state to fsl_dibu objects.
Definition util.h:3891
A container for storing generic error state.
Definition util.h:781
A container type for lists of db record IDs.
Definition util.h:5694
Client callback info for receiving various events during fossil sync processing.
Definition core.h:803
A message object type for use with fsl_sc::status().
Definition core.h:737
An interface which encapsulates data for managing an output destination, primarily intended for use w...
Definition util.h:337
The "Path Finder" class is a utility class for searching the filesystem for files matching a set of c...
Definition util.h:4936