Convert array-of-objects to tabular representation

Description

Convert array-of-objects to tabular representation

Usage

as_tabular_toon(x, strict = TRUE, warn = TRUE)

Arguments

Details

In permissive mode:

• Union schema across all records

• Missing fields filled with NA

• Type promotion to accommodate all values

Value

A data.frame suitable for write_toon_df().

Examples

# Convert array of objects to data.frame
records <- list(
  list(name = "Alice", age = 30),
  list(name = "Bob", age = 25)
)
df <- as_tabular_toon(records)

Assert TOON validity

Description

Assert TOON validity

Usage

assert_toon(
  x,
  is_file = FALSE,
  strict = TRUE,
  allow_comments = TRUE,
  allow_duplicate_keys = TRUE
)

Arguments

Details

Throws toonlite_parse_error condition if invalid, with attached location and snippet information.

Value

Invisibly returns TRUE if valid.

Examples

# Valid TOON (returns invisibly)
assert_toon('name: "Alice"')

# Invalid TOON (throws error)
## Not run: 
assert_toon('invalid: [')

## End(Not run)

toonlite error and warning conditions

Description

Functions for creating and signaling toonlite-specific conditions.

TOON Conversion Functions

Description

Functions for converting between TOON and other formats.

Core TOON I/O functions

Description

Functions for parsing and serializing TOON data.

Convert CSV to TOON

Description

Convert CSV to TOON

Usage

csv_to_toon(
  path_csv,
  path_toon,
  tabular = TRUE,
  strict = TRUE,
  col_types = NULL
)

Arguments

Value

Invisibly returns NULL.

Examples

## Not run: 
csv_to_toon("data.csv", "data.toon")

## End(Not run)

Convert Feather to TOON

Description

Convert Feather to TOON

Usage

feather_to_toon(path_feather, path_toon, tabular = TRUE, strict = TRUE)

Arguments

Details

Requires the arrow package. If not installed, an error is thrown.

Value

Invisibly returns NULL.

Examples

## Not run: 
feather_to_toon("data.feather", "data.toon")

## End(Not run)

Format/pretty-print TOON

Description

Format/pretty-print TOON

Usage

format_toon(
  x,
  is_file = FALSE,
  indent = 2L,
  canonical = FALSE,
  allow_comments = TRUE
)

Arguments

Value

Character scalar with formatted TOON. If is_file=TRUE, returns formatted text (does not rewrite file).

Examples

# Format with default indent
format_toon('name:"Alice"')

# Format with canonical key ordering
format_toon('b: 1\na: 2', canonical = TRUE)

Parse TOON from string

Description

Parse TOON from string

Usage

from_toon(
  text,
  strict = TRUE,
  simplify = TRUE,
  allow_comments = TRUE,
  allow_duplicate_keys = TRUE
)

Arguments

Value

R object representing the parsed TOON data:

• object -> named list

• array -> list or atomic vector (if simplified)

• primitives -> logical/integer/double/character/NULL

Examples

# Parse simple object
from_toon('name: "Alice"\nage: 30')

# Parse array
from_toon('[3]:\n  - 1\n  - 2\n  - 3')

# Parse with comments
from_toon('# comment\nkey: "value"', allow_comments = TRUE)

Convert JSON to TOON

Description

Convert JSON to TOON

Usage

json_to_toon(json, pretty = TRUE, strict = TRUE, allow_comments = TRUE)

Arguments

Details

Requires the jsonlite package. If not installed, an error is thrown.

Value

Character scalar with class "toon".

Examples

## Not run: 
toon <- json_to_toon('{"name": "Alice", "age": 30}')

## End(Not run)

Create a toonlite parse error condition

Description

Create a toonlite parse error condition

Usage

new_toonlite_parse_error(
  message,
  line = NULL,
  column = NULL,
  snippet = NULL,
  file = NULL
)

Arguments

Value

A condition object of class c("toonlite_parse_error", "error", "condition")

Create a toonlite warning condition

Description

Create a toonlite warning condition

Usage

new_toonlite_warning(message, type = "general", details = NULL)

Arguments

Value

A condition object of class c("toonlite_warning", "warning", "condition")

Create a validation error object (not thrown)

Description

Create a validation error object (not thrown)

Usage

new_validation_error(
  type,
  message,
  line = NULL,
  column = NULL,
  snippet = NULL,
  file = NULL
)

Arguments

Value

A list with error details

Convert Parquet to TOON

Description

Convert Parquet to TOON

Usage

parquet_to_toon(path_parquet, path_toon, tabular = TRUE, strict = TRUE)

Arguments

Details

Requires the arrow package. If not installed, an error is thrown.

Value

Invisibly returns NULL.

Examples

## Not run: 
parquet_to_toon("data.parquet", "data.toon")

## End(Not run)

Print method for toon class

Description

Print method for toon class

Usage

## S3 method for class 'toon'
print(x, ...)

Arguments

Value

The input x, invisibly.

Read TOON from file

Description

Read TOON from file

Usage

read_toon(
  file,
  strict = TRUE,
  simplify = TRUE,
  allow_comments = TRUE,
  allow_duplicate_keys = TRUE,
  encoding = "UTF-8"
)

Arguments

Value

R object representing the parsed TOON data.

Examples

# Read from file
## Not run: 
data <- read_toon("config.toon")

## End(Not run)

Read tabular TOON to data.frame

Description

Read tabular TOON to data.frame

Usage

read_toon_df(
  file,
  key = NULL,
  strict = TRUE,
  allow_comments = TRUE,
  allow_duplicate_keys = TRUE,
  warn = TRUE,
  col_types = NULL,
  ragged_rows = c("expand_warn", "error"),
  n_mismatch = c("warn", "error"),
  max_extra_cols = Inf
)

Arguments

Value

A base data.frame.

Examples

## Not run: 
# Read tabular TOON file
df <- read_toon_df("data.toon")

# Read nested tabular array
df <- read_toon_df("config.toon", key = "records")

## End(Not run)

Signal a toonlite parse error

Description

Signal a toonlite parse error

Usage

stop_toonlite_parse(
  message,
  line = NULL,
  column = NULL,
  snippet = NULL,
  file = NULL
)

Arguments

Streaming TOON I/O

Description

Functions for streaming TOON data in batches.

Tabular TOON I/O (data.frame)

Description

Functions for reading and writing tabular TOON data as data.frames.

Serialize R object to TOON

Description

Serialize R object to TOON

Usage

to_toon(x, pretty = TRUE, indent = 2L, strict = TRUE, allow_comments = FALSE)

Arguments

Details

Type conversions:

• factor -> character

• Date -> ISO 8601 string (YYYY-MM-DD)

• POSIXct -> ISO 8601 string (YYYY-MM-DDTHH:MM:SSZ)

• NA values -> null

Value

Character scalar with class "toon" containing the TOON representation.

Examples

# Serialize simple list
to_toon(list(name = "Alice", age = 30))

# Serialize vector
to_toon(c(1, 2, 3))

# Compact format
to_toon(list(x = 1, y = 2), pretty = FALSE)

Get TOON file info

Description

Get TOON file info

Usage

toon_info(file, allow_comments = TRUE)

Arguments

Value

A list with components:

• array_count: Integer. Number of arrays in file.

• object_count: Integer. Number of objects in file.

• has_tabular: Logical. Whether file contains tabular arrays.

• declared_rows: Integer or NA. Declared row count if tabular.

Examples

## Not run: 
info <- toon_info("data.toon")
cat("Arrays:", info$array_count, "\n")
cat("Has tabular:", info$has_tabular, "\n")

## End(Not run)

Peek at TOON file structure

Description

Peek at TOON file structure

Usage

toon_peek(file, n = 50L, allow_comments = TRUE)

Arguments

Value

A list with components:

• type: Character. Top-level type ("object", "array", "tabular_array", "unknown").

• first_keys: Character vector. First few keys if top-level is object.

• preview: Character vector. First n lines.

Examples

## Not run: 
info <- toon_peek("data.toon")
cat("Type:", info$type, "\n")
cat("Preview:\n", info$preview, sep = "\n")

## End(Not run)

Stream non-tabular array items

Description

Stream non-tabular array items

Usage

toon_stream_items(
  file,
  key = NULL,
  callback,
  batch_size = 1000L,
  strict = TRUE,
  allow_comments = TRUE,
  allow_duplicate_keys = TRUE,
  warn = TRUE,
  simplify = TRUE
)

Arguments

Value

Invisibly returns NULL.

Examples

## Not run: 
# Stream array items
toon_stream_items("items.toon",
  callback = function(batch) {
    cat("Got", length(batch), "items\n")
  }
)

## End(Not run)

Stream tabular TOON rows

Description

Stream tabular TOON rows

Usage

toon_stream_rows(
  file,
  key = NULL,
  callback,
  batch_size = 10000L,
  strict = TRUE,
  allow_comments = TRUE,
  allow_duplicate_keys = TRUE,
  warn = TRUE,
  col_types = NULL,
  ragged_rows = c("expand_warn", "error"),
  n_mismatch = c("warn", "error"),
  max_extra_cols = Inf
)

Arguments

Details

Guarantees:

• Batches are independent and may be garbage collected

• Stable column order within stream

Value

Invisibly returns NULL.

Examples

## Not run: 
# Stream large file in batches
toon_stream_rows("large.toon",
  callback = function(batch) {
    cat("Processing", nrow(batch), "rows\n")
  },
  batch_size = 10000
)

## End(Not run)

Stream write tabular rows

Description

Stream write tabular rows

Usage

toon_stream_write_rows(
  file,
  schema,
  row_source,
  batch_size = 10000L,
  indent = 2L
)

Arguments

Details

Writes a tabular TOON array without holding all rows in memory.

Value

Invisibly returns the number of rows written.

Examples

## Not run: 
# Stream write rows
i <- 0
row_source <- function() {
  i <<- i + 1
  if (i > 3) return(NULL)
  data.frame(x = i, y = i * 2)
}
toon_stream_write_rows("output.toon",
  schema = c("x", "y"),
  row_source = row_source
)

## End(Not run)

Convert TOON to CSV

Description

Convert TOON to CSV

Usage

toon_to_csv(
  path_toon,
  path_csv,
  key = NULL,
  strict = TRUE,
  allow_comments = TRUE,
  warn = TRUE
)

Arguments

Value

Invisibly returns NULL.

Examples

## Not run: 
toon_to_csv("data.toon", "data.csv")

## End(Not run)

Convert TOON to Feather

Description

Convert TOON to Feather

Usage

toon_to_feather(
  path_toon,
  path_feather,
  key = NULL,
  strict = TRUE,
  allow_comments = TRUE,
  warn = TRUE
)

Arguments

Details

Requires the arrow package. If not installed, an error is thrown.

Value

Invisibly returns NULL.

Examples

## Not run: 
toon_to_feather("data.toon", "data.feather")

## End(Not run)

Convert TOON to JSON

Description

Convert TOON to JSON

Usage

toon_to_json(toon, pretty = FALSE, strict = TRUE, allow_comments = TRUE)

Arguments

Details

Requires the jsonlite package. If not installed, an error is thrown.

Value

Character scalar containing JSON.

Examples

## Not run: 
json <- toon_to_json('name: "Alice"\nage: 30')

## End(Not run)

Convert TOON to Parquet

Description

Convert TOON to Parquet

Usage

toon_to_parquet(
  path_toon,
  path_parquet,
  key = NULL,
  strict = TRUE,
  allow_comments = TRUE,
  warn = TRUE
)

Arguments

Details

Requires the arrow package. If not installed, an error is thrown.

Value

Invisibly returns NULL.

Examples

## Not run: 
toon_to_parquet("data.toon", "data.parquet")

## End(Not run)

Validate TOON

Description

Validate TOON

Usage

validate_toon(
  x,
  is_file = FALSE,
  strict = TRUE,
  allow_comments = TRUE,
  allow_duplicate_keys = TRUE
)

Arguments

Details

Never throws unless there's an internal error (e.g., file unreadable). May warn for permissive recoveries.

Value

Logical scalar.

• TRUE if valid.

• FALSE if invalid, with attribute attr(result, "error") containing a structured error object with components: type, message, line, column, snippet, file.

Examples

# Valid TOON
validate_toon('key: "value"')

# Invalid TOON (returns FALSE with error attribute)
result <- validate_toon('key: {invalid')
if (!result) print(attr(result, "error")$message)

TOON Validation and Formatting

Description

Functions for validating and formatting TOON data.

Signal a toonlite warning

Description

Signal a toonlite warning

Usage

warn_toonlite(message, type = "general", details = NULL)

Arguments

Write R object to TOON file

Description

Write R object to TOON file

Usage

write_toon(x, file, pretty = TRUE, indent = 2L, strict = TRUE)

Arguments

Value

Invisibly returns NULL.

Examples

## Not run: 
write_toon(list(x = 1, y = 2), "output.toon")

## End(Not run)

Write data.frame to tabular TOON

Description

Write data.frame to tabular TOON

Usage

write_toon_df(
  df,
  file,
  tabular = TRUE,
  pretty = TRUE,
  indent = 2L,
  strict = TRUE
)

Arguments

Value

Invisibly returns NULL.

Examples

## Not run: 
# Write data.frame as tabular TOON
write_toon_df(mtcars[1:3, 1:4], "cars.toon")

## End(Not run)