macros: add initial support

Feature #99

examples/app_macros.rs

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2024, John McNamara, [email protected]
+
+//! An example of adding macros to an `rust_xlsxwriter` file using a VBA macros
+//! file extracted from an existing Excel xlsm file.
+//!
+//! The `vba_extract` utility (https://crates.io/crates/vba_extract) can be used
+//! to extract the `vbaProject.bin` file.
+
+use rust_xlsxwriter::{Workbook, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    // Create a new Excel file object.
+    let mut workbook = Workbook::new();
+
+    // Add the VBA macro file.
+    workbook.add_vba_project("examples/vbaProject.bin")?;
+
+    // Add a worksheet and some text.
+    let worksheet = workbook.add_worksheet();
+
+    // Widen the first column for clarity.
+    worksheet.set_column_width(0, 30)?;
+
+    worksheet.write(2, 0, "Run macro say_hello()")?;
+
+    // Save the file to disk. Note the `.xlsm` extension. This is required by
+    // Excel or it raise a warning.
+    workbook.save("macros.xlsm")?;
+
+    Ok(())
+}

examples/doc_macros_add.rs

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2024, John McNamara, [email protected]
+
+//! The following example demonstrates a simple example of adding a vba project
+//! to an xlsm file.
+use rust_xlsxwriter::{Workbook, XlsxError};
+
+#[allow(unused_variables)]
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+
+    workbook.add_vba_project("examples/vbaProject.bin")?;
+
+    Ok(())
+}

examples/doc_macros_calc.rs

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2024, John McNamara, [email protected]
+
+//! The following example demonstrates a simple example of adding a vba project
+//! to an xlsm file.
+use rust_xlsxwriter::{Workbook, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+
+    workbook.add_vba_project("examples/vbaProject.bin")?;
+
+    let worksheet = workbook.add_worksheet();
+
+    worksheet.write_formula(0, 0, "=MyMortgageCalc(200000, 25)")?;
+
+    // Note the `.xlsm` extension.
+    workbook.save("macros.xlsm")?;
+
+    Ok(())
+}

examples/doc_macros_name.rs

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2024, John McNamara, [email protected]
+
+//! The following example demonstrates a simple example of adding a vba project
+//! to an xlsm file.
+use rust_xlsxwriter::{Workbook, XlsxError};
+
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+
+    workbook.add_vba_project("examples/vbaProject.bin")?;
+    workbook.set_vba_name("MyWorkbook")?;
+
+    let worksheet = workbook.add_worksheet();
+    worksheet.set_vba_name("MySheet1")?;
+
+    // Note the `.xlsm` extension.
+    workbook.save("macros.xlsm")?;
+
+    Ok(())
+}

examples/doc_macros_save.rs

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2024, John McNamara, [email protected]
+
+//! The following example demonstrates a simple example of adding a vba project
+//! to an xlsm file.
+use rust_xlsxwriter::{Workbook, XlsxError};
+
+#[allow(unused_variables)]
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+
+    workbook.add_vba_project("examples/vbaProject.bin")?;
+
+    let worksheet = workbook.add_worksheet();
+
+    // Note the `.xlsm` extension.
+    workbook.save("macros.xlsm")?;
+
+    Ok(())
+}

examples/doc_macros_signed.rs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2024, John McNamara, [email protected]
+
+//! The following example demonstrates a simple example of adding a vba project
+//! to an xlsm file.
+use rust_xlsxwriter::{Workbook, XlsxError};
+
+#[allow(unused_variables)]
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+
+    workbook.add_vba_project_with_signature(
+        "examples/vbaProject.bin",
+        "examples/vbaProjectSignature.bin",
+    )?;
+
+    let worksheet = workbook.add_worksheet();
+
+    // Note the `.xlsm` extension.
+    workbook.save("macros.xlsm")?;
+
+    Ok(())
+}

src/content_types.rs

@@ -52,11 +52,6 @@ impl ContentTypes {
                     "/xl/theme/theme1.xml".to_string(),
                     "application/vnd.openxmlformats-officedocument.theme+xml".to_string(),
                 ),
-                (
-                    "/xl/workbook.xml".to_string(),
-                    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"
-                        .to_string(),
-                ),
             ],
         }
     }
@@ -68,7 +63,7 @@ impl ContentTypes {
     }
 
     // Add elements to the ContentTypes overrides.
-    fn add_override(&mut self, part_name: &str, content_type: &str) {
+    pub(crate) fn add_override(&mut self, part_name: &str, content_type: &str) {
         self.overrides
             .push((part_name.to_string(), content_type.to_string()));
     }

src/content_types/tests.rs

@@ -18,6 +18,11 @@ mod content_types_tests {
         content_types.add_default("jpeg", "image/jpeg");
         content_types.add_worksheet_name(1);
         content_types.add_share_strings();
+        content_types.add_override(
+            "/xl/workbook.xml",
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml",
+        );
+
         content_types.assemble_xml_file();
 
         let got = content_types.writer.read_to_str();
@@ -36,9 +41,9 @@ mod content_types_tests {
               <Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>
               <Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>
               <Override PartName="/xl/theme/theme1.xml" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/>
-              <Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
               <Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
               <Override PartName="/xl/sharedStrings.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml"/>
+              <Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
              </Types>
                 "#,
         );

src/error.rs

@@ -147,6 +147,17 @@ pub enum XlsxError {
     /// incorrect or missing.
     DataValidationError(String),
 
+    /// A general error raised when a VBA name doesn't meet Excel's criteria as
+    /// defined by the following rules:
+    ///
+    /// * The name must be less than 32 characters.
+    /// * The name can only contain word characters: letters, numbers and
+    ///   underscores.
+    /// * The name must start with a letter.
+    /// * The name cannot be blank.
+    ///
+    VbaNameError(String),
+
     /// A customizable error that can be used by third parties to raise errors
     /// or as a conversion target for other Error types.
     CustomError(String),
@@ -302,6 +313,10 @@ impl fmt::Display for XlsxError {
                 write!(f, "Data validation error: '{error}'.")
             }
 
+            XlsxError::VbaNameError(error) => {
+                write!(f, "VBA name error: '{error}'.")
+            }
+
             XlsxError::CustomError(error) => {
                 write!(f, "{error}")
             }

src/lib.rs

@@ -222,6 +222,7 @@ pub mod changelog;
 pub mod chart;
 pub mod conditional_format;
 pub mod cookbook;
+pub mod macros;
 pub mod sparkline;
 pub mod tutorial;
 pub mod utility;