monadic wrapper type for descriptions

Author: ss2165

hugr-cli/src/convert.rs

@@ -49,7 +49,7 @@ pub struct ConvertArgs {
 impl ConvertArgs {
     /// Convert a HUGR between different envelope formats
     pub fn run_convert(&mut self) -> Result<()> {
-        let (env_config, package) = self.input_args.get_described_package()?;
+        let desc_pkg = self.input_args.get_described_package()?;
 
         // Handle text and binary format flags, which override the format option
         let mut config = if self.text {
@@ -67,7 +67,7 @@ impl ConvertArgs {
                     "model-text-exts" => EnvelopeFormat::ModelTextWithExtensions,
                     _ => Err(CliError::InvalidFormat(fmt.clone()))?,
                 },
-                None => env_config.header.config().format, // Use input format if not specified
+                None => desc_pkg.description().header.config().format, // Use input format if not specified
             };
             EnvelopeConfig::new(format)
         };
@@ -78,7 +78,7 @@ impl ConvertArgs {
         }
 
         // Write the package with the requested format
-        hugr::envelope::write_envelope(&mut self.output, &package, config)?;
+        hugr::envelope::write_envelope(&mut self.output, desc_pkg.as_ref(), 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::description::PackageDesc;
+use hugr::envelope::description::DescribedPackage;
 use hugr::envelope::{EnvelopeConfig, read_described_envelope};
 use hugr::extension::ExtensionRegistry;
 use hugr::package::Package;
@@ -49,7 +49,8 @@ impl HugrInputArgs {
     /// 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_described_package().map(|(_, package)| package)
+        self.get_described_package()
+            .map(|dsk_pkg| dsk_pkg.into_inner())
     }
 
     /// Read a hugr envelope from the input and return the envelope
@@ -61,8 +62,10 @@ impl HugrInputArgs {
     /// reading the input as a package will fail.
     #[deprecated(since = "0.24.1", note = "Use get_described_envelope instead")]
     pub fn get_envelope(&mut self) -> Result<(EnvelopeConfig, Package), CliError> {
-        let (desc, package) = self.get_described_package()?;
-        Ok((desc.header.config(), package))
+        let desc_pkg = self.get_described_package()?;
+
+        let config = desc_pkg.description().header.config();
+        Ok((config, desc_pkg.into_inner()))
     }
 
     /// Read a hugr envelope from the input and return the envelope
@@ -72,7 +75,7 @@ impl HugrInputArgs {
     ///
     /// 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_described_package(&mut self) -> Result<(PackageDesc, Package), CliError> {
+    pub fn get_described_package(&mut self) -> Result<DescribedPackage, CliError> {
         let extensions = self.load_extensions()?;
         let buffer = BufReader::new(&mut self.input);
 

hugr-cli/src/mermaid.rs

@@ -43,8 +43,9 @@ impl MermaidArgs {
 
     /// Write the mermaid diagram for a HUGR envelope.
     pub fn run_print_envelope(&mut self) -> Result<()> {
-        let (desc, package) = self.input_args.get_described_package()?;
-        let generator = desc.generator();
+        let desc_pkg = self.input_args.get_described_package()?;
+        let generator = desc_pkg.description().generator();
+        let package = desc_pkg.into_inner();
         if self.validate {
             package
                 .validate()

hugr-cli/src/validate.rs

@@ -37,9 +37,10 @@ impl ValArgs {
                 .map_err(PackageValidationError::Validation)
                 .map_err(|val_err| CliError::validation(generator, val_err))?;
         } else {
-            let (desc, package) = self.input_args.get_described_package()?;
-            let generator = desc.generator();
-            package
+            let desc_pkg = self.input_args.get_described_package()?;
+            let generator = desc_pkg.description().generator();
+            desc_pkg
+                .into_inner()
                 .validate()
                 .map_err(|val_err| CliError::validation(generator, val_err))?;
         };

hugr-cli/tests/convert.rs

@@ -77,8 +77,10 @@ fn test_convert_to_json(test_envelope_file: NamedTempFile, mut convert_cmd: Comm
     let output_content = std::fs::read(output_file.path()).expect("Failed to read output file");
     let reader = BufReader::new(output_content.as_slice());
     let registry = ExtensionRegistry::default();
-    let (desc, _) =
-        read_described_envelope(reader, &registry).expect("Failed to read output envelope");
+    let desc = read_described_envelope(reader, &registry)
+        .expect("Failed to read output envelope")
+        .description()
+        .clone();
     let config = desc.header.config();
 
     // Verify the format is correct
@@ -104,8 +106,10 @@ fn test_convert_to_model(test_envelope_file: NamedTempFile, mut convert_cmd: Com
     let output_content = std::fs::read(output_file.path()).expect("Failed to read output file");
     let reader = BufReader::new(output_content.as_slice());
     let registry = ExtensionRegistry::default();
-    let (desc, _) =
-        read_described_envelope(reader, &registry).expect("Failed to read output envelope");
+    let desc = read_described_envelope(reader, &registry)
+        .expect("Failed to read output envelope")
+        .description()
+        .clone();
     let config = desc.header.config();
     // Verify the format is correct
     assert_eq!(config.format, EnvelopeFormat::Model);
@@ -177,8 +181,10 @@ fn test_convert_model_text_format(test_envelope_file: NamedTempFile, mut convert
     let output_content = std::fs::read(output_file.path()).expect("Failed to read output file");
     let reader = BufReader::new(output_content.as_slice());
     let registry = ExtensionRegistry::default();
-    let (desc, _) =
-        read_described_envelope(reader, &registry).expect("Failed to read output envelope");
+    let desc = read_described_envelope(reader, &registry)
+        .expect("Failed to read output envelope")
+        .description()
+        .clone();
     let config = desc.header.config();
 
     // Verify the format is correct
@@ -197,14 +203,18 @@ fn test_format_roundtrip(test_package: Package) {
     let config_model = EnvelopeConfig::new(EnvelopeFormat::Model);
     let reader = BufReader::new(json_data.as_slice());
     let registry = ExtensionRegistry::default();
-    let (_, package) = read_described_envelope(reader, &registry).unwrap();
+    let package = read_described_envelope(reader, &registry)
+        .unwrap()
+        .into_inner();
 
     let mut model_data = Vec::new();
     hugr::envelope::write_envelope(&mut model_data, &package, config_model).unwrap();
 
     // Convert back to JSON
     let reader = BufReader::new(model_data.as_slice());
-    let (_, package_back) = read_described_envelope(reader, &registry).unwrap();
+    let package_back = read_described_envelope(reader, &registry)
+        .unwrap()
+        .into_inner();
 
     // Package should be the same after roundtrip conversion
     assert_eq!(test_package, package_back);
@@ -220,8 +230,10 @@ fn test_convert_text_flag(test_envelope_text: (String, Package), mut convert_cmd
 
     let reader = BufReader::new(stdout.as_slice());
     let registry = ExtensionRegistry::default();
-    let (desc, _) =
-        read_described_envelope(reader, &registry).expect("Failed to read output envelope");
+    let desc = read_described_envelope(reader, &registry)
+        .expect("Failed to read output envelope")
+        .description()
+        .clone();
     let config = desc.header.config();
 
     // Verify it's a text-based format
@@ -238,8 +250,10 @@ fn test_convert_binary_flag(test_envelope_text: (String, Package), mut convert_c
 
     let reader = BufReader::new(stdout.as_slice());
     let registry = ExtensionRegistry::default();
-    let (desc, _) =
-        read_described_envelope(reader, &registry).expect("Failed to read output envelope");
+    let desc = read_described_envelope(reader, &registry)
+        .expect("Failed to read output envelope")
+        .description()
+        .clone();
     let config = desc.header.config();
 
     // Verify it's a binary format (not ASCII printable)

hugr-core/src/envelope.rs

@@ -46,7 +46,7 @@ pub mod serde_with;
 pub use header::{EnvelopeConfig, EnvelopeFormat, EnvelopeHeader, MAGIC_NUMBERS, ZstdConfig};
 pub use package_json::PackageEncodingError;
 
-use crate::envelope::description::PackageDesc;
+use crate::envelope::description::{Described, DescribedPackage, PackageDesc};
 use crate::envelope::header::HeaderError;
 use crate::extension::resolution::ExtensionResolutionError;
 use crate::{Hugr, HugrView};
@@ -157,7 +157,7 @@ pub fn read_envelope(
 ) -> Result<(EnvelopeConfig, Package), EnvelopeError> {
     let reader = EnvelopeReader::new(reader, registry)?;
     let config = reader.description().header.config();
-    let package = reader.read().1?;
+    let package = reader.read().into_parts().0?;
 
     Ok((config, package))
 }
@@ -174,39 +174,50 @@ pub fn read_envelope(
 pub fn read_described_envelope(
     reader: impl BufRead,
     registry: &ExtensionRegistry,
-) -> Result<(PackageDesc, Package), ReadError> {
-    let reader = EnvelopeReader::new(reader, registry).map_err(Box::new)?;
-    let (desc, res) = reader.read();
-    match res {
-        Ok(pkg) => Ok((desc, pkg)),
-        Err(e) => Err(ReadError::Payload {
-            source: Box::new(e),
-            partial_description: desc,
+) -> Result<DescribedPackage, ReadError> {
+    let reader = EnvelopeReader::new(reader, registry)?;
+    let res = reader.read();
+    match res.as_ref() {
+        Ok(_) => Ok(res.map(Result::unwrap)),
+        Err(_) => Err(ReadError::Payload {
+            inner: res.map(|r| Box::new(r.expect_err("matched on error"))),
         }),
     }
 }
 
 /// Errors during reading a HUGR envelope.
-#[derive(Debug, Error)]
+#[derive(Debug, derive_more::Display)]
+#[non_exhaustive]
 pub enum ReadError {
     /// Error reading the envelope header.
-    #[error(transparent)]
-    EnvelopeHeader(#[from] Box<HeaderError>),
+    EnvelopeHeader(Box<HeaderError>),
     /// Error reading the package payload.
-    #[error("Error reading package payload in envelope.")]
+    #[display("Error reading package payload in envelope.")]
     Payload {
         /// The source error.
-        source: Box<PayloadError>,
-        /// Partial description of the envelope read before the error occurred.
-        partial_description: PackageDesc,
+        inner: Described<Box<PayloadError>, PackageDesc>,
     },
 }
+impl From<HeaderError> for ReadError {
+    fn from(err: HeaderError) -> Self {
+        ReadError::EnvelopeHeader(Box::new(err))
+    }
+}
+
+impl std::error::Error for ReadError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            ReadError::EnvelopeHeader(e) => Some(&**e),
+            ReadError::Payload { inner } => Some(&**inner.as_ref()),
+        }
+    }
+}
 
 impl From<ReadError> for EnvelopeError {
     fn from(err: ReadError) -> Self {
         match err {
             ReadError::EnvelopeHeader(e) => (*e).into(),
-            ReadError::Payload { source, .. } => (*source).into(),
+            ReadError::Payload { inner } => (*(inner.into_inner())).into(),
         }
     }
 }
@@ -650,12 +661,12 @@ pub(crate) mod test {
             }
         }
 
-        let (desc, new_package) =
+        let desc_pkg =
             read_described_envelope(BufReader::new(buffer.as_slice()), &PRELUDE_REGISTRY).unwrap();
-        let decoded_config = desc.header.config();
+        let decoded_config = desc_pkg.description().header.config();
         assert_eq!(config.format, decoded_config.format);
         assert_eq!(config.zstd.is_some(), decoded_config.zstd.is_some());
-        assert_eq!(package, new_package);
+        assert_eq!(&package, desc_pkg.as_ref());
     }
 
     #[rstest]
@@ -679,14 +690,14 @@ pub(crate) mod test {
         let config = EnvelopeConfig { format, zstd: None };
         package.store(&mut buffer, config).unwrap();
 
-        let (desc, new_package) =
+        let desc_pkg =
             read_described_envelope(BufReader::new(buffer.as_slice()), &PRELUDE_REGISTRY).unwrap();
-        let decoded_config = desc.header.config();
+        let decoded_config = desc_pkg.description().header.config();
 
         assert_eq!(config.format, decoded_config.format);
         assert_eq!(config.zstd.is_some(), decoded_config.zstd.is_some());
 
-        assert_eq!(package, new_package);
+        assert_eq!(&package, desc_pkg.as_ref());
     }
 
     /// Test helper to call `check_breaking_extensions_against_registry`