Package 'renviron'

Agregar o actualizar una variable

Description

Actualiza la clave seleccionada en la sesión. Si se guarda, primero escribe el archivo; una cancelación o fallo de escritura deja la sesión intacta.

Usage

renviron_add(
  key,
  value,
  .renviron = NULL,
  in_place = FALSE,
  ...,
  confirm = TRUE
)

Arguments

key	Nombre de una variable.
value	Un valor de caracteres, sin NA ni saltos de línea.
.renviron	Lista o vector nombrado; NULL usa el archivo.
in_place	Guardar también el archivo; el valor predeterminado es FALSE.
...	Argumentos de renviron_path().
confirm	Confirmación interactiva del guardado; para scripts use FALSE.

Details

Sin .renviron, el guardado modifica solo las líneas de la clave; conserva comentarios, líneas vacías y expresiones de las demás variables. Elimina duplicados de la clave editada. Los finales de línea se normalizan a LF y se escribe UTF-8. Si proporciona .renviron, el guardado reemplaza todo el archivo con esa lista modificada. No recalcula otras variables de la sesión que dependan de la clave; use renviron_load() para ello.

Value

Lista modificada, invisiblemente; la lista original si se cancela.

Examples

previous <- Sys.getenv("RNV_ADD_DEMO", unset = NA_character_)
values <- renviron_add("RNV_ADD_DEMO", "sample", .renviron = list())
if (is.na(previous)) Sys.unsetenv("RNV_ADD_DEMO") else
  Sys.setenv(RNV_ADD_DEMO = previous)

---

Eliminar una variable de la sesión y, opcionalmente, del archivo

Description

Elimina únicamente la clave indicada. El comportamiento de edición, conservación de líneas y cancelación es el de renviron_add().

Usage

renviron_delete(key, .renviron = NULL, in_place = FALSE, ..., confirm = TRUE)

Arguments

key	Nombre de una variable.
.renviron	Lista o vector nombrado; NULL usa el archivo.
in_place	Guardar también el archivo; el valor predeterminado es FALSE.
...	Argumentos de renviron_path().
confirm	Confirmación interactiva del guardado; para scripts use FALSE.

Value

Lista restante, invisiblemente; la original si se cancela.

Examples

previous <- Sys.getenv("RNV_DELETE_DEMO", unset = NA_character_)
values <- renviron_delete("RNV_DELETE_DEMO", .renviron = list())
if (!is.na(previous)) Sys.setenv(RNV_DELETE_DEMO = previous)

---

Comprobar si una variable está definida

Description

Comprueba la presencia de la clave, incluso cuando su valor es vacío. No modifica la sesión.

Usage

renviron_exists(key, .renviron = NULL, ...)

Arguments

key	Nombre de una variable.
.renviron	Lista o vector nombrado; NULL lee el archivo.
...	Argumentos de renviron_read().

Value

TRUE o FALSE.

Examples

renviron_exists("RNV_EXAMPLE", .renviron = list(RNV_EXAMPLE = ""))

---

Consultar el valor de una variable

Description

Consulta exclusivamente el archivo o la lista indicada, sin cargar variables ni recuperar valores ajenos del entorno de la sesión.

Usage

renviron_get(key, .renviron = NULL, ...)

Arguments

key	Nombre de una variable.
.renviron	Lista o vector nombrado; NULL lee el archivo.
...	Argumentos de renviron_read().

Value

Valor de caracteres, incluyendo ""; NULL si la clave no existe.

Examples

renviron_get("RNV_EXAMPLE", .renviron = list(RNV_EXAMPLE = ""))

---

Listar nombres con valores enmascarados

Description

Devuelve únicamente los nombres y una máscara constante. No carga variables en la sesión. La máscara no informa la longitud ni el contenido del valor.

Usage

renviron_list(.renviron = NULL, ...)

Arguments

.renviron	Lista o vector nombrado; NULL lee el archivo.
...	Argumentos de renviron_read().

Value

Vector de caracteres nombrado con "*****" por variable; character() si no hay variables.

Examples

renviron_list(list(RNV_EXAMPLE = "demo", RNV_EMPTY = ""))

---

Cargar variables en la sesión actual

Description

Lee y valida el archivo completo antes de modificar la sesión. Solo establece las variables seleccionadas; las demás conservan su valor actual.

Usage

renviron_load(
  scope = c("user", "project"),
  .file = ".Renviron",
  .vars = NULL,
  verbosity = 1,
  ...
)

Arguments

scope	Ámbitos que se consultan en orden: "user" y "project". Se usa el primer archivo existente; si ninguno existe, la primera ruta.
.file	Nombre relativo al ámbito o ruta absoluta explícita.
.vars	Nombres que se devuelven; NULL selecciona todos. Las referencias se resuelven con el archivo completo antes de filtrar.
verbosity	0 suprime el aviso de archivo ausente; 1 lo muestra.
...	Argumentos de renviron_path(), como project y user.

Value

Lista de variables cargadas, devuelta invisiblemente.

Examples

path <- tempfile()
writeLines("RNV_LOAD_DEMO='sample'", path)
previous <- Sys.getenv("RNV_LOAD_DEMO", unset = NA_character_)
values <- renviron_load(.file = path, .vars = "RNV_LOAD_DEMO")
if (is.na(previous)) Sys.unsetenv("RNV_LOAD_DEMO") else
  Sys.setenv(RNV_LOAD_DEMO = previous)
unlink(path)

---

Resolver el archivo de configuración

Description

Consulta los ámbitos en el orden indicado, sin fusionar archivos ni cambiar el proyecto activo. project es el directorio de trabajo por defecto.

Usage

renviron_path(
  scope = c("user", "project"),
  .file = ".Renviron",
  verbosity = 1,
  ...,
  project = getwd(),
  user = path.expand("~")
)

Arguments

scope	Ámbitos que se consultan en orden: "user" y "project". Se usa el primer archivo existente; si ninguno existe, la primera ruta.
.file	Nombre relativo al ámbito o ruta absoluta explícita.
verbosity	0 suprime el aviso de archivo ausente; 1 lo muestra.
...	Argumentos de renviron_path(), como project y user.
project	Directorio para el ámbito de proyecto; por defecto getwd().
user	Directorio para el ámbito de usuario; por defecto el hogar de R.

Details

Una ruta absoluta en .file tiene prioridad sobre los ámbitos. R_ENVIRON_USER se respeta solo para el archivo predeterminado del ámbito user cuando no se especifica user. Un nombre personalizado no se redirige. El orden predeterminado sigue siendo usuario, proyecto; use scope = c("project", "user") para dar prioridad al proyecto.

Value

Ruta absoluta. Si no existe un archivo, devuelve la primera ruta candidata, utilizable para crear un archivo con renviron_save().

Examples

renviron_path("project", project = tempdir())

---

Leer variables sin modificar la sesión

Description

Interpreta un archivo con el lector nativo de R en un proceso aislado. Las referencias a variables se resuelven en orden, con el entorno heredado de la sesión. No modifica variables ni ejecuta perfiles de inicio.

Usage

renviron_read(
  scope = c("user", "project"),
  .file = ".Renviron",
  .vars = NULL,
  verbosity = 1,
  ...
)

Arguments

scope	Ámbitos que se consultan en orden: "user" y "project". Se usa el primer archivo existente; si ninguno existe, la primera ruta.
.file	Nombre relativo al ámbito o ruta absoluta explícita.
.vars	Nombres que se devuelven; NULL selecciona todos. Las referencias se resuelven con el archivo completo antes de filtrar.
verbosity	0 suprime el aviso de archivo ausente; 1 lo muestra.
...	Argumentos de renviron_path(), como project y user.

Details

Admite comillas, =, comentarios de línea, referencias ⁠${VAR}⁠, valores predeterminados de R y el prefijo opcional export. Un ⁠KEY=⁠ sin comillas se ignora, como en R; KEY='' expresa un valor vacío. Un ⁠#⁠ al final de una asignación forma parte del valor. No ejecuta sintaxis de shell. Cada lectura inicia un proceso de R y requiere que Rscript esté disponible. La lista conserva las claves declaradas aunque su valor resulte vacío. Windows representa algunas variables vacías como ausentes en el entorno del proceso; la lista mantiene "". Una expansión vacía sin comillas puede ser ignorada por R y conservar un valor previamente heredado.

Value

Lista nombrada, devuelta invisiblemente. Un archivo vacío o ausente produce list(). Las asignaciones inválidas producen un error sin valores.

Examples

path <- tempfile()
writeLines(c("RNV_DEMO='one=two'", "RNV_COPY='${RNV_DEMO}'"), path)
values <- renviron_read(.file = path)
stopifnot(identical(values$RNV_COPY, "one=two"))
unlink(path)

---

Guardar un conjunto completo de variables

Description

Reemplaza el contenido del archivo con valores literales compatibles con R. Valida todos los datos antes de escribir. La sustitución usa un archivo temporal en el mismo directorio y conserva los permisos de un archivo existente.

Usage

renviron_save(.Renviron, confirm = TRUE, ...)

Arguments

.Renviron	Lista nombrada o vector de caracteres nombrado, con valores escalares sin NA ni saltos de línea. list() crea un archivo vacío.
confirm	Solicitar confirmación interactiva. Para scripts use FALSE.
...	Argumentos de renviron_path().

Details

Esta función reemplaza todo el documento, incluidos comentarios. Para editar una sola clave conservando otras líneas use renviron_add() o renviron_delete() con in_place = TRUE y sin proporcionar .renviron. Los valores ⁠${...}⁠ se guardan como texto literal. No se admiten enlaces simbólicos como destino, valores multilínea ni líneas codificadas de más de 99900 bytes. El directorio debe existir. Los nuevos archivos usan modo 0600 donde el sistema lo soporta; en Windows rigen también las ACL del directorio.

Value

Ruta guardada, invisiblemente; NULL si se cancela. No cambia la sesión.

Examples

path <- tempfile()
renviron_save(list(RNV_SAVE_DEMO = "one=two", RNV_EMPTY = ""),
              .file = path, confirm = FALSE)
renviron_list(.file = path)
unlink(path)

---

Retirar de la sesión las claves seleccionadas del archivo

Description

Lee sin cargar variables y elimina de la sesión solo las claves resultantes. No modifica el archivo ni otras variables del sistema.

Usage

renviron_unset_all(...)

Arguments

...	Argumentos de renviron_read(), incluyendo .vars para filtrar.

Value

NULL, invisiblemente.

Examples

path <- tempfile()
writeLines(character(), path)
renviron_unset_all(.file = path)
unlink(path)

---

Construir una ruta dentro de un ámbito

Description

Función de compatibilidad para resolver un único ámbito. Para buscar archivos en varios ámbitos use renviron_path(). No cambia el proyecto activo.

Usage

scoped_path_r(
  scope = c("user", "project"),
  ...,
  envvar = NULL,
  project = getwd(),
  user = path.expand("~")
)

Arguments

scope	Un ámbito: "user" o "project". El valor predeterminado usa user.
...	Componentes de la ruta.
envvar	Nombre de una variable que puede reemplazar la ruta de usuario.
project	Directorio de proyecto; por defecto getwd().
user	Directorio de usuario; por defecto el hogar de R.

Value

Ruta absoluta.

Examples

scoped_path_r("project", "example.env", project = tempdir())

---