id       = "r"
name     = "R"
homepage = "https://www.r-project.org"
description = "R is a free software environment for statistical computing and graphics."
icon     = "SimpleIcons:r"
# R installs `R` and `Rscript`; it has no lowercase `r`. The `r` a shell offers
# is either zsh's built-in redo (`fc -e -`) or Dirk Eddelbuettel's littler, a
# separate front-end, so neither is listed here.
executables   = ["R", "Rscript"]

[dotfiles]

# ?Startup (base::Startup): R_ENVIRON_USER names the user environment file and,
# "if this is unset, a file called '.Renviron' is searched for in the current
# directory or in the user's home directory (in that order)"; R_PROFILE_USER
# does the same for '.Rprofile'. Only the home copies are user-level — the ones
# in a working directory belong to that project.
#
# R Installation and Administration §6.3.3, "Customizing package compilation":
# personal compilation flags go in HOME/.R/Makevars, or
# HOME/.R/Makevars-R_PLATFORM when they need to differ per platform;
# R_MAKEVARS_USER overrides the location. ?Startup also names
# ~/.R/check.Renviron and ~/.R/build.Renviron, the environment files R CMD
# check and R CMD build read.
paths = [
  "~/.Renviron",
  "~/.Rprofile",
  "~/.R/Makevars",
  "~/.R/Makevars-*",
  "~/.R/check.Renviron",
  "~/.R/build.Renviron",
]

# The user library R_LIBS_USER points at is installed packages, not config.
# .RData is a binary blob of the last session's objects and .Rhistory the
# console history — both are state R writes on exit.
exclude = ["~/R/", "~/.RData", "~/.Rhistory"]

# Neither startup file is wholly a credential: .Renviron is a list of
# NAME=value environment settings, and the credential-shaped ones are lifted
# out below.
secret = []

# Both files are read once, at the start of an R session.
side_effect = false

# usethis, "Managing Git(Hub) Credentials", documents putting a GitHub personal
# access token in .Renviron: "Add a line like this, but substitute your PAT:
# GITHUB_PAT=ghp_xxxxxxxx", and tells users cleaning up to "look for any line
# setting the GITHUB_PAT or GITHUB_TOKEN environment variable". Those are the
# two names R's own tooling (gitcreds, usethis) reads. A .Renviron is a general
# environment file and can hold any other API key besides; scanning values is
# the consumer's layer, the way it is for pip's index-url.
[[dotfiles.secret_paths]]
file  = "~/.Renviron"
match = { prefix = ["GITHUB_PAT", "GITHUB_TOKEN"] }

# R_LIBS and R_LIBS_USER are lists of absolute library directories on this
# machine's disk (?Startup: "the library search path"). Everything else in the
# file — R_MAX_VSIZE, history size, a mirror — is preference.
# Where the user keeps their installed packages is their own arrangement and
# what they need back to rebuild this machine, so it is kept for this device.
[[dotfiles.machine_lines]]
file  = "~/.Renviron"
match = { prefix = ["R_LIBS"] }
scope = "backup"

# A personal Makevars sets compiler flags, and CPPFLAGS / LDFLAGS are where the
# absolute -I and -L paths go — a Homebrew prefix on one machine, a distro path
# on the next. Optimisation levels and the C++ standard are preference and stay.
# Those -I and -L roots follow from the OS and the architecture the libraries
# were installed for, so they hold across every machine of the same class.
[[dotfiles.machine_lines]]
file  = "~/.R/Makevars"
match = { prefix = ["CPPFLAGS", "LDFLAGS"] }
scope = "platform"

[commands]
format = 1
label = "Start R"
description = "Start R with an optional script or expression. Debugger, memory and CMD tools are left out."
quality = "ai-draft"
base = "fig:R"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "fig"
kind = "completion"
url = "https://github.com/withfig/autocomplete/blob/master/src/R.ts"
license = "MIT"

[[commands.field]]
id = "file"
label = "Script file"
type = "path"
option = ["--file", "-f"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["fig"]

[[commands.field]]
id = "expr"
label = "Expression"
description = "Execute an R expression and exit."
type = "string"
option = ["-e"]
sources = ["fig"]

[[commands.field]]
id = "vanilla"
label = "Vanilla"
description = "Combines --no-save, --no-restore, --no-site-file, --no-init-file and --no-environ."
type = "boolean"
option = ["--vanilla"]
sources = ["fig"]

[[commands.field]]
id = "no_save"
label = "Do not save workspace"
type = "boolean"
option = ["--no-save"]
sources = ["fig"]

[[commands.field]]
id = "no_restore"
label = "Do not restore anything"
type = "boolean"
option = ["--no-restore"]
sources = ["fig"]

[[commands.field]]
id = "quiet"
label = "Quiet startup"
type = "boolean"
option = ["--quiet", "--silent", "-q"]
sources = ["fig"]

[[commands.field]]
id = "no_echo"
label = "No echo"
type = "boolean"
option = ["--no-echo", "-s"]
sources = ["fig"]

[[commands.field]]
id = "interactive"
label = "Force interactive"
type = "boolean"
option = ["--interactive"]
sources = ["fig"]

[[commands.field]]
id = "encoding"
label = "Stdin encoding"
type = "string"
option = ["--encoding"]
sources = ["fig"]

[[commands.field]]
id = "verbose"
label = "Verbose"
type = "boolean"
option = ["--verbose"]
sources = ["fig"]

[[commands.task]]
id = "script"
label = "Run a script"
fields = ["file", "vanilla", "no_echo"]
required = ["file"]
set = { no_echo = [true], vanilla = [true] }

[[commands.task]]
id = "expr"
label = "Run an expression"
fields = ["expr", "quiet", "no_save"]
required = ["expr"]
set = { quiet = [true], no_save = [true] }

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["file", "expr", "vanilla", "quiet", "no_save"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["no_restore", "no_echo", "interactive", "encoding", "verbose"]