Skip to contents

Opens a .dtable export and returns a harbour_dtable object. The same verbs that work against a live base work against it - hb_list_tables(), hb_read_table(), hb_list_columns() - so an analysis can be written once and run either way.

Usage

hb_read_dtable(path, ..., assets = c("none", "extract"), assets_dir = NULL)

Arguments

path

Path to a .dtable file.

...

These dots are for future extensions and must be empty.

assets

Whether to extract the bundled asset/ tree. "none", the default, reads only content.json. "extract" unpacks the assets so hb_asset_path() can resolve attachment URLs to local files. An archive whose asset entries could land outside assets_dir - a name that is absolute or has a .. component, between slashes or backslashes, or an entry that is a symbolic link - is refused before anything is extracted. Assets whose names differ only in case may not all be extracted, and a warning names them. Existing paths inside assets_dir are checked before extraction: links leading outside it or whose targets are missing are refused.

assets_dir

Where to extract assets to. Defaults to a session temporary directory. A folder that already holds an asset/ tree is refused: the next hb_write_dtable() would pack that tree as well.

Value

A harbour_dtable: a list with components content (the parsed tree), path, assets (the archive's own listing of its asset/ tree, as zip::zip_list() gives it: one row per entry, folders included), assets_dir and base_name. Note that names() on a harbour_dtable gives its table names, not these components - reach them with $ or unclass().

Details

A .dtable is a ZIP archive containing content.json, the complete base, and optionally an asset/ tree of uploaded files and images.

The parsed JSON is kept verbatim. Real exports carry fields no client would think to model - one column in the reference file holds a serialised React element - and future SeaTable releases will add more. Keeping the tree untouched is what makes hb_write_dtable() lossless; rebuilding it from a typed intermediate would quietly drop whatever harbouR did not know about.

Options

  • harbouR.dtable_tz: the time zone of the SeaTable server a file comes from, such as "Europe/Berlin". A server stores a date-time as the time it shows, with no offset, and its export keeps it so; such a value is read in this zone. Unset, it is read as UTC, with a warning once a session. Date-only cells, and values that carry an offset, need no zone.

  • harbouR.max_dtable_bytes: how large content.json, plus the assets when they are extracted, may be once unpacked. Default 4 GiB. A larger file is refused before anything is read, since a small archive can unpack to enough to fill memory or disk.

Examples

path <- system.file("extdata", "example.dtable", package = "harbouR")
base <- hb_read_dtable(path)
base
#> 
#> ── <harbour_dtable> ────────────────────────────────────────────────────────────
#> • base : "example"
#> • tables : 2
#> • rows : 4
#> • assets : 2
#> 
#> - Samples (27 cols, 2 rows)
#> - Reference (2 cols, 2 rows)

hb_list_tables(base)
#> # A tibble: 2 × 4
#>   name      n_rows n_columns n_views
#>   <chr>      <int>     <int>   <int>
#> 1 Samples        2        27       1
#> 2 Reference      2         2       1
hb_read_table(base, "Samples")
#> # A tibble: 2 × 28
#>   Name  Notes           Concentration Share  Cost Preis Runtime Rating Consented
#>   <chr> <chr>                   <dbl> <dbl> <dbl> <dbl>   <dbl>  <int> <lgl>    
#> 1 S-001 A plain **mark…      0.000587  0.42  20.0  17.5    3661      4 TRUE     
#> 2 S-002 Rendered elsew…      8.1      NA     NA    NA        NA     NA FALSE    
#> # ℹ 19 more variables: Collected <dttm>, Status <chr>, Tags <list>,
#> #   Collaborators <list>, Photos <list>, Reports <list>, Where <list>,
#> #   Homepage <chr>, Contact <chr>, `Temperatur (°C)` <dbl>, Doubled <chr>,
#> #   Ref <chr>, `Created by` <chr>, `Changed by` <chr>, Created <dttm>,
#> #   Changed <dttm>, Action <list>, Signature <list>, `_id` <chr>