readLines_part: readLines_part
In HanOostdijk/HOQCutil: Utilities by Han Oostdijk

readLines_part

R Documentation

readLines_part

Description

readLines_part reads the part of a text file that is delimited by two lines. A use case can be a file that contains a number of functions. While making documentation it is of course possible to include the whole file in an .Rmd chunk. By using this function one can use a more granular approach. In the Detail section one sees an example where code sections are delimited by R comment lines that start with ###HOQC_start (the first line of the section) and with ###HOQC_end (the last line of the section. The last part of these lines can contain an arbitrary name but also e.g. the name of the function that is defined. It is also possible in this way to retrieve consecutive sections (see the second example) or the whole file (see fourth example).

Usage

readLines_part(
  filename,
  suffixes = NULL,
  start_str = "HOQC_start",
  end_str = "HOQC_end",
  symbols = "###",
  warn = FALSE
)

Arguments

`filename`	Character string with the name of the file
`suffixes`	Character vector of length 1 or 2 with the suffixes of the delimitation lines or NULL, Default NULL
`start_str`	Character string with the prefix of the start delimitation line
`end_str`	Character string with the prefix of the end delimitation line
`symbols`	Character string that starts and ends a delimitation line
`warn`	Boolean value passed to readLines. See argument `warn` of readLines function. Default = FALSE

Value

Character string with the selected part of the file.

Details

As an example of use assume that we have a file rlp.txt that looks like this (without the added numbers)

01 # example file for readLines_part
02 ###HOQC_start fun1###
03 fun1 <- function () {
04 return(pi)
05 }
06 ###HOQC_end fun1###
07 ###HOQC_start fun2###
08 fun2 <- function () {
09 return(exp(1))
10 }
11 ###HOQC_end fun2###

Examples:

readLines_part('rlp.txt','fun1')
The first delimitation line is determined by the regex created by concatenating '^', symbols, start_str and the first of the suffixes: ###HOQC_start fun1###
The second delimitation line is determined by the regex created by concatenating '^', symbols, end_str and the second of the suffixes. Because only one suffix is specified the second suffix is assumed to have the same value as the first. So the second delimitation line is ###HOQC_end fun1### .
Therefore the lines 03 - 05 will be read (lines starting with the concatenation of symbols and start_str or end_str are always removed).

readLines_part('rlp.txt',c('fun1','fun2'))
The first delimitation line is the same as in the first example.
The second delimitation line is determined in the same way as in the first example and becomes: ###HOQC_end fun2### .
Therefore the lines 02 - 11 will be read and as in the first example the delimitation lines are removed and therefore the lines 03 - 05 and 08 - 10 remain.

readLines_part('rlp.txt','part3')
Because only one suffix is specified the second suffix is supposed to have the same value as the first. The first delimitation line is then ###HOQC_start part3### and the second delimitation line becomes ###HOQC_end part3### . However the first delimitation line is not in the file and therefore we start from the first line. In this case also the second delimitation line is not in the file and therefore we end with the last line.
Therefore the lines 01 - 11 will be read and after removing the delimitation lines only the lines 01 (this is not a delimitation line), 03 - 05 and 08 - 10 remain.

readLines_part('rlp.txt')
In this case suffixes get the default value NULL and the contents of the whole file will be returned.
Therefore the lines 01 - 11 will all be read and returned.