Browse Source

Reformat docstrings to 76 character width

As recommended by Shellfu style:

    https://github.com/AloisMahdal/shellfu/blob/master/notes/style.md
Alois Mahdal 7 years ago
parent
commit
2f28cdf75d
1 changed files with 68 additions and 73 deletions
  1. 68
    73
      src/saturnin.sh.skel

+ 68
- 73
src/saturnin.sh.skel View File

9
 # Git commit hash of application source tree
9
 # Git commit hash of application source tree
10
 #
10
 #
11
 # This is supposed to be set by your build scripts when building your
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
 # Look for 'satcmd' template for a working example.
15
 # Look for 'satcmd' template for a working example.
16
 #
16
 #
20
 # Your application version
20
 # Your application version
21
 #
21
 #
22
 # This is supposed to be set by your build scripts when building your
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
 # Look for 'satcmd' template for a working example.
26
 # Look for 'satcmd' template for a working example.
27
 #
27
 #
35
 #
35
 #
36
 # Path where saturnin__conf should look for files
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
 SATURNIN_CONF_PATH="${SATURNIN_CONF_PATH:-}"
43
 SATURNIN_CONF_PATH="${SATURNIN_CONF_PATH:-}"
44
 
44
 
45
 #
45
 #
46
 # Expected config filename extension (for guessing from path head)
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
 SATURNIN_CONF_SUFFIX="${SATURNIN_CONF_SUFFIX:-.ini}"
52
 SATURNIN_CONF_SUFFIX="${SATURNIN_CONF_SUFFIX:-.ini}"
53
 
53
 
54
 #
54
 #
55
 # Directory where to look for subcommands
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
 SATURNIN_LIBEXEC="${SATURNIN_LIBEXEC:-}"
60
 SATURNIN_LIBEXEC="${SATURNIN_LIBEXEC:-}"
60
 
61
 
61
 #
62
 #
62
 # Subcommand file prefix
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
 SATURNIN_LIBEXEC_PREFIX="${SATURNIN_LIBEXEC_PREFIX:-}"
69
 SATURNIN_LIBEXEC_PREFIX="${SATURNIN_LIBEXEC_PREFIX:-}"
68
 
70
 
72
     # Warn about bug in your software
74
     # Warn about bug in your software
73
     #
75
     #
74
     # Issue warning using warn() from pretty but also add application
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
     local msg
83
     local msg
82
     for msg in "$@";
84
     for msg in "$@";
97
     # File arguments
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
     # Each *file* argument is then processed as follows:
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
     # Following calls are equivalent
128
     # Following calls are equivalent
132
     #
129
     #
133
     #     saturnin__conf foo.bar.baz
130
     #     saturnin__conf foo.bar.baz
134
     #     saturnin__conf foo.bar.baz foo.ini
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
     #     saturnin__conf -j foo.bar.baz
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
     local ig_mode               # retrieval mode
142
     local ig_mode               # retrieval mode
147
     local ig_query              # keypath or section name (when listing keys)
143
     local ig_query              # keypath or section name (when listing keys)
184
     #
180
     #
185
     # Find all existing instances of sub-path $1 on $SATURNIN_CONF_PATH
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
     # If at least one path was found, return zero.  Otherwise, return one,
186
     # If at least one path was found, return zero.  Otherwise, return one,
191
     # or more in case of error.
187
     # or more in case of error.
208
 
204
 
209
 saturnin__get() {
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
     local key=${1#--saturnin-get-}
215
     local key=${1#--saturnin-get-}
221
     case "$key" in
216
     case "$key" in
248
     #
243
     #
249
     # Main meta-command entry function
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
     local subcommand
249
     local subcommand
255
     test -n "$SATURNIN_CACHE_HOME"     || die "SATURNIN_CACHE_HOME is not set"
250
     test -n "$SATURNIN_CACHE_HOME"     || die "SATURNIN_CACHE_HOME is not set"
283
     #
278
     #
284
     # Assemble SATURNIN_CONF_PATH from locations $@
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
     local location      # one location argument
287
     local location      # one location argument
294
     local path          # one path listed
288
     local path          # one path listed
312
     #
306
     #
313
     # Run custom hook named $1 from respective configuration section
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
     local hname="$1"
313
     local hname="$1"
319
     local hook_code
314
     local hook_code
423
     #
418
     #
424
     # Print contents of files specified in $@
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
     local arg es
430
     local arg es
436
     es=0
431
     es=0
486
     #
481
     #
487
     # Convert newline-based list of paths to colon:based:list
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
     local idx=0     # current item index (zero-based)
487
     local idx=0     # current item index (zero-based)
493
     local path
488
     local path