orgutils (version 0.5-2)

readOrg: Read Org Tables

Description

Read an Org table from a file.

Usage

readOrg(file, header = TRUE, dec = ".", comment.char = "",
        encoding = "", strip.white = TRUE,
        stringsAsFactors = FALSE,
        table.name = NULL, text,
        table.missing = NULL, ...,
        strip.format = TRUE,
        strip.horiz.rules = TRUE,
        collapse.header = FALSE)

Value

a data.frame

Arguments

file

character

header

logical: If TRUE, and collapse.header is FALSE, the first row of the table is used for column names (strip.horiz.rules determines whether initial rules are removed first).

dec

character; see read.table

comment.char

character; see read.table

encoding

string; see read.table

strip.white

logical; see read.table

strip.format

logical: strip rows of format instructions, such as <c>

strip.horiz.rules

logical: string horizontal rules from table

collapse.header

logical: if TRUE, all rows before the first horizontal rule are considered table headers (as defined in the Org manual)

stringsAsFactors

logical: note that the default FALSE differs from read.csv

table.name

character: a regex; the name of the table to read.

text

character: if file is not supplied, text is read via textConnection

table.missing

what to do if a table specified by table.name is not found. Default is to return NULL. Set to string "stop" to throw an error.

...

further arguments

Author

Enrico Schumann

Details

Org tables are very human-readable plain-text tables that look like

| Column1 | Column2 |
|---------+---------|
|       1 |       2 |
|       3 |       4 |

A line that starts with ‘|’ (after optional whitespace) is considered a table row; a line that starts with ‘|-’ (after optional whitespace) is a horizontal rule. Rows before the first horizontal rule are header lines (see the Org manual).

Depending on the settings of strip.format and strip.horiz.rules, format instructions such as <5> and are discarded. Then the function uses read.csv to read the remainder of the file/table.

When table.name is specified, the function looks for a line that starts with #+NAME: <table.name> and reads the table that follows that line.

For empty files, readOrg behaves like read.csv: when completely empty, it fails; when headers are found, a zero-row data.frame is returned.

References

Org manual https://orgmode.org/manual/Tables.html

See Also

read.csv

Examples

# \donttest{
## create an Org file with a table and read the table
tmp <-
"#+TITLE: A Table

Next comes a table.

#+name: test_table
| a | b |
|---+---|
| 1 | 2 |
| 3 | 4 |

That was a table.
"

fname <- tempfile("testfile", fileext = ".org")
writeLines(tmp, fname)

library("orgutils")
readOrg(fname, table.name = "test_table")
# }