Merge remote-tracking branch 'origin/main' into acl/linking_prelims

Author: acl-cqc

hugr-cli/src/convert.rs

@@ -0,0 +1,85 @@
+//! Convert between different HUGR envelope formats.
+use anyhow::Result;
+use clap::Parser;
+use clio::Output;
+use hugr::envelope::{EnvelopeConfig, EnvelopeFormat, ZstdConfig};
+
+use crate::CliError;
+use crate::hugr_io::HugrInputArgs;
+
+/// Convert between different HUGR envelope formats.
+#[derive(Parser, Debug)]
+#[clap(version = "1.0", long_about = None)]
+#[clap(about = "Convert a HUGR between different envelope formats.")]
+#[group(id = "hugr")]
+#[non_exhaustive]
+pub struct ConvertArgs {
+    /// Hugr input.
+    #[command(flatten)]
+    pub input_args: HugrInputArgs,
+
+    /// Output file. Use '-' for stdout.
+    #[clap(short, long, value_parser, default_value = "-")]
+    pub output: Output,
+
+    /// Output format. One of: json, model, model-exts, model-text, model-text-exts
+    #[clap(short, long, value_name = "FORMAT")]
+    pub format: Option<String>,
+
+    /// Use default text-based envelope configuration.
+    /// Cannot be combined with --format or --binary.
+    #[clap(long, conflicts_with_all = ["format", "binary"])]
+    pub text: bool,
+
+    /// Use default binary envelope configuration.
+    /// Cannot be combined with --format or --text.
+    #[clap(long, conflicts_with_all = ["format", "text"])]
+    pub binary: bool,
+
+    /// Enable zstd compression for the output
+    #[clap(long)]
+    pub compress: bool,
+
+    /// Zstd compression level (1-22, where 1 is fastest and 22 is best compression)
+    /// Uses the default level if not specified.
+    #[clap(long, value_name = "LEVEL", requires = "compress")]
+    pub compression_level: Option<u8>,
+}
+
+impl ConvertArgs {
+    /// Convert a HUGR between different envelope formats
+    pub fn run_convert(&mut self) -> Result<()> {
+        let (env_config, package) = self.input_args.get_envelope()?;
+
+        // Handle text and binary format flags, which override the format option
+        let mut config = if self.text {
+            EnvelopeConfig::text()
+        } else if self.binary {
+            EnvelopeConfig::binary()
+        } else {
+            // Parse the requested format
+            let format = match &self.format {
+                Some(fmt) => match fmt.as_str() {
+                    "json" => EnvelopeFormat::PackageJson,
+                    "model" => EnvelopeFormat::Model,
+                    "model-exts" => EnvelopeFormat::ModelWithExtensions,
+                    "model-text" => EnvelopeFormat::ModelText,
+                    "model-text-exts" => EnvelopeFormat::ModelTextWithExtensions,
+                    _ => Err(CliError::InvalidFormat(fmt.clone()))?,
+                },
+                None => env_config.format, // Use input format if not specified
+            };
+            EnvelopeConfig::new(format)
+        };
+
+        // Configure compression
+        if let Some(level) = self.compress.then_some(self.compression_level).flatten() {
+            config = config.with_zstd(ZstdConfig::new(level));
+        }
+
+        // Write the package with the requested format
+        hugr::envelope::write_envelope(&mut self.output, &package, config)?;
+
+        Ok(())
+    }
+}

hugr-cli/src/hugr_io.rs

@@ -1,7 +1,7 @@
 //! Input/output arguments for the HUGR CLI.
 
 use clio::Input;
-use hugr::envelope::{EnvelopeError, read_envelope};
+use hugr::envelope::{EnvelopeConfig, EnvelopeError, read_envelope};
 use hugr::extension::ExtensionRegistry;
 use hugr::package::Package;
 use hugr::{Extension, Hugr};
@@ -43,18 +43,29 @@ impl HugrInputArgs {
     /// Read a hugr envelope from the input and return the package encoded
     /// within.
     ///
+    /// # Errors
+    ///
     /// If [`HugrInputArgs::hugr_json`] is `true`, [`HugrInputArgs::get_hugr`] should be called instead as
     /// reading the input as a package will fail.
     pub fn get_package(&mut self) -> Result<Package, CliError> {
+        self.get_envelope().map(|(_, package)| package)
+    }
+
+    /// Read a hugr envelope from the input and return the envelope
+    /// configuration and the package encoded within.
+    ///
+    /// # Errors
+    ///
+    /// If [`HugrInputArgs::hugr_json`] is `true`, [`HugrInputArgs::get_hugr`] should be called instead as
+    /// reading the input as a package will fail.
+    pub fn get_envelope(&mut self) -> Result<(EnvelopeConfig, Package), CliError> {
         let extensions = self.load_extensions()?;
         let buffer = BufReader::new(&mut self.input);
-        match read_envelope(buffer, &extensions) {
-            Ok((_, pkg)) => Ok(pkg),
-            Err(EnvelopeError::MagicNumber { .. }) => Err(CliError::NotAnEnvelope),
-            Err(e) => Err(CliError::Envelope(e)),
-        }
+        read_envelope(buffer, &extensions).map_err(|e| match e {
+            EnvelopeError::MagicNumber { .. } => CliError::NotAnEnvelope,
+            _ => CliError::Envelope(e),
+        })
     }
-
     /// Read a hugr JSON file from the input.
     ///
     /// This is a legacy option for reading old HUGR JSON files when the

hugr-cli/src/lib.rs

@@ -63,6 +63,7 @@ use hugr::package::PackageValidationError;
 use std::ffi::OsString;
 use thiserror::Error;
 
+pub mod convert;
 pub mod extensions;
 pub mod hugr_io;
 pub mod mermaid;
@@ -92,6 +93,8 @@ pub enum CliCommand {
     GenExtensions(extensions::ExtArgs),
     /// Write HUGR as mermaid diagrams.
     Mermaid(mermaid::MermaidArgs),
+    /// Convert between different HUGR envelope formats.
+    Convert(convert::ConvertArgs),
     /// External commands
     #[command(external_subcommand)]
     External(Vec<OsString>),
@@ -118,4 +121,9 @@ pub enum CliError {
         "Input file is not a HUGR envelope. Invalid magic number.\n\nUse `--hugr-json` to read a raw HUGR JSON file instead."
     )]
     NotAnEnvelope,
+    /// Invalid format string for conversion.
+    #[error(
+        "Invalid format: '{_0}'. Valid formats are: json, model, model-exts, model-text, model-text-exts"
+    )]
+    InvalidFormat(String),
 }

hugr-cli/src/main.rs

@@ -29,6 +29,7 @@ fn main() {
         CliCommand::Validate(mut args) => args.run(),
         CliCommand::GenExtensions(args) => args.run_dump(&hugr::std_extensions::STD_REG),
         CliCommand::Mermaid(mut args) => args.run_print(),
+        CliCommand::Convert(mut args) => args.run_convert(),
         CliCommand::External(args) => run_external(args),
         _ => Err(anyhow!("Unknown command")),
     };