Skip to content

README.md

Latest commit

 

History

History
93 lines (76 loc) · 3.56 KB

README.md

File metadata and controls

93 lines (76 loc) · 3.56 KB
Raw

lib_str.sh

String-oriented Bash helpers shared by CLI commands.

Dependency

Source lib/bash/std/lib_std.sh before this library so logging and validation helpers are available.

Public API

  • base_str_lower <result_var> Convert a named variable's value to lowercase in place.
  • base_str_upper <result_var> Convert a named variable's value to uppercase in place.
  • base_str_trim <result_var> Remove leading and trailing whitespace from a named variable in place.
  • base_str_ltrim <result_var> Remove leading whitespace from a named variable in place.
  • base_str_rtrim <result_var> Remove trailing whitespace from a named variable in place.
  • base_str_contains <value> <substring> Return success when a string contains a substring.
  • base_str_starts_with <value> <prefix> Return success when a string starts with a prefix.
  • base_str_ends_with <value> <suffix> Return success when a string ends with a suffix.
  • base_str_split <result_array> <value> <separator> Split a string by a delimiter into a caller-provided array variable.
  • base_str_join <result_var> <separator> <source_array> Join a caller-provided array variable into a caller-provided result variable.

Shared TSV field escaping

Modules that emit line-oriented tab-delimited records share the internal __base_bash_libs_str_escape_tsv_field__ primitive. It escapes backslashes, tabs, newlines, and carriage returns as \\, \\t, \\n, and \\r in that order, keeping each record on one physical line without changing ordinary values. The Git and application modules import lib_str.sh automatically when needed; the internal helper is not application API.

Usage

source "/absolute/path/to/lib/bash/std/lib_std.sh"
declare -a app_args=()
base_init app_args --source "${BASH_SOURCE[0]}" --
base_std_import str/lib_str.sh

name="  Example Project  "
base_str_trim name
base_str_lower name

if base_str_starts_with "$name" "example"; then
    base_std_log_info "Example project detected."
fi

parts=()
base_str_split parts "alpha,beta,,gamma" ","

joined=""
base_str_join joined "|" parts

Behavior Notes

  • Case conversion uses Bash's native ${value,,} and ${value^^} expansions.
  • Trim helpers remove Bash character-class whitespace from the requested side.
  • String transformation helpers mutate the named variable in place and do not print transformed values for command substitution.
  • Predicate helpers require exactly two arguments, return shell status, and do not print output.
  • base_str_split preserves empty fields between repeated delimiters.
  • base_str_split preserves an empty first field when the input begins with the separator.
  • base_str_split preserves a trailing empty field when the input ends with the separator.
  • base_str_join preserves empty array elements, including trailing empty elements.
  • base_str_join requires distinct result and source variable names and rejects an alias before changing caller state.
  • Use base_list_contains from lib/bash/list/lib_list.sh for indexed-array membership checks.
  • Named string, result, and array arguments must be valid Bash variable names.
  • Array arguments and array result variables must already be declared as indexed arrays, for example with declare -a parts=().
  • Scalar string results must be untyped or exported-only variables; integer (-i) and case-converting (-l/-u) attributes are rejected to prevent Bash from silently changing values. Readonly variables and nameref outputs are rejected before publication.

Tests

BATS coverage lives in lib/bash/str/tests/lib_str.bats.