Initial files (#1)

Added src_utils API and filter_srcs rule.
Added documentation generation.
Added Github Actions workflow

.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,36 @@
+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 //... 
+

.gitignore

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

BUILD.bazel

@@ -0,0 +1,4 @@
+alias(
+    name = "update_all",
+    actual = "//doc:update",
+)

README.md

@@ -1,2 +1,39 @@
-# bazel-starlib
-Rules, macros and APIs that are useful for the implementation of Bazel repositories.
+# Starlib
+
+Starlib is a library of Starlark APIs and rules that are useful for the implementation of Bazel
+projects, but do not exist in the [Skylib](https://github.com/bazelbuild/bazel-skylib) repository.
+
+## Quickstart
+
+The following provides a quick introduction on how to get started using the rules and APIs in this
+repository. Check out [the documentation](/doc/) for more information.
+
+### Workspace Configuration
+
+```python
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "cgrindel_bazel_starlib",
+    sha256 = "",
+    strip_prefix = "bazel-starlib-0.1.0",
+    urls = ["https://github.com/cgrindel/bazel-starlib/archive/v0.1.0.tar.gz"],
+)
+
+load("@cgrindel_bazel_starlib//:deps.bzl", "bazel_starlib_dependencies")
+
+bazel_starlib_dependencies()
+
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+
+bazel_skylib_workspace()
+
+load("@cgrindel_bazel_doc//bazeldoc:deps.bzl", "bazeldoc_dependencies")
+
+bazeldoc_dependencies()
+
+load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
+
+stardoc_repositories()
+```
+

WORKSPACE

@@ -0,0 +1,17 @@
+workspace(name = "cgrindel_bazel_starlib")
+
+load("//:deps.bzl", "bazel_starlib_dependencies")
+
+bazel_starlib_dependencies()
+
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+
+bazel_skylib_workspace()
+
+load("@cgrindel_bazel_doc//bazeldoc:deps.bzl", "bazeldoc_dependencies")
+
+bazeldoc_dependencies()
+
+load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
+
+stardoc_repositories()

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,21 @@
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
+
+def bazel_starlib_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_doc",
+        sha256 = "26b269eec6dda36f3f24a4ffef1b997f057c78a53300e6c83a110cd79cd0918e",
+        strip_prefix = "bazel-doc-0.1.1",
+        urls = ["https://github.com/cgrindel/bazel-doc/archive/v0.1.1.tar.gz"],
+    )

doc/BUILD.bazel

@@ -0,0 +1,109 @@
+load(
+    "@cgrindel_bazel_doc//bazeldoc:bazeldoc.bzl",
+    "doc_for_provs",
+    "write_file_list",
+    "write_header",
+    doc_providers = "providers",
+)
+
+# MARK: - Documentation Providers
+
+_RULE_DOC_PROVIDERS = [
+    doc_providers.create(
+        name = "filter_srcs",
+        stardoc_input = "//rules:filter_srcs.bzl",
+        symbols = [
+            "filter_srcs",
+        ],
+        deps = ["//rules:filter_srcs"],
+    ),
+]
+
+_API_SRCS = [
+    "src_utils",
+]
+
+_API_DOC_PROVIDERS = [
+    doc_providers.create(
+        name = name,
+        stardoc_input = "//lib:{name}.bzl".format(name = name),
+        symbols = [name],
+        deps = ["//lib:{name}".format(name = name)],
+    )
+    for name in _API_SRCS
+]
+
+_ALL_DOC_PROVIDERS = [
+    doc_providers.create(
+        name = "api",
+        is_stardoc = False,
+        stardoc_input = "",
+        deps = [],
+    ),
+    doc_providers.create(
+        name = "rules",
+        is_stardoc = False,
+        stardoc_input = "",
+        deps = [],
+    ),
+] + _RULE_DOC_PROVIDERS + _API_DOC_PROVIDERS
+
+# MARK: - Headers
+
+# Write rule headers
+[
+    write_header(
+        name = doc_prov.header_label,
+        out = doc_prov.header_basename,
+        header_content = [
+            "# `{name}` Rule".format(name = doc_prov.name),
+        ],
+    )
+    for doc_prov in _RULE_DOC_PROVIDERS
+    if doc_prov.is_stardoc
+]
+
+# Write the API headers
+[
+    write_header(
+        name = doc_prov.header_label,
+        out = doc_prov.header_basename,
+        header_content = [
+            "# `{name}` API".format(name = doc_prov.name),
+        ],
+    )
+    for doc_prov in _API_DOC_PROVIDERS
+    if doc_prov.is_stardoc
+]
+
+# MARK: - Special Case api.md
+
+# Write the api.md_ file as a special case.
+write_file_list(
+    name = "api_doc",
+    out = "api.md_",
+    doc_provs = _API_DOC_PROVIDERS,
+    header_content = [
+        "# Build API",
+        "",
+        "The APIs listed below are available in this repository.",
+        "",
+    ],
+)
+
+# Write the rules.md_ file as a special case.
+write_file_list(
+    name = "rules_doc",
+    out = "rules.md_",
+    doc_provs = _RULE_DOC_PROVIDERS,
+    header_content = [
+        "# Rules",
+        "",
+        "The rules listed below are available in this repository.",
+        "",
+    ],
+)
+
+# MARK: - Generate Documentation from Providers
+
+doc_for_provs(doc_provs = _ALL_DOC_PROVIDERS)

doc/README.md

@@ -0,0 +1,4 @@
+# Documentation for Starlib
+
+- [API](/doc/api.md)
+- [Rules](/doc/rules.md)

doc/api.md

@@ -0,0 +1,7 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
+# Build API
+
+The APIs listed below are available in this repository.
+
+  * [src_utils](/doc/src_utils.md)
+

doc/filter_srcs.md

@@ -0,0 +1,25 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
+# `filter_srcs` Rule
+
+
+<a id="#filter_srcs"></a>
+
+## filter_srcs
+
+<pre>
+filter_srcs(<a href="#filter_srcs-name">name</a>, <a href="#filter_srcs-expected_count">expected_count</a>, <a href="#filter_srcs-filename_ends_with">filename_ends_with</a>, <a href="#filter_srcs-srcs">srcs</a>)
+</pre>
+
+Filters the provided inputs using the specified criteria.
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="filter_srcs-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
+| <a id="filter_srcs-expected_count"></a>expected_count |  The expected number of results.   | Integer | optional | -1 |
+| <a id="filter_srcs-filename_ends_with"></a>filename_ends_with |  The suffix of the path will be compared to this value.   | String | optional | "" |
+| <a id="filter_srcs-srcs"></a>srcs |  The inputs that will be evaluated by the filter.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | required |  |
+
+

doc/rules.md

@@ -0,0 +1,7 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
+# Rules
+
+The rules listed below are available in this repository.
+
+  * [filter_srcs](/doc/filter_srcs.md)
+

doc/src_utils.md

@@ -0,0 +1,48 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
+# `src_utils` API
+
+
+<a id="#src_utils.is_path"></a>
+
+## src_utils.is_path
+
+<pre>
+src_utils.is_path(<a href="#src_utils.is_path-src">src</a>)
+</pre>
+
+Determines whether the provided string is a path.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="src_utils.is_path-src"></a>src |  A <code>string</code> value.   |  none |
+
+**RETURNS**
+
+A `bool` specifying whether the `string` value looks like a path.
+
+
+<a id="#src_utils.is_label"></a>
+
+## src_utils.is_label
+
+<pre>
+src_utils.is_label(<a href="#src_utils.is_label-src">src</a>)
+</pre>
+
+Determines whether the provided string is a label.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="src_utils.is_label-src"></a>src |  A <code>string</code> value.   |  none |
+
+**RETURNS**
+
+A `bool` specifying whether the `string` value looks like a label.
+
+

lib/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//visibility:public"])
+
+bzl_library(
+    name = "src_utils",
+    srcs = ["src_utils.bzl"],
+)

lib/src_utils.bzl

@@ -0,0 +1,26 @@
+def _is_label(src):
+    """Determines whether the provided string is a label.
+
+    Args:
+        src: A `string` value.
+
+    Returns:
+        A `bool` specifying whether the `string` value looks like a label.
+    """
+    return src.find("//") > -1 or src.find(":") > -1
+
+def _is_path(src):
+    """Determines whether the provided string is a path.
+
+    Args:
+        src: A `string` value.
+
+    Returns:
+        A `bool` specifying whether the `string` value looks like a path.
+    """
+    return not _is_label(src)
+
+src_utils = struct(
+    is_path = _is_path,
+    is_label = _is_label,
+)