base-bash-libs/lib/bash/str/lib_str.sh at main · basefoundry/base-bash-libs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
# shellcheck shell=bash
#
# lib_str.sh - Bash library of generic string manipulation functions.
#

[[ -n "${BASE_BASH_LIBS_STR_LOADED:-}" ]] && return 0
if [[ "${BASE_BASH_LIBS_STDLIB_LOADED:-}" != "1" ]]; then
    printf '%s\n' "Error: lib_str.sh requires lib_std.sh to be sourced first." >&2
    return 1 2> /dev/null || exit 1
fi
readonly BASE_BASH_LIBS_STR_LOADED=1

# __base_bash_libs_str_escape_tsv_field__ - Escape one value for a TSV record.
#
# This internal primitive is shared by modules that publish line-oriented
# tab-delimited records. Backslashes are escaped first so the control-character
# escapes cannot be re-escaped.
__base_bash_libs_str_escape_tsv_field__() {
    local value="${1-}"

    value="${value//\\/\\\\}"
    value="${value//$'\t'/\\t}"
    value="${value//$'\n'/\\n}"
    value="${value//$'\r'/\\r}"
    printf '%s' "$value"
}

base_str_lower() {
    (($# == 1)) || {
        base_std_log_error -l base_bash_libs.str "base_str_lower: usage: base_str_lower <variable_name>"
        return 2
    }
    __base_bash_libs_std_validate_variable_names__ base_str_lower "${1-}" || return 2
    local __base_bash_libs_str_var_name="$1" __base_bash_libs_str_value

    __base_bash_libs_std_assert_writable_output__ base_str_lower "$__base_bash_libs_str_var_name" scalar || return 2
    __base_bash_libs_str_value="${!__base_bash_libs_str_var_name-}"
    printf -v "$__base_bash_libs_str_var_name" '%s' "${__base_bash_libs_str_value,,}"
}

base_str_upper() {
    (($# == 1)) || {
        base_std_log_error -l base_bash_libs.str "base_str_upper: usage: base_str_upper <variable_name>"
        return 2
    }
    __base_bash_libs_std_validate_variable_names__ base_str_upper "${1-}" || return 2
    local __base_bash_libs_str_var_name="$1" __base_bash_libs_str_value

    __base_bash_libs_std_assert_writable_output__ base_str_upper "$__base_bash_libs_str_var_name" scalar || return 2
    __base_bash_libs_str_value="${!__base_bash_libs_str_var_name-}"
    printf -v "$__base_bash_libs_str_var_name" '%s' "${__base_bash_libs_str_value^^}"
}

base_str_ltrim() {
    (($# == 1)) || {
        base_std_log_error -l base_bash_libs.str "base_str_ltrim: usage: base_str_ltrim <variable_name>"
        return 2
    }
    __base_bash_libs_std_validate_variable_names__ base_str_ltrim "${1-}" || return 2
    local __base_bash_libs_str_var_name="$1" __base_bash_libs_str_value

    __base_bash_libs_std_assert_writable_output__ base_str_ltrim "$__base_bash_libs_str_var_name" scalar || return 2
    __base_bash_libs_str_value="${!__base_bash_libs_str_var_name-}"
    __base_bash_libs_str_value="${__base_bash_libs_str_value#"${__base_bash_libs_str_value%%[![:space:]]*}"}"
    printf -v "$__base_bash_libs_str_var_name" '%s' "$__base_bash_libs_str_value"
}

base_str_rtrim() {
    (($# == 1)) || {
        base_std_log_error -l base_bash_libs.str "base_str_rtrim: usage: base_str_rtrim <variable_name>"
        return 2
    }
    __base_bash_libs_std_validate_variable_names__ base_str_rtrim "${1-}" || return 2
    local __base_bash_libs_str_var_name="$1" __base_bash_libs_str_value

    __base_bash_libs_std_assert_writable_output__ base_str_rtrim "$__base_bash_libs_str_var_name" scalar || return 2
    __base_bash_libs_str_value="${!__base_bash_libs_str_var_name-}"
    __base_bash_libs_str_value="${__base_bash_libs_str_value%"${__base_bash_libs_str_value##*[![:space:]]}"}"
    printf -v "$__base_bash_libs_str_var_name" '%s' "$__base_bash_libs_str_value"
}

base_str_trim() {
    (($# == 1)) || {
        base_std_log_error -l base_bash_libs.str "base_str_trim: usage: base_str_trim <variable_name>"
        return 2
    }
    __base_bash_libs_std_validate_variable_names__ base_str_trim "${1-}" || return 2
    base_str_ltrim "$1" || return $?
    base_str_rtrim "$1" || return $?
}

base_str_contains() {
    local value="${1-}" needle="${2-}"

    (($# == 2)) || {
        base_std_log_error -l base_bash_libs.str "base_str_contains: usage: base_str_contains <value> <needle>"
        return 2
    }
    [[ "$value" == *"$needle"* ]]
}

base_str_starts_with() {
    local value="${1-}" prefix="${2-}"

    (($# == 2)) || {
        base_std_log_error -l base_bash_libs.str "base_str_starts_with: usage: base_str_starts_with <value> <prefix>"
        return 2
    }
    [[ "$value" == "$prefix"* ]]
}

base_str_ends_with() {
    local value="${1-}" suffix="${2-}"

    (($# == 2)) || {
        base_std_log_error -l base_bash_libs.str "base_str_ends_with: usage: base_str_ends_with <value> <suffix>"
        return 2
    }
    [[ "$value" == *"$suffix" ]]
}

# Splits a value into a caller-owned indexed array. Empty fields are preserved,
# including the final empty field produced by a trailing separator.
base_str_split() {
    (($# == 3)) || {
        base_std_log_error -l base_bash_libs.str "base_str_split: usage: base_str_split <result_array> <value> <separator>"
        return 2
    }
    __base_bash_libs_std_validate_variable_names__ base_str_split "${1-}" || return 2
    local __base_bash_libs_str_split_result_name="$1" __base_bash_libs_str_split_value="$2" __base_bash_libs_str_split_separator="$3"

    __base_bash_libs_std_validate_array_kind__ base_str_split a "$__base_bash_libs_str_split_result_name" || return 2
    __base_bash_libs_std_assert_writable_output__ base_str_split "$__base_bash_libs_str_split_result_name" indexed-array || return 2

    local -a __base_bash_libs_str_split_fields=()
    local __base_bash_libs_str_split_remainder="$__base_bash_libs_str_split_value"

    if [[ -z "$__base_bash_libs_str_split_separator" ]]; then
        __base_bash_libs_str_split_fields=("$__base_bash_libs_str_split_value")
    else
        while [[ "$__base_bash_libs_str_split_remainder" == *"$__base_bash_libs_str_split_separator"* ]]; do
            __base_bash_libs_str_split_fields+=("${__base_bash_libs_str_split_remainder%%"$__base_bash_libs_str_split_separator"*}")
            __base_bash_libs_str_split_remainder="${__base_bash_libs_str_split_remainder#*"$__base_bash_libs_str_split_separator"}"
        done
        __base_bash_libs_str_split_fields+=("$__base_bash_libs_str_split_remainder")
    fi

    eval "$__base_bash_libs_str_split_result_name=(\"\${__base_bash_libs_str_split_fields[@]}\")"
}

base_str_join() {
    (($# == 3)) || {
        base_std_log_error -l base_bash_libs.str "base_str_join: usage: base_str_join <result_variable> <separator> <source_array>"
        return 2
    }
    __base_bash_libs_std_validate_variable_names__ base_str_join "${1-}" "${3-}" || return 2
    local __base_bash_libs_str_join_result_name="$1" __base_bash_libs_str_join_separator="$2" __base_bash_libs_str_join_array_name="$3"

    if [[ "$__base_bash_libs_str_join_result_name" == "$__base_bash_libs_str_join_array_name" ]]; then
        base_std_log_error -l base_bash_libs.str \
            "base_str_join: result and source variables must be distinct; '$__base_bash_libs_str_join_result_name' was provided for both."
        return 2
    fi
    __base_bash_libs_std_assert_writable_output__ base_str_join "$__base_bash_libs_str_join_result_name" scalar || return 2
    __base_bash_libs_std_validate_array_kind__ base_str_join a "$__base_bash_libs_str_join_array_name" || return 2

    local __base_bash_libs_str_join_joined="" __base_bash_libs_str_join_value __base_bash_libs_str_join_has_value=0
    local -a __base_bash_libs_str_join_values=()
    eval "if [[ -n \"\${${__base_bash_libs_str_join_array_name}[@]+set}\" ]]; then __base_bash_libs_str_join_values=(\"\${${__base_bash_libs_str_join_array_name}[@]}\"); fi"

    for __base_bash_libs_str_join_value in "${__base_bash_libs_str_join_values[@]+"${__base_bash_libs_str_join_values[@]}"}"; do
        if ((__base_bash_libs_str_join_has_value == 0)); then
            __base_bash_libs_str_join_joined="$__base_bash_libs_str_join_value"
            __base_bash_libs_str_join_has_value=1
        else
            __base_bash_libs_str_join_joined+="$__base_bash_libs_str_join_separator$__base_bash_libs_str_join_value"
        fi
    done

    printf -v "$__base_bash_libs_str_join_result_name" '%s' "$__base_bash_libs_str_join_joined"
}