Added workbook doc properties.

Closes #25

Changes.txt

@@ -4,8 +4,8 @@
 
 ## 0.2.4 December 13 2015
 
-- Added `worksheet_hide()` function to hide a worksheet. See @ref
-  hide_sheet.c.
+- Added `worksheet_hide()` function to hide a worksheet. See the @ref
+  hide_sheet.c example.
 
 - Added `worksheet_set_first_sheet()` function to set the first visible
   worksheet in a workbook with a large number of worksheets.
@@ -14,7 +14,7 @@
 ## 0.2.3 December 12 2015
 
 - Added `worksheet_set_tab_color()` function to set the worksheet tab
-  color. See @ref tab_colors.c.
+  color. See the @ref tab_colors.c example.
 
 
 ## 0.2.2 December 11 2015

dev/release/fix_example_docs.pl

@@ -32,6 +32,7 @@ my @examples = (
     [ 'defined_name.c',      'Example of how to create defined names' ],
     [ 'tab_colors.c',        'Example of how to set worksheet tab colors' ],
     [ 'hide_sheet.c',        'Example of hiding a worksheet' ],
+    [ 'doc_properties.c',    'Example of setting workbook doc properties' ],
     [ 'panes.c',             'Example of how to create worksheet panes' ],
 );
 
@@ -73,7 +74,7 @@ while ( my $line = <> ) {
             my $filename = $aref->[0];
             my $desc     = $aref->[1];
 
-            $example =~ s/.c/_8c-example.html/;
+            $example =~ s/\.c/_8c-example.html/;
 
             printf qq(<li><a class="el" href="%s">%s</a> %s</li>\n\n),
               $example, $filename, $desc;

docs/src/examples.dox

@@ -157,10 +157,17 @@ Next example: @ref hide_sheet.c
 @example hide_sheet.c
 Example of how to hide an Excel worksheet.
 
-Next example: @ref panes.c
+Next example: @ref doc_properties.c
 @image html hide_sheet.png
 
 
+@example doc_properties.c
+Example of setting Excel document properties.
+
+Next example: @ref panes.c
+@image html doc_properties.png
+
+
 @example panes.c
 An example of how to create panes in a worksheet, both “freeze” panes and “split” panes.
 

examples/doc_properties.c

@@ -0,0 +1,41 @@
+/*
+ * Example of setting document properties such as Author, Title, etc., for an
+ * Excel spreadsheet using libxlsxwriter.
+ *
+ * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook       *workbook   = new_workbook("doc_properties.xlsx");
+    lxw_worksheet      *worksheet  = workbook_add_worksheet(workbook, NULL);
+
+    /* Create a properties structure and set some of the fields. */
+    lxw_doc_properties *properties = calloc(1, sizeof(lxw_doc_properties));
+
+    properties->title    = strdup("This is an example spreadsheet");
+    properties->subject  = strdup("With document properties");
+    properties->author   = strdup("John McNamara");
+    properties->manager  = strdup("Dr. Heinz Doofenshmirtz");
+    properties->company  = strdup("of Wolves");
+    properties->category = strdup("Example spreadsheets");
+    properties->keywords = strdup("Sample, Example, Properties");
+    properties->comments = strdup("Created with libxlsxwriter");
+    properties->status   = strdup("Quo");
+
+    /* Set the properties in the workbook. */
+    workbook_set_properties(workbook, properties);
+
+    /* Add some text to the file. */
+    worksheet_set_column(worksheet, 0, 0, 70, NULL, NULL);
+    worksheet_write_string(worksheet, 0, 0,
+        "Select 'Workbook Properties' to see properties." , NULL);
+
+     workbook_close(workbook);
+
+    free(properties);
+    return 0;
+}

include/xlsxwriter/app.h

@@ -1,6 +1,6 @@
 /*
  * libxlsxwriter
- * 
+ *
  * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
  *
  * app - A libxlsxwriter library for creating Excel XLSX app files.
@@ -11,7 +11,7 @@
 
 #include <stdint.h>
 #include <string.h>
-#include "xlsxwriter/third_party/queue.h"
+#include "xlsxwriter/workbook.h"
 
 #include "common.h"
 

include/xlsxwriter/common.h

@@ -80,19 +80,6 @@ typedef struct lxw_tuple {
     STAILQ_ENTRY (lxw_tuple) list_pointers;
 } lxw_tuple;
 
-typedef struct lxw_doc_properties {
-    char *title;
-    char *subject;
-    char *author;
-    char *manager;
-    char *company;
-    char *category;
-    char *keywords;
-    char *comments;
-    char *status;
-    time_t created;
-} lxw_doc_properties;
-
 
  /* *INDENT-OFF* */
 #ifdef __cplusplus

include/xlsxwriter/content_types.h

@@ -1,6 +1,6 @@
 /*
  * libxlsxwriter
- * 
+ *
  * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
  *
  * content_types - A libxlsxwriter library for creating Excel XLSX
@@ -12,7 +12,6 @@
 
 #include <stdint.h>
 #include <string.h>
-#include "xlsxwriter/third_party/queue.h"
 
 #include "common.h"
 

include/xlsxwriter/core.h

@@ -1,6 +1,6 @@
 /*
  * libxlsxwriter
- * 
+ *
  * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
  *
  * core - A libxlsxwriter library for creating Excel XLSX core files.
@@ -10,8 +10,8 @@
 #define __LXW_CORE_H__
 
 #include <stdint.h>
-#include "xlsxwriter/third_party/queue.h"
 
+#include "xlsxwriter/workbook.h"
 #include "common.h"
 
 /*

include/xlsxwriter/format.h

@@ -63,7 +63,6 @@
 #include <stdint.h>
 #include <string.h>
 #include "hash_table.h"
-#include "xlsxwriter/third_party/queue.h"
 
 #include "common.h"
 

include/xlsxwriter/hash_table.h

@@ -10,7 +10,6 @@
 #ifndef __LXW_HASH_TABLE_H__
 #define __LXW_HASH_TABLE_H__
 
-#include "xlsxwriter/third_party/queue.h"
 #include "common.h"
 
 /* Macro to loop over hash table elements in insertion order. */

include/xlsxwriter/packager.h

@@ -1,6 +1,6 @@
 /*
  * libxlsxwriter
- * 
+ *
  * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
  *
  * packager - A libxlsxwriter library for creating Excel XLSX packager files.
@@ -10,7 +10,6 @@
 #define __LXW_PACKAGER_H__
 
 #include <stdint.h>
-#include "xlsxwriter/third_party/queue.h"
 #include "xlsxwriter/third_party/minizip/zip.h"
 
 #include "common.h"

include/xlsxwriter/relationships.h

@@ -1,6 +1,6 @@
 /*
  * libxlsxwriter
- * 
+ *
  * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
  *
  * relationships - A libxlsxwriter library for creating Excel XLSX
@@ -11,7 +11,6 @@
 #define __LXW_RELATIONSHIPS_H__
 
 #include <stdint.h>
-#include "xlsxwriter/third_party/queue.h"
 
 #include "common.h"
 

include/xlsxwriter/styles.h

@@ -1,6 +1,6 @@
 /*
  * libxlsxwriter
- * 
+ *
  * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
  *
  * styles - A libxlsxwriter library for creating Excel XLSX styles files.
@@ -10,7 +10,6 @@
 #define __LXW_STYLES_H__
 
 #include <stdint.h>
-#include "xlsxwriter/third_party/queue.h"
 
 #include "format.h"
 

include/xlsxwriter/theme.h

@@ -10,7 +10,6 @@
 #define __LXW_THEME_H__
 
 #include <stdint.h>
-#include "xlsxwriter/third_party/queue.h"
 
 #include "common.h"
 

include/xlsxwriter/workbook.h

@@ -44,7 +44,6 @@
 #include <stdint.h>
 #include <stdio.h>
 #include <errno.h>
-#include "xlsxwriter/third_party/queue.h"
 
 #include "worksheet.h"
 #include "shared_strings.h"
@@ -117,6 +116,44 @@ enum lxw_workbook_error {
     LXW_ERROR_WORKBOOK_MEMORY_ERROR
 };
 
+/**
+ * Workbook document properties.
+ */
+typedef struct lxw_doc_properties {
+    /** The title of the Excel Document. */
+    char *title;
+
+    /** The subject of the Excel Document. */
+    char *subject;
+
+    /** The author of the Excel Document. */
+    char *author;
+
+    /** The manager field of the Excel Document. */
+    char *manager;
+
+    /** The company field of the Excel Document. */
+    char *company;
+
+    /** The category of the Excel Document. */
+    char *category;
+
+    /** The keywords of the Excel Document. */
+    char *keywords;
+
+    /** The comment field of the Excel Document. */
+    char *comments;
+
+    /** The status of the Excel Document. */
+    char *status;
+
+    /** The hyperlink base url of the Excel Document. */
+    char *hyperlink_base;
+
+    time_t created;
+
+} lxw_doc_properties;
+
 /**
  * @brief Workbook options.
  *
@@ -314,6 +351,59 @@ lxw_format *workbook_add_format(lxw_workbook *workbook);
  */
 uint8_t workbook_close(lxw_workbook *workbook);
 
+/**
+ * @brief Set the document properties such as Title, Author etc.
+ *
+ * @param workbook   Pointer to a lxw_workbook instance.
+ * @param properties Document properties to set.
+ *
+ * The `%workbook_set_properties` method can be used to set the document
+ * properties of the Excel file created by `libxlsxwriter`. These properties
+ * are visible when you use the `Office Button -> Prepare -> Properties`
+ * option in Excel and are also available to external applications that read
+ * or index windows files.
+ *
+ * The properties that can be set are:
+ *
+ * - `title`
+ * - `subject`
+ * - `author`
+ * - `manager`
+ * - `company`
+ * - `category`
+ * - `keywords`
+ * - `comments`
+ * - `hyperlink_base`
+ *
+ * The properties are specified via a `lxw_doc_properties` struct. All the
+ * members are `char *` and they are all optional. An example of how to create
+ * and pass the properties is:
+ *
+ * @code
+ *    // Create a properties structure and set some of the fields.
+ *    lxw_doc_properties *properties = calloc(1, sizeof(lxw_doc_properties));
+ *
+ *    properties->title    = strdup("This is an example spreadsheet");
+ *    properties->subject  = strdup("With document properties");
+ *    properties->author   = strdup("John McNamara");
+ *    properties->manager  = strdup("Dr. Heinz Doofenshmirtz");
+ *    properties->company  = strdup("of Wolves");
+ *    properties->category = strdup("Example spreadsheets");
+ *    properties->keywords = strdup("Sample, Example, Properties");
+ *    properties->comments = strdup("Created with libxlsxwriter");
+ *    properties->status   = strdup("Quo");
+ *
+ *    // Set the properties in the workbook.
+ *    workbook_set_properties(workbook, properties);
+ * @endcode
+ *
+ * @image html doc_properties.png
+ *
+ * @return 0 for success, non-zero on error.
+ */
+uint8_t workbook_set_properties(lxw_workbook *workbook,
+                                lxw_doc_properties *properties);
+
 /**
  * @brief Create a defined name in the workbook to use as a variable.
  *

include/xlsxwriter/xmlwriter.h

@@ -23,7 +23,6 @@
 #include <stdlib.h>
 #include <stdint.h>
 #include "common.h"
-#include "xlsxwriter/third_party/queue.h"
 
 #define MAX_ATTRIBUTE_LENGTH 256
 #define ATTR_32              32

src/app.c

@@ -302,6 +302,22 @@ _write_shared_doc(lxw_app *self)
     _xml_data_element(self->file, "SharedDoc", "false", NULL);
 }
 
+/*
+ * Write the <HyperlinkBase> element.
+ */
+STATIC void
+_write_hyperlink_base(lxw_app *self)
+{
+    lxw_doc_properties *properties = self->properties;
+
+    if (!properties)
+        return;
+
+    if (properties->hyperlink_base)
+        _xml_data_element(self->file, "HyperlinkBase",
+                          properties->hyperlink_base, NULL);
+}
+
 /*
  * Write the <HyperlinksChanged> element.
  */
@@ -346,6 +362,7 @@ _app_assemble_xml_file(lxw_app *self)
     _write_company(self);
     _write_links_up_to_date(self);
     _write_shared_doc(self);
+    _write_hyperlink_base(self);
     _write_hyperlinks_changed(self);
     _write_app_version(self);
 

src/packager.c

@@ -236,6 +236,9 @@ _write_app_file(lxw_packager *self)
         _add_heading_pair(app, "Named Ranges", number);
     }
 
+    /* Set the app/doc properties. */
+    app->properties = workbook->properties;
+
     _app_assemble_xml_file(app);
 
     _add_file_to_zip(self, app->file, "docProps/app.xml");

src/workbook.c

@@ -23,6 +23,28 @@
  *
  ****************************************************************************/
 
+/*
+ * Free workbook properties.
+ */
+void
+_free_doc_properties(lxw_doc_properties *properties)
+{
+    if (properties) {
+        free(properties->title);
+        free(properties->subject);
+        free(properties->author);
+        free(properties->manager);
+        free(properties->company);
+        free(properties->category);
+        free(properties->keywords);
+        free(properties->comments);
+        free(properties->status);
+        free(properties->hyperlink_base);
+    }
+
+    free(properties);
+}
+
 /*
  * Free a workbook object.
  */
@@ -36,19 +58,7 @@ _free_workbook(lxw_workbook *workbook)
     if (!workbook)
         return;
 
-    if (workbook->properties) {
-        free(workbook->properties->title);
-        free(workbook->properties->subject);
-        free(workbook->properties->author);
-        free(workbook->properties->manager);
-        free(workbook->properties->company);
-        free(workbook->properties->category);
-        free(workbook->properties->keywords);
-        free(workbook->properties->comments);
-        free(workbook->properties->status);
-    }
-
-    free(workbook->properties);
+    _free_doc_properties(workbook->properties);
 
     free(workbook->filename);
 
@@ -1140,3 +1150,77 @@ workbook_define_name(lxw_workbook *self, const char *name,
 {
     return _store_defined_name(self, name, NULL, formula, -1, LXW_FALSE);
 }
+
+/*
+ * Set the document properties such as Title, Author etc.
+ */
+uint8_t
+workbook_set_properties(lxw_workbook *self, lxw_doc_properties *user_props)
+{
+    lxw_doc_properties *doc_props;
+
+    /* Free any existing properties. */
+    _free_doc_properties(self->properties);
+
+    doc_props = calloc(1, sizeof(lxw_doc_properties));
+    GOTO_LABEL_ON_MEM_ERROR(doc_props, mem_error);
+
+    /* Copy the user properties to an internal structure. */
+    if (user_props->title) {
+        doc_props->title = strdup(user_props->title);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->title, mem_error);
+    }
+
+    if (user_props->subject) {
+        doc_props->subject = strdup(user_props->subject);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->subject, mem_error);
+    }
+
+    if (user_props->author) {
+        doc_props->author = strdup(user_props->author);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->author, mem_error);
+    }
+
+    if (user_props->manager) {
+        doc_props->manager = strdup(user_props->manager);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->manager, mem_error);
+    }
+
+    if (user_props->company) {
+        doc_props->company = strdup(user_props->company);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->company, mem_error);
+    }
+
+    if (user_props->category) {
+        doc_props->category = strdup(user_props->category);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->category, mem_error);
+    }
+
+    if (user_props->keywords) {
+        doc_props->keywords = strdup(user_props->keywords);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->keywords, mem_error);
+    }
+
+    if (user_props->comments) {
+        doc_props->comments = strdup(user_props->comments);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->comments, mem_error);
+    }
+
+    if (user_props->status) {
+        doc_props->status = strdup(user_props->status);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->status, mem_error);
+    }
+
+    if (user_props->hyperlink_base) {
+        doc_props->hyperlink_base = strdup(user_props->hyperlink_base);
+        GOTO_LABEL_ON_MEM_ERROR(doc_props->hyperlink_base, mem_error);
+    }
+
+    self->properties = doc_props;
+
+    return 0;
+
+mem_error:
+    _free_doc_properties(doc_props);
+    return -1;
+}

test/functional/src/test_properties01.c

@@ -0,0 +1,34 @@
+/*****************************************************************************
+ * Test cases for libxlsxwriter.
+ *
+ * Test to compare output against Excel files.
+ *
+ * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook       *workbook   = new_workbook("test_properties01.xlsx");
+    lxw_worksheet      *worksheet  = workbook_add_worksheet(workbook, NULL);
+    lxw_doc_properties *properties = calloc(1, sizeof(lxw_doc_properties));
+
+    properties->title    = strdup("This is an example spreadsheet");
+    properties->subject  = strdup("With document properties");
+    properties->author   = strdup("Someone");
+    properties->manager  = strdup("Dr. Heinz Doofenshmirtz");
+    properties->company  = strdup("of Wolves");
+    properties->category = strdup("Example spreadsheets");
+    properties->keywords = strdup("Sample, Example, Properties");
+    properties->comments = strdup("Created with Perl and Excel::Writer::XLSX");
+    properties->status   = strdup("Quo");
+
+    workbook_set_properties(workbook, properties);
+
+    worksheet_set_column(worksheet, 0, 0, 70, NULL, NULL);
+    worksheet_write_string(worksheet, CELL("A1"), "Select 'Office Button -> Prepare -> Properties' to see the file properties." , NULL);
+
+    return workbook_close(workbook);
+}

test/functional/src/test_properties02.c

@@ -0,0 +1,25 @@
+/*****************************************************************************
+ * Test cases for libxlsxwriter.
+ *
+ * Test to compare output against Excel files.
+ *
+ * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook       *workbook   = new_workbook("test_properties02.xlsx");
+    lxw_worksheet      *worksheet  = workbook_add_worksheet(workbook, NULL);
+    lxw_doc_properties *properties = calloc(1, sizeof(lxw_doc_properties));
+
+    properties->hyperlink_base = strdup("C:\\");
+
+    workbook_set_properties(workbook, properties);
+
+    (void)worksheet;
+
+    return workbook_close(workbook);
+}

test/functional/test_properties.py

@@ -0,0 +1,20 @@
+###############################################################################
+#
+# Tests for libxlsxwriter.
+#
+# Copyright 2014-2015, John McNamara, jmcnamara@cpan.org
+#
+
+import base_test_class
+
+class TestCompareXLSXFiles(base_test_class.XLSXBaseTest):
+    """
+    Test file created with libxlsxwriter against a file created by Excel.
+
+    """
+
+    def test_properties01(self):
+        self.run_exe_test('test_properties01')
+
+    def test_properties02(self):
+        self.run_exe_test('test_properties02')