Document import
The following interfaces handle importing of contents and properties related to the entire document store.
-
class import_factory
This interface is the entry point for the import filter code to instantiate other, more specialized interfaces. The life cycles of any specialized interfaces returned from this interface shall be managed by the implementor of this interface.
The implementer of this interface may wrap a backend document store that needs to be populated.
Subclassed by orcus::spreadsheet::import_factory
Public Functions
-
virtual ~import_factory()
-
virtual import_global_settings *get_global_settings()
Obtain an optional interface for global settings, which the import filter uses to specify global filter settings that may affect how certain values and properties should be processed. The implementor can use this interface to decide how to process relevant values and properties.
- Returns:
pointer to the global settings interface, or a
nullptr
if the implementor doesn’t support it.
Obtain an optional interface for importing shared strings for string cells. Implementing this interface is required in order to import string cell values.
- Returns:
pointer to the shared strings interface, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_named_expression *get_named_expression()
Obtain an optional interface for importing global named expressions.
Note that import_sheet also provides the same interface, but its interface is for importing sheet-local named expressions.
- Returns:
pointer to the global named expression interface, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_styles *get_styles()
Obtain an optional interface for importing styles used to add formatting properties to cell values.
- Returns:
pointer to the styles interface, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_reference_resolver *get_reference_resolver(formula_ref_context_t cxt)
Obtain an optional interface for resolving cell and cell-range references from string values.
- Parameters:
cxt – context in which the formula expression containing the references to be resolved occurs.
- Returns:
pointer to the reference resolve interfance, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_pivot_cache_definition *create_pivot_cache_definition(pivot_cache_id_t cache_id)
Obtain an optional interface for pivot cache definition import for a specified cache ID. In case a pivot cache alrady exists for the passed ID, the implementor should overwrite the existing cache with a brand-new cache instance.
- Parameters:
cache_id – numeric ID associated with the pivot cache.
- Returns:
pointer to the pivot cache interface, or a
nullptr
if the implementor doesn’t support pivot cache import.
-
virtual import_pivot_cache_records *create_pivot_cache_records(pivot_cache_id_t cache_id)
Obtain an optional interface for pivot cache records import for a specified cache ID.
- Parameters:
cache_id – numeric ID associated with the pivot cache.
- Returns:
pointer to the pivot cache records interface, or a
nullptr
if the implementor doesn’t support pivot cache import.
-
virtual import_sheet *append_sheet(sheet_t sheet_index, std::string_view name) = 0
Append a sheet with a specified sheet position index and name and return an interface for importing its content. The implementor can use a call to this method as a signal to create and append a new sheet instance to the document store.
- Parameters:
sheet_index – position index of the sheet to be appended. It is 0-based i.e. the first sheet to be appended will have an index value of 0.
name – sheet name.
- Returns:
pointer to the sheet instance, or a
nullptr
if the implementor doesn’t support it. Note, however, that if the implementor doesn’t support this interface, no cell values will get imported.
-
virtual import_sheet *get_sheet(std::string_view name) = 0
Get a sheet instance by name. The import filter may use this method to get access to an existing sheet after it has been created.
- Parameters:
name – sheet name.
- Returns:
pointer to the sheet instance whose name matches the name passed to this method. It returns a
nullptr
if no sheet instance exists by the specified name.
-
virtual import_sheet *get_sheet(sheet_t sheet_index) = 0
Retrieve a sheet instance by a specified numerical sheet index.
- Parameters:
sheet_index – sheet index.
- Returns:
pointer to the sheet instance, or a
nullptr
if no sheet instance exists at the specified sheet index.
-
virtual void finalize() = 0
The import filter calls this method after completing its import, to give the implementor a chance to perform post-processing.
-
virtual ~import_factory()
-
class import_global_settings
Interface for specifying global settings that may affect how the implementor should process certain values and properties.
Public Functions
-
virtual ~import_global_settings()
-
virtual void set_origin_date(int year, int month, int day) = 0
Set the date that is to be represented by a value of 0. All date values should be represented relative to this date. This may affect, for instance, values imported via import_sheet::set_date_time().
- Parameters:
year – 1-based value representing year
month – 1-based value representing month, varying from 1 through 12.
day – 1-based value representing day, varying from 1 through 31.
-
virtual void set_default_formula_grammar(formula_grammar_t grammar) = 0
Set the formula grammar to be used globally when parsing formulas if the grammar is not specified. This grammar should also be used when parsing range strings associated with shared formula ranges, array formula ranges, autofilter ranges etc.
Note that the import filter may specify what formula grammar to use locally when importing formula expressions for cells via import_formula::set_formula(), in which case the implementor should honor that one instead.
- Parameters:
grammar – default formula grammar to use globally unless otherwise specified.
-
virtual formula_grammar_t get_default_formula_grammar() const = 0
Get current global formula grammar. The import filter may use this method to query the current global formula grammar.
- Returns:
current default formula grammar.
-
virtual void set_character_set(character_set_t charset) = 0
Set the character set to use when parsing encoded string values.
- Parameters:
charset – character set to use when parsing encoded string values.
-
virtual ~import_global_settings()
Interface for importing raw string values shared in string cells. String values may be either with or without formatted segments.
To insert an unformatted string, simply use either append() or add() method. The string will then be immediately pushed to the pool.
To insert a string with mixed formatted segments, you need to first use one or more of:
import_shared_strings* iface = ...; // store a segment with specific font, size and boldness. iface->set_segment_font_name("FreeMono"); iface->set_segment_font_size(14); iface->set_segment_font_bold(true); iface->append_segment("a bold and big segment"); // store an unformatted segment. iface->append_segment(" followed by "); // store a segment with smaller, italic font. iface->set_segment_font_size(7); iface->set_segment_font_italic(true); iface->append_segment("a small and italic segment"); iface->commit_segments(); // commit the whole formatted string to the pool.
Public Functions
Append a new string to the sequence of strings. Order of insertion determines the numerical ID value of an inserted string. Note that this method assumes that the caller knows the string being appended is not yet in the pool; it does not check on duplicated strings.
- Parameters:
s – string to append to the pool.
- Returns:
ID of the inserted string.
Similar to the append() method, it adds a new string to the string pool; however, this method checks if the string being added is already in the pool before each insertion, to avoid duplicated strings.
- Parameters:
s – string to add to the pool.
- Returns:
ID of the inserted string.
Set the index of a font to apply to the current format attributes. Refer to the import_font_style interface on how to obtain a font index. Note that a single font index is associated with multiple font-related formatting attributes, such as font name, font color, boldness and italics.
- Parameters:
font_index – positive integer representing the font to use.
Set whether or not to make the current segment bold.
- Parameters:
b – true if it’s bold, false otherwise.
Set whether or not to make the current segment italic.
- Parameters:
b – true if it’s italic, false otherwise.
Set the name of a font to the current segment.
- Parameters:
s – font name.
Set a font size to the current segment.
- Parameters:
point – font size in points.
Set the color of a font in ARGB format to the current segment.
- Parameters:
alpha – alpha component value (0-255).
red – red component value (0-255).
green – green component value (0-255).
blue – blue component value (0-255).
Push the current string segment to the buffer. Any formatting attributes defined so far will be applied to this segment.
- Parameters:
s – string value for the segment.
Store the entire formatted string in the current buffer to the shared strings pool. The implementor may choose to unconditionally append the string to the pool, or choose to find an existing duplicate and reuse it instead.
- Returns:
ID of the string just inserted, or the ID of an existing string with identical formatting.
-
class import_named_expression
Interface for importing named expressions or ranges.
This interface has two different methods for defining named expressions:
Generally speaking, set_named_expression() can be used to define both named expression and named range. However, the implementor may choose to apply a different syntax rule to parse an expression passed to set_named_range(), depending on the formula grammar defined via import_global_settings::set_default_formula_grammar(). For instance, the OpenDocument Spreadsheet format is known to use different syntax rules between named expressions and named ranges.A named range is a special case of a named expression where the expression consists of only one single cell range token.
Here is a code example of how a named expression is defined:
import_named_expression* iface = ...; // set the A1 on the first sheet as its origin (optional). src_address_t origin{0, 0, 0}; iface->set_base_position(origin); iface->set_named_expression("MyExpression", "SUM(A1:B10)+SUM(D1:D4)"); iface->commit();
Replace the above set_named_expression() call with set_named_range() if you wish to define a named range instead.
Public Functions
-
virtual ~import_named_expression()
-
virtual void set_base_position(const src_address_t &pos) = 0
Specify an optional base position, or origin, from which to evaluate a named expression. If not specified, the implementor should use the top-left corner cell on the first sheet as its origin.
- Parameters:
pos – cell position to be used as the origin.
-
virtual void set_named_expression(std::string_view name, std::string_view expression) = 0
Set a named expression to the buffer.
- Parameters:
name – name of the expression to be defined.
expression – expression to be associated with the name.
-
virtual void set_named_range(std::string_view name, std::string_view range) = 0
Set a named range to the buffer.
- Parameters:
name – name of the expression to be defined.
range – range to be associated with the name.
-
virtual void commit() = 0
Commit the named expression or range currently in the buffer to the document.
-
virtual ~import_named_expression()
-
class import_reference_resolver
This is an interface to allow the implementor to provide its own reference address parsers, for both single cell references and cell range references. The implementor may choose to provide a different parser depending of the type of formula_ref_context_t argument given to the import_factory::get_reference_resolver() call.
Public Functions
-
virtual ~import_reference_resolver()
-
virtual src_address_t resolve_address(std::string_view address) = 0
Resolve a textural representation of a single cell address.
- Parameters:
address – single cell address string.
- Throws:
orcus::invalid_arg_error – the string is not a valid single cell addreess.
- Returns:
structure containing the column and row positions of the address.
-
virtual src_range_t resolve_range(std::string_view range) = 0
Resolve a textural representation of a range address. Note that a string representing a valid single cell address should be considered a valid range address.
- Parameters:
range – range address string.
- Throws:
invalid_arg_error – the string is not a valid range addreess.
- Returns:
structure containing the start and end positions of the range address.
-
virtual ~import_reference_resolver()