id       = "perl"
name     = "Perl"
homepage = "https://www.perl.org"
description = "Perl is a highly capable, feature-rich programming language with over 38 years of development."
# Perl's own sentence, from the front page of www.perl.org.
icon     = "SimpleIcons:perl"
executables   = ["perl", "cpan"]
platforms = ["macos", "linux"]

[dotfiles]

# Two user-level files, from Perl's own documentation:
#
# perldebug, Configurable Options: the debugger reads a startup file before a
# session begins — "The file is named ./.perldb or ~/.perldb under Unix with
# /dev/tty, perldb.ini otherwise." The home-directory one is the user's; the
# ./.perldb beside a project is not.
#
# perldoc CPAN: "Default values defined in the CPAN/Config.pm file can be
# overridden in a user specific file: CPAN/MyConfig.pm. Such a file is best
# placed in $HOME/.cpan/CPAN/MyConfig.pm", and `o conf mkmyconfig` writes it
# there. It is Perl source: one hash of configuration keys.
#
# Both are joined to $HOME by the tools themselves, so they stay literal rather
# than becoming a base directory.
paths = [
  "~/.perldb",
  "~/.cpan/CPAN/MyConfig.pm",
]

# The rest of ~/.cpan is CPAN.pm's working area, and perldoc CPAN names the two
# keys that put it there: `build_dir`, "Directory where the distributions are
# built", and `keep_source_where`, "Directory in which to keep the source", both
# defaulting under `cpan_home`. Downloaded tarballs and unpacked build trees are
# not configuration.
exclude = [
  "~/.cpan/build/",
  "~/.cpan/sources/",
]

# Neither file is a credential. A CPAN mirror needing authentication carries it
# in the mirror URL rather than in a separate file.
secret = []

# perldoc CPAN describes cpan_home as "The directory where CPAN.pm keeps its
# state", build_dir as the build area and keep_source_where as the download
# cache — three absolute paths into this machine's disk, written by
# `mkmyconfig` from wherever it was run. MyConfig.pm is Perl source with one
# key per line (`'build_dir' => q[/home/octocat/.cpan/build],`), which prefix
# matching reads once leading whitespace is stripped. Everything else in the
# file — the mirror list, the build and test policies, the term settings — is
# a preference worth carrying.
[[dotfiles.machine_lines]]
file  = "~/.cpan/CPAN/MyConfig.pm"
match = { prefix = ["'cpan_home'", "'build_dir'", "'keep_source_where'"] }

# No machine_lines for ~/.perldb: it is debugger options and aliases, and the
# `parse_options` line a user puts there is the same on every machine.

[commands]
format = 1
label = "Run Perl"
description = "Run a script or a one-liner, or check syntax. Debugger, Unicode (-C) and taint switches are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = false, short_attached = true, short_bundles = false }

[[commands.source]]
id = "help"
kind = "help"
revision = "perl -h (local)"
evidence = """
Usage: perl [switches] [--] [programfile] [arguments]
  -a                    autosplit mode with -n or -p (splits $_ into @F)
  -c                    check syntax only (runs BEGIN and CHECK blocks)
  -e commandline        one line of program (several -e's allowed, omit programfile)
  -E commandline        like -e, but enables all optional features
  -F/pattern/           split() pattern for -a switch (//'s are optional)
  -i[extension]         edit <> files in place (makes backup if extension supplied)
  -Idirectory           specify @INC/#include directory (several -I's allowed)
  -l[octnum]            enable line ending processing, specifies line terminator
  -[mM][-]module        execute "use/no module..." before executing program
  -n                    assume "while (<>) { ... }" loop around program
  -p                    assume loop like -n but print line also, like sed
  -w                    enable many useful warnings
  -W                    enable all warnings
"""

[[commands.field]]
id = "one_liner"
label = "One-line program (-e)"
type = "string"
option = ["-e"]
sources = ["help"]

[[commands.field]]
id = "one_liner_features"
label = "One-line program with all features (-E)"
type = "string"
option = ["-E"]
sources = ["help"]

[[commands.field]]
id = "loop_n"
label = "Loop over input lines (-n)"
type = "boolean"
option = ["-n"]
sources = ["help"]

[[commands.field]]
id = "loop_p"
label = "Loop and print each line (-p)"
type = "boolean"
option = ["-p"]
sources = ["help"]

[[commands.field]]
id = "autosplit"
label = "Autosplit into @F (-a)"
type = "boolean"
option = ["-a"]
sources = ["help"]

[[commands.field]]
id = "line_ending"
label = "Line-ending processing (-l)"
type = "boolean"
option = ["-l"]
sources = ["help"]

[[commands.field]]
id = "inplace"
label = "Edit files in place (-i)"
description = "Without a backup extension; files are overwritten."
type = "boolean"
option = ["-i"]
effect = "overwrite"
sources = ["help"]

[[commands.field]]
id = "syntax_check"
label = "Check syntax only"
type = "boolean"
option = ["-c"]
sources = ["help"]

[[commands.field]]
id = "warnings"
label = "Enable warnings"
type = "boolean"
option = ["-w"]
sources = ["help"]

[[commands.field]]
id = "include_dir"
label = "Extra @INC directory"
type = "path"
path = { kind = "directory", role = "input" }
option = ["-I"]
multiple = true
sources = ["help"]

[[commands.field]]
id = "script"
label = "Script file"
type = "path"
path = { kind = "file", role = "input" }
position = 0
sources = ["help"]

[[commands.field]]
id = "args"
label = "Arguments or input files"
type = "path"
path = { kind = "any", role = "input" }
position = 1
multiple = true
sources = ["help"]

[[commands.task]]
id = "run_script"
label = "Run a script"
fields = ["script", "args", "warnings"]
required = ["script"]

[[commands.task]]
id = "filter"
label = "Filter lines with a one-liner"
fields = ["one_liner", "loop_p", "args"]
required = ["one_liner", "loop_p"]
set = { loop_p = [true] }

[[commands.task]]
id = "check"
label = "Check script syntax"
fields = ["script", "syntax_check"]
required = ["script", "syntax_check"]
set = { syntax_check = [true] }

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["script", "one_liner", "args", "warnings", "syntax_check"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["one_liner_features", "loop_n", "loop_p", "autosplit", "line_ending", "inplace", "include_dir"]