readOrg {orgutils}R Documentation

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)

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

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.

Value

a data.frame

Author(s)

Enrico Schumann

References

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

See Also

read.csv

Examples


## 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")
[Package orgutils version 0.5-3 Index]