Merge pull request #20 from ejrgilbert/task/add_man_pages

Task/add man pages

.gitignore

@@ -20,5 +20,8 @@ Cargo.lock
 tests/apps/*.wat
 output/
 
+# Ignore the wasm playground files
+wasm_playground/*.wasm
+
 # Ignore mac files
 .DS_Store

Cargo.toml

@@ -7,12 +7,13 @@ edition = "2021"
 doc = false
 name = "whamm"
 path = "src/main.rs"
-required-features = ["exe"]
+#required-features = ["exe"]
 
 [dependencies]
 failure = "0.1.5"
 glob = "0.3.1"
 lazy_static = "1.4.0"
+convert_case = "0.6.0"
 regex = "1.10.4"
 walrus = "0.20.3"
 
@@ -30,11 +31,12 @@ graphviz-rust = "0.9.0"
 project-root = "0.2.2"
 opener = { version = "0.7.0", default-features = false }
 
-[dependencies.clap]
-optional = true
-version = "3.2.23"
-features = ["derive"]
+# CLI
+clap = { version = "4.5.4", features = ["derive", "cargo", "env"] }
+clap_complete = "4.5.2"
 
-[features]
-default = ["exe"]
-exe = ["clap"]
+[build-dependencies]
+clap = { version = "4.5.4", features = ["derive", "cargo", "env"] }
+clap_complete = "4.5.2"
+clap_mangen = "0.2.20"
+project-root = "0.2.2"

build.rs

@@ -0,0 +1,57 @@
+use std::fs::File;
+use std::io::Error;
+use std::path::{Path, PathBuf};
+use std::process::exit;
+use clap::CommandFactory;
+use clap_mangen::Man;
+use project_root::get_project_root;
+
+include!("src/cli.rs");
+
+fn build_man(out_dir: &Path) -> Result<(), Error> {
+    let app = WhammCli::command();
+
+    let file = Path::new(&out_dir).join("example.1");
+    let mut file = File::create(&file)?;
+
+    Man::new(app).render(&mut file)?;
+
+    Ok(())
+}
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    println!("cargo:rerun-if-changed=src/cli.rs");
+    println!("cargo:rerun-if-changed=man");
+
+    // Create `target/assets/` folder.
+    let mut path = match get_pb(&PathBuf::from("target")) {
+        Ok(pb) => {
+            pb
+        }
+        Err(_) => {
+            exit(1)
+        }
+    };
+    path.push("assets");
+    std::fs::create_dir_all(&path).unwrap();
+
+    // build_shell_completion(&path)?;
+    build_man(&path)?;
+
+    Ok(())
+}
+
+fn get_pb(file_pb: &PathBuf) -> Result<PathBuf, String> {
+    if file_pb.is_relative() {
+        match get_project_root() {
+            Ok(r) => {
+                let mut full_path = r.clone();
+                full_path.push(file_pb);
+                Ok(full_path)
+            }
+            Err(e) => Err(format!("the root folder does not exist: {:?}", e)),
+        }
+    } else {
+        Ok(file_pb.clone())
+    }
+}

src/behavior/builder_visitor.rs

@@ -9,7 +9,7 @@ use regex::Regex;
 use crate::behavior::tree::ParamActionType;
 use crate::behavior::tree::DecoratorType::{HasAltCall, PredIs};
 use crate::common::error::ErrorGen;
-use crate::parser::types::Global;
+use crate::parser::types::{Global, ProvidedFunctionality};
 
 pub type SimpleAST = HashMap<String, HashMap<String, HashMap<String, HashMap<String, Vec<Probe>>>>>;
 
@@ -114,6 +114,23 @@ impl BehaviorTreeBuilder<'_> {
         }
     }
 
+    fn visit_provided_globals(&mut self, globals: &HashMap<String, (ProvidedFunctionality, Global)>) {
+        if globals.len() > 0 {
+            self.tree.sequence(self.err);
+
+            // visit globals
+            for (_name, (.., global)) in globals.iter() {
+                if global.is_comp_provided {
+                    if let Expr::VarId { name, ..} = &global.var_name {
+                        self.tree.define(self.context_name.clone(),
+                                         name.clone(), self.err);
+                    }
+                }
+            }
+            self.tree.exit_sequence(self.err);
+        }
+    }
+
     fn is_in_context(&self, pattern: &str) -> bool {
         let regex = Regex::new(pattern).unwrap();
         if let Some(_caps) = regex.captures(self.context_name.as_str()) {
@@ -282,7 +299,7 @@ impl WhammVisitor<()> for BehaviorTreeBuilder<'_> {
             // .enter_scope(self.context_name.clone());
 
         // visit globals
-        self.visit_globals(&whamm.globals);
+        self.visit_provided_globals(&whamm.globals);
 
         // visit whammys
         whamm.whammys.iter().for_each(| whammy | self.visit_whammy(whammy));
@@ -323,7 +340,7 @@ impl WhammVisitor<()> for BehaviorTreeBuilder<'_> {
         self.tree.enter_scope(self.context_name.clone(), provider.name.clone(), self.err);
 
         // visit globals
-        self.visit_globals(&provider.globals);
+        self.visit_provided_globals(&provider.globals);
 
         provider.packages.iter().for_each(| (_name, package) | {
             self.visit_package(package)

src/cli.rs

@@ -0,0 +1,96 @@
+use clap::{Args, Parser, Subcommand};
+
+/// `whamm` instruments a Wasm application with the Probes defined in the specified Whammy.
+#[derive(Debug, Parser)]
+#[clap(author, version, about, long_about = None)]
+pub struct WhammCli {
+    // #[clap(flatten)]
+    // global_opts: GlobalOpts,
+
+    #[command(subcommand)]
+    pub(crate) command: Cmd
+}
+
+#[derive(Debug, Subcommand)]
+pub(crate) enum Cmd {
+    // /// Generate shell completion
+    // Completion {
+    //     /// Shell to generate completion for
+    //     #[arg(arg_enum)]
+    //     shell: Shell,
+    // },
+    /// To provide the globals and functions available for the given probe specification.
+    /// To use this option, simply follow the command with a full or partial specification
+    /// (use pattern matching to see what would be triggered).
+    Info {
+        #[arg(short, long, value_parser)]
+        spec: String,
+
+        /// Show the globals in-scope when using the probe specification.
+        #[arg(long, short, action, default_value = "false")]
+        globals: bool,
+
+        /// Show the functions in-scope when using the probe specification.
+        #[arg(long, short, action, default_value = "false")]
+        functions: bool,
+    },
+
+    /// To instrument a Wasm application.
+    Instr(InstrArgs),
+
+    /// To visualize the relationship between various structures in the module and its instructions
+    VisWasm {
+        /// The path to the Wasm module we want to visualize.
+        #[clap(short, long, value_parser)]
+        wasm: String,
+
+        /// The path to output the visualization to.
+        #[clap(short, long, value_parser, default_value = "output/wasm.dot")]
+        output_path: String,
+    },
+
+    /// To visualize the generated behavior tree from the specified `whammy`
+    VisWhammy {
+        /// The path to the `whammy` file we want to visualize.
+        #[clap(short, long, value_parser)]
+        whammy: String,
+
+        /// Whether to run the verifier on the specified whammy
+        #[clap(long, short, action, default_value = "false")] // TODO -- change this default value to true when I have this implemented
+        run_verifier: bool,
+
+        /// The path to output the visualization to.
+        #[clap(short, long, value_parser, default_value = "output/vis.svg")]
+        output_path: String,
+    }
+}
+
+// #[derive(Debug, Args)]
+// struct GlobalOpts {
+//     // (not needed yet)
+// }
+
+#[derive(Debug, Args)]
+pub struct InstrArgs {
+    /// The path to the application's Wasm module we want to instrument.
+    #[arg(short, long, value_parser)]
+    pub app: String,
+    /// The path to the Whammy containing the instrumentation Probe definitions.
+    #[arg(short, long, value_parser)]
+    pub whammy: String,
+    /// The path that the instrumented version of the Wasm app should be output to.
+    #[arg(short, long, value_parser, default_value = "./output/output.wasm")]
+    pub output_path: String,
+
+    /// Whether to emit Virgil code as the instrumentation code
+    #[arg(short, long, action, default_value = "false")]
+    pub virgil: bool,
+
+    /// Whether to run the verifier on the specified whammy
+    #[arg(long, short, action, default_value = "false")] // TODO -- change this default value to true when I have this implemented
+    pub run_verifier: bool
+}
+
+// pub fn print_completion<G: Generator>(gen: G, app: &mut App) {
+//     generate(gen, app, app.get_name().to_string(), &mut io::stdout());
+// }

src/common.rs

@@ -1 +1,2 @@
-pub mod error;
+pub mod error;
+pub mod terminal;