Title:	Basic R Input Output
Version:	1.1.5
Description:	Functions to handle basic input output, these functions always read and write UTF-8 (8-bit Unicode Transformation Format) files and provide more explicit control over line endings.
License:	MIT + file LICENSE
URL:	https://brio.r-lib.org, https://github.com/r-lib/brio
BugReports:	https://github.com/r-lib/brio/issues
Depends:	R (≥ 3.6)
Suggests:	covr, testthat (≥ 3.0.0)
Config/Needs/website:	tidyverse/tidytemplate
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.2.3
NeedsCompilation:	yes
Packaged:	2024-04-24 18:51:29 UTC; gaborcsardi
Author:	Jim Hester [aut], Gábor Csárdi [aut, cre], Posit Software, PBC [cph, fnd]
Maintainer:	Gábor Csárdi <csardi.gabor@gmail.com>
Repository:	CRAN
Date/Publication:	2024-04-24 19:20:07 UTC

brio: Basic R Input Output

Description

Functions to handle basic input output, these functions always read and write UTF-8 (8-bit Unicode Transformation Format) files and provide more explicit control over line endings.

Author(s)

Maintainer: Gábor Csárdi csardi.gabor@gmail.com

Authors:

• Jim Hester (ORCID)

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://brio.r-lib.org

• https://github.com/r-lib/brio

• Report bugs at https://github.com/r-lib/brio/issues

Retrieve the type of line endings used by a file

Description

Retrieve the type of line endings used by a file

Usage

file_line_endings(path)

Arguments

Value

The line endings used, one of

• '\n' - if the file uses Unix line endings

• '\r\n' - if the file uses Windows line endings

• NA - if it cannot be determined

Examples

tf1 <- tempfile()
tf2 <- tempfile()
write_lines("foo", tf1, eol = "\n")
write_lines("bar", tf2, eol = "\r\n")

file_line_endings(tf1)
file_line_endings(tf2)

unlink(c(tf1, tf2))

Read text lines from a file

Description

This is a drop in replacement for base::readLines() with restricted functionality. Compared to base::readLines() it:

• Only works with file paths, not connections.

• Assumes the files are always UTF-8 encoded.

• Does not warn or skip embedded nulls, they will likely crash R.

• Does not warn if the file is missing the end of line character.

• The arguments ok, warn, encoding and skipNul are ignored, with a warning.

Usage

readLines(con, n = -1, ok, warn, encoding, skipNul)

Arguments

Value

A UTF-8 encoded character vector of the lines in the file.

See Also

writeLines()

Examples

authors_file <- file.path(R.home("doc"), "AUTHORS")
data <- readLines(authors_file)

# Trying to use connections throws an error
con <- file(authors_file)
try(readLines(con))
close(con)

# Trying to use unsupported args throws a warning
data <- readLines(authors_file, encoding = "UTF-16")

Read an entire file

Description

read_file() reads an entire file into a single character vector. read_file_raw() reads an entire file into a raw vector.

Usage

read_file(path)

read_file_raw(path)

Arguments

Details

read_file() assumes the file has a UTF-8 encoding.

Value

• read_file(): A length 1 character vector.

• read_file_raw(): A raw vector.

Examples

authors_file <- file.path(R.home("doc"), "AUTHORS")
data <- read_file(authors_file)
data_raw <- read_file_raw(authors_file)
identical(data, rawToChar(data_raw))

Read text lines from a file

Description

The file is assumed to be UTF-8 and the resulting text has its encoding set as such.

Usage

read_lines(path, n = -1)

Arguments

Details

Both '\r\n' and '\n' are treated as a newline.

Value

A UTF-8 encoded character vector of the lines in the file.

Examples

authors_file <- file.path(R.home("doc"), "AUTHORS")
data <- read_lines(authors_file)

Write lines to a file

Description

This is a drop in replacement for base::writeLines() with restricted functionality. Compared to base::writeLines() it:

• Only works with file paths, not connections.

• Uses enc2utf8() to convert text() to UTF-8 before writing.

• Uses sep unconditionally as the line ending, regardless of platform.

• The useBytes argument is ignored, with a warning.

Usage

writeLines(text, con, sep = "\n", useBytes)

Arguments

Value

The UTF-8 encoded input text (invisibly).

See Also

readLines()

Examples

tf <- tempfile()

writeLines(rownames(mtcars), tf)

# Trying to use connections throws an error
con <- file(tf)
try(writeLines(con))
close(con)

# Trying to use unsupported args throws a warning
writeLines(rownames(mtcars), tf, useBytes = TRUE)

unlink(tf)

Write data to a file

Description

This function differs from write_lines() in that it writes the data in text directly, without any checking or adding any newlines.

Usage

write_file(text, path)

Arguments

Value

The UTF-8 encoded input text (invisibly).

Examples

tf <- tempfile()

write_file("some data\n", tf)

unlink(tf)

Write data to a file

Description

This function differs from write_lines() in that it writes the data in text directly, without any checking or adding any newlines.

Usage

write_file_raw(raw, path)

Arguments

Examples

tf <- tempfile()

write_file_raw(as.raw(c(0x66, 0x6f, 0x6f, 0x0, 0x62, 0x61, 0x72)), tf)

unlink(tf)

Write lines to a file

Description

The text is converted to UTF-8 encoding before writing.

Usage

write_lines(text, path, eol = "\n")

Arguments

Details

The files are opened in binary mode, so they always use exactly the string given in eol as the line separator.

To write a file with windows line endings use write_lines(eol = "\r\n")

Value

The UTF-8 encoded input text (invisibly).

Examples

tf <- tempfile()

write_lines(rownames(mtcars), tf)

# Write with Windows style line endings
write_lines(rownames(mtcars), tf, eol = "\r\n")

unlink(tf)