view release on metacpan or  search on metacpan

lib/Developer/Dashboard.pm  view on Meta::CPAN

  /*
  child layers can still override
  any value later in the root-to-leaf chain
  */
  CHAINED=$ROOT_CACHE/$TOKEN

=head2 Open File Commands

C<dashboard of> is the shorthand name for C<dashboard open-file>.

These commands support:

=over 4

=item *

direct file paths

=item *

C<file:line> references

=item *

Perl module names such as C<My::Module>

=item *

Java class names such as C<com.example.App> or C<javax.jws.WebService>

=item *

recursive regex searches inside a resolved directory alias or path

=back

Without C<--print>, C<dashboard of> and C<dashboard open-file> now behave like
the older picker workflow again: one unique match opens directly in
C<--editor>, C<VISUAL>, C<EDITOR>, or C<vim> as the final fallback, and
multiple matches render a numbered prompt. At that prompt you can press Enter
to open all matches with C<vim -p>, type one number to open one file, type comma-separated
numbers such as C<1,3>, or use a range such as C<2-5>. Scoped searches also
rank exact helper/script names before broader regex hits, so
C<dashboard of . jq> lists C<jq> and C<jq.js> ahead of C<jquery.js>. Every
scoped search token is treated as a case-insensitive regex, so
C<dashboard of . 'Ok\.js$'> matches C<ok.js> but not C<ok.json>.

Java class lookup first checks live F<.java> files under the current project,
workspace roots, and C<@INC>-adjacent source trees. If no live source file
exists, it also searches local source archives such as F<-sources.jar>,
F<-src.jar>, F<src.zip>, F<war>, and F<jar> files under the current roots,
F<~/.m2/repository>, Gradle caches, and C<JAVA_HOME>. When a local archive
still does not provide the requested class, the helper can fetch a matching
Maven source jar, cache it under
F<~/.developer-dashboard/cache/open-file/>, and then open the extracted Java
source.

=head2 Data Query Commands

These built-in commands parse structured text and can then either extract a
dotted path or evaluate a Perl expression against the decoded document through
C<$d>:

=over 4

=item *

C<dashboard jq [path] [file]> for JSON

=item *

C<dashboard yq [path] [file]> for YAML

=item *

C<dashboard tomq [path] [file]> for TOML

=item *

C<dashboard propq [path] [file]> for Java properties

=back

If the selected value is a hash or array, the command prints canonical JSON.
If the selected value is a scalar, it prints the scalar plus a trailing
newline.

The file path and query text are order-independent, and C<$d> selects the
whole parsed document. For example, C<cat file.json | dashboard jq '$d'> and
C<dashboard jq file.json '$d'> return the same result. If the query text uses
C<$d> inside a Perl expression, the command evaluates that expression against
the decoded document. For example, C<echo '{"foo":[1],"bar":[2]}' | dashboard
jq 'sort keys %$d'> prints C<["bar","foo"]>. The same contract applies to
C<yq>, C<tomq>, C<propq>, C<iniq>, C<csvq>, and C<xmlq>.

C<xmlq> follows the same decoded-data model as the other query commands. XML
elements decode into nested hashes and arrays, repeated sibling tags become
arrays, attributes live under C<_attributes>, and mixed text lives under
C<_text>. That means C<printf '<root><value>demo</value></root>' | dashboard
xmlq root.value> prints C<demo>, while C<dashboard xmlq feed.xml '$d'> prints
the full decoded XML tree as canonical JSON.

=head1 MANUAL

=head2 Installation

Bootstrap a blank Alpine, Debian, Ubuntu, Fedora, or macOS machine from a checkout with:

  ./install.sh

Bootstrap a blank Windows PowerShell host from a checkout or the current shell with:

  powershell -ExecutionPolicy Bypass -File .\install.ps1
  irm https://raw.githubusercontent.com/manif3station/developer-dashboard/refs/heads/master/install.ps1 | iex

F<install.sh> and F<install.ps1> are checkout-only bootstrap helpers. They ship
in the source tree and release tarball so operators can run them explicitly
from a checkout, extracted tarball, or streamed bootstrap, but CPAN and
C<cpanm> do not install them as global commands. When the Unix-like installer
is streamed through C<sh> without a checkout, such as C<curl ... | sh>, it
falls back to embedded Debian-family, Alpine, Fedora, and Homebrew package
manifests instead of assuming repo-local F<aptfile>, F<apkfile>, F<dnfile>,
and F<brewfile> files exist on disk, then clones the current GitHub
C<master> checkout into a temporary local tree and installs that checkout so
the streamed bootstrap gets the same implementation snapshot that shipped the
installer instead of a stale CPAN release.

That installer reads the repo-root F<aptfile> on Debian-family hosts and runs
C<apt-get update> plus C<apt-get install -y> for the listed packages, reads
the repo-root F<apkfile> on Alpine hosts and runs
C<apk add --no-cache> for the listed packages, reads the repo-root
F<dnfile> on Fedora hosts and runs C<dnf install -y> for the listed
packages, reads the repo-root
F<brewfile> on macOS and runs C<brew install> for the listed packages,
ships C<tmux> in every one of those bootstrap package lists because
C<dashboard workspace> is a first-party tmux workflow, verifies that C<node>,
C<npm>, and C<npx> are available from those
bootstrap packages before finishing the install, or falls back to the embedded
copies of those package lists when the script is streamed without the checkout
files, installs Debian-family Node tooling in a conflict-aware order by
bringing in C<nodejs> first and only attempting the distro C<npm> package if
C<npm> and C<npx> are still missing, prints a visible install progress board
before doing any system changes, prints that full checklist once and then only
emits step transitions so the active pointer does not appear duplicated in
interactive terminals, explains that any upcoming C<sudo> prompt is asking for
the user's operating-system account password only for package-manager work,
bootstraps Homebrew itself on blank macOS hosts before it tries to read the
repo-root F<brewfile>, updates C<PATH> from the discovered Homebrew prefix so
the same run can immediately install the listed macOS packages without asking
the operator to reopen the shell,
bootstraps user-space Perl
tooling under F<~/perl5> with
C<cpanm --no-wget --notest --local-lib-contained "$HOME/perl5" local::lib App::cpanminus File::ShareDir::Install>,
appends exactly one C<local::lib> bootstrap line to F<~/.bashrc>,
F<~/.zshrc>, or F<~/.profile> depending on the preferred login shell even
when the installer is run through plain C<sh>, keeps bash login shells wired
by bridging F<~/.profile> to F<~/.bashrc>, prefers
Homebrew Perl on macOS when C<brew --prefix perl> exposes a brewed
interpreter, bootstraps a user-space C<perlbrew> Perl on Debian-family,
Alpine, or Fedora hosts when the system Perl is older than the required
C<5.38>, installs C<App::perlbrew> into F<~/perl5/bin> first if the package manager did not