You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This release enhances the public stack trace feature and adds it to `@go.log FATAL` output.
3
+
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!)
4
4
5
5
## The `./go` script: a unified development environment interface
6
6
@@ -16,31 +16,97 @@ This software is made available as [Open Source software](https://opensource.org
16
16
17
17
## What's new in this release
18
18
19
-
### Make `@go.print_stack_trace` take a numerical `skip_callers` argument
19
+
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).
20
20
21
-
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.
21
+
### `lib/log` updates
22
22
23
-
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.
23
+
`lib/log` gained a number of powerful new features in this update:
24
24
25
-
### Include stack trace output on `@go.log FATAL` conditions
25
+
- Timestamp prefixes are available by defining `_GO_LOG_TIMESTAMP_FORMAT`.
26
+
- Each log level can now emit output to any arbitrary number of file descriptors by applying `@go.log_add_output_file`.
27
+
-`_GO_LOG_LEVEL_FILTER` and `_GO_LOG_CONSOLE_FILTER` help control the amount of information logged to files or to the console, respectively.
28
+
- 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.
29
+
- The new `QUIT` log level exits the process like `FATAL`, but without a stack trace.
30
+
-`@go.log_command` now captures all command output (even from subprocesses!) and emits it across all file descriptors configured for the `RUN` log level.
31
+
-`@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`
32
+
- The new `demo-core log` builtin subcommand provides an interactive demonstration of `log` module features; see `./go help demo-core log`.
33
+
- Testing assertions and helper functions are publicly available in `lib/testing/log` and `lib/testing/stack-trace`.
26
34
27
-
`@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.
35
+
See `./go modules -h log`for more information.
28
36
29
-
##Changes since v1.2.0
37
+
### New `lib/file` module for file descriptor-based file I/O
30
38
31
-
<pre>
32
-
b2ad688 Mike Bland <mbland@acm.org>
33
-
Merge pull request #28 from mbland/stack-trace
39
+
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.
40
+
41
+
### New `lib/validation` file to validate caller-supplied data
42
+
43
+
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.
44
+
45
+
### Expanded and improved `lib/bats` module and the new `lib/testing` module for testing
46
+
47
+
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.
48
+
49
+
`lib/bats/assertions` now contains:
50
+
51
+
- The `fail_if` assertion negator for `lib/bats/assertions` assertions, which makes it easy to write negative conditions with robust output
52
+
- The new `assert_lines_match` assertion
53
+
-`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
54
+
55
+
Goodies now available in `lib/bats/helpers` include:
56
+
57
+
-`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
58
+
-`test_join` for joining multiple expected output elements into a single variable
59
+
-`test_printf` and the `TEST_DEBUG` variable for producing targeted test debugging output
60
+
-`test_filter` and the `TEST_FILTER` variable for pinpointing specific test cases within a suite and skipping the rest
61
+
-`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
62
+
-`stub_program_in_path` to easily write temporary test stubs for programs in `PATH`
63
+
64
+
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.
65
+
66
+
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.
67
+
68
+
### `lib/format` updates
69
+
70
+
The `lib/format` module gained two new functions:
71
+
72
+
-`@go.array_printf` for transforming an entire array of items at once using `printf -v`
73
+
-`@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`
74
+
75
+
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.
34
76
35
-
965782d Mike Bland <mbland@acm.org>
36
-
log: Add stack trace to FATAL output
77
+
### New `lib/strings` modules
37
78
38
-
a0f4413 Mike Bland <mbland@acm.org>
39
-
stack-trace: Move, add helpers to environment.bash
79
+
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.
40
80
41
-
cd57da0 Mike Bland <mbland@acm.org>
42
-
print-stack-trace: Add go-core stack test helper
81
+
`@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.
43
82
44
-
8424338 Mike Bland <mbland@acm.org>
45
-
print_stack_trace: Make skip_callers arg numerical
83
+
### `_GO_USE_MODULES` exported for subprocess use
84
+
85
+
Now any Bash process spawned by the `./go` script has access to the `_GO_USE_MODULES` mechanism, most notably Bats test cases and assertions.
86
+
87
+
### New `demo-core` framework and `lib/subcommands` module
88
+
89
+
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.
90
+
91
+
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.
92
+
93
+
### `@go.printf` works independently of `fold`
94
+
95
+
`@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.
96
+
97
+
### Uses `[` instead of `[[` in all Bats test cases
98
+
99
+
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.
100
+
101
+
### Uses ASCII Unit Separator (`$'\x1f'`) instead of NUL to export arrays
102
+
103
+
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.
104
+
105
+
## Changes since v1.2.1
106
+
107
+
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
0 commit comments