Skip to content

Latest commit

 

History

History
246 lines (172 loc) · 8.34 KB

typex.md

File metadata and controls

246 lines (172 loc) · 8.34 KB

typex(1) - report salient information about commands, programs, and filesystem items

SYNOPSIS

Reports salient information about available commands, programs, and
filesystem items, such as command or file type, (ultimate) location,
and version.

typex [-p] [-V] [-v] [<nameOrPath>...]

-p     look for files only (ignore shell aliases, keywords, functions,  
       builtins)
-V     skip attempt to obtain executable version information
-v     verbose mode: report additional information

Install / uninstall sourcing via shell-initialization files (required
to detect aliases, functions, shell builtins - supported in
Bash, Ksh, Zsh):

typex -i
typex -u

DESCRIPTION

typex combines and extends features found in the standard type,
which, and file utilities.

Not specying any operands prints information about the current shell.

When given a command name (as opposed to a filesystem path), the
following command forms are recognized:

  • shell aliases, shell keywords, shell functions, shell builtins, and
    executable files in the $PATH

Alternatively, filesystem paths rather than mere (file)names may be
given, in which case extended information about theses paths is
reported.

NOTE: For this utility to detect shell-based command forms, it must be
sourced, which is supported in the following shells:
bash, ksh, and zsh

Sourcing this utility in your shell's per-user initialization file will
define a function of the same name that will be available in interactive
sessions:

  • typex -i installs this sourcing for all supported shells.
  • typex -u uninstalls it.

Alternatively, you can source and invoke at the same time; e.g.:

. typex read

If you instead invoke this utility directly (as a script):

  • only executable files and filesystem items will be detected -
    no other command forms;
  • a warning to that effect is printed, unless only filesystem paths are
    supplied; suppress it with -p.

Unless you specify a filesystem path, ALL defined
forms of a given command name are reported, in order of precedence
(highest first; if this utility is invoked directly or -p is specified,
only executable files with that name are reported):

  • bash, zsh:
    alias > shell keyword > shell function > builtin > executable

  • ksh
    shell keyword > alias > shell function > builtin > executable

The exit code is 0 if all operands were found, the number of
non-existent operands otherwise.

Note: typex is designed for interactive use, to provide humans with
concise, salient information about a command or filesystem object.
As such, its output is geared toward readability by humans,
and should not be relied on for programmatic parsing.

OPTIONS

  • -p, --files-only
    Only looks for (executable) files (ignores aliases, keywords,
    functions, and builtins).
    This option applies implicity if a given operand is a filesystem path
    rather than a mere command name.

  • -V, --skip-version
    Suppresses the attempt to obtain version information from executable
    files. Helpful if you know that the target file doesn't support
    --version, or you're wary of what invocation with --version`
    might do.

  • -v, --verbose
    Verbose mode: prints additional information - see below.

  • -i, --install-sourcing
    Updates the user-specific shell-initialization files of all supported
    shells, if present, to include a command to source this utility,
    which is the prerequisite for it to be able to detect shell-based
    definitions, namely shell aliases, keywords, functions,
    and builtins.

  • -u, --uninstall-sourcing
    Removes a previously installed sourcing command from the
    user-specific initialization files of supported shells.

OUTPUT FORMAT

All output starts with a capitalized headword identifying the command
form / path type, as in the headings below.
Output for each command form is single-line, except for the optional
information added by -v; the latter is indented with 2 spaces.

ALIAS

Prints the shell alias's definition. If the first token of the alias's
definition is itself a command, information about that command is
printed as well, in indented form, potentially recursively.
No attempt is made to detect additional commands inside the alias
definition.
-v is never applied to the recursive calls.

KEYWORD

A shell-language keyword, such as while; the name is printed.

FUNCTION

Prints the shell function name, followed by (); e.g., foo().
In Bash, if the function is also exported, # -x is appended.

With -v specified:
The function definition (its source code) is printed, too.

BUILTIN

Prints the shell builtin's name.

BINARY / SCRIPT / DIRECTORY / FILE

Prints files' full path, and, in the case of symlinks, the entire
symlink chain to the ultimate target file, using full paths.

If the file is not itself a symlink, but has symlink components
(directories) in its directory path, both the full form of the input
path as well as the canonical path with all symlinks resolved are
printed.

If the file is an executable script, interpreter information is
appended in parentheses; e.g., (bash script).
If the file is non-executable, file-type information obtained with
file is appended in parentheses; e.g., (ASCII text).
If the file is a special file such as /dev/null, its type is also
appended in parentheses; e.g., (character special).

For executable files, unless -V is specified, an attempt is made
to obtain version information through invocation with --version.
If -V was specified, or if no version information was found, the
last-modified timestamp of the (ultimate target) file is used.
Whatever information is available is appended in square brackets; e.g.,
[ls (GNU coreutils) 8.21] or [2014-09-09]

With -v specified:

  • File statistics (permissions, owner, ...) are printed using ls -l.
  • For symlinks, this happens for every file in the symlink chain.

Additional information printed for executables:

  • binaries: file-type information obtained with file.
  • scripts: the shebang line.

STANDARD OPTIONS

All standard options provide information only.

  • -h, --help
    Prints the contents of the synopsis chapter to stdout for quick reference.

  • --man
    Displays this manual page, which is a helpful alternative to using
    man, if the manual page isn't installed.

  • --version
    Prints version information.

  • --home
    Opens this utility's home page in the system's default web browser.

COMPATIBILITY

Platforms supported in principle:

  • OSX, Linux, BSD (with Bash installed)

On those, sourcing the script (recommmended) works in the following
shells:

  • Bash, Ksh, Zsh

LICENSE

For license information, bug reports, and more, visit this utility's
home page by running typex --home

EXAMPLES

  # Print info about the current shell.
$ typex 
BINARY:     /bin/bash  [GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin14)]

  # Print info about utility 'awk' and its symlink chain:
$ typex awk  
BINARY:     /usr/bin/awk@ -> /etc/alternatives/awk -> /usr/bin/gawk [GNU Awk 4.0.1]

  # Print information about command forms named 'printf' in order of 
  # precedence:
$ typex printf
BUILTIN:    printf
BINARY:     /usr/bin/printf  [printf (GNU coreutils) 8.21]

  # Print information about script 'npm':
$ typex -p npm
SCRIPT:     /usr/local/bin/npm  (node script)  [2.1.7]

  # Print information about executables 'nawk' and 'mawk':
$ typex -p nawk mawk
BINARY:     /usr/bin/nawk@ -> /etc/alternatives/nawk@ -> /usr/bin/gawk  [GNU Awk 4.0.1]
BINARY:     /usr/bin/mawk  [2014-03-24]

  # Define an alias and print information about it.
$ alias lsx='ls -FAhl'; typex lsx
ALIAS:      lsx='ls -FAhl'
  BINARY:     /bin/ls  [ls (GNU coreutils) 8.21]

  # Print extended information about a filesystem object:
$ typex -v '/User Guides And Information'
DIRECTORY:  /User Guides And Information@ -> /Library/Documentation/User Guides and Information.localized
  lrwxr-xr-x  1 root  wheel    60B Jul  2  2012 
  drwxrwxr-x@ 9 root  admin   306B Oct 16  2014