identifyAllExecutables

#!/usr/bin/env perl -w
#
# identifyAllExecutables: Search shell functions, aliases, executables, etc.
# 2006-10: Written by Steven J. DeRose.
#
use strict;
use Getopt::Long;

our %metadata = (
    'title'        => "identifyAllExecutables.pm",
    'description'  => "Search shell functions, aliases, executables, etc.",
    'rightsHolder' => "Steven J. DeRose",
    'creator'      => "http://viaf.org/viaf/50334488",
    'type'         => "http://purl.org/dc/dcmitype/Software",
    'language'     => "Perl 5.18",
    'created'      => "2006-10",
    'modified'     => "2022-04-06",
    'publisher'    => "http://github.com/sderose",
    'license'      => "https://creativecommons.org/licenses/by-sa/3.0/"
);
our $VERSION_DATE = $metadata{'modified'};

=pod


=head1 Usage

identifyAllExecutables [options]

For example:

    identifyAllExecutables --find '^python'
    
will attempt to find anything you can execute whose name starts with 'python' (not just
the one that will actually be invoked in a given situation); while

    identifyAllExecutables 

withg no options tries to locate all command regardless of type or name (this will be
a long list).
    
This should find anything that can be typed as a command, and display
it along with the type:

    alias
    shell function
    shell builtin
    shell keyword
    executable file along your \$PATH

By default:

    all types are shown (but see I<--sa --sb --f --x>)
    names beginning with "_" are omitted (see I<--underscore>.


=head1 Options

=over

=item * B<-c> OR B<--count>

Count by type (and executable files by directory).

=item * B<--find> I<regex>

Go through as specified by other options but only display items whose
names match I<regex>. See also I<--ignoreCase>.

=item * B<--ignoreCase> OR B<-i>

With I<--find>, ignore case when testing whether commands match the regex.

=item * B<--login>

Invoke shell with I<--login> when using it to get lists of things (PATH,
aliases, shell functions, ...), rather than searching for profiles manually.

=item * B<--profile> I<path>

Add the item at I<path> to the list of profiles to check for definitions of
aliases, shell functions, etc. By default, the usual bash and zsh suspects
are already included. Also, if C<$sjdUtilsDir/BashSetup> is a directory,
zprofile and bash_profile from there are included.

=item * B<-q> OR B<--quiet>

Suppress most messages.

=item * B<--sa> OR B<--showAliases> OR B<--aliases>

Show aliases.

=item * B<--sb> OR B<--showBuiltins> OR B<--builtins>

Show builtins and keywords.

=item * B<--sf> OR B<--showFunctions> OR B<--functions>

Show shell functions.

=item * B<--sp> OR B<--showPathDirs> OR B<--pathDirs>

Show directories of \$PATH.

=item * B<--sx> OR B<--showExecutables> OR B<--executables>

Show executable files.

=item * B<--system>

Include system command directories (default; use I<--nosystem> to turn off).
System commands are taken to include
executables under /usr, /bin, /sbin, or (mainly for MacOS) /Library.

=item * B<--underscore>

Show items whose names begin with "_" (default: off, because there
are a lot and they're rarely interesting).

=item * B<-v> OR B<--verbose>

Add more detailed messages.

=item * B<--version>

Display version info and exit.

=back


=head1 Known bugs and limitations

Has to get information about aliases, shell functions, environment variables, etc.
from a newly-spawned shell, not the one it was called from. There's no guarantee
that will be the same, though it tries to mimic states such as being login or
interactive.

May not correctly find all applicable profile files, or especially, anything
sourced indirectly from them.

Doesn't know anything about things like inactive Python venv or pyenv environments,
which aren't listed in \$PATH.

C<bash help> output (used to get the list of builtins),
is not parsed correctly enough. Also need to support zsh for this.


=head1 To do

    Sort by priority or alpha
    Show definitions (aliases)? Cf C<ecmd>.
    Show or filter by shebang lines?


=head1 Related Commands

C<which -a>: lists all executables of a given name, along $PATH. However, it
doesn't seem to deal with aliases, shell functions, or symlinks.

C<ecmd>: Tries to locate and edit the definition of an alias, shell function,
or non-binary executable file.


=head1 History

=over

=item 2006-10: Written by Steven J. DeRose.

=item 2007-12-17 sjd: Handle profiles/rcs better.

=item 2010-09-12 sjd: ??

=item 2012-01-09 sjd: Refactor. Add --underscore. Test for bash use.

=item 2013-02-08 sjd: Add --system, --login.

=item 2015-08-27: --. Option aliases. Improve doc. Color.

=item 2015-09-18: Add --ignoreCase. Improve output layout.

=item 2020-03-04: New layout?

=item 2021-12-03: Work on zsh support. Add --profile.

=item 2022-04-06: Start zsh support.

=back


=head1 Ownership

This work by Steven J. DeRose is licensed under a Creative Commons
Attribution-Share Alike 3.0 Unported License. For further information on
this license, see L<here|"http://creativecommons.org/licenses/by-sa/3.0/">.

For the most recent version, see L<here|"http://www.derose.net/steve/utilities/">.


=cut


###############################################################################
# Options
#
my $color             = ($ENV{CLI_COLOR} && -t STDERR) ? 1:0;
my $count             = 0;
my $find              = "";
my $ignoreCase        = 0;
my $login             = 0;
#my $managers          = 0;
my @profiles          = ();
my $quiet             = 0;
my $showAliases       = 0;
my $showBuiltins      = 0;
my $showExecutables   = 0;
my $showFunctions     = 0;
my $showPathDirs      = 0;
my $sort              = 0;
my $system            = 1;
my $underscore        = 0;
my $verbose           = 0;

my %getoptHash = (
    "c|count!"                        => \$count,
    "f|find=s"                        => \$find,
    "h|help|?"                        => sub { system "perldoc $0"; exit; },
    "i|ignoreCase!"                   => \$ignoreCase,
    "login!"                          => \$login,
    #"managers!"                       => \$managers,
    "profile=s"                       => \@profiles,
    "q|quiet!"                        => \$quiet,
    "sa|showAliases|aliases!"         => \$showAliases,
    "sb|showBuiltins|builtins!"       => \$showBuiltins,
    "sx|showExecutables|executables!" => \$showExecutables,
    "sf|showFunctions|functions!"     => \$showFunctions,
    "sp|showPathDirs|pathDirs!"       => \$showPathDirs,
    "sort!"                           => \$sort,
    "system!"                         => \$system,
    "underscore!"                     => \$underscore,
    "v|verbose+"                      => \$verbose,
    "version"                         => sub {
        die "Version of $VERSION_DATE, by Steven J. DeRose.\n";
    },
);
Getopt::Long::Configure ("ignore_case");
GetOptions(%getoptHash) || die "Bad options.\n";

# Show everything unless they asked for specifics.
my $showAll =
    ($showAliases+$showBuiltins+$showFunctions+$showExecutables+$showPathDirs+$count
     == 0);

my $findExpr = "";
if ($find) {
    $findExpr = qr/$find/;
}


###############################################################################
# Find startup and profile files to consider.
#
my $home = $ENV{HOME};
my $shell = $ENV{SHELL};
($shell eq "/bin/bash") || warn
    "Not guaranteed when not using bash (current \$SHELL is '$shell').\n";
($shell eq "/bin/zsh" && $ENV{ZDOTDIR} != $home) && warn
    "In zsh, with \$ZDOTDIR is $ENV{ZDOTDIR} -- not supported yet.\n";

my @zshProfiles = (
    "/etc/profile",
    "$home/.bash_profile",
    "$home/.bash_login",
    "$home/.profile",
    "$home/.bashrc",
);
my @bashProfiles = (
    "/etc/zshenv",	 "$home/.zshenv",	# for all shells
    "/etc/zprofile", "$home/.zprofile",	# for LOGIN shells only
    "/etc/zshrc",    "$home/.zshrc",	# for INTERACTIVE shells only
    "/etc/zlogin",	 "$home/.zlogin",	# for LOGIN shells only
);
if ($ENV{BASH_ENV}) { push @bashProfiles, $ENV{BASH_ENV}; }

my @profs = ();
if ($shell eq "/bin/bash") {
    @profs = @bashProfiles;
    
}
else {
    @profs = @zshProfiles;
}
for my $p (@profiles) {
    push @profs, $p;
}

my $sjdUtilsDir = $ENV{"sjdUtilsDir"};
my $sjdSetup =  "$sjdUtilsDir/BashSetup";
if (-d $sjdSetup) {
    for my $p (@profiles){
        if ($shell eq "/bin/bash") { push @profs, "$sjdSetup/bash_profile"; }
        if ($shell eq "/bin/zsh") { push @profs, "$sjdSetup/zprofile"; }
    }
}
else {
    ($verbose) && warn "\$sjdUtilsDir area not found ($sjdUtilsDir).\n";
}

($verbose) && warn sprintf("List of setup files:\n%s\n", join(@profs, "\n    "));


###############################################################################
# Launch shell so it looks mostly like caller's state.
#
my $rcf = "";
if ($login) {
    $rcf = "--login";
}
else {
    my $nfound = 0;
    my @foundProfiles = ();
    for my $p (@profs) {  # TODO: This only keeps one, though checks many!
        if (-f $p) {
            ($verbose) && warn "Profile/rc file found: '$p'.\n";
            push @foundProfiles, $p;
            if ($shell eq "/bin/bash") {
                $rcf = "--rcfile $p";
            }
            else {
                warn "Cannot do --rcfile $p in non-bash.\n";
            }
            $nfound++;
        }
    }
    if ($nfound > 1) {
        warn "WARNING: Found multiple profiles:\n    "
            . join("\n    ", @foundProfiles) . "\n";
        warn "Only '$rcf' will be used.\n";
    }
}


###############################################################################
# Main
#
my @pathdirs  = split(/:/, $ENV{PATH});
if (!$system) {  # In that case, remove system directoriess
    for (my $i = scalar(@pathdirs)-1; $i>=0; $i--) {
        if ($pathdirs[$i] =~ m@^/(usr|bin|sbin|Library)@) {
            delete $pathdirs[$i];
        }
    }
}

my @aliases   = @{getAliases()};
my @builtins  = @{getBuiltins()};
my @functions = @{getFunctions()};
my @xfiles    = ();
my %xcounts   = ();
# Only look for files if we need to
if ($showExecutables || $showAll || $count) {
    @xfiles = @{getFiles()};
}

report();

exit;


###############################################################################
# Get an array of all the aliases.
# The difficulty is that we're not in the interactive shell the user has.
# Could instead use 'alias -p'.
#
sub getAliases {
    # $rcf says what kind of shell to launch, like --login or --rcfile x
    my $cmd = "$shell $rcf -l -c alias " .
        "| grep '^alias'" .
        "| sed -e 's/alias *//' -e 's/=.*\$//'";
    ($verbose) && warn "getting Aliases via $cmd.\n";
    my @aliases = `$cmd`;
    (scalar @aliases > 1) || die "    -- nope\n";
    for (my $i=0; $i<scalar(@aliases); $i++) {
        chomp $aliases[$i];
    }
    if (!$underscore) { dropUS(\@aliases); }
    return(\@aliases);
}


###############################################################################
# Get an array of all the builtins.
#
sub getBuiltins {
    my $cmd = "$shell $rcf -i";
    if ($shell eq "/bin/bash") { $cmd .= " -c help"; }
    ($verbose) && warn "getting builtins via $cmd.\n";
    my @raw = `$cmd`; # in 2 columns
    (scalar @aliases > 1) || die "    -- nope\n";
    my @builtins = ();
    for (my $i=0; $i<scalar(@raw); $i++) {
        if ($raw[$i] =~ m/^[^ ]/ ||  # Skip intro text
            $raw[$i] =~ m/^\s*$/) {
            next;
        }
        chomp $raw[$i];
        if (length($raw[$i]) > 35 && substr($raw[$i],35,1) ne " ") {
            warn "WARNING: Data from 'help' not formatted as expected:\n";
            warn "[" . substr($raw[$i],0,35) . "]\n" .
                "[" . substr($raw[$i],35,1) . "]\n" .
                "[" . substr($raw[$i],36)   . "]\n";
        }
        elsif ($verbose) {
        }
        my $b1 = substr($raw[$i],1,35);
        if ($b1 =~ m/^\w/) { $b1 =~ s/\s.*//; }
        push @builtins, $b1;
        my $b2 = substr($raw[$i],36);
        if ($b2 =~ m/^\w/) { $b2 =~ s/\s.*//; }
        push @builtins, $b2;
    }
    if (!$underscore) { dropUS(\@builtins); }
    return(\@builtins);
}


###############################################################################
# Get an array of all the shell functions.
# 'typeset' command is a bash builtin that sets or prints variables,
# including shell functions (-f), arrays (-a), associative arrays (-A).
#
sub getFunctions {
    my @functions = ();
    if ($shell eq "/bin/bash") {
        my $cmd = "$shell $rcf -i -c typeset -f" .
            " | grep '^[^ ].*()'" .
            " | sed 's/ ()//'";
        ($verbose) && warn "getting functions via $cmd.\n";
        @functions = `$cmd`;
        for (my $i=0; $i<scalar(@functions); $i++) {
            chomp $functions[$i];
        }
    }
    elsif ($shell eq "/bin/zsh") {
    }
    else {
        warn "getFunctions: Unsupported shell $shell.\n";
    }
    if (!$underscore) { dropUS(\@functions); }
    return(\@functions);
}


###############################################################################
# Collect up all the executables in directories listed in @pathDirs.
#
sub getFiles {
    @xfiles = ();
    %xcounts = ();
    for my $d (@pathdirs) {
        next unless (defined $d);
        ($verbose) && warn "Checking \$PATH dir '$d'.\n";
        if (! -d $d) { next; }
        if ($xcounts{$d}) {
            ($quiet) || warn "WARNING: Duplicate dir in \$PATH: '$d'.\n";
            next;
        }
        for my $f (`ls $d 2>/dev/null`) {
            chomp $f;
            ($verbose >= 2) && warn "    File '$d/$f'.\n";
            next unless (-x "$d/$f");
            push @xfiles, "$d/$f";
            $xcounts{$d}++;
            # Check for #! line?
        }
    }
    if (!$underscore) { dropUS(\@xfiles); }
    return(\@xfiles);
}

sub dropUS {
    my ($aRef) = @_;
    my @copy = ();
    ($verbose) && warn "dropUS: aRef: $aRef.\n";
    for my $name (@{$aRef}) {
        if ($name !~ m/^_/) { push @copy, $name; }
    }
    @{$aRef} = @copy;
}


###############################################################################
# Reporting
#
sub rline {
    my ($type, $path) = @_;
    my $n = rindex($path, "/");
    my $dir = "";
    my $file = $path;
    if ($n>=0) {
        $dir = substr($path, 0, $n+1);
        $file = substr($path, $n+1);
    }
    if ($find) {
        if (!$ignoreCase && $file !~ /$findExpr/)  { return; }
        if ( $ignoreCase && $file !~ /$findExpr/i) { return; }
    }
    printf("%-20s%-20s%s\n", $file, $type, $dir);
}

sub report {
    if ($showAll) {
        my %all = ();
        for my $c (@aliases)   {  $all{$c} = "ALIAS"; }
        for my $c (@builtins)  {  $all{$c} = "BUILTIN"; }
        for my $c (@functions) {  $all{$c} = "FUNCTION"; }
        for my $c (@xfiles)    {  $all{$c} = "FILE"; }

        ($quiet) || print "\nItems found:\n";
        for my $cmd (sort keys %all) {
            rline($all{$cmd}, $cmd);
        }
    }
    else {
        if ($showAliases) {
            print "ALIASES:\n";
            print "    " . join("\n    ", @aliases)   . "\n";
        }
        if ($showBuiltins) {
            print "BUILTINS:\n";
            print "    " . join("\n    ", @builtins)  . "\n";
        }
        if ($showFunctions) {
            print "FUNCTIONS:\n";
            print "    " . join("\n    ", @functions) . "\n";
        }
        if ($showPathDirs) {
            print "PATH DIRS:\n";
            print "    " . join("\n    ", @pathdirs)  . "\n";
        }
        if ($showExecutables) {
            print "EXECUTABLES:\n";
            for my $cmd (sort @xfiles) {
                print "    $cmd\n";
            }
        }
    }

    if ($count) {
        print "\nCOUNTS (executable files are alphabetical by directory):\n";
        my $lastTop = "";
        my $xtot = 0;
        for my $c (sort keys %xcounts) {
            (my $nextTop = $c) =~ s|(/[^/]+/).*|$1|;
            if ($nextTop ne $lastTop) {
                ($quiet) || print "\n";
                $lastTop = $nextTop;
            }
            printf("    %5d  %s\n", $xcounts{$c}, $c);
            $xtot += $xcounts{$c};
        }
        ($quiet) || print "\n";
        printf("    Aliases:   %5d\n", scalar(@aliases));
        printf("    Functions: %5d\n", scalar(@functions));
        printf("    Builtins:  %5d\n", scalar(@builtins));
        printf("    Files:     %5d\n", $xtot);
        printf("    Total:     %5d\n",
        $xtot + scalar(@builtins) + scalar(@functions) + scalar(@aliases));
    }
}