@struktoai/mirage-core/dist/shell/bytes.d.ts

A Unified Virtual Filesystem For AI Agents

/**
 * Stand in for one raw output byte inside a text string.
 *
 * `\xHH` and `\NNN` name a byte, not a code point: bash writes `\xff` as
 * the single byte 0xFF, which is not valid UTF-8 on its own and so has no
 * character to stand for it. A byte above ASCII is therefore carried as
 * its surrogate escape, the same convention Python's own filesystem paths
 * use, and `encodeText` turns it back into that byte.
 *
 * Three octal digits reach past one byte (`\400` is 256, `\777` is 511)
 * and bash writes the low byte of those, so the value is masked rather
 * than refused.
 */
export declare function byteChar(value: number): string;
/**
 * Encode shell text for output, byte escapes included.
 *
 * Every place the shell turns its own text into bytes goes through here,
 * because a string that reached it from `byteChar` holds a lone surrogate
 * that `TextEncoder` would write as U+FFFD.
 */
export declare function encodeText(text: string): Uint8Array;
/**
 * Read bytes back as shell text, the inverse of `encodeText`.
 *
 * Valid UTF-8 comes back as its characters and every other byte as its
 * surrogate escape, the stand-in `byteChar` makes, so the text round-trips
 * to exactly the bytes it was read from. `TextDecoder`'s replacement cannot:
 * one invalid byte becomes U+FFFD, three bytes wide, and every byte offset
 * counted back past it runs ahead of GNU's.
 */
export declare function decodeText(raw: Uint8Array): string;
/**
 * Text whose raw bytes read as the characters they spell together.
 *
 * A word joined from pieces can hold byte stand-ins that only spell a
 * character side by side: `$'\xc3'$'\xa9'` is the two bytes of `é`, each
 * escaped alone. bash holds the word as bytes, so it is `é`, the same word
 * `$'\xc3\xa9'` gives, to compare, measure and name a file by. Mirrors
 * Python's `join_bytes`.
 */
export declare function joinBytes(text: string): string;
/**
 * Whether the environment names a UTF-8 locale, as setlocale reads it.
 *
 * POSIX takes the character type from the first of `LC_ALL`, `LC_CTYPE` and
 * `LANG` that is set and not empty, so `LC_ALL=C` outranks `LANG=C.UTF-8`. A
 * name is `language[_territory][.codeset][@modifier]`, and glibc compares the
 * codeset with case and punctuation dropped, so `C.UTF-8`, `en_US.utf8` and
 * `de_DE.UTF-8@euro` all name UTF-8. Every UTF-8 name counts as installed,
 * where glibc falls back to the C locale for one it lacks. Mirrors Python's
 * `utf8_locale`.
 */
export declare function utf8Locale(env: Readonly<Record<string, string>> | undefined): boolean;
/**
 * The same bytes as a string of one character per byte.
 *
 * A command that runs in GNU's C locale (grep, sed, awk, tr, expr) counts,
 * matches and indexes bytes, not characters: `.` matches one byte, `length`
 * counts bytes, and a match may end inside a character. All of that follows
 * from running on this representation and converting only at the command's
 * edges, where a typed `é`, its `$'\xc3\xa9'` spelling and the file's own
 * bytes all arrive as the same two characters. Mirrors Python's `byte_view`.
 *
 * Under a UTF-8 locale (`utf8`) grep, sed and expr count, match and index
 * characters instead, so the view is the text itself: a byte that is no part
 * of a character stays its surrogate escape, one element of its own, as it
 * does in glibc's matcher.
 */
export declare function byteView(value: string | Uint8Array, utf8?: boolean): string;
/**
 * The bytes a byte view stands for, the inverse of `byteView`. An invalid
 * sequence or half a character comes back as itself, which is what GNU
 * writes. Under `utf8` the view is the text itself.
 */
export declare function fromByteView(view: string, utf8?: boolean): Uint8Array;
/** A byte view as shell text again, for a path or a nested command line. */
export declare function textView(view: string, utf8?: boolean): string;
//# sourceMappingURL=bytes.d.ts.map