use std::fmt;
use std::path::Path;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Command {
name: String,
args: Vec<String>,
}
impl Command {
pub fn new(name: impl Into<String>) -> Self {
let name = name.into();
let name = if name.starts_with('-') || name.is_empty() {
name
} else {
format!("-{name}")
};
Self {
name,
args: Vec::new(),
}
}
pub fn arg(mut self, arg: impl Into<String>) -> Self {
self.args.push(arg.into());
self
}
pub fn args<I, S>(mut self, args: I) -> Self
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
self.args.extend(args.into_iter().map(Into::into));
self
}
pub fn name(&self) -> &str {
&self.name
}
pub fn arguments(&self) -> &[String] {
&self.args
}
pub fn render(&self, token: u32) -> String {
let mut out = format!("{token}{}", self.name);
for arg in &self.args {
out.push(' ');
out.push_str("e(arg));
}
out
}
}
impl fmt::Display for Command {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.name)?;
for arg in &self.args {
write!(f, " {}", quote(arg))?;
}
Ok(())
}
}
pub fn quote(arg: &str) -> String {
let needs_quoting = arg.is_empty()
|| arg
.chars()
.any(|ch| ch.is_whitespace() || ch == '"' || ch == '\\' || ch.is_control());
if !needs_quoting {
return arg.to_owned();
}
let mut out = String::with_capacity(arg.len() + 2);
out.push('"');
for ch in arg.chars() {
match ch {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
other => out.push(other),
}
}
out.push('"');
out
}
pub fn file_exec_and_symbols(path: &Path) -> Command {
Command::new("-file-exec-and-symbols").arg(path.display().to_string())
}
pub fn exec_arguments<I, S>(args: I) -> Command
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
Command::new("-exec-arguments").args(args)
}
pub fn environment_cd(path: &Path) -> Command {
Command::new("-environment-cd").arg(path.display().to_string())
}
pub fn inferior_tty_set(path: &Path) -> Command {
Command::new("-inferior-tty-set").arg(path.display().to_string())
}
pub fn exec_run_to_start() -> Command {
Command::new("-exec-run").arg("--start")
}
pub fn exec_run() -> Command {
Command::new("-exec-run")
}
pub fn exec_continue() -> Command {
Command::new("-exec-continue")
}
pub fn exec_interrupt() -> Command {
Command::new("-exec-interrupt").arg("--all")
}
pub fn exec_step_instruction() -> Command {
Command::new("-exec-step-instruction")
}
pub fn exec_next_instruction() -> Command {
Command::new("-exec-next-instruction")
}
pub fn exec_step() -> Command {
Command::new("-exec-step")
}
pub fn exec_next() -> Command {
Command::new("-exec-next")
}
pub fn exec_step_instruction_reverse() -> Command {
Command::new("-exec-step-instruction").arg("--reverse")
}
pub fn exec_next_instruction_reverse() -> Command {
Command::new("-exec-next-instruction").arg("--reverse")
}
pub fn exec_step_reverse() -> Command {
Command::new("-exec-step").arg("--reverse")
}
pub fn exec_continue_reverse() -> Command {
Command::new("-exec-continue").arg("--reverse")
}
pub fn console(command: &str) -> Command {
Command::new("-interpreter-exec")
.arg("console")
.arg(command)
}
pub fn record_full() -> Command {
console("record full")
}
pub fn record_stop() -> Command {
console("record stop")
}
pub fn exec_finish() -> Command {
Command::new("-exec-finish")
}
pub fn break_insert(location: &str) -> Command {
Command::new("-break-insert").arg(location)
}
pub fn break_insert_with(location: &str, enabled: bool, condition: Option<&str>) -> Command {
let mut command = Command::new("-break-insert");
if !enabled {
command = command.arg("-d");
}
if let Some(condition) = condition {
command = command.arg("-c").arg(condition);
}
command.arg(location)
}
pub fn break_watch(expression: &str) -> Command {
Command::new("-break-watch").arg(expression)
}
pub fn break_condition(number: u32, condition: Option<&str>) -> Command {
let command = Command::new("-break-condition").arg(number.to_string());
match condition {
Some(condition) => command.arg(condition),
None => command,
}
}
pub fn break_insert_at_line(file: &str, line: usize) -> Command {
Command::new("-break-insert").arg(format!("{file}:{line}"))
}
pub fn break_insert_at_address(address: u64) -> Command {
Command::new("-break-insert").arg(format!("*0x{address:x}"))
}
pub fn break_insert_temporary(location: &str) -> Command {
Command::new("-break-insert").arg("-t").arg(location)
}
pub fn break_insert_temporary_at_address(address: u64) -> Command {
Command::new("-break-insert")
.arg("-t")
.arg(format!("*0x{address:x}"))
}
pub fn break_delete(number: u32) -> Command {
Command::new("-break-delete").arg(number.to_string())
}
pub fn break_enable(number: u32) -> Command {
Command::new("-break-enable").arg(number.to_string())
}
pub fn break_disable(number: u32) -> Command {
Command::new("-break-disable").arg(number.to_string())
}
pub fn break_list() -> Command {
Command::new("-break-list")
}
pub fn data_list_register_names() -> Command {
Command::new("-data-list-register-names")
}
pub fn data_list_register_values() -> Command {
Command::new("-data-list-register-values").arg("x")
}
pub fn data_list_changed_registers() -> Command {
Command::new("-data-list-changed-registers")
}
pub fn data_read_memory_bytes(address: u64, count: usize) -> Command {
Command::new("-data-read-memory-bytes")
.arg(format!("0x{address:x}"))
.arg(count.to_string())
}
pub fn data_write_memory_bytes(address: u64, contents: &str) -> Command {
Command::new("-data-write-memory-bytes")
.arg(format!("0x{address:x}"))
.arg(contents)
}
pub fn data_disassemble_range(start: u64, end: u64) -> Command {
Command::new("-data-disassemble")
.arg("-s")
.arg(format!("0x{start:x}"))
.arg("-e")
.arg(format!("0x{end:x}"))
.arg("--")
.arg("4")
}
pub fn data_disassemble_range_plain(start: u64, end: u64) -> Command {
Command::new("-data-disassemble")
.arg("-s")
.arg(format!("0x{start:x}"))
.arg("-e")
.arg(format!("0x{end:x}"))
.arg("--")
.arg("2")
}
pub fn data_evaluate_expression(expression: &str) -> Command {
Command::new("-data-evaluate-expression").arg(expression)
}
pub fn stack_list_frames() -> Command {
Command::new("-stack-list-frames")
}
pub fn stack_select_frame(level: u32) -> Command {
Command::new("-stack-select-frame").arg(level.to_string())
}
pub fn thread_info() -> Command {
Command::new("-thread-info")
}
pub fn gdb_exit() -> Command {
Command::new("-gdb-exit")
}
pub fn gdb_set(name: &str, value: &str) -> Command {
Command::new("-gdb-set").arg(name).arg(value)
}
pub fn set_disassembly_flavor(intel: bool) -> Command {
gdb_set("disassembly-flavor", if intel { "intel" } else { "att" })
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_command_renders_with_its_token() {
assert_eq!(Command::new("-exec-run").render(7), "7-exec-run");
}
#[test]
fn a_missing_leading_dash_is_added() {
assert_eq!(Command::new("exec-run").name(), "-exec-run");
assert_eq!(Command::new("-exec-run").name(), "-exec-run");
}
#[test]
fn plain_arguments_are_not_quoted() {
let command = Command::new("-break-insert").arg("_start");
assert_eq!(command.render(1), "1-break-insert _start");
}
#[test]
fn arguments_with_spaces_are_quoted() {
let command = Command::new("-file-exec-and-symbols").arg("/tmp/my project/main");
assert_eq!(
command.render(2),
"2-file-exec-and-symbols \"/tmp/my project/main\""
);
}
#[test]
fn quotes_and_backslashes_are_escaped() {
assert_eq!(quote(r#"a"b"#), r#""a\"b""#);
assert_eq!(quote(r"a\b"), r#""a\\b""#);
assert_eq!(quote("a\nb"), r#""a\nb""#);
assert_eq!(quote("a\tb"), r#""a\tb""#);
}
#[test]
fn an_empty_argument_is_quoted_so_it_is_not_lost() {
assert_eq!(quote(""), r#""""#);
assert_eq!(Command::new("-x").arg("").render(1), r#"1-x """#);
}
#[test]
fn a_path_that_would_break_framing_is_neutralised() {
let hostile = Path::new("/tmp/evil\" -exec-run \"/x");
let rendered = file_exec_and_symbols(hostile).render(3);
assert_eq!(
rendered,
r#"3-file-exec-and-symbols "/tmp/evil\" -exec-run \"/x""#
);
assert_eq!(rendered.matches("-exec-run").count(), 1);
}
#[test]
fn an_inferior_terminal_path_is_a_single_mi_argument() {
assert_eq!(
inferior_tty_set(Path::new("/dev/pts/12")).render(4),
"4-inferior-tty-set /dev/pts/12"
);
}
#[test]
fn breakpoint_commands_render_correctly() {
assert_eq!(break_insert("_start").render(1), "1-break-insert _start");
assert_eq!(
break_insert_at_line("main.asm", 12).render(2),
"2-break-insert main.asm:12"
);
assert_eq!(break_delete(3).render(4), "4-break-delete 3");
assert_eq!(break_enable(1).render(5), "5-break-enable 1");
assert_eq!(break_disable(1).render(6), "6-break-disable 1");
assert_eq!(break_list().render(7), "7-break-list");
}
#[test]
fn a_temporary_breakpoint_carries_the_delete_flag() {
assert_eq!(
break_insert_temporary("_start").render(1),
"1-break-insert -t _start"
);
assert_eq!(
break_insert_temporary_at_address(0x401000).render(2),
"2-break-insert -t *0x401000"
);
}
#[test]
fn an_address_breakpoint_uses_the_star_prefix() {
assert_eq!(
break_insert_at_address(0x40_00b0).render(1),
"1-break-insert *0x4000b0"
);
}
#[test]
fn a_file_with_a_space_is_quoted_in_a_line_breakpoint() {
let command = break_insert_at_line("my source.asm", 5);
assert_eq!(command.render(1), "1-break-insert \"my source.asm:5\"");
}
#[test]
fn memory_commands_use_hexadecimal_addresses() {
assert_eq!(
data_read_memory_bytes(0x7fff_ffff_e000, 64).render(1),
"1-data-read-memory-bytes 0x7fffffffe000 64"
);
}
#[test]
fn disassembly_requests_the_documented_mode() {
assert_eq!(
data_disassemble_range(0x4000, 0x4010).render(1),
"1-data-disassemble -s 0x4000 -e 0x4010 -- 4"
);
assert_eq!(
data_disassemble_range_plain(0x4000, 0x4010).render(2),
"2-data-disassemble -s 0x4000 -e 0x4010 -- 2"
);
}
#[test]
fn execution_commands_render_correctly() {
assert_eq!(exec_run_to_start().render(1), "1-exec-run --start");
assert_eq!(exec_continue().render(2), "2-exec-continue");
assert_eq!(exec_step_instruction().render(3), "3-exec-step-instruction");
assert_eq!(exec_next_instruction().render(4), "4-exec-next-instruction");
assert_eq!(exec_step().render(5), "5-exec-step");
assert_eq!(exec_next().render(6), "6-exec-next");
assert_eq!(exec_finish().render(7), "7-exec-finish");
assert_eq!(exec_interrupt().render(8), "8-exec-interrupt --all");
}
#[test]
fn reverse_execution_commands_carry_the_reverse_flag() {
assert_eq!(
exec_step_instruction_reverse().render(1),
"1-exec-step-instruction --reverse"
);
assert_eq!(
exec_next_instruction_reverse().render(2),
"2-exec-next-instruction --reverse"
);
assert_eq!(exec_step_reverse().render(3), "3-exec-step --reverse");
assert_eq!(
exec_continue_reverse().render(4),
"4-exec-continue --reverse"
);
}
#[test]
fn recording_goes_through_the_console_because_mi_has_no_command_for_it() {
assert_eq!(
record_full().render(1),
"1-interpreter-exec console \"record full\""
);
}
#[test]
fn a_console_command_with_spaces_is_quoted_as_one_argument() {
let rendered = console("set confirm off").render(1);
assert_eq!(rendered, "1-interpreter-exec console \"set confirm off\"");
}
#[test]
fn register_commands_request_hexadecimal_values() {
assert_eq!(
data_list_register_values().render(1),
"1-data-list-register-values x"
);
assert_eq!(
data_list_register_names().render(2),
"2-data-list-register-names"
);
assert_eq!(
data_list_changed_registers().render(3),
"3-data-list-changed-registers"
);
}
#[test]
fn the_disassembly_flavour_defaults_to_intel() {
assert_eq!(
set_disassembly_flavor(true).render(1),
"1-gdb-set disassembly-flavor intel"
);
assert_eq!(
set_disassembly_flavor(false).render(2),
"2-gdb-set disassembly-flavor att"
);
}
#[test]
fn program_arguments_are_quoted_individually() {
let command = exec_arguments(["--flag", "a value", "plain"]);
assert_eq!(
command.render(1),
"1-exec-arguments --flag \"a value\" plain"
);
}
#[test]
fn display_omits_the_token() {
assert_eq!(break_insert("_start").to_string(), "-break-insert _start");
}
#[test]
fn a_rendered_command_never_contains_a_newline() {
let command = Command::new("-break-insert").arg("evil\n-gdb-exit");
let rendered = command.render(1);
assert!(!rendered.contains('\n'), "rendered: {rendered}");
assert!(rendered.contains("\\n"));
}
#[test]
fn arguments_are_preserved_unquoted_for_inspection() {
let command = Command::new("-x").arg("a b").arg("c");
assert_eq!(command.arguments(), ["a b", "c"]);
}
}