xclifn

func NewError ¶

func NewError(message string, args ...any) error

NewError creates and returns an error with a formatted message.

Arguments:

• message: The text string to be used directly or as a format base.
• args: Optional variadic parameters to populate the formatting placeholders.

Returns:

• error: A standard Go error wrapping the generated message string.

func ParseBool ¶

func ParseBool(val string) (bool, error)

ParseBool converts a raw string flag value into a native Go boolean.

Arguments:

• val: The raw string representation from the terminal (e.g., "true", "false").

Returns:

• bool: The parsed boolean value state.
• error: Returns an xerrors.IErrorCLI if the conversion fails.

Error & Panic Natures:

• Complex Errors: Returns an error if the string is not a valid boolean expression.

func ParseDate ¶

func ParseDate(val string) (time.Time, error)

ParseDate converts a raw string flag value into a native Go time.Time object using YYYY-MM-DD layout.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• time.Time: The parsed time object anchored at midnight.
• error: Returns an xerrors.IErrorCLI if the conversion fails.

Error & Panic Natures:

• Complex Errors: Returns an error if the string layout does not strictly match 'YYYY-MM-DD'.

func ParseDateTime ¶

func ParseDateTime(val string) (time.Time, error)

ParseDateTime converts a raw string flag value into a native Go time.Time object using YYYY-MM-DD HH:MM:SS layout.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• time.Time: The fully parsed calendar and clock time object.
• error: Returns an xerrors.IErrorCLI if the conversion fails.

Error & Panic Natures:

• Complex Errors: Returns an error if the string layout does not strictly match 'YYYY-MM-DD HH:MM:SS'.

func ParseDirname ¶

func ParseDirname(val string) (string, error)

ParseDirname evaluates if a string is a syntactically valid directory name layout.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The cleaned semantic directory name layout text.
• error: Returns an xerrors.IErrorCLI if the payload is empty.

func ParseDirpath ¶

func ParseDirpath(val string) (string, error)

ParseDirpath normalizes and cleans a raw string payload for physical directory evaluation tracks.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The cleaned physical directory path layout text.
• error: Returns an xerrors.IErrorCLI if the payload is empty.

func ParseDuration ¶

func ParseDuration(val string) (time.Duration, error)

ParseDuration converts a raw string flag value into a native Go time.Duration.

Arguments:

• val: The raw string representation from the terminal (e.g., "30s", "2h45m").

Returns:

• time.Duration: The parsed duration object.
• error: Returns an xerrors.IErrorCLI if the conversion fails.

Error & Panic Natures:

• Complex Errors: Returns an error if the string format does not match Go duration syntax rules.

func ParseEmail ¶

func ParseEmail(val string) (string, error)

ParseEmail validates a raw string flag value ensuring it adheres to strict email syntax formats.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The validated and sanitized email address string.
• error: Returns an xerrors.IErrorCLI if the validation fails.

Error & Panic Natures:

• Complex Errors: Returns an error if the payload fails RFC 5322 address formatting rules.

func ParseFilename ¶

func ParseFilename(val string) (string, error)

ParseFilename evaluates if a string is a syntactically valid standalone filename.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The cleaned semantic filename string layout.
• error: Returns an xerrors.IErrorCLI if directory slashes are detected.

Error & Panic Natures:

• Complex Errors: Returns an error if the payload is empty or contains path separator bounds.

func ParseFilepath ¶

func ParseFilepath(val string) (string, error)

ParseFilepath normalizes and cleans a raw string payload for physical file evaluation tracks.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The cleaned physical file path layout text.
• error: Returns an xerrors.IErrorCLI if the payload is empty.

func ParseFloat ¶

func ParseFloat(val string) (float64, error)

ParseFloat converts a raw string flag value into a native Go float64.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• float64: The parsed floating-point decimal.
• error: Returns an xerrors.IErrorCLI if the conversion fails.

Error & Panic Natures:

• Complex Errors: Returns an error if the string is not a valid decimal representation.

func ParseFullURL ¶

func ParseFullURL(val string) (string, error)

ParseFullURL validates if a raw string payload is a fully qualified URL locator domain.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The validated full URL text string layout.
• error: Returns an xerrors.IErrorCLI if the protocol scheme or host layer is absent.

func ParseInt ¶

func ParseInt(val string) (int, error)

ParseInt converts a raw string flag value into a native Go integer.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• int: The parsed integer primitive.
• error: Returns an xerrors.IErrorCLI if the conversion fails.

Error & Panic Natures:

• Complex Errors: Returns an error if the string contains non-numeric characters.

func ParseJSON ¶

func ParseJSON(val string) (string, error)

ParseJSON validates if a raw string flag value is a syntactically correct JSON payload.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The validated raw JSON text string.
• error: Returns an xerrors.IErrorCLI if the format evaluation fails.

Error & Panic Natures:

• Complex Errors: Returns an error if the string payload contains broken or unparsable JSON syntax.

func ParsePath ¶

func ParsePath(val string) (string, error)

ParsePath evaluates if a string is a grammatically valid filesystem layout component.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The cleaned and standardized semantic path layout text.
• error: Returns an xerrors.IErrorCLI if the payload is empty.

func ParseRawArgs ¶

func ParseRawArgs(rawArgs []string) (map[string]string, error)

ParseRawArgs extracts flags and their associated raw values from terminal arguments.

Arguments:

• rawArgs: A slice containing strictly the flag segments of the command line, with all command and subcommand nodes already resolved and stripped out.

Returns:

• map[string]string: A map linking the clean flag name (without dashes) to its raw string value.
• error: Returns an error if any argument violates the strict flag syntax rules.

Error & Panic Natures:

• Complex Errors: Returns an xerrors.IErrorCLI via SetMessage if a positional argument is found, if a flag name is empty, or if a short flag exceeds length boundaries.

func ParseRelativeURL ¶

func ParseRelativeURL(val string) (string, error)

ParseRelativeURL validates if a raw string payload is a strict relative target locator layout.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The validated relative URL text string layout.
• error: Returns an xerrors.IErrorCLI if a protocol scheme or host layer is present.

func ParseString ¶

func ParseString(val string) (string, error)

ParseString evaluates and cleans a raw string flag value from the terminal.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The trimmed and standardized target string.
• error: Returns nil as text translation natively always succeeds.

func ParseTime ¶

func ParseTime(val string) (time.Time, error)

ParseTime converts a raw string flag value into a native Go time.Time object.

It flexibly accepts both full clock layout 'HH:MM:SS' and short layout 'HH:MM'. The resulting object will be anchored at the neutral Year Zero (0000-01-01).

Arguments:

• val: The raw string representation from the terminal.

Returns:

• time.Time: The parsed time object containing only clock metrics.
• error: Returns an xerrors.IErrorCLI if the conversion fails.

Error & Panic Natures:

• Complex Errors: Returns an error if the string layout does not match 'HH:MM:SS' or 'HH:MM'.

func ParseURLStandard ¶

func ParseURLStandard(val string) (string, error)

ParseURLStandard validates if a raw string payload adheres to basic URL architecture criteria.

Arguments:

• val: The raw string representation from the terminal.

Returns:

• string: The validated raw URL text string layout.
• error: Returns an xerrors.IErrorCLI if formatting rules fail evaluation.

func PrintError ¶

func PrintError(err error)

PrintError writes an error's message directly to the standard error output.

func PrintStderr ¶

func PrintStderr(message string, args ...any)

PrintStderr writes a message to the standard error output.

Arguments:

• message: The text string to be printed or used as a format base.
• args: Optional variadic parameters to populate the formatting placeholders.

Error & Panic Natures:

• Complex Errors: Silently fails to print if the underlying os.Stderr stream is closed or encounters a hardware write block.

func PrintStdout ¶

func PrintStdout(message string, args ...any)

PrintStdout writes a message to the standard output.

Arguments:

• message: The text string to be printed or used as a format base.
• args: Optional variadic parameters to populate the formatting placeholders.

Error & Panic Natures:

• Complex Errors: Silently fails to print if the underlying os.Stdout stream is closed or encounters a hardware write block.

func ValidateArrayLimits ¶

func ValidateArrayLimits(
	flag string,
	totalItems int,
	spec xclistruc.Flag,
) error

ValidateArrayLimits enforces capacity item layout boundaries on a strongly-typed slice.

Arguments:

• flag: The command line flag identifier label (e.g., "--ids", "-i").
• totalItems: The calculated length metric of the active slice matrix instance.
• spec: The complete core flag layout containing the validation metadata guidelines.

Returns:

• error: Returns an xerrors.IErrorCLI if the slice layout violates capacity boundaries.

func ValidateDiskResources ¶

func ValidateDiskResources(
	flag string,
	val string,
	spec xclistruc.Flag,
) error

ValidateDiskResources performs OS evaluation tracks ensuring system capabilities match requirements.

Arguments:

• flag: The command line flag identifier label (e.g., "--src", "-s").
• val: The cleaned physical path target string wrapped in a generic interface.
• spec: The complete core flag layout containing the validation metadata guidelines.

Returns:

• error: Returns an xerrors.IErrorCLI if any filesystem constraint or capability check fails.

Error & Panic Natures:

• Complex Errors: Performs physical disk lookups evaluating spec.MustExist boundaries. Inferes dynamically if the target must be a directory or a file matching the underlying spec.Type metadata configuration. Triggers a formatted error block indicating read or write access permission violations by testing low-level OS capabilities.

func ValidateNumberLimits ¶

func ValidateNumberLimits[T xcliintfc.Quantifiable](
	flag string,
	val T,
	spec xclistruc.Flag,
) error

ValidateNumberLimits verifies if a quantifiable value resides between inclusive mathematical bounds.

Arguments:

• flag: The command line flag identifier label (e.g., "--count", "-c").
• val: The native converted quantifiable primitive instance to evaluate (int, float64, time.Duration, time.Time).
• spec: The complete core flag layout containing the validation metadata guidelines.

Returns:

• error: Returns an xerrors.IErrorCLI if any mathematical boundary evaluation fails.

func ValidateStringLimits ¶

func ValidateStringLimits(
	flag string,
	val string,
	spec xclistruc.Flag,
) error

ValidateStringLimits enforces length boundaries and regular expression pattern matching on a text value.

Arguments:

• flag: The command line flag identifier label (e.g., "--name", "-n").
• val: The already parsed and cleaned target string wrapped in a generic interface.
• spec: The complete core flag layout containing the validation metadata guidelines.

Returns:

• error: Returns an xerrors.IErrorCLI if any constraint condition is violated.

Error & Panic Natures:

• Complex Errors: Extracts and evaluates MinLength and MaxLength tracking unicode character counts via rune evaluation bounds. Evaluates custom regex patterns triggering a formatted terminal layout error if the expression evaluation fails.