orcus_xml

Defined in header: <orcus/orcus_xml.hpp>

class orcus_xml

Public Functions

orcus_xml() = delete
orcus_xml(const orcus_xml&) = delete
orcus_xml &operator=(const orcus_xml&) = delete
orcus_xml(xmlns_repository &ns_repo, spreadsheet::iface::import_factory *im_fact, spreadsheet::iface::export_factory *ex_fact)
orcus_xml(xmlns_repository &ns_repo, spreadsheet::iface::import_factory *im_fact)
~orcus_xml()
void set_namespace_alias(std::string_view alias, std::string_view uri)

Register a namespace URI and associate it with a short alias for use in XPath expressions passed to other methods. The alias does not need to match the prefix declared in the XML document; it is local to this mapping session.

Passing an empty string as alias designates the URI as the default namespace. Any unprefixed name in a subsequent XPath expression will then be resolved against that namespace.

Parameters:

  • alias – Short prefix to use in XPath expressions, or an empty string to set the default namespace.

  • uri – Namespace URI to associate with the alias.

void set_cell_link(std::string_view xpath, std::string_view sheet, spreadsheet::row_t row, spreadsheet::col_t col)

Define a mapping of a single element or attribute to a single cell location.

Parameters:

  • xpath – path to the element or attribute to link.

  • sheet – sheet index (0-based) of the linked cell location.

  • row – row index (0-based) of the linked cell location.

  • col – column index (0-based) of the linked cell location.

void start_range(std::string_view sheet, spreadsheet::row_t row, spreadsheet::col_t col)

Initiate the mapping definition of a linked range. The definition will get committed when the commit_range method is called.

Parameters:

  • sheet – sheet index (0-based) of the linked cell location.

  • row – row index (0-based) of the linked cell location.

  • col – column index (0-based) of the linked cell location.

void append_field_link(std::string_view xpath, std::string_view label)

Append a field that is mapped to a specified path in the XML document to the current linked range.

Parameters:

  • xpath – path to the element or attribute to link as a field.

  • label – custom header label to use in lieu of the name of the linked entity.

Throws:

std::invalid_argument – if the xpath argument is empty.

void set_range_row_group(std::string_view xpath)

Set the element located in the specified path as a row group in the current linked range.

If the element is defined as a row-group element, the row index will increment whenever that element closes.

Parameters:

xpath – path to the element to use as a row group element.

void commit_range()

Commit the mapping definition of the current range.

void append_sheet(std::string_view name)

Append a new sheet to the spreadsheet document.

Parameters:

name – name of the sheet.

void read_stream(std::string_view stream)

Read the stream containing the source XML document.

Parameters:

stream – stream containing the content of the source XML document.

void read_map_definition(std::string_view stream)

Read an XML stream that contains an entire set of mapping rules.

This method also inserts all necessary sheets into the document model.

Parameters:

stream – stream containing the XML string.

void detect_map_definition(std::string_view stream)

Read a stream containing the source XML document, automatically detect all linkable ranges and import them one range per sheet.

Parameters:

stream – stream containing the source XML document.

void write_map_definition(std::string_view stream, std::ostream &out) const

Read a stream containing the source XML document, automatically detect all linkable ranges, and write a map definition file depicting the detected ranges.

Parameters:

  • stream – stream containing the source XML document.

  • out – output stream to write the map definition file to.

void write(std::string_view stream, std::ostream &out) const

Write the linked cells and ranges in the spreadsheet document as an XML document using the same map definition rules used to load the content.

Note that this requires the source XML document stream, as it re-uses parts of the source stream.

Parameters:

  • stream – stream containing the source XML document.

  • out – output stream to write the XML document to.

Public Static Functions

static bool detect(std::string_view strm)
static bool has_range(std::string_view stream)

Detect whether or not a given XML document contains at least one linkable range.

Parameters:

stream – XML document stream to check.

Returns:

True if the document contains at least one linkable range, otherwise false.