Initial files (#1)

- Added `paths.sh`, `arrays.sh`, `messages.sh`, and `files.sh`.

.bazelrc

@@ -0,0 +1,8 @@
+# Import Shared settings
+import %workspace%/shared.bazelrc
+
+# Import CI settings.
+import %workspace%/ci.bazelrc
+
+# Try to import a local.rc file; typically, written by CI
+try-import %workspace%/local.bazelrc

.github/workflows/bazel.yml

@@ -0,0 +1,67 @@
+name: Build
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  macos_build:
+
+    runs-on: macos-11.0
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Write local.bazelrc File
+      shell: bash
+      run: |
+        cat >local.bazelrc <<EOF
+        common --config=ci
+        EOF
+
+    - name: Output the Bazel Info
+      shell: bash
+      run: |
+        bazelisk info
+
+    - name: Execute Tests
+      shell: bash
+      run: |
+        bazelisk test //... 
+
+    - name: Build Anything Not Tested
+      shell: bash
+      run: |
+        bazelisk build //... 
+
+  ubuntu_build:
+
+    runs-on: ubuntu-20.04
+
+    env:
+      CC: clang
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Write local.bazelrc File
+      shell: bash
+      run: |
+        cat >local.bazelrc <<EOF
+        common --config=ci
+        EOF
+
+    - name: Output the Bazel Info
+      shell: bash
+      run: |
+        bazelisk info
+
+    - name: Execute Tests
+      shell: bash
+      run: |
+        bazelisk test //... 
+
+    - name: Build Anything Not Tested
+      shell: bash
+      run: |
+        bazelisk build //... 

.gitignore

@@ -0,0 +1,3 @@
+# Ignore Bazel symlinks
+bazel-*
+

BUILD.bazel

@@ -0,0 +1,12 @@
+load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg")
+load(
+    "@cgrindel_rules_updatesrc//updatesrc:updatesrc.bzl",
+    "updatesrc_update_all",
+)
+
+bzlformat_pkg(name = "bzlformat")
+
+# Define a runnable target to copy all of the formatted files to the workspace directory.
+updatesrc_update_all(
+    name = "update_all",
+)

README.md

@@ -1,2 +1,92 @@
-# bazel_shlib
-Bazel project that contains shared/common shell functions and binaries.
+# Shlib 
+
+Shlib is a library of Bash shell functions that are useful when implementing shell binaries, libraries, and tests.
+
+
+## Quickstart
+
+The following provides a quick introduction on how to get started using the libraries in this
+repository.
+
+###  Workspace Configuration
+
+Add the following to your `WORKSPACE` file.
+
+```python
+# TODO: Add http_archive command after release.
+
+load("@cgrindel_bazel_shlib//:deps.bzl", "shlib_rules_dependencies")
+
+shlib_rules_dependencies()
+
+load("@cgrindel_rules_bzlformat//bzlformat:deps.bzl", "bzlformat_rules_dependencies")
+
+bzlformat_rules_dependencies()
+
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+
+bazel_skylib_workspace()
+
+load("@cgrindel_bazel_starlib//:deps.bzl", "bazel_starlib_dependencies")
+
+bazel_starlib_dependencies()
+
+load("@cgrindel_rules_updatesrc//updatesrc:deps.bzl", "updatesrc_rules_dependencies")
+
+updatesrc_rules_dependencies()
+```
+
+### Reference Libraries As Dependencies
+
+Add the desired library and the Bazel runfiles as a dependency to your shell binary, library, or
+test declaration. In this example, the
+[sh_binary](https://docs.bazel.build/versions/main/be/shell.html#sh_binary) has a dependency on the
+`paths.sh` library.
+
+```python
+sh_binary(
+    name = "foo",
+    srcs = ["foo.sh"],
+    deps = [
+        "@bazel_tools//tools/bash/runfiles",
+        "@cgrindel_bazel_shlib//lib:paths",
+    ],
+)
+```
+
+### Source The Library And Use It
+
+In your shell script, add the following to source the library. 
+
+```sh
+# --- begin runfiles.bash initialization v2 ---
+# Copy-pasted from the Bazel Bash runfiles library v2.
+set -uo pipefail; f=bazel_tools/tools/bash/runfiles/runfiles.bash
+source "${RUNFILES_DIR:-/dev/null}/$f" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " "${RUNFILES_MANIFEST_FILE:-/dev/null}" | cut -f2- -d' ')" 2>/dev/null || \
+  source ".runfiles/$f" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " ".runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " ".exe.runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
+  { echo>&2 "ERROR: cannot find $f"; exit 1; }; f=; set -e
+# --- end runfiles.bash initialization v2 ---
+
+# Load the library file
+paths_lib="$(rlocation cgrindel_bazel_shlib/lib/paths.sh)"
+source "${paths_lib}"
+
+# ...
+
+# Use the library functions
+foo_path="$(normalize_path "${foo_path}")"
+```
+
+If you want to avoid sourcing a library that has already been loaded, the following code will check
+if the library is already loaded.
+
+```sh
+# Load the library file, it it is not already loaded.
+if [[ $(type -t cgrindel_bazel_shlib_lib_paths_loaded) != function ]]; then
+  paths_lib="$(rlocation cgrindel_bazel_shlib/lib/paths.sh)"
+  source "${paths_lib}"
+fi
+```

WORKSPACE

@@ -0,0 +1,35 @@
+workspace(name = "cgrindel_bazel_shlib")
+
+load("//:deps.bzl", "shlib_rules_dependencies")
+
+shlib_rules_dependencies()
+
+load("@cgrindel_rules_bzlformat//bzlformat:deps.bzl", "bzlformat_rules_dependencies")
+
+bzlformat_rules_dependencies()
+
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+
+bazel_skylib_workspace()
+
+load("@cgrindel_bazel_starlib//:deps.bzl", "bazel_starlib_dependencies")
+
+bazel_starlib_dependencies()
+
+load("@cgrindel_rules_updatesrc//updatesrc:deps.bzl", "updatesrc_rules_dependencies")
+
+updatesrc_rules_dependencies()
+
+load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
+
+go_rules_dependencies()
+
+go_register_toolchains(version = "1.17.2")
+
+load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
+
+gazelle_dependencies()
+
+load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
+
+protobuf_deps()

ci.bazelrc

@@ -0,0 +1,14 @@
+# CI Settings for Bazel
+
+# Output information about the flags that are applied
+common:ci --announce_rc
+
+# Disable color
+common:ci --color=no
+
+# Information about Github Action hosted runners
+# https://docs.github.com/en/free-pro-team@latest/actions/reference/specifications-for-github-hosted-runners#supported-runners-and-hardware-resources
+build:ci --local_cpu_resources=2
+
+# Test output information
+test:ci --test_output=errors --test_summary=detailed

deps.bzl

@@ -0,0 +1,29 @@
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
+
+def shlib_rules_dependencies():
+    maybe(
+        http_archive,
+        name = "bazel_skylib",
+        sha256 = "1c531376ac7e5a180e0237938a2536de0c54d93f5c278634818e0efc952dd56c",
+        urls = [
+            "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz",
+            "https://github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz",
+        ],
+    )
+
+    maybe(
+        http_archive,
+        name = "cgrindel_bazel_starlib",
+        sha256 = "1f5c6b13243a1a6f79742a8a0e883f7f4591f7890a388f87c8323f4242dc718d",
+        strip_prefix = "bazel-starlib-0.1.0",
+        urls = ["https://github.com/cgrindel/bazel-starlib/archive/v0.1.0.tar.gz"],
+    )
+
+    maybe(
+        http_archive,
+        name = "cgrindel_rules_bzlformat",
+        sha256 = "b45b392613092b42c4ee94051be104b990e3c8651dea17410dfd63b98957cd57",
+        strip_prefix = "rules_bzlformat-0.1.0",
+        urls = ["https://github.com/cgrindel/rules_bzlformat/archive/v0.1.0.tar.gz"],
+    )

lib/BUILD.bazel

@@ -0,0 +1,35 @@
+load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg")
+
+package(default_visibility = ["//visibility:public"])
+
+bzlformat_pkg(name = "bzlformat")
+
+sh_library(
+    name = "messages",
+    srcs = ["messages.sh"],
+)
+
+sh_library(
+    name = "assertions",
+    testonly = True,
+    srcs = ["assertions.sh"],
+)
+
+sh_library(
+    name = "paths",
+    srcs = ["paths.sh"],
+)
+
+sh_library(
+    name = "files",
+    srcs = ["files.sh"],
+    deps = [
+        ":paths",
+        "@bazel_tools//tools/bash/runfiles",
+    ],
+)
+
+sh_library(
+    name = "arrays",
+    srcs = ["arrays.sh"],
+)

lib/arrays.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+# This is used to determine if the library has been loaded
+cgrindel_bazel_shlib_lib_arrays_loaded() { return; }
+
+# Sorts the arguments and outputs a unique and sorted list with each item on its own line.
+#
+# Args:
+#   *: The items to sort.
+#
+# Outputs:
+#   stdout: A line per unique item.
+#   stderr: None.
+sort_items() {
+  local IFS=$'\n'
+  sort -u <<<"$*"
+}
+
+# Prints the arguments with each argument on its own line.
+#
+# Args:
+#   *: The items to print.
+#
+# Outputs:
+#   stdout: A line per item.
+#   stderr: None.
+print_by_line() {
+  for item in "${@:-}" ; do
+    echo "${item}"
+  done
+}
+
+# Joins the arguments by the provided separator.
+#
+# Args:
+#   separator: The separator that should be printed between each item.
+#   *: The items to join.
+#
+# Outputs:
+#   stdout: A string where the items are separated by the separator.
+#   stderr: None.
+join_by() {
+  # Lovingly inspired by https://dev.to/meleu/how-to-join-array-elements-in-a-bash-script-303a
+  local IFS="$1"
+  shift
+  echo "$*"
+}
+

lib/assertions.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+# This is used to determine if the library has been loaded
+cgrindel_bazel_shlib_lib_assertions_loaded() { return; }
+
+# Fail a test with the specified message.
+#
+# Args:
+#   err_msg: The message to print to stderr.
+#
+# Outputs:
+#   stdout: None.
+#   stderr: The error message.
+fail() {
+  local err_msg="${1:-}"
+  [[ -n "${err_msg}" ]] || err_msg="Unspecified error occurred."
+  echo >&2 "${err_msg}"
+  exit 1
+}
+
+# Asserts that the actual value equals the expected value.
+#
+# Args:
+#   expected: The expected value.
+#   actual: The actual value.
+#   err_msg: Optional. The error message to print if the assertion fails.
+#
+# Outputs:
+#   stdout: None.
+#   stderr: None.
+assert_equal() {
+  local expected="${1}"
+  local actual="${2}"
+  local err_msg="${3:-Expected to be equal. expected: ${expected}, actual: ${actual}}"
+  [[ "${expected}" == "${actual}" ]] || fail "${err_msg}"
+}
+