https://github.com/binaryphile/nano
a nano-sized bash library
https://github.com/binaryphile/nano
bash
Last synced: 2 months ago
JSON representation
a nano-sized bash library
- Host: GitHub
- URL: https://github.com/binaryphile/nano
- Owner: binaryphile
- License: other
- Created: 2017-05-11T20:36:50.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2017-08-22T14:59:56.000Z (almost 9 years ago)
- Last Synced: 2025-02-06T11:31:06.404Z (over 1 year ago)
- Topics: bash
- Language: Shell
- Size: 35.2 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
nano [](https://travis-ci.org/binaryphile/nano)
====
A nano-sized bash library
Defines a handful of less-visible (with leading underscores) functions
which are useful for writing other libraries.
nano API
========
- **`_joina`** *`delimiter array_name return_variable`* - joins the
elements of the array `array_name` with the character `delimiter`
*Returns*: the joined string in the variable `return_variable`
`return_variable` must exist outside of your function scope, usually
declared by your function's caller.
- **`_puts`** *`string`* - prints `string` with a newline
*Returns*: the string, with newline, on stdout
Uses the POSIX-recommended `printf` function instead of `echo`. Unlike
`echo`, `string` must be a single argument.
- **`_putserr`** *`string`* - prints `string` with a newline to stderr
*Returns*: the string, with newline, on stderr
`string` must be a single argument.
- **`_ret`** *`return_variable string_value|array_name|hash_name`* -
return a value via a named return variable
*Returns*: the value, in `return_variable`
`return_variable` must exist outside of your function scope, usually
declared by your function's caller. The existing variable must also be
the appropriate type; scalar, array or hash (a.k.a. associative array).
`return_variable` is therefore usually passed into your function as an
argument, which is then passed onto `_ret`.
Example:
myfunc () {
return_variable=$1
local "$return_variable" || return
_ret "$return_variable" 'my value' # pass back a string
}
Before calling `_ret`, your function must also declare `return_variable`
locally, as shown. Since the variable name may not be a valid identifier
string, this is usually done with a `return` clause in case it errors.
This should only be done right before calling `_ret`.
You could accomplish the same thing without `_ret` by using indirection
via `local -n ref` or `${!ref}`, but both of these allow the referenced
variable name to conflict with your local variables. `_ret` prevents
naming conflicts with your local variables.
Calling `_ret`, however, does unset the named variable in your
function's scope. If the variable name is also used by one of your local
variables (always possible), then your variable will be unset. Therefore
you may not be able to rely on variables after calling `_ret`, so you
should only do so right before your function returns.
The returned value(s) may be a scalar value, or may be contained in a
named array or hash. If passing an array or hash, simply use the
variable name as the second argument. If passing back a scalar value,
use the value, not its variable name (if stored in a variable).
As a corollary, the `_ret` function is unable to pass back the names of
arrays or hashes as scalar values. They will always be passed as their
array values. Be forewarned.
`_ret` is based on the discussion [here], but is enhanced to pass arrays
by name.
[here]: http://fvue.nl/wiki/Bash:_Passing_variables_by_reference