Unique Return Code System

The Unique Return Code (URC) system introduces a symbolic approach for handling function and script return codes in shell-based environments. Instead of relying on raw numeric exit codes, each return condition is represented by a descriptive symbolic identifier.

This approach improves testability, traceability, and debugging efficiency, especially in larger shell-based toolchains and automated test environments.

---

Concept Overview

Each non-success return path in a function is assigned a unique symbolic return code. These symbols follow a strict naming convention:

RC_<descriptiveName>_<nr>

Example:

RC_mainMissingOptionParameter_1
RC_mainUnknownOption_1

The symbolic identifier represents the logical error condition, while the numeric suffix reflects the local error context within a function.

Symbolic identifiers remain stable across all execution modes. Scripts may safely compare return codes against symbolic constants, independent of whether unique or production mappings are active.

rcGen operates exclusively at generation and transformation time. No runtime dependency on rcGen exists once a tool has been patched.

---

Three-Layer Model

The URC system separates return code handling into three layers:

;Symbolic Layer (Source Code) : Human-readable identifiers used in scripts and tests

;Test-Time Layer (unique.sh) : Each symbol is mapped to a unique numeric value for precise failure tracing

;Production Layer (error.sh) : Each symbol is mapped to compact POSIX-compatible exit codes (0–255)

This separation allows deterministic test behavior while preserving shell compatibility constraints.

---

Key Idea

Instead of asserting numeric return values such as:

if [ "$rc" -eq 2 ]; then ...

test cases can use symbolic assertions:

if [ "$rc" = "RC_mainUnknownOption_1" ]; then ...

During testing, these symbolic codes are mapped to unique numeric identifiers to allow precise failure localization.

In production builds, the same symbols are replaced with compact numeric exit codes compatible with standard shell constraints.

---

Generation Model

The URC system is driven by a generator that scans source code for symbolic return definitions and produces:

• a test-time definition file (*-unique.sh)
• a production-time definition file (*-error.sh)
• a lookup table for diagnostic cross-reference

The generator is invoked during build or packaging:

rcGen gen <pathToTool>
rcGen patch <pathToTool>
rcGen unpatch <pathToTool>

---

Runtime Usage

Scripts include the generated definition file during development and testing:

readonly TN=${BASH_SOURCE[0]##*/}
readonly TD=$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")

source "${TD}/${TN}-unique.sh"

This ensures that symbolic return codes are available at runtime while preserving portability and deterministic behavior across execution contexts.

---

Execution Context Awareness

The path resolution mechanism ensures correct behavior even when scripts are executed via symbolic links or included as part of larger script suites:

readonly TN=${BASH_SOURCE[0]##*/}
readonly TD=$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")

---

Patch Mode

During patching, the generator replaces the source reference to the external -unique.sh file with an embedded block containing the -error.sh definitions.

This ensures the tool can operate in a standalone production state without external dependencies.

---

Design Rationale

Shell environments restrict process exit codes to the range 0–255. This limitation is addressed by separating:

• symbolic return semantics (URC Layer)
• numeric execution return codes (shell layer)
• test-time diagnotic mapping (unique layer)

This separation enables scalable test design while maintaining compatibility with standard POSIX shell semantics.

---

Summary

The Unique Return Code system provides:

• descriptive and test-friendly return values
• deterministic mapping between symbolic and numeric codes
• improved debugging through precise failure identification
• compatibility with standard shell execution constraints
• stable symbolic return-code semantics across development, testing, and production modes
• a build-time transformation model without runtime dependency on rcGen

It is designed as a foundational layer for structured and scalable shell-based test automation frameworks.