-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
96 additions
and
27 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| # go-script-bash v1.2.1 | ||
| # go-script-bash v1.3.0 | ||
|
|
||
| This release enhances the public stack trace feature and adds it to `@go.log FATAL` output. | ||
| This is a massive feature update that greatly extends the capabilities of the `log` module, improves existing test helpers and adds many new ones, adds several new modules available via `_GO_USE_MODULES`, plus much more. (And it goes without saying there are tons of bug fixes and compatibility workarounds!) | ||
|
|
||
| ## The `./go` script: a unified development environment interface | ||
|
|
||
|
|
@@ -16,31 +16,97 @@ This software is made available as [Open Source software](https://opensource.org | |
|
|
||
| ## What's new in this release | ||
|
|
||
| ### Make `@go.print_stack_trace` take a numerical `skip_callers` argument | ||
| All of the issues and pull requests for this release are visible in the [v1.3.0 milestone](https://github.com/mbland/go-script-bash/milestone/1?closed=1). Many of the new features were inspired by the enthusiastic and thoughtful input from [John Omernik](https://github.com/JohnOmernik), based on his experience integrating the framework into his [JohnOmernik/zetago project](https://github.com/JohnOmernik/zetago). | ||
|
|
||
| Previously `@go.print_stack_trace` would only skip the immediate caller if the first argument was not null. Now it enforces that the number be a positive integer, in order to skip over the specified number of callers while printing the stack trace. This was done to support better `@go.log FATAL` output, described below. | ||
| ### `lib/log` updates | ||
|
|
||
| Normally an API change like this would warrant a major version bump, but since the impact should be minimal, it any potential for impact exists at all, it's included in this patch release. | ||
| `lib/log` gained a number of powerful new features in this update: | ||
|
|
||
| ### Include stack trace output on `@go.log FATAL` conditions | ||
| - Timestamp prefixes are available by defining `_GO_LOG_TIMESTAMP_FORMAT`. | ||
| - Each log level can now emit output to any arbitrary number of file descriptors by applying `@go.log_add_output_file`. | ||
| - `_GO_LOG_LEVEL_FILTER` and `_GO_LOG_CONSOLE_FILTER` help control the amount of information logged to files or to the console, respectively. | ||
| - The new lowest-priority `DEBUG` log level isn't emitted by default; use one of the above filters or `@go.log_add_output_file` to capture it. | ||
| - The new `QUIT` log level exits the process like `FATAL`, but without a stack trace. | ||
| - `@go.log_command` now captures all command output (even from subprocesses!) and emits it across all file descriptors configured for the `RUN` log level. | ||
| - `@go.critical_section_begin` now takes an argument to determine whether failing commands run under `@go.log_command` will log `QUIT` or `FATAL` upon error; the default is set by `_GO_CRITICAL_SECTION_DEFAULT`, which defaults to `FATAL` | ||
| - The new `demo-core log` builtin subcommand provides an interactive demonstration of `log` module features; see `./go help demo-core log`. | ||
| - Testing assertions and helper functions are publicly available in `lib/testing/log` and `lib/testing/stack-trace`. | ||
|
|
||
| `@go.log FATAL` now prints a stack trace before exiting the process, since such information is generally useful under `FATAL` conditions. Every function in the `log` module that calls `@go.log FATAL` removes itself from the stack trace, so the top of the stack shows the location of the user code that triggered the condition, rather than the location of the `log` module function. | ||
| See `./go modules -h log` for more information. | ||
|
|
||
| ## Changes since v1.2.0 | ||
| ### New `lib/file` module for file descriptor-based file I/O | ||
|
|
||
| <pre> | ||
| b2ad688 Mike Bland <[email protected]> | ||
| Merge pull request #28 from mbland/stack-trace | ||
| The new `lib/file` functions make it easy to open, write to, and close file descriptors in a safe and convenient fashion. While most of these functions support the new `lib/log` features, they are general-purpose and available to import via `. "$_GO_USE_MODULES" file`. See `./go modules -h file` for more information. | ||
|
|
||
| ### New `lib/validation` file to validate caller-supplied data | ||
|
|
||
| The functions from `lib/validation` help make sure that caller-supplied data and variable names are well-formed and won't execute arbitrary code. The `*_or_die` variations will exit with a stack trace if an item violates validation constraints. Useful for examining identifiers before invoking `eval` or builtins such as `printf -v` that expect an identifier name as an argument. See `./go modules -h validation` for more information. | ||
|
|
||
| ### Expanded and improved `lib/bats` module and the new `lib/testing` module for testing | ||
|
|
||
| It's now easier than ever to compose new assertions from `lib/bats/assertions`, thanks to the new `set "$BATS_ASSERTION_DISABLE_SHELL_OPTIONS"` and `return_from_bats_assertion` convention. New assertions are also easier to test thanks to the new `lib/bats/assertion-test-helpers` utilities. | ||
|
|
||
| `lib/bats/assertions` now contains: | ||
|
|
||
| - The `fail_if` assertion negator for `lib/bats/assertions` assertions, which makes it easy to write negative conditions with robust output | ||
| - The new `assert_lines_match` assertion | ||
| - `set_bats_output_and_lines_from_file`, which is used to implement the new `assert_file_equals`, `assert_file_matches`, and `assert_file_lines_match` assertions | ||
|
|
||
| Goodies now available in `lib/bats/helpers` include: | ||
|
|
||
| - `fs_missing_permission_support` and `skip_if_cannot_trigger_file_permission_failure` for skipping test cases on platforms that cannot trigger file permission-based conditions | ||
| - `test_join` for joining multiple expected output elements into a single variable | ||
| - `test_printf` and the `TEST_DEBUG` variable for producing targeted test debugging output | ||
| - `test_filter` and the `TEST_FILTER` variable for pinpointing specific test cases within a suite and skipping the rest | ||
| - `split_bats_output_into_lines` to ensure blank lines from `output` are preserved in `lines`; this facilitates using `assert_lines_equal` and `assert_lines_match` with output containing blank lines | ||
| - `stub_program_in_path` to easily write temporary test stubs for programs in `PATH` | ||
|
|
||
| Also, framework-specific test helpers have been exported to `lib/testing`, to help with writing tests that depend on core framework output and behavior, including functions that help validate stack trace and `@go.log` output. | ||
|
|
||
| All existing and new test helper functions have also been thoroughly tested on multiple platforms to ensure portability, ease-of-use, and a minimum of surprises. | ||
|
|
||
| ### `lib/format` updates | ||
|
|
||
| The `lib/format` module gained two new functions: | ||
|
|
||
| - `@go.array_printf` for transforming an entire array of items at once using `printf -v` | ||
| - `@go.strip_formatting_codes` for removing ASCII formatting codes from a string, used by `@go.log` when writing to non-console file descriptors in the absence of `_GO_LOG_FORMATTING` | ||
|
|
||
| Also, `@go.pad_items` and `@go.zip_items` have updated interfaces that expect the caller to provide the name of the output variable, now that both are defined in terms of `@go.array_printf` (which is in turn implemented using the new `@go.split`, described below.) See `./go modules -h format` for more information. | ||
|
|
||
| 965782d Mike Bland <[email protected]> | ||
| log: Add stack trace to FATAL output | ||
| ### New `lib/strings` modules | ||
|
|
||
| a0f4413 Mike Bland <[email protected]> | ||
| stack-trace: Move, add helpers to environment.bash | ||
| The `lib/strings` module provides `@go.split` and `@go.join` functions that implement behavior common to other programming language libraries. See `./go modules -h strings` for more information. | ||
|
|
||
| cd57da0 Mike Bland <[email protected]> | ||
| print-stack-trace: Add go-core stack test helper | ||
| `@go.split` in particular is highly recommend for widespread use to avoid an obscure Bash bug on Travis CI; see the function comments and `git show 99ab78 2297b4` for details. | ||
|
|
||
| 8424338 Mike Bland <[email protected]> | ||
| print_stack_trace: Make skip_callers arg numerical | ||
| ### `_GO_USE_MODULES` exported for subprocess use | ||
|
|
||
| Now any Bash process spawned by the `./go` script has access to the `_GO_USE_MODULES` mechanism, most notably Bats test cases and assertions. | ||
|
|
||
| ### New `demo-core` framework and `lib/subcommands` module | ||
|
|
||
| The `lib/subcommands` module exports the `@go.show_subcommands` function, which may be used to implement commands that are only shells for a number of subcommands. See `./go modules -h subcommands` for more information. | ||
|
|
||
| The new `demo-core` command demonstrates the use of `@go.show_subcommands`, and provides a framework for writing small demonstration programs for module features. As a first step, the `demo-core log` subcommand provides a demonstration of various `log` module features. See `./go help demo-core` and `./go help demo-core log` for more information. | ||
|
|
||
| ### `@go.printf` works independently of `fold` | ||
|
|
||
| `@go.printf` no longer opens a pipe to the `fold` program, and now folds lines itself. The performance difference was a very minor improvement or degradation across systems, and now output is folded regardless of the presence of `fold` on the host system. | ||
|
|
||
| ### Uses `[` instead of `[[` in all Bats test cases | ||
|
|
||
| Turns out there's a gotcha when using `[[` in Bats test cases under Bash versions lower than 4.1, such as the stock 3.2.57(1)-release that ships on macOS. See `git show fefce2` for details. | ||
|
|
||
| ### Uses ASCII Unit Separator (`$'\x1f'`) instead of NUL to export arrays | ||
|
|
||
| Previously, `$'\0'` was used to export the `_GO_CMD_NAME` and `_GO_CMD_ARGV` arrays to commands written in other languages. However, it wasn't possible to successfully use NUL to implement the new `@go.array_printf` in the `lib/format` module, or to pass it as a delimiter to `@go.split` from the new `lib/strings` module, since Bash can join strings using `IFS=$'\0'`, but not split them. (Setting `IFS=$'\0'` is equivalent to setting it to the null string, which disables word splitting.) Consequently, the ASCII Unit Separator character seemed a fine substitute for that purpose, and it seemed wise to apply it to `_GO_CMD_NAME` and `_GO_CMD_ARGV` as well. | ||
|
|
||
| ## Changes since v1.2.1 | ||
|
|
||
| You can see the details of every change by issuing one or more of the following commands after cloning: https://github.com/mbland/go-script-bash | ||
|
|
||
| <pre> | ||
| $ ./go changes v1.2.1 v1.3.0 | ||
| $ gitk v1.2.1..HEAD | ||
| </pre> | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters