Finish documenting UDLs and making them available

BUILD.bazel

@@ -90,7 +90,7 @@ BASE_UNIT_STRING = " ".join(BASE_UNITS)
 
 GIT_ID_CMD = "cat bazel-out/stable-status.txt | grep STABLE_GIT_ID | sed 's/STABLE_GIT_ID \\(.*\\)/\\1/' | tr -d '\\n'"
 
-CMD_ROOT = "$(location tools/bin/make-single-file) {extra_opts} {units} {all_constants} --version-id $$({id_cmd}) > $(OUTS)"
+CMD_ROOT = "$(location tools/bin/make-single-file) {extra_opts} {units} {all_literals} {all_constants} --version-id $$({id_cmd}) > $(OUTS)"
 
 ################################################################################
 # Release single-file package `au.hh`
@@ -101,6 +101,7 @@ genrule(
     outs = ["docs/au.hh"],
     cmd = CMD_ROOT.format(
         all_constants = "",
+        all_literals = "",
         extra_opts = "",
         id_cmd = GIT_ID_CMD,
         units = "--units " + BASE_UNIT_STRING,
@@ -125,6 +126,7 @@ genrule(
     outs = ["docs/au_noio.hh"],
     cmd = CMD_ROOT.format(
         all_constants = "",
+        all_literals = "",
         extra_opts = "--noio",
         id_cmd = GIT_ID_CMD,
         units = "--units " + BASE_UNIT_STRING,
@@ -149,6 +151,7 @@ genrule(
     outs = ["docs/au_all_units.hh"],
     cmd = CMD_ROOT.format(
         all_constants = "--all-constants",
+        all_literals = "--all-literals",
         extra_opts = "",
         id_cmd = GIT_ID_CMD,
         units = "--all-units",
@@ -173,6 +176,7 @@ genrule(
     outs = ["docs/au_all_units_noio.hh"],
     cmd = CMD_ROOT.format(
         all_constants = "--all-constants",
+        all_literals = "--all-literals",
         extra_opts = "--noio",
         id_cmd = GIT_ID_CMD,
         units = "--all-units",
@@ -197,6 +201,7 @@ genrule(
     outs = ["docs/au_stdformat.hh"],
     cmd = CMD_ROOT.format(
         all_constants = "",
+        all_literals = "",
         extra_opts = "--std-format",
         id_cmd = GIT_ID_CMD,
         units = "--units " + BASE_UNIT_STRING,
@@ -217,6 +222,7 @@ genrule(
     outs = ["docs/au_stdformat_noio.hh"],
     cmd = CMD_ROOT.format(
         all_constants = "",
+        all_literals = "",
         extra_opts = "--std-format --noio",
         id_cmd = GIT_ID_CMD,
         units = "--units " + BASE_UNIT_STRING,
@@ -237,6 +243,7 @@ genrule(
     outs = ["docs/au_all_units_stdformat.hh"],
     cmd = CMD_ROOT.format(
         all_constants = "--all-constants",
+        all_literals = "--all-literals",
         extra_opts = "--std-format",
         id_cmd = GIT_ID_CMD,
         units = "--all-units",
@@ -257,6 +264,7 @@ genrule(
     outs = ["docs/au_all_units_stdformat_noio.hh"],
     cmd = CMD_ROOT.format(
         all_constants = "--all-constants",
+        all_literals = "--all-literals",
         extra_opts = "--std-format --noio",
         id_cmd = GIT_ID_CMD,
         units = "--all-units",

docs/install.md

@@ -96,7 +96,7 @@ to your `deps` attribute, and include the appropriate files.
 
 | Dependency | Headers provided | Notes |
 |------------|------------------|-------|
-| `@au//au` | `"au/au.hh"`<br>`"au/fwd.hh"`<br>`"au/units/*.hh"`<br>`"au/units/*_fwd.hh"`<br>`"au/constants/*.hh"` | Core library functionality.  See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units) and [constants](./reference/constant.md#built-in) |
+| `@au//au` | `"au/au.hh"`<br>`"au/fwd.hh"`<br>`"au/units/*.hh"`<br>`"au/units/*_fwd.hh"`<br>`"au/units/literals/*.hh"`<br>`"au/constants/*.hh"` | Core library functionality.  See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units), [unit literals](./reference/constant.md#unit-literals), and [constants](./reference/constant.md#built-in) |
 | `@au//au:io` | `"au/io.hh"` | `operator<<` support |
 | `@au//au:std_format` | `"au/std_format.hh"` | `std::format` support[^1] |
 | `@au//au:testing` | `"au/testing.hh"` | Utilities for writing googletest tests<br>_Note:_ `testonly = True` |
@@ -176,7 +176,7 @@ In either case, here are the main targets and include files provided by the Au l
 
 | Target | Headers provided | Notes |
 |--------|------------------|-------|
-| `Au::au` | `"au/au.hh"`<br>`"au/fwd.hh"`<br>`"au/io.hh"`<br>`"au/std_format.hh"`[^1]<br>`"au/units/*.hh"`<br>`"au/units/*_fwd.hh"`<br>`"au/constants/*.hh"` | Core library functionality.  See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units) |
+| `Au::au` | `"au/au.hh"`<br>`"au/fwd.hh"`<br>`"au/io.hh"`<br>`"au/std_format.hh"`[^1]<br>`"au/units/*.hh"`<br>`"au/units/*_fwd.hh"`<br>`"au/units/literals/*.hh"`<br>`"au/constants/*.hh"` | Core library functionality.  See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units) and [unit literals](./reference/constant.md#unit-literals) |
 | `Au::testing` | `"au/testing.hh"` | Utilities for writing googletest tests |
 
 [^1]: Do not include `"au/std_format.hh"` unless you know that both your compiler and your build
@@ -426,6 +426,11 @@ Here's how:
     - Similarly, to see the full list of available constants, search the `.hh` files in the
       `au/constants/` folder.  For example, `speed_of_light` will include the contents of
       `"au/constants/speed_of_light.hh"`, which provides the constant `au::SPEED_OF_LIGHT`.
+    - To include [unit literals](./reference/constant.md#unit-literals), pass the `--literals` flag
+      with the units whose literals you want: for example,<br>
+      `tools/bin/make-single-file --units meters seconds --literals meters`.<br>
+      Each entry named here also pulls in the unit itself, so `--literals meters` works even if
+      `meters` isn't in the `--units` list.
     - Provide the `--noio` flag if you prefer to avoid the expense of the `<iostream>` library.
 
 Now you have a file, `~/au.hh`, which you can add to your `third_party` folder.

tools/bin/make-single-file

@@ -51,6 +51,7 @@ def main(argv=None):
         filenames=filenames(
             main_files=args.main_files,
             units=args.units,
+            literals=args.literals,
             constants=args.constants,
             include_io=args.include_io,
             include_std_format=args.std_format,
@@ -61,7 +62,7 @@ def main(argv=None):
     return 0
 
 
-def filenames(main_files, units, constants, include_io, include_std_format):
+def filenames(main_files, units, literals, constants, include_io, include_std_format):
     """Construct the list of project filenames to include.
 
     The script will be sure to include all of these, and will also include any
@@ -70,6 +71,7 @@ def filenames(main_files, units, constants, include_io, include_std_format):
     names = (
         ["au/au.hh"]
         + [f"au/units/{u}.hh" for u in units]
+        + [f"au/units/literals/{u}.hh" for u in literals]
         + [f"au/constants/{c.lower()}.hh" for c in constants]
         + main_files
     )
@@ -96,6 +98,19 @@ def parse_command_line_args(argv):
         help="Include all units (may slow compilation!)",
     )
 
+    literal_group = parser.add_mutually_exclusive_group(required=False)
+    literal_group.add_argument(
+        "--literals",
+        nargs="*",
+        default=[],
+        help="The units whose unit literals to include (implies the unit itself)",
+    )
+    literal_group.add_argument(
+        "--all-literals",
+        action="store_true",
+        help="Include all unit literals (may slow compilation!)",
+    )
+
     constant_group = parser.add_mutually_exclusive_group(required=False)
     constant_group.add_argument(
         "--constants", nargs="*", default=[], help="The constants to include"
@@ -134,7 +149,8 @@ def enumerate_units_and_constants(args):
     Massage args object so that it's "as if" user had specified all units/constants manually.
 
     This means that if `--all-units` is specified, we populate the `units` list with every existing
-    entry, and then delete `--all-units`, and similarly for `--all-constants`.
+    entry, and then delete `--all-units`, and similarly for `--all-literals` and
+    `--all-constants`.
     """
     def looks_like_header(f):
         return f.endswith(".hh") and not f.endswith("_fwd.hh")
@@ -145,6 +161,12 @@ def enumerate_units_and_constants(args):
         ]
     del args.all_units
 
+    if args.all_literals:
+        args.literals = [
+            f[:-3] for f in os.listdir("au/units/literals/") if looks_like_header(f)
+        ]
+    del args.all_literals
+
     if args.all_constants:
         args.constants = [
             f[:-3].upper()
@@ -296,6 +318,8 @@ def manifest(args):
             "List of included units:",
         ]
         + [f"  {u}" for u in sorted(args.units)]
+        + ["List of included unit literals:"]
+        + [f"  {u}" for u in sorted(args.literals)]
         + ["List of included constants:"]
         + [f"  {c}" for c in sorted(args.constants)]
     )