/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 
/* vim: set ts=2 et sw=2 tw=80: */
#if !defined(_NET_FOSSIL_SCM_FOSSILAPP_H_INCLUDED_)
#define _NET_FOSSIL_SCM_FOSSILAPP_H_INCLUDED_
/*
  Copyright (c) 2013 D. Richard Hipp

  This program is free software; you can redistribute it and/or
  modify it under the terms of the Simplified BSD License (also
  known as the "2-Clause License" or "FreeBSD License".)

  This program is distributed in the hope that it will be useful,
  but without any warranty; without even the implied warranty of
  merchantability or fitness for a particular purpose.

  Author contact information:
  drh@hwaci.com
  http://www.hwaci.com/drh/

  *****************************************************************************
  This file provides a basis for basic libfossil-using apps. It is intended
  to be used as the basis for test/demo apps, and not necessarily full-featured
  applications.
*/

/* Force assert() to always work... */
#if defined(NDEBUG)
#undef NDEBUG
#define DEBUG 1
#endif
#include "fossil-scm/fossil.h"
#include <assert.h> /* for the benefit of test apps */
#include <stdlib.h> /* EXIT_SUCCESS and friends */

/** @page page_fcli fcli (formerly FossilApp)

    ::fcli (formerly FossilApp) provides a small framework for
    bootstrapping simple libfossil applications which only need a
    single fsl_cx instance managing a single checkout and/or
    repository. It is primarily intended for use with CLI apps
    implementing features similar to those in fossil(1), but can also
    be used with GUI apps. It provides the following basic services to
    applications:

    - The global ::fcli struct holds global state.

    - fcli_setup() bootstraps the environment. This must be the
    first call made into the API, as this replaces the libfossil
    memory allocator with a fail-fast variant to simplify app-level
    code a bit (by removing the need to check for OOM errors). This
    also registers an atexit(3) handler to clean up fcli-owned
    resources at app shutdown.

    - Automatically tries to open a checkout (and its associated
    repository) under the current directory, but not finding one
    is not an error (the app needs to check for this if it should
    be an error: use fsl_cx_db_repo() and fsl_cx_db_checkout()).

    - fcli_flag(), fcli_next_arg(), and friends provide uniform access
    to CLI arguments.

    - A (very) basic help subsystem, triggered by the --help or -? CLI
    flags, or if the first non-flag argument is "help".  Applications
    may optionally assign fcli.appHelp to a function which outputs
    app-specific help. If help is triggered and the --global boolean
    flag is passed then framework-level help text will be output,
    otherwise a hint about the --global option will be output instead.

    - Basic error reporting mechanism. See fcli_err_report().

    The source tree contains several examples of using fcli
    in the files named f-*.c.
*/

/**
   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.
*/
#define FCLI_VN(N,pfexp)                        \
  if(fcli.verbose>=(N)) do {                    \
      fcli_printf("VERBOSE %d: ", (int)(N));    \
      fcli_printf pfexp;                        \
    } while(0)

/**
   Convenience form of FCLI_VN for level-2 verbosity.
*/
#define FCLI_V2(pfexp) FCLI_VN(2,pfexp)

/**
   Convenience form of FCLI_VN for level-1 verbosity. Levels 1
   and 2 are intended for application-level use.
*/
#define FCLI_V(pfexp) FCLI_VN(1,pfexp)

#if defined(__cplusplus)
extern "C" {
#endif


/**
   Describes help text for an application flag.
*/
struct fcli_help_arg_t {
  /** "Short" flag, with no leading dashes. */
  char const * flagShort;
  /** "Long" flag, with no leading dashes. */
  char const * flagLong;
  /** Brief description of value type, e.g. "int" or "string",
      or 0 if the flag is a boolean (has no value).
  */
  char const * valType;
  /**
     If not 0 and (this->brief!=0) then this is called to render the
     help text. It should simply render the text to f_out().
  */
  void (*callback)();

  /**
     Brief description text.
  */
  char const * brief;
};
typedef struct fcli_help_arg_t fcli_help_arg_t;

/**
   Structure for holding app-level --help info.
*/
struct fcli_help_t {
  /** Brief description of what the app does. */
  char const * briefDescription;
  /** Brief usage text. It will be prefixed by the
      app's name. e.g. "options file1 ... fileN".
  */
  char const * briefUsage;
  /**
     If not NULL, it must include a sentry entry at the end of the
     list with a NULL for both flagShort and flagLong pointer
     values.
  */
  fcli_help_arg_t const * flags;
  /**
     If not 0 then this is called after outputing any flags' help.
     It should output any additional help text using f_out().
  */
  void (*callback)();
};
typedef struct fcli_help_t fcli_help_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.

   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.

*/
struct fcli_t {
  /**
     Holds a help function callback which should output any
     app-specific help. 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 called.
  */
  void (*appHelp)();
  /**
     If not NULL, it must be a pointer to fcli_help_t holding help
     info for the app.  It will be formated and output when --help
     is triggered, in place of appHelp.
  */
  fcli_help_t const * appHelp2;
  /**
     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).
  */
  fsl_cx * f;
  /**
     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.
  */
  int verbose;
  /**
     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|-C flags.
  */
  char const * checkoutDir;
  /**
     The current list of CLI arguments. This list gets modified
     by fcli_flag() and friends.
  */
  char ** argv;
  /**
     Current number of items in this->argv.
  */
  int argc;
  /**
     Application's name. Currently argv[0] but needs to be
     adjusted for Windows platforms.
  */
  char const * appName;
  /**
     True if the --dry-run flag is seen during initial arguments
     processing. ::fcli does not use this itself - it is
     intended as a convenience for applications. Those which want
     to support a short-form flag can implement that like this:

     @code
     char dryRun = fcli.fDryRun ? fcli.fDryRun :
     fcli_flag("n", NULL);
     @endcode

  */
  char fDryRun;
  /**
     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.
  */
  struct {
    /**
       fsl_malloc()'d repo db name string made by args processing.
    */
    char * repoDbArg;
    /**
       Set to true if fcli_setup() detects -? or --help in the
       argument list, or if the first non-flag argument is "help".
    */
    char helpRequested;
    /**
       Don't use this - it will likely go away. The following text
       was at some point true but is currently a lie:

       If the --gmt flag is found, this is set to true.  That
       causes the FSL_CX_F_LOCALTIME_GMT flag to be set on this->f.
    */
    char gmtTime;
  } transient;
  /**
     Holds bits which can/should be configured by clients BEFORE
     calling fcli_setup().
  */
  struct {
    /**
       Whether or not to enable fossil's SQL tracing.
       This should start with a negative value, which helps
       fcli_process_args() process it. Setting this after
       initialization has no effect.
    */
    int traceSql;
    /**
       This output channel is used when initializing this->f. The
       default implementation uses fsl_outputer_FILE to output to
       stdout.
    */
    fsl_outputer outputer;

  } config;
};
typedef struct fcli_t fcli_t;

/** @var 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:

    @code
    // from early on in main():
    int rc;
    fcli.appHelp = fcli_local_help;
    rc = fcli_setup(argv, argc);
    if(FSL_RC_BREAK==rc) return 0; // --help|-?|help
    else if(rc) goto end;

    // Else proceed. At the end do:

    end:
    return (fcli_err_report(0)||rc) ? EXIT_FAILURE : EXIT_SUCCESS;

    @endcode

    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.
*/
extern fcli_t fcli;

/**
   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.
*/
int fcli_setup(int argc, char * const * argv );

/**
   Returns the libfossil context associated with the fcli API.
*/
fsl_cx * fcli_cx();

/**
   Calls fcli_local_help() then displays global help options
   to stdout.
*/
void fcli_help();

/**
   Works like printf() but sends its output to fsl_outputf() using
   the fcli.f fossil conext (if set) or fsl_fprintf() (to
   stdout).
*/
void fcli_printf(char const * fmt, ...)
#if 0
/* Would be nice, but complains about our custom format options: */
  __attribute__ ((__format__ (__printf__, 1, 2)))
#endif
  ;

/**
   f_out() is a shorthand for fcli_printf().
*/
#define f_out fcli_printf  

/**
   Returns the verbosity level set via CLI args. 0 is no verbosity.
*/
int fcli_is_verbose();

/**
   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.
*/
char fcli_flag(char const * opt, 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.

   @code
   char * v = NULL;
   fcli_flag2("n", "limit", &v);
   if(v) { ...; fsl_free(v); }
   @endcode
*/
char fcli_flag2(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.
*/
char fcli_flag_or_arg(char const * opt1, char const * opt2,
                      char ** value);


/**
   Clears any error state in fcli.f.
*/
void fcli_err_reset();

/**
   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).
*/
int fcli_err_set(int code, char const * fmt, ...);

/**
   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_error * fcli_error();


/**
   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 fcli_err_report()
*/
int fcli_err_report2(char clear, char const * file, int line);

/**
   Convenience macro for using fcli_err_report2().
*/
#define fcli_err_report(CLEAR) fcli_err_report2((CLEAR), __FILE__, __LINE__)

/**
   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.
*/
char * fcli_next_arg(char take);

/**
   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).
*/
char fcli_has_unused_flags(char outputError);

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

   @see fcli_dispatch_commands()
*/
typedef int (*FossilCommand_f)();

/**
   Describes a named callback command.

   @see fcli_dispatch_commands()
*/
struct FossilCommand {
  /** The name of the command. */
  char const * name;
  /** The callback for this command. */
  FossilCommand_f f;
};
typedef struct FossilCommand FossilCommand;

/**
   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.
*/
int fcli_dispatch_commands( FossilCommand const * cmdList,
                            char reportErrors);

/**
   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:

   @code
   int main(){
   int rc;

   ...set up fcli...assign rc...

   return fcli_end_of_main(rc);
   }
   @endcode

   @see fcli_error()
   @see fcli_err_set()
   @see fcli_err_report()
   @see fcli_err_reset()
*/
int fcli_end_of_main(int mainRc);

#if defined(__cplusplus)
} /*extern "C"*/
#endif


#endif
/* _NET_FOSSIL_SCM_FOSSILAPP_H_INCLUDED_ */
