Skip to content

Commit e0f6a20

Browse files
mulle-natmulle-nat
committed
* add usage to README.md (and improve some text at the same time)
1 parent 6d39ee0 commit e0f6a20

14 files changed

+233
-19
lines changed

‎.github/workflows/ci.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ jobs:
1010
os: [ ubuntu-latest, macos-latest ]
1111

1212
steps:
13-
- uses: actions/checkout@v3
13+
- uses: actions/checkout@v4
1414

1515
- name: Test
1616
run: |

‎README.md

Lines changed: 119 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ tested on **Debian**, **FreeBSD**, **macOS**, **Manjaro**, **MinGW**,
88

99
| Release Version | Release Notes
1010
|-------------------------------------------------------|--------------
11-
| ![Mulle kybernetiK tag](https://img.shields.io/github/tag/mulle-nat/mulle-bashfunctions.svg?branch=release) [![Build Status](https://github.com/mulle-nat/mulle-bashfunctions/workflows/CI/badge.svg?branch=release)](//github.com/mulle-nat/mulle-bashfunctions/actions)| [RELEASENOTES](RELEASENOTES.md) |
11+
| ![Mulle kybernetiK tag](https://img.shields.io/github/tag/mulle-nat/mulle-bashfunctions.svg?branch=release) [![Build Status](https://github.com/mulle-nat/mulle-bashfunctions/workflows/CI/badge.svg?branch=release)](//github.com/mulle-nat/mulle-bashfunctions/actions) | [RELEASENOTES](RELEASENOTES.md) |
1212

1313
## Executables
1414

@@ -20,7 +20,48 @@ tested on **Debian**, **FreeBSD**, **macOS**, **Manjaro**, **MinGW**,
2020

2121
## API
2222

23-
With `mulle-bashfunction.sh` preloaded you have access to a basic selection
23+
Use mulle-bashfunctions for discovery and documentation about itself.
24+
25+
You can list all the functions in **mulle-bashfunctions** like
26+
this:
27+
28+
``` sh
29+
for i in `mulle-bashfunctions libraries`
30+
do
31+
echo "### $i"
32+
mulle-bashfunctions functions "$i"
33+
echo
34+
done
35+
```
36+
37+
but you can also use `apropos` to discover functionality:
38+
39+
``` sh
40+
mulle-bashfunctions apropos uppercase
41+
```
42+
43+
Once you have found a function of interest, you can checkout its description
44+
with
45+
46+
47+
``` sh
48+
mulle-bashfunctions man r_uppercase
49+
```
50+
and try it out with `eval` for functions printing to standard output,
51+
or `r-eval`, for functions that return values in the `RVAL` global variable
52+
(these functionss are prefixed with `r_`):
53+
54+
55+
``` sh
56+
$ mulle-bashfunctions r-eval r_uppercase xyz
57+
XYZ
58+
```
59+
60+
61+
### Libraries
62+
63+
Your script running under `#! /usr/bin/env mulle-bash` will have
64+
`mulle-bashfunction.sh` preloaded. So you have access to a basic selection
2465
of libraries, namely:
2566

2667

@@ -36,7 +77,7 @@ of libraries, namely:
3677

3778

3879
Use `include "<name>"` to get access to the functions not included in
39-
`mulle-bashfunctions.sh` (but in `mulle-bashfunctions-all.sh`), namely:
80+
`mulle-bashfunctions.sh` namely:
4081

4182
| Name | Descriptions |
4283
|-----------------------------------|-----------------------------------------------------------------|
@@ -48,6 +89,77 @@ Use `include "<name>"` to get access to the functions not included in
4889
| [version](src/mulle-version.sh) | semver version management major.minor.version |
4990

5091

92+
### Example
93+
94+
This example loads some additional functionality into a mulle-bashfunctions
95+
script and executes it:
96+
97+
98+
``` sh
99+
#! /usr/bin/env mulle-bash
100+
101+
102+
include "case"
103+
104+
r_smart_downcase_identifier "${1:-EO.Foundation}"
105+
printf "%s\n" "${RVAL}"
106+
```
107+
108+
109+
## Usage
110+
111+
```
112+
Usage:
113+
mulle-bashfunctions [command]
114+
115+
mulle-bashfunctions main purpose is to help load the library functions
116+
into an interactive shell. The library functions are almalgamated in a
117+
file called "mulle-bashfunctions.sh". There are variants though (none,
118+
minimal, all) with different sizes.
119+
120+
But mulle-bashfunctions can also
121+
122+
* embed "mulle-bashfunctions.sh" into another shell script
123+
* show the path to "mulle-bashfunctions.sh"
124+
* locate the "mulle-bashfunctions.sh" install path for a desired variant
125+
* show documentation for any of the defined functions
126+
* list the available libraries, which you can "include"
127+
* run an arbitrary mulle-bashfunction with eval and r-eval
128+
129+
Examples:
130+
Load "mulle-bashfunctions-all.sh" into the current interactive shell:
131+
132+
eval `mulle-bashfunctions load all`
133+
134+
Commands:
135+
apropos <f> : search for a function by keywords
136+
embed : embed mulle-bashfunctions into a script
137+
env : environment needed for "mulle-bashfunctions.sh"
138+
eval <cmd> : evaluate cmd inside of mulle-bashfunctions
139+
functions : list defined functions
140+
hostname : show system hostname used by mulle-bashfunctions
141+
libraries : list available libraries
142+
load [variant] : use eval `mulle-bashfunctions load` to load
143+
man <function> : show documention for function, if available
144+
path [variant] : path to "mulle-bashfunctions.sh"
145+
r-eval <cmd> : evaluate cmd inside of mulle-bashfunctions and print RVAL
146+
username : show username used by mulle-bashfunctions
147+
uname : show system short name used by mulle-bashfunctions
148+
version : print currently used version
149+
versions : list installed versions
150+
151+
```
152+
153+
154+
155+
### How to write single-file mulle-bash scripts
156+
157+
1. Say `mulle-sde add my-script.sh` to create a mulle-bash script skeleton.
158+
2. ... actually write the script ...
159+
3. Say `mulle-bashfunction embed < my-script-sh` to create a standalone script.
160+
161+
The resulting script will run with `#! /bin/sh` and does not need a
162+
mulle-bashfunctions installation.
51163

52164

53165
### Runtime environment
@@ -60,21 +172,22 @@ and `setopt POSIX_ARGZERO` and will also `set -o GLOB_SUBST`.
60172
* `expand_aliases` is set and required for use of the `.for .do .done` macros.
61173
* `-u` or `+u` should work
62174
* `-e` will not work (!)
175+
* `posix` is turned off
63176

64177
Glob settings are unaffected and expected to be enabled by default.
65178

66179
### Conventions
67180

68181
`RVAL` is a global variable. It is used to pass return values from functions.
69182
The RVAL value can be clobbered by **any** function. Functions that return RVAL
70-
are prefixed with `r_` or `_r_` or somesuch. Functions that return multiple
183+
are prefixed with `r_` or `_r_` or some such. Functions that return multiple
71184
values are currently prefixed with `__`. This may change to `g_` in the
72185
future.
73186

74187

75188
### Develop
76189

77-
Do not edit the almagamated `mulle-bashfunctions*.sh` files, they are generated
190+
Do not edit the amalgamated `mulle-bashfunctions*.sh` files, they are generated
78191
by running `cmake .` in the project directory.
79192
Check out the small pamphlet [Modern Bash (Zsh) Scripting](https://www.mulle-kybernetik.com/modern-bash-scripting)
80193
by yours truly, for some background information on the techniques being used.
@@ -85,6 +198,7 @@ by yours truly, for some background information on the techniques being used.
85198

86199

87200

201+
88202
## Install
89203

90204
The command to install the latest mulle-bashfunctions into `/usr/local` (with **sudo**) is:

‎RELEASENOTES.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
### 6.2.4
2+
3+
* add usage to README.md (and improve some text at the same time)
4+
15
### 6.2.3
26

37
* fix `MULLE_BASH_EXE_SHELL` not being honored (any more ?)

‎cola/api.md.bud

Lines changed: 59 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,47 @@
11
## API
22

3-
With `mulle-bashfunction.sh` preloaded you have access to a basic selection
3+
Use mulle-bashfunctions for discovery and documentation about itself.
4+
5+
You can list all the functions in **mulle-bashfunctions** like
6+
this:
7+
8+
``` sh
9+
for i in `mulle-bashfunctions libraries`
10+
do
11+
echo "### $i"
12+
mulle-bashfunctions functions "$i"
13+
echo
14+
done
15+
```
16+
17+
but you can also use `apropos` to discover functionality:
18+
19+
``` sh
20+
mulle-bashfunctions apropos uppercase
21+
```
22+
23+
Once you have found a function of interest, you can checkout its description
24+
with
25+
26+
27+
``` sh
28+
mulle-bashfunctions man r_uppercase
29+
```
30+
and try it out with `eval` for functions printing to standard output,
31+
or `r-eval`, for functions that return values in the `RVAL` global variable
32+
(these functionss are prefixed with `r_`):
33+
34+
35+
``` sh
36+
$ mulle-bashfunctions r-eval r_uppercase xyz
37+
XYZ
38+
```
39+
40+
41+
### Libraries
42+
43+
Your script running under `#! /usr/bin/env mulle-bash` will have
44+
`mulle-bashfunction.sh` preloaded. So you have access to a basic selection
445
of libraries, namely:
546

647

@@ -16,7 +57,7 @@ of libraries, namely:
1657

1758

1859
Use `include "<name>"` to get access to the functions not included in
19-
`mulle-bashfunctions.sh` (but in `mulle-bashfunctions-all.sh`), namely:
60+
`mulle-bashfunctions.sh` namely:
2061

2162
| Name | Descriptions |
2263
|-----------------------------------|-----------------------------------------------------------------|
@@ -28,3 +69,19 @@ Use `include "<name>"` to get access to the functions not included in
2869
| [version](src/mulle-version.sh) | semver version management major.minor.version |
2970

3071

72+
### Example
73+
74+
This example loads some additional functionality into a mulle-bashfunctions
75+
script and executes it:
76+
77+
78+
``` sh
79+
#! /usr/bin/env mulle-bash
80+
81+
82+
include "case"
83+
84+
r_smart_downcase_identifier "${1:-EO.Foundation}"
85+
printf "%s\n" "${RVAL}"
86+
```
87+

‎cola/info.md.bud

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
### How to write single-file mulle-bash scripts
22

3-
Use `mulle-sde add my-script.sh` to create a mulle-bash script skeleton. This
4-
script needs mulle-bashfunctions installed to work.
5-
Search for desired functionality with `mulle-bashfunctions apropos`. Once your
6-
script is ready for distribution, say `mulle-bashfunction embed < my-script-sh`.
7-
Now you have a single script file, that you can copy to any other host/OS that
8-
has bash or zsh installed, but needs no mulle-bashfunctions installation.
9-
(Undo with `mulle-bashfunction extract`).
3+
1. Say `mulle-sde add my-script.sh` to create a mulle-bash script skeleton.
4+
2. ... actually write the script ...
5+
3. Say `mulle-bashfunction embed < my-script-sh` to create a standalone script.
6+
7+
The resulting script will run with `#! /bin/sh` and does not need a
8+
mulle-bashfunctions installation.
9+
1010

1111
### Runtime environment
1212

‎cola/properties.plist

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
{
44
showButtons = YES;
55
showCodacy = NO;
6+
createUsage = YES;
67
};
78
authors =
89
(

‎cola/usage.md.bud

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{%
2+
haveFile = [exists file:"usage.txt"]
3+
usage = nil
4+
5+
if not haveFile and config.createUsage
6+
pwd = [[NSFileManager defaultManager] currentDirectoryPath]
7+
name = [pwd lastPathComponent]
8+
executable = [pwd stringByAppendingPathComponent:name];
9+
cmdline = [executable stringByAppendingString:" "];
10+
cmdline = [cmdline stringByAppendingString:"help"];
11+
taskInfo = [NSTask mulleStringSystemCallWithCommandString:cmdline]
12+
if taskInfo[ "standardErrorString"]
13+
usage = taskInfo[ "standardErrorString"]
14+
endif
15+
endif
16+
%}
17+
{% if haveFile or usage %}
18+
## Usage
19+
20+
{% if usage %}
21+
```
22+
{{ usage }}
23+
```
24+
{% else %}
25+
```
26+
{% includes optionally verbatim "usage.txt" %}
27+
```
28+
{% endif %}
29+
{% else %}
30+
# No usage
31+
{% endif %}
32+
33+

‎mulle-bash

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ fi
149149
# this is "our" version
150150
# the actual loaded version may differ (and will change this variable)
151151
#
152-
MULLE_BASHFUNCTIONS_VERSION="6.2.3"
152+
MULLE_BASHFUNCTIONS_VERSION="6.2.4"
153153
MULLE_BASHFUNCTIONS_LIBEXEC_DIRNAME="libexec"
154154
MULLE_EXECUTABLE="$1"
155155

‎mulle-bashfunctions

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ usage()
4242
{
4343
[ ! -z "$*" ] && echo "error: $*" >&2
4444

45-
cat <<EOF
45+
cat <<EOF >&2
4646
Usage:
4747
${MULLE_EXECUTABLE_NAME} [command]
4848

‎src/mulle-bashfunctions-all.sh

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ then
163163
fi
164164
fi
165165

166+
166167
if ! [ ${MULLE_BASHLOADER_SH+x} ]
167168
then
168169
MULLE_BASHLOADER_SH='included'

‎src/mulle-bashfunctions-minimal.sh

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ then
163163
fi
164164
fi
165165

166+
166167
if ! [ ${MULLE_BASHLOADER_SH+x} ]
167168
then
168169
MULLE_BASHLOADER_SH='included'

‎src/mulle-bashfunctions-none.sh

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ then
163163
fi
164164
fi
165165

166+
166167
if ! [ ${MULLE_BASHLOADER_SH+x} ]
167168
then
168169
MULLE_BASHLOADER_SH='included'

‎src/mulle-bashfunctions.sh

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ then
163163
fi
164164
fi
165165

166+
166167
if ! [ ${MULLE_BASHLOADER_SH+x} ]
167168
then
168169
MULLE_BASHLOADER_SH='included'

‎src/mulle-file.sh

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1029,8 +1029,9 @@ function dir_has_files()
10291029
#
10301030
# dir_list_files <directory> [pattern] [filetypes]
10311031
#
1032-
# Lists file in <directory> (or directories as <directory> may contain
1033-
# wildcards) line by line.
1032+
# Lists file in <directory> line by line.
1033+
# (<directory> may contain wildcards). Filenames will have the directory
1034+
# prepended, which maybe absolute or not.
10341035
# <directory> may contain white space but no tabs. filetypes may be "f" for
10351036
# files or "d" for directories or "l" for symlinks. It can be a combination
10361037
# of these filetypes.

0 commit comments

Comments
 (0)