implement proper cli

Author: kleinesfilmroellchen

docs/src/Home.md

@@ -2,7 +2,7 @@
 
 This documentation details the Stack with Objects and Functions programming language, an experimental stack-based reverse-polish-notation functional programming language created by kleines Filmröllchen.
 
-- [Source code](https://github.com/kleinesfilmroellchen/sof-language)
+[Source code](https://github.com/kleinesfilmroellchen/sof-language)
 
 While the README is comprehensive on basic concepts and a good starting point for interested people (like you), the docs shall provide the most thorough information on SOF, including a full language description/specification and a from-scratch tutorial (no programming knowledge required).
 

sof-rs/Cargo.lock

@@ -5,6 +5,7 @@ edition = "2024"
 
 [dependencies]
 ahash = { version = "0.8", default-features = false, features = ["std"] }
+argh = { version = "0.1", default-features = false }
 env_logger = { version = "0.11", default-features = false, features = [
 	"auto-color",
 ] }

sof-rs/Cargo.toml

@@ -0,0 +1,114 @@
+use std::path::{Path, PathBuf};
+use std::str::FromStr;
+
+use argh::FromArgs;
+
+#[derive(FromArgs, Debug, Clone)]
+/// sof-rs: interpreter for the Stack with Objects and Functions Language.
+pub struct Args {
+	/// run sof-rs in interactive mode.
+	#[argh(switch, short = 'i')]
+	interactive: bool,
+
+	/// code to execute (before interactive mode or source files)
+	#[argh(option, short = 'c')]
+	command: Option<String>,
+
+	/// internal debugging options, see documentation for a full list.
+	#[argh(option, short = 'D', long = "debug-opt")]
+	pub(crate) debug_options: Vec<DebugOption>,
+
+	/// path to library
+	#[argh(option, short = 'l', default = "Path::new(\"../lib\").into()")]
+	pub(crate) library_path: PathBuf,
+
+	/// SOF source file to execute. (Root module.)
+	#[argh(positional)]
+	pub(crate) input: Option<PathBuf>,
+}
+
+impl Args {
+	/// Determines whether a REPL should be opened. The rules are:
+	/// - if --interactive, always open REPL
+	/// - otherwise, only open REPL if neither input file nor inline command was used.
+	pub fn should_open_repl(&self) -> bool {
+		self.interactive || (!self.input.is_some() && !self.command.is_some())
+	}
+
+	/// Configure the logger with the options that control logging behavior.
+	pub fn configure_env_logger(&self, builder: &mut env_logger::Builder) {
+		let mut should_apply_default = true;
+		for log_level in self.debug_options.iter().filter_map(|f| match f {
+			DebugOption::LogLevel(log_level) => Some(log_level),
+			_ => None,
+		}) {
+			log_level.configure_env_logger(builder);
+			should_apply_default = false;
+		}
+
+		if should_apply_default {
+			builder.filter_level(log::LevelFilter::Info);
+		}
+	}
+}
+
+#[derive(Clone, Debug)]
+pub enum DebugOption {
+	/// Outputs serialized version of stack after execution, which can be used as a snapshot for faster module loading
+	/// or integrating into the binary.
+	ExportSnapshot { target_filename: PathBuf },
+	/// Sets interpreter log level.
+	LogLevel(LogLevel),
+}
+
+#[derive(Clone, Copy, Debug)]
+pub enum LogLevel {
+	/// All logging, even default logging, disabled.
+	Off,
+	/// Enable debug logging in sof-rs.
+	SelfDebug,
+	/// Enable debug logging everywhere.
+	AllDebug,
+	/// Enable tracing in sof-rs (no change to external debug logging).
+	Trace,
+}
+
+impl LogLevel {
+	pub fn configure_env_logger(&self, builder: &mut env_logger::Builder) {
+		match self {
+			Self::Off => builder.filter_level(log::LevelFilter::Off),
+			Self::SelfDebug => builder.filter_module("sof", log::LevelFilter::Debug),
+			Self::AllDebug => builder.filter_level(log::LevelFilter::Debug),
+			Self::Trace => builder.filter_module("sof", log::LevelFilter::Trace),
+		};
+	}
+}
+
+impl FromStr for DebugOption {
+	type Err = String;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		let Some((option, value)) = s.split_once('=') else {
+			return Err(format!("invalid debug option {s}, should have format `key=value`"));
+		};
+		match option {
+			"export-snapshot" => Ok(Self::ExportSnapshot { target_filename: Path::new(value).to_owned() }),
+			"log" => Ok(Self::LogLevel(value.parse()?)),
+			_ => Err(format!("invalid debug option {option}")),
+		}
+	}
+}
+
+impl FromStr for LogLevel {
+	type Err = String;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		Ok(match s {
+			"off" => Self::Off,
+			"self-debug" => Self::SelfDebug,
+			"all-debug" => Self::AllDebug,
+			"trace" => Self::Trace,
+			_ => return Err(format!("invalid log configuration: {s}")),
+		})
+	}
+}

sof-rs/src/cli.rs

@@ -12,10 +12,12 @@ use miette::{NamedSource, miette};
 use rustyline::Config;
 use rustyline::error::ReadlineError;
 
+use crate::cli::{Args, DebugOption};
 use crate::runtime::StackArena;
 use crate::runtime::interpreter::{new_arena, run, run_on_arena};
 
 mod arc_iter;
+mod cli;
 mod error;
 mod identifier;
 mod lib;
@@ -77,36 +79,42 @@ fn main() -> miette::Result<()> {
 				.build(),
 		)
 	}))?;
-	env_logger::Builder::from_default_env().filter_level(log::LevelFilter::Info).init();
+	let args: Args = argh::from_env();
+
+	let mut builder = env_logger::Builder::new();
+	builder.parse_default_env();
+	args.configure_env_logger(&mut builder);
+	builder.init();
 
 	let cwd = std::env::current_dir().map_err(|err| {
 		miette! {
 			code = "IOError",
 			"could not determine current directory: {err}"
 		}
 	})?;
-	let library_path = cwd.join("../lib").canonicalize().map_err(|err| {
+	let library_path = cwd.join(&args.library_path).canonicalize().map_err(|err| {
 		miette! {
 			code = "IOError",
-			"could not determine standard library path: {err}"
+			"standard library path {} invalid: {err}", args.library_path.display()
 		}
 	})?;
 
-	if let Some(filename) = std::env::args().nth(1) {
-		let readable_filename = file_name_for(Path::new(filename.as_str()));
+	if let Some(filename) = &args.input {
+		let readable_filename = file_name_for(filename);
 		info!("sof version {} (sof-rs), main file is {readable_filename}", env!("CARGO_PKG_VERSION"),);
 		let code = std::fs::read_to_string(&readable_filename).map_err(|err| {
 			miette! {
 				code = "IOError",
 				"could not read source file {readable_filename}: {err}"
 			}
 		})?;
-		let result = sof_main(&code, Path::new(&filename), library_path);
-		match result {
-			Ok(()) => Ok(()),
-			Err(why) => Err(why.with_source_code(NamedSource::new(readable_filename, code))),
+		let result = sof_main(&code, filename, &library_path);
+		if let Err(why) = result {
+			return Err(why.with_source_code(NamedSource::new(readable_filename, code)));
 		}
-	} else {
+	}
+
+	if args.should_open_repl() {
 		let fake_filename = cwd.join(".repl-input.sof");
 
 		let mut rl =
@@ -126,15 +134,31 @@ fn main() -> miette::Result<()> {
 					}
 				},
 				Err(ReadlineError::Interrupted | ReadlineError::Eof) => {
-					break Ok(());
+					break;
 				},
 				Err(err) => {
 					println!("error: {err:#?}");
-					break Ok(());
+					break;
 				},
 			}
 		}
 	}
+
+	// Finalize.
+
+	if let Some(snapshot_filename) = args
+		.debug_options
+		.iter()
+		.filter_map(|d| match d {
+			DebugOption::ExportSnapshot { target_filename } => Some(target_filename),
+			_ => None,
+		})
+		.next()
+	{
+		info!("Output snapshot to {}", snapshot_filename.display());
+	}
+
+	Ok(())
 }
 
 fn run_code_on_arena(