Skip to content

feat(api): implement stream-conditional colour API and runtime policy - #3

Open
synesissoftware wants to merge 2 commits into
devfrom
api
Open

feat(api): implement stream-conditional colour API and runtime policy#3
synesissoftware wants to merge 2 commits into
devfrom
api

Conversation

@synesissoftware

@synesissoftware synesissoftware commented Sep 6, 2026

Copy link
Copy Markdown
Owner

Introduce a compiled runtime library component to complement the existing header-only SGR macros. The object-like colour macros remain unbound and require no linking; the compiled component adds stream-conditional colour sequences, environmental policy parsing, Windows console virtual-terminal gating, and runtime ABI version inspection.

Key changes:

  • add runtime version functions woad_version() and woad_version_string() in src/api.c to provide an ABI probe;
  • implement stream-conditional colour selection and stream inspection for FILE*, file descriptor, and Windows console handles;
  • provide function-like conditional macros (WOAD_SEQ_FOR, WOAD_FG_FOR, WOAD_RESET_FOR, and colour-named variants) with type dispatch via _Generic in C11+ and overloading in C++;
  • evaluate environmental colour policy honouring WOAD_COLOUR / WOAD_COLOR, NO_COLOR, CLICOLOR_FORCE, CLICOLOR, and TERM=dumb;
  • support WOAD_SET_CONSOLE_MODE to withhold console modification while falling back to querying existing virtual-terminal capability;
  • gate Windows virtual-terminal processing via RtlGetVersion() and SetConsoleMode(), elected once per module/process via atomic CAS;
  • transition woad to a compiled library target in CMakeLists.txt and update woad.pc.in, while retaining unbound header-only SGR macros;
  • add section-3 manual page template man/woad.3.in, example colour_for.c, and unit tests in test.unit.gating.c and test.unit.version.c;
  • support --build-shared-libs in prepare_cmake.sh and unify options passed across MinGW and default CMake invocations;
  • smoke-test colour policy and precedence in CI across all matrix cells, and advance version to 0.0.1-beta1;

Introduce a compiled runtime library component to complement the existing
header-only SGR macros. The object-like colour macros remain unbound and
require no linking; the compiled component adds stream-conditional colour
sequences, environmental policy parsing, Windows console virtual-terminal
gating, and runtime ABI version inspection.

Key changes:
- add runtime version functions woad_version() and woad_version_string() in
  src/api.c to provide an ABI probe;
- implement stream-conditional colour selection and stream inspection for
  FILE*, file descriptor, and Windows console handles;
- provide function-like conditional macros (WOAD_SEQ_FOR, WOAD_FG_FOR,
  WOAD_RESET_FOR, and colour-named variants) with type dispatch via
  _Generic in C11+ and overloading in C++;
- evaluate environmental colour policy honouring WOAD_COLOUR / WOAD_COLOR,
  NO_COLOR, CLICOLOR_FORCE, CLICOLOR, and TERM=dumb;
- support WOAD_SET_CONSOLE_MODE to withhold console modification while
  falling back to querying existing virtual-terminal capability;
- gate Windows virtual-terminal processing via RtlGetVersion() and
  SetConsoleMode(), elected once per module/process via atomic CAS;
- transition woad to a compiled library target in CMakeLists.txt and update
  woad.pc.in, while retaining unbound header-only SGR macros;
- add section-3 manual page template man/woad.3.in, example colour_for.c,
  and unit tests in test.unit.gating.c and test.unit.version.c;
- support --build-shared-libs in prepare_cmake.sh and unify options passed
  across MinGW and default CMake invocations;
- smoke-test colour policy and precedence in CI across all matrix cells,
  and advance version to 0.0.1-beta1;
@synesissoftware synesissoftware self-assigned this Sep 6, 2026
@synesissoftware
synesissoftware changed the base branch from master to dev September 6, 2026 02:34
@mwsis
mwsis requested a review from GarthJL1965 September 7, 2026 01:12
@synesissoftware synesissoftware added the enhancement New feature or request label Sep 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants