blob: ec3e31d70dc44ada4adbcc86bef9d9514fd45bfe [file]
// Copyright 2026 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use bstr::{BStr, BString, ByteSlice, ByteVec};
use std::ffi::{CStr, CString, NulError};
use std::path::{Path, PathBuf};
/// Converts a `PathBuf` into a `BString` without allocating a new buffer if possible.
pub fn path_buf_to_bstring(path: PathBuf) -> Option<BString> {
Vec::from_path_buf(path).ok().map(BString::from)
}
/// Converts a `&Path` into a `BString`.
#[allow(dead_code)]
pub fn path_to_bstring(path: &Path) -> Option<BString> {
<[u8]>::from_path(path).map(BString::from)
}
/// Parse an integer of generic type `T` from a byte slice, ignoring leading and trailing ASCII
/// whitespace. Supports optional leading '+' or '-'.
///
/// **When to use**: Use [`parse_int`] when parsing arbitrary signed or unsigned integer types
/// (including negative numbers or types like `usize`/`u64`/`i32`). For validating shell
/// numerical arguments where negative values or overflows above `i32::MAX` are forbidden, use
/// [`parse_non_negative_int`].
pub fn parse_int<T: std::str::FromStr>(bytes: &[u8]) -> Option<T> {
let trimmed = bytes.trim_ascii();
if trimmed.is_empty() {
return None;
}
std::str::from_utf8(trimmed).ok()?.parse::<T>().ok()
}
/// Parse a non-negative 32-bit signed integer (in `0..=i32::MAX`) from a byte slice, ignoring
/// leading and trailing ASCII whitespace.
///
/// **When to use**: Use [`parse_non_negative_int`] when parsing and validating non-negative
/// numerical shell builtin arguments (such as for `exit`, `return`, `shift`, or `trap`).
/// Unlike [`parse_int`], this function rejects negative numbers, overflow values greater than
/// `i32::MAX`, empty inputs, or non-numeric strings.
#[allow(dead_code)]
pub fn parse_non_negative_int(bytes: &[u8]) -> Option<i32> {
let trimmed = bytes.trim_ascii();
if trimmed.is_empty() {
return None;
}
let str_val = std::str::from_utf8(trimmed).ok()?;
let val = str_val.parse::<i64>().ok()?;
if (0..=i32::MAX as i64).contains(&val) { Some(val as i32) } else { None }
}
/// Parse a file mode mask (in octal or symbolic format) from a byte slice.
/// `current_umask` is used as the baseline when evaluating symbolic mode modifications (+, -, =).
/// Returns `Some(new_umask)` if the mode string is valid, or `None` if invalid.
pub fn parse_mode_mask(bytes: &[u8], current_umask: u32) -> Option<u32> {
let trimmed = bytes.trim_ascii();
if trimmed.is_empty() {
return None;
}
if trimmed[0].is_ascii_digit() {
let mut new_mask: u32 = 0;
for &b in trimmed {
if !(b'0'..=b'7').contains(&b) {
return None;
}
new_mask = (new_mask << 3) + u32::from(b - b'0');
}
if new_mask > 0o777 {
return None;
}
return Some(new_mask);
}
let mask = 0o777 & !current_umask;
let mut new_mask = mask;
let mut idx = 0;
let mut positions = 0u32;
while idx < trimmed.len() {
while idx < trimmed.len() && matches!(trimmed[idx], b'a' | b'u' | b'g' | b'o') {
match trimmed[idx] {
b'a' => positions |= 0o111,
b'u' => positions |= 0o100,
b'g' => positions |= 0o010,
b'o' => positions |= 0o001,
_ => {}
}
idx += 1;
}
let pos = if positions == 0 { 0o111 } else { positions };
if idx >= trimmed.len() {
break;
}
let op = trimmed[idx];
if op != b'=' && op != b'+' && op != b'-' {
break;
}
idx += 1;
let mut new_val = 0u32;
while idx < trimmed.len()
&& matches!(trimmed[idx], b'r' | b'w' | b'x' | b'u' | b'g' | b'o' | b'X' | b's')
{
match trimmed[idx] {
b'r' => new_val |= 0o4,
b'w' => new_val |= 0o2,
b'x' => new_val |= 0o1,
b'u' => new_val |= (mask >> 6) & 7,
b'g' => new_val |= (mask >> 3) & 7,
b'o' => new_val |= mask & 7,
b'X' => {
if (mask & 0o111) != 0 {
new_val |= 0o1;
}
}
b's' => {}
_ => {}
}
idx += 1;
}
new_val = (new_val & 0o7) * pos;
match op {
b'-' => new_mask &= !new_val,
b'=' => new_mask = new_val | (new_mask & !(pos * 0o7)),
b'+' => new_mask |= new_val,
_ => unreachable!(),
}
if idx < trimmed.len() {
if trimmed[idx] == b',' {
positions = 0;
idx += 1;
} else if !matches!(trimmed[idx], b'=' | b'+' | b'-') {
break;
}
}
}
if idx != trimmed.len() {
return None;
}
Some(0o777 & !new_mask)
}
/// Converts a byte slice (e.g., `&BStr` or `&BString`) into a `CString` for FFI calls.
pub fn bstr_to_cstring(s: &[u8]) -> Result<CString, NulError> {
CString::new(s)
}
/// Converts a slice of `BString`s into a vector of `CString`s for FFI calls.
pub fn bstrings_to_cstrings(strings: &[BString]) -> Result<Vec<CString>, NulError> {
strings.iter().map(|s| bstr_to_cstring(s.as_slice())).collect()
}
/// Converts a slice of `CString`s into a vector of `&CStr` references for FFI calls.
pub fn cstrings_to_c_strs(cstrings: &[CString]) -> Vec<&CStr> {
cstrings.iter().map(|s| s.as_c_str()).collect()
}
/// Returns `true` if `name` is a valid shell variable name (a letter or underscore
/// followed by zero or more letters, underscores, and digits).
pub fn is_valid_var_name(name: &BStr) -> bool {
let bytes = name.as_bytes();
if bytes.is_empty() {
return false;
}
let first = bytes[0];
if !(first.is_ascii_alphabetic() || first == b'_') {
return false;
}
bytes[1..].iter().all(|&b| b.is_ascii_alphanumeric() || b == b'_')
}
/// Splits a byte slice around the first `=` character into `(key, value)`.
/// Returns `Some((&BStr, &BStr))` if `=` is present, or `None` if there is no `=`.
pub fn split_key_value(bytes: &[u8]) -> Option<(&BStr, &BStr)> {
bytes.find_byte(b'=').map(|idx| (BStr::new(&bytes[..idx]), BStr::new(&bytes[idx + 1..])))
}
/// Formats a byte string into a single-quoted string suitable for shell input,
/// matching dash's `single_quote` function semantics.
pub fn single_quote(s: &BStr) -> BString {
let mut result = Vec::new();
let bytes = s.as_bytes();
let mut s_slice = bytes;
loop {
let len = s_slice.iter().position(|&b| b == b'\'').unwrap_or(s_slice.len());
result.push(b'\'');
result.extend_from_slice(&s_slice[..len]);
result.push(b'\'');
s_slice = &s_slice[len..];
let quote_len = s_slice.iter().take_while(|&&b| b == b'\'').count();
if quote_len == 0 {
break;
}
result.push(b'"');
result.extend_from_slice(&s_slice[..quote_len]);
result.push(b'"');
s_slice = &s_slice[quote_len..];
if s_slice.is_empty() {
break;
}
}
BString::from(result)
}
/// Represents a byte in an input line read by `read`, tracking whether it was escaped by a
/// backslash.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct LineChar {
pub byte: u8,
pub escaped: bool,
}
impl LineChar {
#[cfg(test)]
pub fn unescaped(byte: u8) -> Self {
Self { byte, escaped: false }
}
}
/// Splits input `LineChar`s according to IFS rules for the shell `read` command into
/// `num_vars` fields.
pub fn split_ifs_read(input: &[LineChar], ifs: &BStr, num_vars: usize) -> Vec<BString> {
if num_vars == 0 {
return Vec::new();
}
let is_ifs_whitespace = |ch: &LineChar| {
!ch.escaped
&& (ch.byte == b' ' || ch.byte == b'\t' || ch.byte == b'\n')
&& ifs.as_bytes().contains(&ch.byte)
};
let is_ifs_non_whitespace =
|ch: &LineChar| !ch.escaped && !is_ifs_whitespace(ch) && ifs.as_bytes().contains(&ch.byte);
let mut fields = Vec::new();
let mut start = 0;
// Skip leading IFS whitespace
while start < input.len() && is_ifs_whitespace(&input[start]) {
start += 1;
}
for _ in 0..num_vars - 1 {
if start >= input.len() {
break;
}
let mut i = start;
let mut delim_start = None;
let mut delim_end = None;
while i < input.len() {
let ch = &input[i];
if is_ifs_whitespace(ch) {
if delim_start.is_none() {
delim_start = Some(i);
}
i += 1;
while i < input.len() && is_ifs_whitespace(&input[i]) {
i += 1;
}
if i < input.len() && is_ifs_non_whitespace(&input[i]) {
i += 1;
while i < input.len() && is_ifs_whitespace(&input[i]) {
i += 1;
}
}
delim_end = Some(i);
break;
} else if is_ifs_non_whitespace(ch) {
delim_start = Some(i);
i += 1;
while i < input.len() && is_ifs_whitespace(&input[i]) {
i += 1;
}
delim_end = Some(i);
break;
} else {
i += 1;
}
}
if let (Some(ds), Some(de)) = (delim_start, delim_end) {
let field_bytes: Vec<u8> = input[start..ds].iter().map(|c| c.byte).collect();
fields.push(BString::from(field_bytes));
start = de;
} else {
let field_bytes: Vec<u8> = input[start..].iter().map(|c| c.byte).collect();
fields.push(BString::from(field_bytes));
start = input.len();
}
}
if start < input.len() {
let mut end = input.len();
while end > start && is_ifs_whitespace(&input[end - 1]) {
end -= 1;
}
let last_slice = &input[start..end];
let ifs_non_whitespace_count =
last_slice.iter().filter(|c| is_ifs_non_whitespace(c)).count();
let mut last_bytes: Vec<u8> = last_slice.iter().map(|c| c.byte).collect();
if ifs_non_whitespace_count == 1
&& last_slice.last().map_or(false, |c| is_ifs_non_whitespace(c))
{
last_bytes.pop();
}
fields.push(BString::from(last_bytes));
}
while fields.len() < num_vars {
fields.push(BString::default());
}
fields
}
/// Splits input bytes according to IFS rules for the shell `read` command into `num_vars` fields.
#[cfg(test)]
pub fn split_ifs_read_bytes(input: &[u8], ifs: &BStr, num_vars: usize) -> Vec<BString> {
let line_chars: Vec<LineChar> = input.iter().map(|&b| LineChar::unescaped(b)).collect();
split_ifs_read(&line_chars, ifs, num_vars)
}
/// Returns the byte value for a standard escape character if valid.
pub fn parse_standard_escape(c: u8) -> Option<u8> {
match c {
b'a' => Some(b'\x07'),
b'b' => Some(b'\x08'),
b'f' => Some(b'\x0c'),
b'n' => Some(b'\n'),
b'r' => Some(b'\r'),
b't' => Some(b'\t'),
b'v' => Some(b'\x0b'),
b'\\' => Some(b'\\'),
_ => None,
}
}
/// Parses up to `max_digits` octal digits (`0`..=`7`) from `slice` and returns `(val, num_digits)`.
pub fn parse_octal_digits(slice: &[u8], max_digits: usize) -> (u8, usize) {
let mut val: u16 = 0;
let mut count = 0;
while count < max_digits && count < slice.len() && (b'0'..=b'7').contains(&slice[count]) {
val = (val << 3) + (slice[count] - b'0') as u16;
count += 1;
}
(val as u8, count)
}
/// Processes escape sequences in `arg` (e.g. for `echo -e` and `printf %b`).
/// Returns the processed bytes and a boolean indicating whether execution should halt (`\c`).
pub fn process_escape_bytes(arg: &[u8]) -> (Vec<u8>, bool) {
let mut out = Vec::with_capacity(arg.len());
let mut i = 0;
while i < arg.len() {
if arg[i] == b'\\' {
if i + 1 < arg.len() {
let next = arg[i + 1];
if next == b'c' {
return (out, true);
} else if let Some(b) = parse_standard_escape(next) {
out.push(b);
i += 2;
} else if next == b'0' && i + 2 < arg.len() && (b'0'..=b'7').contains(&arg[i + 2]) {
let (val, count) = parse_octal_digits(&arg[i + 2..], 3);
out.push(val);
i += 2 + count;
} else if (b'0'..=b'7').contains(&next) {
let (val, count) = parse_octal_digits(&arg[i + 1..], 3);
out.push(val);
i += 1 + count;
} else {
out.push(b'\\');
i += 1;
}
} else {
out.push(b'\\');
i += 1;
}
} else {
out.push(arg[i]);
i += 1;
}
}
(out, false)
}