Parcourir la source

Reformat docstrings to 76 character width

As recommended by Shellfu style:

    https://github.com/AloisMahdal/shellfu/blob/master/notes/style.md
Alois Mahdal il y a 7 ans
Parent
révision
2f28cdf75d
1 fichiers modifiés avec 68 ajouts et 73 suppressions
  1. 68
    73
      src/saturnin.sh.skel

+ 68
- 73
src/saturnin.sh.skel Voir le fichier

@@ -9,8 +9,8 @@ shellfu import pretty
9 9
 # Git commit hash of application source tree
10 10
 #
11 11
 # This is supposed to be set by your build scripts when building your
12
-# application.  The string is returned by calling your meta-command
13
-# with option --saturnin-app-git-hash.
12
+# application.  The string is returned by calling your meta-command with
13
+# option --saturnin-app-git-hash.
14 14
 #
15 15
 # Look for 'satcmd' template for a working example.
16 16
 #
@@ -20,8 +20,8 @@ SATURNIN_APP_GIT_HASH=${SATURNIN_APP_GIT_HASH:-}
20 20
 # Your application version
21 21
 #
22 22
 # This is supposed to be set by your build scripts when building your
23
-# application.  The string is returned by calling your meta-command
24
-# with options --version, --version-semver or  --saturnin-app-version.
23
+# application.  The string is returned by calling your meta-command with
24
+# options --version, --version-semver or  --saturnin-app-version.
25 25
 #
26 26
 # Look for 'satcmd' template for a working example.
27 27
 #
@@ -35,34 +35,36 @@ SATURNIN_CACHE_HOME=${SATURNIN_CACHE_HOME:-}
35 35
 #
36 36
 # Path where saturnin__conf should look for files
37 37
 #
38
-# If filename does not contain slash, it is looked up in each
39
-# (or all, based on strategy--see saturnin__conf() doc) path in this
40
-# list.  The list is colon-separated and non-dirs as well as
41
-# empty strings are silently ignored.
38
+# If filename does not contain slash, it is looked up in each (or all,
39
+# based on strategy--see saturnin__conf() doc) path in this list. The
40
+# list is colon-separated and non-dirs as well as empty strings are
41
+# silently ignored.
42 42
 #
43 43
 SATURNIN_CONF_PATH="${SATURNIN_CONF_PATH:-}"
44 44
 
45 45
 #
46 46
 # Expected config filename extension (for guessing from path head)
47 47
 #
48
-# If no filename to read is given, saturnin__conf() will guess
49
-# filename as the path head plus this suffix (e.g. `foo.ini` for
50
-# `saturnin__conf foo.bar.baz`)
48
+# If no filename to read is given, saturnin__conf() will guess filename
49
+# as the path head plus this suffix (e.g. `foo.ini` for `saturnin__conf
50
+# foo.bar.baz`)
51 51
 #
52 52
 SATURNIN_CONF_SUFFIX="${SATURNIN_CONF_SUFFIX:-.ini}"
53 53
 
54 54
 #
55 55
 # Directory where to look for subcommands
56 56
 #
57
-# Files here starting with $SATURNIN_LIBEXEC_PREFIX are considered subcommands
57
+# Files here starting with $SATURNIN_LIBEXEC_PREFIX are considered
58
+# subcommands
58 59
 #
59 60
 SATURNIN_LIBEXEC="${SATURNIN_LIBEXEC:-}"
60 61
 
61 62
 #
62 63
 # Subcommand file prefix
63 64
 #
64
-# This is recommended to be set to meta-command name plus dash.  For example,
65
-# if your meta-command is `mykit`, this should be set to `mykit-`.
65
+# This is recommended to be set to meta-command name plus dash.  For
66
+# example, if your meta-command is `mykit`, this should be set to
67
+# `mykit-`.
66 68
 #
67 69
 SATURNIN_LIBEXEC_PREFIX="${SATURNIN_LIBEXEC_PREFIX:-}"
68 70
 
@@ -72,11 +74,11 @@ saturnin__bug() {
72 74
     # Warn about bug in your software
73 75
     #
74 76
     # Issue warning using warn() from pretty but also add application
75
-    # version.  This is useful when an assertion in your application
76
-    # fails such that it is certain that there is a bug inside it.
77
+    # version.  This is useful when an assertion in your application fails
78
+    # such that it is certain that there is a bug inside it.
77 79
     #
78
-    # In such cases, it makes sense to print also version information
79
-    # to help users with reporting.
80
+    # In such cases, it makes sense to print also version information to
81
+    # help users with reporting.
80 82
     #
81 83
     local msg
82 84
     for msg in "$@";
@@ -97,51 +99,45 @@ saturnin__conf() {
97 99
     # File arguments
98 100
     # ==============
99 101
     #
100
-    # If omitted, *file* argument is inferred by taking part of
101
-    # kpath name before first dot and appending value of
102
-    # `$SATURNIN_CONF_SUFFIX`, (".ini" by default).
102
+    # If omitted, *file* argument is inferred by taking part of kpath name
103
+    # before first dot and appending value of `$SATURNIN_CONF_SUFFIX`,
104
+    # (".ini" by default).
103 105
     #
104 106
     # Each *file* argument is then processed as follows:
105 107
     #
106
-    #  *  `-` (single dash) is interpreted as reading from
107
-    #     STDIN.
108
+    #  *  `-` (single dash) is interpreted as reading from standard input.
108 109
     #
109
-    #  *  If argument contains slash, it is expanded as a regular
110
-    #     path (relative or absolute).
110
+    #  *  If argument contains slash, it is expanded as a regular path
111
+    #     (relative or absolute).
111 112
     #
112
-    #  *  Otherwise, it is taken as filename and searched for
113
-    #     in directories given in `$SATURNIN_CONF_PATH`.  (This can
114
-    #     yield more than one path, which is equivalent as if
115
-    #     all paths were provided.)
113
+    #  *  Otherwise, it is taken as filename and searched for in directories
114
+    #     given in `$SATURNIN_CONF_PATH`.  (This can yield more than one
115
+    #     path, which is equivalent as if all paths were provided.)
116 116
     #
117
-    #     Not all files expanded based on `$SATURNIN_CONF_PATH`
118
-    #     are read by default; reading is governed by "merge
119
-    #     strategy": the default strategy "first" reads only
120
-    #     the first existing file.
117
+    #     Not all files expanded based on `$SATURNIN_CONF_PATH` are read by
118
+    #     default; reading is governed by "merge strategy": the default
119
+    #     strategy "first" reads only the first existing file.
121 120
     #
122
-    #     "join" strategy on the other hand, means that any
123
-    #     files are simply concatenated and prefixed with
124
-    #     comment (visible only in raw mode) containing path
125
-    #     to the file.
121
+    #     "join" strategy on the other hand, means that any files are simply
122
+    #     concatenated and prefixed with comment (visible only in raw mode)
123
+    #     containing path to the file.
126 124
     #
127
-    #     This means that if a section is queried that is
128
-    #     present in both files, it is effectively concatenated
129
-    #     as well.
125
+    #     This means that if a section is queried that is present in both
126
+    #     files, it is effectively concatenated as well.
130 127
     #
131 128
     # Following calls are equivalent
132 129
     #
133 130
     #     saturnin__conf foo.bar.baz
134 131
     #     saturnin__conf foo.bar.baz foo.ini
135 132
     #
136
-    # and both result in reading of key *baz* from section *foo.bar*
137
-    # in file *foo.ini*, which is selected from *SATURNIN_CONF_PATH*.
138
-    # Should there be more foo.ini's, the first is selected.
139
-    # Using `-j` switch
133
+    # and both result in reading of key *baz* from section *foo.bar* in file
134
+    # *foo.ini*, which is selected from *SATURNIN_CONF_PATH*.  Should there
135
+    # be more foo.ini's, the first is selected.  Using `-j` switch
140 136
     #
141 137
     #     saturnin__conf -j foo.bar.baz
142 138
     #
143
-    # would cause all foo.ini's on *SATURNIN_CONF_PATH* be
144
-    # concatenated instead.
139
+    # would cause all foo.ini's on *SATURNIN_CONF_PATH* be concatenated
140
+    # instead.
145 141
     #
146 142
     local ig_mode               # retrieval mode
147 143
     local ig_query              # keypath or section name (when listing keys)
@@ -184,8 +180,8 @@ saturnin__conf_find() {
184 180
     #
185 181
     # Find all existing instances of sub-path $1 on $SATURNIN_CONF_PATH
186 182
     #
187
-    # Go through all elements of $SATURNIN_CONF_PATH, looking for file
188
-    # on sub-path $1.  Print each existing path, ignore rest.
183
+    # Go through all elements of $SATURNIN_CONF_PATH, looking for file on
184
+    # sub-path $1.  Print each existing path, ignore rest.
189 185
     #
190 186
     # If at least one path was found, return zero.  Otherwise, return one,
191 187
     # or more in case of error.
@@ -208,14 +204,13 @@ saturnin__conf_find() {
208 204
 
209 205
 saturnin__get() {
210 206
     #
211
-    # Show Saturnin Internal info by key $1 and exit
207
+    # Show Saturnin internal info by key $1 and exit
212 208
     #
213
-    # Key $1 can be whole `--saturnin-get-stuff` argument or just
214
-    # the part after `--saturnin-get-`.
209
+    # Key $1 can be whole `--saturnin-get-stuff` argument or just the part
210
+    # after `--saturnin-get-`.
215 211
     #
216
-    # This is aimed to help debugging and testing the app (or
217
-    # Saturnin itself) by showing packaging and deployment related
218
-    # info.
212
+    # This is aimed to help debugging and testing the app (or Saturnin
213
+    # itself) by showing packaging and deployment related info.
219 214
     #
220 215
     local key=${1#--saturnin-get-}
221 216
     case "$key" in
@@ -248,8 +243,8 @@ saturnin__main() {
248 243
     #
249 244
     # Main meta-command entry function
250 245
     #
251
-    # After setting all mandatory environment variables, call this from
252
-    # your main meta-command script.
246
+    # After setting all mandatory environment variables, call this from your
247
+    # main meta-command script.
253 248
     #
254 249
     local subcommand
255 250
     test -n "$SATURNIN_CACHE_HOME"     || die "SATURNIN_CACHE_HOME is not set"
@@ -283,12 +278,11 @@ saturnin__conf_mkpath() {
283 278
     #
284 279
     # Assemble SATURNIN_CONF_PATH from locations $@
285 280
     #
286
-    # For each location, print colon-delimited list of
287
-    # directories.  If location ends with "/ini.d", list of
288
-    # subfolders, sorted by C locale is printed--this allows
289
-    # for modular configuration.  Otherwise the location
290
-    # is printed.  Non-existent or non-directory locations
291
-    # are silently ignored.
281
+    # For each location, print colon-delimited list of directories.  If
282
+    # location ends with "/ini.d", list of subfolders, sorted by C locale is
283
+    # printed--this allows for modular configuration.  Otherwise the
284
+    # location is printed.  Non-existent or non-directory locations are
285
+    # silently ignored.
292 286
     #
293 287
     local location      # one location argument
294 288
     local path          # one path listed
@@ -312,8 +306,9 @@ saturnin__runhook() {
312 306
     #
313 307
     # Run custom hook named $1 from respective configuration section
314 308
     #
315
-    # Will load joined multi-line key "hook.$SATURNIN_SUBCOMMAND.$1",
316
-    # and execute it as Bash code.
309
+    # Will load joined multi-line key "hook.$SATURNIN_SUBCOMMAND.$1" and
310
+    # unless syntax check fails, execute it as Bash code (in separate
311
+    # process).
317 312
     #
318 313
     local hname="$1"
319 314
     local hook_code
@@ -423,14 +418,14 @@ _saturnin__conf__load() {
423 418
     #
424 419
     # Print contents of files specified in $@
425 420
     #
426
-    # Each argument means possible file candidate.  If candidate
427
-    # contains slash, it's treated as file path and is printed
428
-    # directly.  If it's single dash, standard input is copied.
421
+    # Each argument means possible file candidate.  If candidate contains
422
+    # slash, it's treated as file path and is printed directly.  If it's
423
+    # single dash, standard input is copied.
429 424
     #
430
-    # In all other cases, filename is searched in all elements
431
-    # of SATURNIN_CONF_PATH; output then depends on chosen $Strategy:
432
-    # with 'first' strategy, first existing file is printed, with
433
-    # 'join' strategy. all existing files are printed.
425
+    # In all other cases, filename is searched in all elements of variable
426
+    # SATURNIN_CONF_PATH; output then depends on chosen $Strategy: with
427
+    # 'first' strategy, first existing file is printed, with 'join'
428
+    # strategy, all existing files are printed.
434 429
     #
435 430
     local arg es
436 431
     es=0
@@ -486,8 +481,8 @@ _saturnin__nl2colon() {
486 481
     #
487 482
     # Convert newline-based list of paths to colon:based:list
488 483
     #
489
-    # Empty paths must not be included in the resulting list,
490
-    # so we need to drop them and also get the colons right.
484
+    # Empty paths must not be included in the resulting list, so we need to
485
+    # drop them and also get the colons right.
491 486
     #
492 487
     local idx=0     # current item index (zero-based)
493 488
     local path