Makefile.am: Also distribute the `README' file.

[runlisp] / common.h

/* -*-c-*-
 *
 * Common functionality of a less principled nature
 *
 * (c) 2020 Mark Wooding
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Runlisp, a tool for invoking Common Lisp scripts.
 *
 * Runlisp is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 3 of the License, or (at your
 * option) any later version.
 *
 * Runlisp 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.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Runlisp.  If not, see <https://www.gnu.org/licenses/>.
 */

#ifndef COMMON_H
#define COMMON_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Externally defined types ------------------------------------------*/

struct dstr;
struct argv;

/*----- Public variables --------------------------------------------------*/

extern struct config config;
extern struct config_section *toplevel, *builtin, *common, *env;
extern unsigned verbose;

/*----- Functions provided ------------------------------------------------*/

extern const char *my_getenv(const char */*name*/, const char */*dflt*/);
	/* Look up the environment variable NAME.
	 *
	 * If it's found, return the value; otherwise return DFLT.  This
	 * function looks up the environment variable in the `@ENV'
	 * configuration section, so (a) it's likely more efficient than
	 * getenv(3), and (b) the `init_config' function must have been
	 * called earlier.
	 */

extern long parse_int(const char */*what*/, const char */*p*/,
		      long /*min*/, long /*max*/);
	/* Parse and return an integer from the string P.
	 *
	 * Report an error if the string doesn't look like an integer, or if
	 * it's not between MIN and MAX (inclusive).  Qualify error messages
	 * using the adjective WHAT.
	 */

extern void argv_string(struct dstr */*d*/, const struct argv */*av*/);
	/* Format string-vector AV as a sequence of possibly-quoted words.
	 *
	 * Append the resulting list to D.
	 */

extern int file_exists_p(const char */*path*/, unsigned /*f*/);
#define FEF_EXEC 1u
#define FEF_VERBOSE 2u
	/* Return whether PATH names an existing file.
	 *
	 * This will return zero if PATH names something which isn't a
	 * regular file.  If `FEF_EXEC' is set in F, then additionally ensure
	 * that it's executable by the (real) calling uid.  If `FEF_VERBOSE'
	 * is set in F, then report on the outcome of the check to standard
	 * error.
	 */

extern int found_in_path_p(const char */*prog*/, unsigned /*f*/);
	/* Return whether PROG can be found in the `PATH'.
	 *
	 * If PROG is a pathname (absolute or relative -- i.e., if it
	 * contains a `/'), then just check that it names an executable
	 * program.  Otherwise check to see whether `DIR/PROG' exists and is
	 * executable for any DIR in the `PATH'.  The flags F are as for
	 * `file_exists_p'.
	 */

extern int try_exec(struct argv */*av*/, unsigned /*f*/);
#define TEF_DRYRUN 1u
#define TEF_VERBOSE 2u
	/* Try to run a program as indicated by the argument list AV.
	 *
	 * This is essentially execvp(3).  If `TEF_VERBOSE' is set in F then
	 * trace what's going on to standard error.  If `TEF_DRYRUN' is set
	 * in F then don't actually try to run the program: just check
	 * whether it exists and is vaguely plausible.  Return -1 if there
	 * was a problem, or 0 if it was successful but didn't actually run
	 * the program because of the flags settings.
	 */

extern void init_config(void);
	/* Initialize the configuration machinery.
	 *
	 * This establishes the standard configuration sections `@CONFIG',
	 * `@BUILTIN', `@COMMON', and `@ENV', setting the corresponding
	 * global variables, and populates `@BUILTIN' (from compile-time
	 * configuration) and `@ENV' (from the environment variables).
	 */

extern void read_config_file(const char */*what*/,
			     const char */*file*/, unsigned /*f*/);
	/* Read a named configuration FILE.
	 *
	 * WHAT is an adjective describing the configuration file, to be used
	 * in diagnostics; FILE is the actual filename to read; and F holds
	 * `CF_...'  flags for `config_read_file', which actually does most
	 * of the work.
	 */

extern void read_config_dir(const char */*what*/,
			    const char */*path*/, unsigned /*f*/);
	/* Read all of the configuration files in directory PATH.
	 *
	 * WHAT is an adjective describing the configuration directory, to be
	 * used in diagnostics; FILE is the actual filename to read; and F
	 * holds `CF_...'  flags for `config_read_file', which actually reads
	 * the files.
	 *
	 * All of the files named `*.conf' in the directory are read, in
	 * ascending lexicographical order by name.  If `CF_NOENTOK' is set
	 * in F, then ignore an error explaining that the directory doesn't
	 * exist.  (This only ignores `ENOENT': any other problem is still a
	 * fatal error.)
	 */

extern void read_config_path(const char */*path*/, unsigned /*f*/);
	/* Read configuration from a file or directory PATH.
	 *
	 * If PATH exists and names a directory then process all of the files
	 * within, as for `read_config_dir'; otherwise try to read it as a
	 * file, as for `read_config_file'. The flags F are passed to the
	 * respective function.
	 */

extern int set_config_var(const char */*assign*/);
	/* Apply a configuration variable setting in command-line syntax.
	 *
	 * ASSIGN should be a string in the form `[SECT:]VAR=VALUE'.  Set VAR
	 * to VALUE in section SECT (defaults to `@CONFIG').  The variable is
	 * set with `CF_OVERRIDE' set to prevent the setting from being
	 * overwritten by a configuration file.
	 */

extern void load_default_config(void);
	/* Load the default configuration files.
	 *
	 * This will read `ETCDIR/runlisp.d/*.conf', `ETCDIR/runlisp.conf',
	 * `~/.runlisp.conf', and `~/.config/runlisp.conf'.
	 */

extern void dump_config(void);
	/* Dump the configuration to standard error. */

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif