| Title: | Compact Package Representations |
| Version: | 0.2.4 |
| Description: | A tool, grammar, and standard to represent and exchange R package source code as text files. Converts one or more source packages to a text file and restores the package structures from the file. |
| License: | GPL-3 |
| URL: | https://merck.github.io/pkglite/, https://github.com/Merck/pkglite |
| BugReports: | https://github.com/Merck/pkglite/issues |
| Encoding: | UTF-8 |
| VignetteBuilder: | knitr |
| Depends: | R (≥ 3.5.0) |
| Imports: | crayon, magrittr, remotes |
| Suggests: | covr, knitr, rmarkdown, testthat |
| RoxygenNote: | 7.3.2 |
| NeedsCompilation: | no |
| Packaged: | 2024-11-09 21:33:17 UTC; xiaonan4 |
| Author: | Nan Xiao  [aut,
cre],
Yilong Zhang [aut],
Keaven Anderson [aut],
Amin Shirazi [ctb],
Jeff Cheng [ctb],
Danfeng Fu [ctb],
Merck & Co., Inc., Rahway, NJ, USA and its affiliates [cph] |
| Maintainer: | Nan Xiao <nan.xiao1@merck.com> |
| Repository: | CRAN |
| Date/Publication: | 2024-11-09 21:50:02 UTC |
pkglite: Compact Package Representations
Description
A tool, grammar, and standard to represent and exchange R package source code as text files. Converts one or more source packages to a text file and restores the package structures from the file.
Author(s)
Maintainer: Nan Xiao nan.xiao1@merck.com (ORCID)
Authors:
Yilong Zhang
Keaven Anderson keaven_anderson@merck.com
Other contributors:
Amin Shirazi [contributor]
Jeff Cheng [contributor]
Danfeng Fu [contributor]
Merck & Co., Inc., Rahway, NJ, USA and its affiliates [copyright holder]
See Also
Useful links:
Report bugs at https://github.com/Merck/pkglite/issues
Pipe operator
Description
See magrittr::%>% for details.
Usage
lhs %>% rhs
Value
The evaluation result of rhs(lhs),
if rhs is a function and lhs is an object.
See magrittr::%>% for more details.
Evaluate a list of file specifications
Description
Evaluate a list of file specifications and bind the results as a file collection.
Usage
collate(pkg = ".", ...)
Arguments
pkg |
Path to the package directory. |
... |
One or more file specification objects. |
Value
A file collection object containing the package name, file paths, and file format types.
Specification
The contents of this section are shown in PDF user manual only.
Examples
system.file("examples/pkg1/", package = "pkglite") %>%
collate(file_default())
Common file extensions (binary)
Description
Common file extensions (binary)
Usage
ext_binary(flat = FALSE)
Arguments
flat |
Flatten the list and return a vector? |
Value
A list or vector of standard binary file extensions.
Specification
The contents of this section are shown in PDF user manual only.
Examples
ext_binary()
Common file extensions (text)
Description
Common file extensions (text)
Usage
ext_text(flat = FALSE)
Arguments
flat |
Flatten the list and return a vector? |
Value
A list or vector of standard text file extensions.
Specification
The contents of this section are shown in PDF user manual only.
Examples
ext_text()
File specification (automatic guess)
Description
Lists all files under a folder recursively and guesses the file format type (text or binary) based on the file extension.
Usage
file_auto(path)
Arguments
path |
The directory's relative path (relative to the
package root), for example, |
Value
A list of file specifications.
Specification
The contents of this section are shown in PDF user manual only.
Examples
file_auto("inst/")
File specification (default combination)
Description
A default combination of common file specifications.
Usage
file_default()
Value
A list of file specifications.
Specification
The contents of this section are shown in PDF user manual only.
Examples
file_default()
File specification (eCTD submission)
Description
A combination of file specifications for eCTD submissions.
Usage
file_ectd()
Value
A list of file specifications.
Specification
The contents of this section are shown in PDF user manual only.
Examples
file_ectd()
Common File name patterns
Description
Common File name patterns
Usage
pattern_file_root_core()
pattern_file_root_all()
pattern_file_src()
pattern_file_sanitize()
Value
A vector of file name patterns.
Specification
The contents of this section are shown in PDF user manual only.
Create a file specification
Description
Specify which files to include
Usage
file_spec(
path,
pattern = NULL,
format = c("binary", "text"),
recursive = TRUE,
ignore_case = TRUE,
all_files = FALSE
)
Arguments
path |
Path relative to the package root), for example, |
pattern |
Regular expression for matching the file names. |
format |
File format type, one of |
recursive |
List files in the sub-directories? |
ignore_case |
Should pattern-matching be case-insensitive? |
all_files |
List all files including the invisible ones? |
Details
Most of the parameters are passed through list.files().
Value
A file specification object.
Specification
The contents of this section are shown in PDF user manual only.
Examples
file_spec(
"R/",
pattern = "\\.R$", format = "text",
recursive = FALSE, ignore_case = TRUE, all_files = FALSE
)
File specification templates
Description
-
file_root_core()- core files under the package root -
file_root_all()- all files under the package root -
file_r()- files underR/ -
file_man()- files underman/ -
file_src()- files undersrc/ -
file_vignettes()- files undervignettes/ -
file_data()- files underdata/ -
file_tests()- files undertests/
Usage
file_root_core()
file_root_all()
file_r()
file_man()
file_src()
file_vignettes()
file_data()
file_tests()
Value
A file specification or a list of file specifications.
Specification
The contents of this section are shown in PDF user manual only.
Is this a file collection object?
Description
Is this a file collection object?
Usage
is_file_collection(object)
Arguments
object |
Any R object. |
Value
Logical. TRUE if it is a file collection object,
FALSE otherwise.
Specification
The contents of this section are shown in PDF user manual only.
Examples
system.file("examples/pkg1/", package = "pkglite") %>%
collate(file_default()) %>%
is_file_collection()
Is this a file specification object?
Description
Is this a file specification object?
Usage
is_file_spec(object)
Arguments
object |
Any R object |
Value
Logical. TRUE if it is a file specification object,
FALSE otherwise.
Specification
The contents of this section are shown in PDF user manual only.
Examples
file_spec(
"R/",
pattern = "\\.R$", format = "text",
recursive = FALSE, ignore_case = TRUE, all_files = FALSE
) %>%
is_file_spec()
Merge file collections
Description
Merge file collections
Usage
## S3 method for class 'file_collection'
merge(x, y, ...)
Arguments
x |
File collection. |
y |
Another file collection. |
... |
Additional file collections. |
Value
Merged file collection.
Specification
The contents of this section are shown in PDF user manual only.
Examples
pkg <- system.file("examples/pkg1/", package = "pkglite")
fc1 <- pkg %>% collate(file_root_core())
fc2 <- pkg %>% collate(file_r(), file_man())
merge(fc1, fc2)
Pack packages into a text file
Description
Pack packages into a text file
Usage
pack(..., output, quiet = FALSE)
Arguments
... |
One or more file collection objects
generated by |
output |
Path to the output text file.
If empty, will create a txt file using the lower-cased package name
in the current working directory. For multiple packages,
will use |
quiet |
Suppress printing of progress? |
Value
The output file path.
Specification
The contents of this section are shown in PDF user manual only.
Examples
# pack two packages
pkg1 <- system.file("examples/pkg1", package = "pkglite")
pkg2 <- system.file("examples/pkg2", package = "pkglite")
fc1 <- pkg1 %>% collate(file_default())
fc2 <- pkg2 %>% collate(file_default())
txt <- tempfile(fileext = ".txt")
pack(fc1, fc2, output = txt, quiet = TRUE)
txt %>%
readLines() %>%
head() %>%
cat(sep = "\n")
txt %>%
readLines() %>%
length()
Print a file collection
Description
Print a file collection
Usage
## S3 method for class 'file_collection'
print(x, ...)
Arguments
x |
An object of class |
... |
Additional parameters for |
Value
The input file_collection object.
Specification
The contents of this section are shown in PDF user manual only.
Examples
fc <- system.file("examples/pkg1/", package = "pkglite") %>%
collate(file_default())
fc
Print a file specification
Description
Print a file specification
Usage
## S3 method for class 'file_spec'
print(x, ...)
Arguments
x |
An object of class |
... |
Additional parameters for |
Value
The input file_spec object.
Specification
The contents of this section are shown in PDF user manual only.
Examples
fs <- file_spec(
"R/",
pattern = "\\.R$", format = "text",
recursive = FALSE, ignore_case = TRUE, all_files = FALSE
)
fs
Remove files from a file collection
Description
Remove files from a file collection
Usage
prune(x, path)
## S3 method for class 'file_collection'
prune(x, path)
Arguments
x |
File collection. |
path |
Character vector. Relative paths of the files to remove. |
Value
Pruned file collection.
Specification
The contents of this section are shown in PDF user manual only.
Examples
system.file("examples/pkg1/", package = "pkglite") %>%
collate(file_default()) %>%
prune(path = c("NEWS.md", "man/figures/logo.png"))
Remove content lines from a pkglite file
Description
Remove content lines from a pkglite file
Usage
remove_content(input, x, quiet = FALSE)
Arguments
input |
Path to the text file. |
x |
A character vector. Exactly matched lines in the file content will be removed. |
quiet |
Suppress printing of progress? |
Value
The input file path.
Specification
The contents of this section are shown in PDF user manual only.
Examples
pkg <- system.file("examples/pkg1", package = "pkglite")
txt <- tempfile(fileext = ".txt")
pkg %>%
collate(file_default()) %>%
pack(output = txt, quiet = TRUE) %>%
remove_content(c("## New Features", "## Improvements"), quiet = TRUE)
Sanitize file collection
Description
Remove commonly excluded files from a file collection.
Usage
sanitize(x)
## S3 method for class 'file_collection'
sanitize(x)
Arguments
x |
File collection. |
Value
Sanitized file collection.
Specification
The contents of this section are shown in PDF user manual only.
Examples
system.file("examples/pkg1/", package = "pkglite") %>%
collate(file_default()) %>%
sanitize()
Sanitize file collection (deprecated)
Description
Remove commonly excluded files from a file collection.
Usage
sanitize_file_collection(x)
Arguments
x |
File collection. |
Value
Sanitized file collection.
Specification
The contents of this section are shown in PDF user manual only.
Examples
system.file("examples/pkg1/", package = "pkglite") %>%
collate(file_default()) %>%
sanitize()
Unpack packages from a text file
Description
Unpack packages from a text file
Usage
unpack(input, output = ".", install = FALSE, quiet = FALSE, ...)
Arguments
input |
Path to the text file. |
output |
Path to the output directory. Each package is placed under a subdirectory named after the package name. Default is the current working directory. |
install |
Try install the unpacked package(s)? |
quiet |
Suppress printing of progress? |
... |
Additional parameters for |
Details
If install = TRUE, the packages will be installed by the order of
appearance in the input file. When internal dependencies exist between
these packages, make sure they are packed in the order where the
low-level dependencies appear first.
Value
The output directory path.
Specification
The contents of this section are shown in PDF user manual only.
Examples
# pack two packages
pkg1 <- system.file("examples/pkg1", package = "pkglite")
pkg2 <- system.file("examples/pkg2", package = "pkglite")
fc1 <- pkg1 %>% collate(file_default())
fc2 <- pkg2 %>% collate(file_default())
txt <- tempfile(fileext = ".txt")
pack(fc1, fc2, output = txt, quiet = TRUE)
# unpack the two packages
out <- file.path(tempdir(), "twopkgs")
txt %>% unpack(output = out, quiet = TRUE)
out %>%
file.path("pkg1") %>%
list.files()
out %>%
file.path("pkg2") %>%
list.files()
Check if a file contains only ASCII characters
Description
Check if a file contains only ASCII characters
Usage
verify_ascii(input, quiet = FALSE)
Arguments
input |
Path to the text file. |
quiet |
Print the elements containing non-ASCII characters? |
Value
Logical. TRUE if the file only contains ASCII characters,
FALSE otherwise.
Specification
The contents of this section are shown in PDF user manual only.
Examples
pkg <- system.file("examples/pkg1", package = "pkglite")
txt <- tempfile(fileext = ".txt")
pkg %>%
collate(file_default()) %>%
pack(output = txt, quiet = TRUE) %>%
verify_ascii()