lib.c (config_set_var_n): Return a pointer even if we don't change the var.

[runlisp] / query-runlisp-config.1.in

.\" -*-nroff-*-
.\"
.\" Manual for `query-runlisp-config'
.\"
.\" (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/>.
..
.ie t \{\
.  ds o \(bu
.  if \n(.g \{\
.    fam P
.    ev an-1
.    fam P
.    ev
.  \}
.\}
.el \{\
.  ds o o
.\}
.
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.
.\"--------------------------------------------------------------------------
.TH query-runlisp-config 1 "2 August 2020" "Mark Wooding"
.SH NAME
query-runlisp-config \- inspect and debug runlisp configuration files
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.B query-runlisp-config
.RB [ \-Lqv ]
.RB [ \-c
.IR conf ]
.RB [ \-o
.RI [ sect \c
.BR : ] \c
.IB var = \c
.IR value ]
.br
	\&
.RB [ \-l
.IR sect ]
.RB [ \-p
.RI [ sect \c
.BR : ] \c
.IR var ]
.RB [ \-w
.RI [ sect \c
.BR : ] \c
.IR var ]
.RB [ \-x
.RI [ sect \c
.BR : ] \c
.IR var ]
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
The
.B query-runlisp-config
program assists with understanding and debugging
.BR runlisp.conf (5)
files.
.
.SS "Options"
The command-line options are as follows.
.
.TP
.BR "\-h" ", " "\-\-help"
Write a synopsis of
.BR query-runlisp-config 's
command-line syntax
and a description of the command-line options
to standard output
and immediately exit with status 0.
.
.TP
.BR "\-V" ", " "\-\-version"
Write
.BR query-runlisp-config 's
version number
to standard output
and immediately exit with status 0.
.
.TP
.BR "\-L" ", " "\-\-list-sections"
List all of the known section names to standard output.
.
.TP
.BI "\-c" "\fR, " "\-\-config-file=" conf
Read configuration from
.IR conf .
If
.I conf
is a directory, then all of the files within
whose names end with
.RB ` .conf ',
are loaded, in ascending lexicographical order;
otherwise,
.I conf
is opened as a file.
All of the files are expected to as described in
.BR runlisp.conf (5).
.
.TP
.BI "\-l" "\fR, " "\-\-list-variables=" sect
List all of the variables assigned in section
.I sect
to standard output.
.
.TP
.BI "\-o" "\fR, " "\-\-set-option=\fR[" sect :\fR] var = value
Assign
.I value
to the variable
.I var
in configuration section
.IR sect ,
or
.B @CONFIG
if no section is specified.
The value is unexpandable,
and overrides any similarly named setting
from the configuration file(s).
.
.TP
.BI "\-p" "\fR, " "\-\-print-variable=\fR[" sect :\fR] var
Print the raw (unexpanded) result of looking up the variable
.I var
in configuration section
.I sect
(defaulting to
.BR @CONFIG ).
.
.TP
.BR "\-q" ", " "\-\-quiet"
Don't print warning messages.
This option may be repeated:
each use reduces verbosity by one step,
counteracting one
.RB ` \-v '
option.
The default verbosity level is 1,
which prints only warning measages.
.
.TP
.BR "\-v" ", " "\-\-verbose"
Print informational or debugging messages.
This option may be repeated:
each use increases verbosity by one step,
counteracting one
.RB ` \-q '
option.
The default verbosity level is 1,
which prints only warning measages.
Higher verbosity levels print informational and debugging messages.
.
.TP
.BI "\-w" "\fR, " "\-\-split-variable=\fR[" sect :\fR] var
Print the result of looking up, expanding, and word-splitting the variable
.I var
in configuration section
.I sect
(defaulting to
.BR @CONFIG ).
The words are quoted in shell-style, and separated by spaces.
.
.TP
.BI "\-x" "\fR, " "\-\-expand-variable=\fR[" sect :\fR] var
Print the result of looking up and expanding the variable
.I var
in configuration section
.I sect
(defaulting to
.BR @CONFIG ).
.
.\"--------------------------------------------------------------------------
.
.SH SEE ALSO
.BR dump-runlisp-image (1),
.BR query-runlisp-config (1),
.BR runlisp (1).
.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
.
.
.\"----- That's all, folks --------------------------------------------------