chiark - git - mdw - distorted-keys/blob - extract-profile.1

   1 .\" -*-nroff-*-
   2 .ie t \{\
   3 .  ds o \(bu
   4 .  if \n(.g .fam P
   5 .\}
   6 .el \{\
   7 .  ds o o
   8 .\}
   9 .de hP
  10 .IP
  11 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
  12 ..
  13 .de VS
  14 .sp 1
  15 .RS
  16 .nf
  17 .ft B
  18 ..
  19 .de VE
  20 .ft R
  21 .fi
  22 .RE
  23 .sp 1
  24 ..
  25 .TH extract-profile 1 "3 May 2015" "distorted.org.uk key management"
  26 .SH NAME
  27 extract-profile \- determine configuration using inheritance and substitution
  28 .SH SYNOPSIS
  29 .B extract-profile
  30 .I section
  31 .IR file | directory ...
  32 .SH DESCRIPTION
  33 The
  34 .B extract-profile
  35 utility reads a number of
  36 .BR .ini -style
  37 configuration files from the named
  38 .IR file s
  39 and
  40 .IR directori es,
  41 combines the sections according to inheritance rules (described below),
  42 performs substitutions on the values,
  43 and writes the resulting effective contents of the named
  44 .I section
  45 to standard output.
  46 .PP
  47 A
  48 .I directory
  49 named on the command line
  50 causes files within to be examined:
  51 specifically, each file whose name consists only of
  52 upper- and lowercase letters,
  53 digits,
  54 underscores
  55 .RB (` _ '),
  56 and
  57 hyphens
  58 .RB (` \- ')
  59 will be processed;
  60 other files are ignored,
  61 as are objects in the
  62 .I directory
  63 which aren't files
  64 (so, in particular, directories are not processed recursively).
  65 The files within a directory are processed
  66 in ascending lexicographic order.
  67 It may be useful to prefix filenames with numbers
  68 in order to ensure that they're read in the correct order.
  69 .SS Command-line options
  70 The following options are recognized.
  71 .TP
  72 .B \-h, \-\-help
  73 Print an overview
  74 of the options and commands
  75 to standard output
  76 and exit successfully.
  77 .TP
  78 .B \-\-version
  79 Print the version number
  80 of the
  81 .B distorted-keys
  82 package
  83 to standard output
  84 and exit successfully.
  85 .SS Configuration data model
  86 A
  87 .I property
  88 has a
  89 .I name
  90 and a
  91 .IR value .
  92 A property's name must consist only of
  93 upper- and lowercase letters,
  94 digits,
  95 underscores
  96 .RB (` _ '),
  97 and
  98 percent signs
  99 .RB (` % ').
 100 A property is
 101 .I internal
 102 if its name contains
 103 a percent sign;
 104 otherwise it is
 105 .IR external .
 106 .PP
 107 A
 108 .I direct section
 109 has a name,
 110 an
 111 .I inclusion list
 112 of other sections,
 113 and a collection of
 114 .I direct properties
 115 with distinct names.
 116 .PP
 117 There is a special section
 118 named
 119 .B @GLOBAL
 120 which is implicitly included by every other section.
 121 .SS Configuration syntax
 122 Configuration files are line-oriented.
 123 Leading and trailing whitespace is always ignored.
 124 There is no line-continuation syntax.
 125 There are four kinds of lines.
 126 .hP \*o
 127 .IR "Blank lines" ,
 128 consisting only of whitespace,
 129 are ignored.
 130 .hP \*o
 131 .IR Comments ,
 132 beginning with
 133 hash
 134 .RB (` # ')
 135 or
 136 semicolon
 137 .RB (` ; '),
 138 are also ignored.
 139 .hP \*o
 140 .IR "Section headings" ,
 141 consisting of a name
 142 surrounded by square brackets
 143 .RB (` [ ... ] '),
 144 cause the following assignments,
 145 as far as the next section heading
 146 or the end of the file,
 147 to define or override properties in the named section.
 148 .hP \*o
 149 .IR Assignments ,
 150 of the form
 151 .I name
 152 .B =
 153 .I value
 154 or
 155 .I name
 156 .B :
 157 .IR value ,
 158 define (or override) direct properties
 159 or pseudoproperties
 160 in the current section.
 161 Spaces around the
 162 .RB ` = '
 163 or
 164 .RB ` : '
 165 are optional and, if present, ignored.
 166 Hyphens
 167 .RB (` - ')
 168 in the
 169 .I name
 170 are converted to
 171 underscores
 172 .RB (` _ ').
 173 Assignments preceding the first section header in a file
 174 apply to the special section
 175 .BR @GLOBAL .
 176 .PP
 177 The same property
 178 or pseudoproperty
 179 may be defined multiple times in a section:
 180 only the last definition is significant;
 181 earlier definitions are silently ignored.
 182 .PP
 183 Pseudoproperties have names beginning with an at sign
 184 .RB (` @ ').
 185 The following pseudoproperties are recognized.
 186 .TP
 187 .B @include
 188 The value is a list of section names separated by whitespace.
 189 The current section's inclusion list is set to
 190 the corresponding named sections.
 191 .PP
 192 Sections may be defined in any order.
 193 The same section may be defined more than once:
 194 the effect is the same as a single section containing
 195 all of the assignments of the individual sections
 196 in the same order.
 197 .SS Inheritance
 198 The
 199 .I inferiors
 200 of a section
 201 .I S
 202 are the sections in
 203 .IR S 's
 204 inclusion list,
 205 together with their inferiors.
 206 It is an error if a section is its own inferior.
 207 (Consequently, it is an error if
 208 .B @GLOBAL
 209 has a non-empty inclusion list.)
 210 If
 211 .I T
 212 is an inferior of
 213 .I S
 214 then
 215 .I S
 216 is a
 217 .I superior
 218 of
 219 .IR T .
 220 .PP
 221 A section
 222 .I S
 223 has an
 224 .I effective property
 225 named
 226 .I P
 227 if either
 228 .I S
 229 has a direct property named
 230 .IR P ,
 231 or any inferior of
 232 .I S
 233 has a direct property named
 234 .IR P .
 235 .PP
 236 If
 237 .I S
 238 has an effective property named
 239 .I P
 240 then
 241 .IR P 's
 242 .I defining set
 243 consists of those sections out of
 244 .I S
 245 and its inferiors
 246 which have a direct property named
 247 .IR P .
 248 The
 249 .I reduced defining set
 250 for
 251 .I P
 252 consists of those sections in the
 253 .I defining set
 254 of
 255 .I P
 256 which have no superiors in the defining set.
 257 .PP
 258 If all of the sections in the reduced defining set for
 259 .I P
 260 assign the same value to
 261 .I P
 262 then that is the
 263 .I effective value
 264 for
 265 .I P
 266 in
 267 .IR S ;
 268 otherwise the configuration is erroneous.
 269 .PP
 270 Note that,
 271 according to these rules,
 272 if
 273 .I S
 274 has a direct property
 275 .I P
 276 then
 277 .I S
 278 has an effective property
 279 .I P
 280 with the same value.
 281 .SS Output
 282 The
 283 .B extract-profile
 284 program's output consists of assignments
 285 .IB name = value
 286 for the effective properties of the named
 287 .IR section ,
 288 one per line,
 289 in an arbitrary order.
 290 .SH AUTHOR
 291 Mark Wooding, <mdw@distorted.org.uk>
 292 .SH SEE ALSO
 293 .BR distorted-keys (7).