Package {xmlrectr}

xmlrectr: generic XML rectangling

Description

Convert arbitrary XML into canonical node tables and analysis-friendly rectangles with explicit profiles, bounded streaming, optional native acceleration, and automatic record-level parallel execution.

Details

The normal workflow is proposal, review, profile, compilation, and rectangling. For exploratory work, the analyst layer provides a self-contained single-table projection. See the package README and vignettes for complete workflows.

See Also

propose_xml_profile(), xml_profile(), rectangle_xml(), rectangle_xml_analyst()

Coerce a portable object to an XML profile

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

as_xml_profile(x)

Arguments

Value

An object of class xml_profile. The returned named list is a validated portable profile representation suitable for compilation, serialization, and reuse.

See Also

xml_profile(), rectangle_xml()

Compile a profile into an executable rectangle specification

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

compile_xml_profile(
profile,
sample,
whitespace = c("drop_blank", "preserve"))

Arguments

Value

An object of class xml_rect_spec. It is an executable, namespace-aware rectangle specification resolved against sample and includes the originating validated xml_profile in its profile component.

See Also

xml_profile(), rectangle_xml()

Inspect XML structure before defining a rectangle

Description

Work with the canonical XML-node representation that preserves node identity, parentage, source order, namespaces, node types and scalar values.

Usage

inspect_xml(
x,
whitespace = c("drop_blank", "preserve"))

Arguments

Value

An object of class xml_structure, implemented as a list containing the source, whitespace policy, canonical node table, namespace-aware structural index, and likely record paths. It represents reviewable structural evidence about the XML sample.

See Also

xml_profile(), rectangle_xml()

Inspect advisory XSD evidence

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

inspect_xsd(xsd)

Arguments

Details

This is deliberately an advisory XSD inspection layer, not a complete XSD validator or resolver.

Value

An object of class xml_xsd_inspection, implemented as a list containing the schema source, target namespace, a declaration tibble, and explicit inspection limitations. It represents advisory evidence from directly declared XSD elements and attributes rather than a complete schema validation result.

See Also

xml_profile(), rectangle_xml()

Create a lower-level rectangle specification

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

make_rectangle(
structure,
one_row_per = NULL,
namespace = NULL,
identify_by = NULL,
fields = NULL,
types = NULL,
representation = c("auto", "wide", "long"))

Arguments

Value

An object of class xml_rect_spec, implemented as a list describing the resolved record path, identifier rule, representation, repeated paths, field mapping, and field catalogue. It is an executable rectangle specification compiled from the inspected structure.

See Also

xml_profile(), rectangle_xml()

Propose candidate rows, identifiers and fields

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

propose_xml_profile(
sample,
rows = NULL,
namespace = NULL,
xsd = NULL,
whitespace = c("drop_blank", "preserve"))

Arguments

Details

The returned proposal is review-only and is not an executable profile.

Value

An object of class xml_profile_proposal, implemented as a review-only list containing ranked row candidates, identifier candidates, field candidates, optional XSD evidence, and a portable profile template when a row structure can be proposed. It is not an executable xml_profile.

See Also

xml_profile(), rectangle_xml()

Read an XML profile from JSON or YAML

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

read_xml_profile(
file,
format = c("auto", "json", "yaml"))

Arguments

Value

An object of class xml_profile, reconstructed and validated from the serialized JSON or YAML representation.

See Also

xml_profile(), rectangle_xml()

Create an explicit rectangle specification

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

rectangle_spec(
sample,
one_row_per = NULL,
namespace = NULL,
identify_by = NULL,
fields = NULL,
types = NULL,
representation = c("auto", "wide", "long"),
whitespace = c("drop_blank", "preserve"))

Arguments

Value

An object of class xml_rect_spec. It is the executable rectangle specification obtained by inspecting sample and resolving the requested row, identifier, field, type, and representation choices.

See Also

xml_profile(), rectangle_xml()

Read and rectangle an XML file

Description

Apply an explicit profile/specification while preserving repeated values and output order. Parallelism is an execution option of the same public workflow.

Usage

rectangle_xml(
file,
spec,
whitespace = NULL,
parallel = FALSE,
workers = NULL,
strategy = "auto",
chunk_records = NULL,
task_records = NULL,
progress = FALSE)

Arguments

Details

Use parallel = FALSE for the exact sequential path, parallel = TRUE to request tuned parallel defaults, or parallel = "auto" to let the engine avoid parallel overhead on small in-memory workloads.

Value

A tibble containing the rectangular analytical result for file, with the same single-table atomic-column contract as xml_rectangle(). Its columns and wide/long structure are determined by the supplied profile or compiled specification.

See Also

xml_profile(), rectangle_xml()

Create an analyst-oriented table directly from XML

Description

Create or work with the exploratory single-table analyst projection, which keeps universal xml_* provenance/entity columns alongside atomic analytical values.

Usage

rectangle_xml_analyst(
file,
whitespace = c("drop_blank", "preserve"),
infer_types = TRUE,
include_misc = TRUE)

Arguments

Value

A tibble in the same self-contained analyst-table format as xml_analyst_table(): one row per emitted XML entity occurrence, xml_* provenance/entity columns, atomic analytical columns, and the xml_analyst_metadata attribute.

See Also

xml_profile(), rectangle_xml()

Write the analyst-oriented XML table to CSV

Description

Create or work with the exploratory single-table analyst projection, which keeps universal xml_* provenance/entity columns alongside atomic analytical values.

Usage

rectangle_xml_analyst_csv(
file,
output,
whitespace = c("drop_blank", "preserve"),
infer_types = TRUE,
include_misc = TRUE,
na = "\\N",
overwrite = FALSE)

Arguments

Value

Invisibly, the analyst-table tibble that was written to output. The side effect is transactional publication of that same table as one CSV file.

See Also

xml_profile(), rectangle_xml()

Write the analyst-oriented XML table to Parquet

Description

Create or work with the exploratory single-table analyst projection, which keeps universal xml_* provenance/entity columns alongside atomic analytical values.

Usage

rectangle_xml_analyst_parquet(
file,
output,
whitespace = c("drop_blank", "preserve"),
infer_types = TRUE,
include_misc = TRUE,
overwrite = FALSE,
compression = "snappy")

Arguments

Value

Invisibly, the analyst-table tibble that was written to output. The side effect is transactional publication of that same table as one Parquet file.

See Also

xml_profile(), rectangle_xml()

Rectangle XML to a staged CSV file

Description

Apply an explicit profile/specification while preserving repeated values and output order. Parallelism is an execution option of the same public workflow.

Usage

rectangle_xml_csv(
file,
spec,
output,
overwrite = FALSE,
document_id = NULL,
whitespace = NULL,
chunk_rows = 100000L,
batch_rows = 100000L,
id_check = c("memory", "none"),
parallel = FALSE,
workers = NULL,
strategy = "auto",
chunk_records = NULL,
task_records = NULL)

Arguments

Details

The streaming parser and record-boundary detection remain coordinator-side. Parallel workers receive only complete independent record subtrees.

Value

Invisibly, a one-row tibble of streaming execution statistics augmented with output_file and output_format. The main side effect is transactional publication of the completed CSV at output.

See Also

xml_profile(), rectangle_xml()

Read and rectangle XML with explicit parallel execution

Description

Lower-level explicit parallel entry point retained for diagnostics, regression tests and advanced tuning. Routine use should normally use the corresponding ordinary function with the parallel argument.

Usage

rectangle_xml_parallel(
file,
spec,
whitespace = NULL,
workers = NULL,
strategy = c("shared_chunk", "parallel_chunks"),
chunk_records = NULL,
task_records = NULL,
progress = FALSE)

Arguments

Value

A tibble containing the same rectangular analytical result and atomic-column structure as rectangle_xml(), after reading the XML file and executing the compiled/profile rectangle in parallel.

See Also

xml_profile(), rectangle_xml()

Rectangle XML to a staged Parquet dataset

Description

Apply an explicit profile/specification while preserving repeated values and output order. Parallelism is an execution option of the same public workflow.

Usage

rectangle_xml_parquet(
file,
spec,
output_dir,
overwrite = FALSE,
compression = "snappy",
document_id = NULL,
whitespace = NULL,
chunk_rows = 100000L,
batch_rows = 100000L,
id_check = c("memory", "none"),
parallel = FALSE,
workers = NULL,
strategy = "auto",
chunk_records = NULL,
task_records = NULL)

Arguments

Details

The streaming parser and record-boundary detection remain coordinator-side. Parallel workers receive only complete independent record subtrees.

Value

Invisibly, a one-row tibble of streaming execution statistics augmented with the published output directory, format, number of Parquet parts, and compression setting. The main side effect is transactional publication of the completed Parquet dataset.

See Also

xml_profile(), rectangle_xml()

Review a compiled rectangle specification

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

review_rectangle(spec)

Arguments

Value

A tibble giving the atomic output-field mapping of an xml_rect_spec. It reports each output name, source, declared type, value kind, owning entity, whether it lies under repetition, and its observed maximum multiplicity per record.

See Also

xml_profile(), rectangle_xml()

Review one part of an XML profile proposal

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

review_xml_proposal(
proposal,
what = c("rows", "ids", "fields", "xsd"))

Arguments

Value

A tibble containing the requested review section of an xml_profile_proposal. Depending on what, it contains row candidates, identifier candidates, field candidates, or XSD declarations, with internal matching keys removed from the user-facing candidate tables.

See Also

xml_profile(), rectangle_xml()

Validate the canonical XML node-table contract

Description

Work with the canonical XML-node representation that preserves node identity, parentage, source order, namespaces, node types and scalar values.

Usage

validate_xml_nodes(nodes)

Arguments

Value

Invisibly returns TRUE when nodes satisfies the canonical node-table invariants. The function otherwise stops with an error describing the violated invariant.

See Also

xml_profile(), rectangle_xml()

Write an XML profile to JSON or YAML

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

write_xml_profile(
profile,
file,
format = c("auto", "json", "yaml"),
overwrite = FALSE)

Arguments

Value

Invisibly, a character scalar giving the normalized path of the JSON or YAML file that was written. Writing the serialized profile is the function's side effect.

See Also

xml_profile(), rectangle_xml()

Expand analyst-table entity context

Description

Create or work with the exploratory single-table analyst projection, which keeps universal xml_* provenance/entity columns alongside atomic analytical values.

Usage

xml_analyst_expand_context(x, entity = NULL, levels = Inf)

Arguments

Value

A tibble with the same columns as x, optionally filtered by entity, in which missing analytical cells are filled from owning fields of the requested ancestor levels. Provenance/entity columns are retained so the expanded values remain traceable to the analyst-table hierarchy.

See Also

xml_profile(), rectangle_xml()

Project canonical XML into one analyst-oriented table

Description

Create or work with the exploratory single-table analyst projection, which keeps universal xml_* provenance/entity columns alongside atomic analytical values.

Usage

xml_analyst_table(
nodes,
infer_types = TRUE,
include_misc = TRUE,
.validate_nodes = TRUE)

Arguments

Value

A tibble representing one self-contained analyst-oriented table. Each row is an XML entity occurrence with xml_* provenance/entity columns plus atomic analytical value columns; the table also carries an xml_analyst_metadata attribute containing entity/path mappings, column sources, amplification diagnostics, and audit information.

See Also

xml_profile(), rectangle_xml()

Return direct canonical children of XML nodes

Description

Work with the canonical XML-node representation that preserves node identity, parentage, source order, namespaces, node types and scalar values.

Usage

xml_node_children(
nodes,
node_id,
document_id = NULL,
include_attributes = FALSE)

Arguments

Value

A tibble containing the direct children of node_id, using the canonical node-table columns. Rows are returned in XML content order, with attributes optionally included ahead of content children.

See Also

xml_profile(), rectangle_xml()

Return the canonical XML node-table schema

Description

Work with the canonical XML-node representation that preserves node identity, parentage, source order, namespaces, node types and scalar values.

Usage

xml_nodes_schema()

Value

A zero-row tibble with the 12 canonical XML node-table columns and their stable atomic types. It is the executable schema used to initialize and validate canonical node output.

See Also

xml_profile(), rectangle_xml()

Create a human-facing reusable XML profile

Description

Discover structural evidence and define a reviewable, reusable extraction contract. Proposals and XSD evidence are advisory rather than silently executable.

Usage

xml_profile(
rows,
id = NULL,
fields = NULL,
types = NULL,
namespace = NULL,
layout = c("safe", "wide", "long"))

Arguments

Value

An object of class xml_profile, implemented as a named list containing the portable user choices rows, id, fields, types, namespace, and layout together with a profile version. It does not contain sample-specific internal path keys.

See Also

xml_profile(), rectangle_xml()

Rectangle a canonical XML node table

Description

Apply an explicit profile/specification while preserving repeated values and output order. Parallelism is an execution option of the same public workflow.

Usage

xml_rectangle(
nodes,
spec,
parallel = FALSE,
workers = NULL,
strategy = "auto",
chunk_records = NULL,
task_records = NULL,
progress = FALSE)

Arguments

Details

Use parallel = FALSE for the exact sequential path, parallel = TRUE to request tuned parallel defaults, or parallel = "auto" to let the engine avoid parallel overhead on small in-memory workloads.

Value

A tibble containing the rectangular analytical result defined by spec. The table is always a single data frame with atomic columns; its exact columns and wide/long structure are determined by the compiled specification while preserving record and repetition semantics.

See Also

xml_profile(), rectangle_xml()

Rectangle canonical nodes with explicit parallel execution

Description

Lower-level explicit parallel entry point retained for diagnostics, regression tests and advanced tuning. Routine use should normally use the corresponding ordinary function with the parallel argument.

Usage

xml_rectangle_parallel(
nodes,
spec,
workers = NULL,
strategy = c("shared_chunk", "parallel_chunks"),
chunk_records = NULL,
task_records = NULL,
progress = FALSE)

Arguments

Value

A tibble containing the same rectangular analytical result and atomic-column structure as xml_rectangle(), computed with explicit record-level parallel execution.

See Also

xml_profile(), rectangle_xml()

Stream canonical XML node batches

Description

Work with the canonical XML-node representation that preserves node identity, parentage, source order, namespaces, node types and scalar values.

Usage

xml_stream_nodes(
file,
callback,
document_id = NULL,
whitespace = c("preserve", "drop_blank"),
chunk_rows = 100000L)

Arguments

Value

Invisibly, a one-row tibble containing document_id, total node_count, and emitted chunk_count. The main side effect is repeated invocation of callback with bounded canonical node-table chunks.

See Also

xml_profile(), rectangle_xml()

Stream complete XML records through a rectangle callback

Description

Apply an explicit profile/specification while preserving repeated values and output order. Parallelism is an execution option of the same public workflow.

Usage

xml_stream_rectangle(
file,
spec,
callback,
document_id = NULL,
whitespace = NULL,
chunk_rows = 100000L,
batch_rows = 100000L,
id_check = c("memory", "none"),
parallel = FALSE,
workers = NULL,
strategy = "auto",
chunk_records = NULL,
task_records = NULL)

Arguments

Details

The streaming parser and record-boundary detection remain coordinator-side. Parallel workers receive only complete independent record subtrees.

Value

Invisibly, a one-row tibble of streaming execution statistics, including document/node counts, record count, emitted result rows and chunks, maximum record size, and identifier-check status; parallel execution also reports scheduling statistics. Rectangular result batches are delivered through callback as the main side effect.

See Also

xml_profile(), rectangle_xml()

Stream XML records with explicit parallel execution

Description

Lower-level explicit parallel entry point retained for diagnostics, regression tests and advanced tuning. Routine use should normally use the corresponding ordinary function with the parallel argument.

Usage

xml_stream_rectangle_parallel(
file,
spec,
callback,
document_id = NULL,
whitespace = NULL,
chunk_rows = 100000L,
batch_rows = 100000L,
id_check = c("memory", "none"),
workers = NULL,
strategy = c("shared_chunk", "parallel_chunks"),
chunk_records = NULL,
task_records = NULL)

Arguments

Value

Invisibly, a one-row tibble of streaming and parallel execution statistics: document/node counts, parser chunks, record and result counts, maximum record size, identifier-check status, strategy, worker count, parallel chunk/task counts, buffering, and chunk/task sizes. Rectangular result batches are delivered through callback as the main side effect.

See Also

xml_profile(), rectangle_xml()

Read XML text into the canonical node table

Description

Work with the canonical XML-node representation that preserves node identity, parentage, source order, namespaces, node types and scalar values.

Usage

xml_text_to_nodes_memory(
text,
document_id = "inline-xml",
whitespace = c("preserve", "drop_blank"),
initial_capacity = 1024L)

Arguments

Value

A tibble with one row per retained node in the supplied XML text and the 12 canonical node-table columns describing document identity, tree position, node type, names, namespace information, and scalar value.

See Also

xml_profile(), rectangle_xml()

Read an XML file into the canonical node table

Description

Work with the canonical XML-node representation that preserves node identity, parentage, source order, namespaces, node types and scalar values.

Usage

xml_to_nodes_memory(
file,
document_id = NULL,
whitespace = c("preserve", "drop_blank"),
initial_capacity = 1024L)

Arguments

Value

A tibble with one row per retained XML node and the 12 canonical node-table columns describing document identity, tree position, node type, names, namespace information, and scalar value.

See Also

xml_profile(), rectangle_xml()

Read XML with the sequential streaming canonical engine

Description

Work with the canonical XML-node representation that preserves node identity, parentage, source order, namespaces, node types and scalar values.

Usage

xml_to_nodes_stream(
file,
document_id = NULL,
whitespace = c("preserve", "drop_blank"),
chunk_rows = 100000L)

Arguments

Value

A complete canonical XML node-table tibble assembled from the streaming reader, with one row per retained XML node and the same 12 columns and types as xml_nodes_schema().

See Also

xml_profile(), rectangle_xml()