etc/whichpm/doc/whichpm.md

   1 <!-- DO NOT EDIT THIS FILE: It is auto-generated by `make update-man` -->
   2
   3 # whichpm(1) - locate installed Perl modules
   4
   5 ## SYNOPSIS
   6
   7 Prints the filesystem paths of the specified Perl modules, if installed.
   8
   9     whichpm    [-v] [-q] [-e] <module_name>...
  10     whichpm -a [-v] [-q] [-e] [<module_name>...]
  11
  12     -a ... lists all installed module files / all module files matching
  13            the specified name(s) (checks for accidental duplicates)
  14     -v ... verbose mode: also prints name, version, core-module status
  15     -q ... suppresses warnings
  16     -e ... opens modules in default text editor
  17
  18 Standard options: `--help`, `--man`, `--version`, `--home`
  19
  20 ## DESCRIPTION
  21
  22 `whichpm` reports the filesystem path of Perl modules by module (package)
  23 name, similar to what the Unix `which` utility does for binaries.
  24
  25 Optionally, additional information can be output, and all installed modules
  26 can be listed.
  27
  28 The exit code reflects the number of modules that could NOT be found.
  29 I.e., a non-zero exit code implies that at least one module could not be
  30 found.
  31 Conversely, exit code 0 implies that all specified modules were located
  32 successfully.
  33
  34 Note that using `-v` requires starting a separate Perl instance for each
  35 module examined in order to determine the version number. A separate Perl
  36 instance is the only safe way to load a module without affecting operation
  37 of this utility itself.
  38 Combining `-v` with `-a` with no module names therefore results in a
  39 lengthy, resource-intensive operation.
  40
  41 ## OPTIONS
  42
  43 * `-a, --all`, if no module names are specified, prints the filesystem paths
  44   of all installed modules. See caveat re combining with `-v` above.
  45   Otherwise, prints the paths of all files matching the specified module
  46   name(s), which effectively tells you whether a given module is accidentally
  47   installed in more than one location.
  48
  49 * `-e, --edit` also opens the module files in your system's default text
  50   editor. On Windows, you may be prompted to choose that editor on first run.
  51   Caveat: Will not work on Cygwin.
  52
  53 * `-v, --verbose` also outputs the package name, version number, and
  54   information about whether the module is a core module; see performance
  55   caveat above.
  56   Output format:
  57    `<name>\t<version>\t<core-indicator>\t<path>`
  58   On Unix platforms, pipe to `column -t` for column-aligned display.
  59   If the package name or version number cannot be determined, `?` is printed.
  60   `<core-indicator>` shows the following:
  61
  62     * If the module is a core module:
  63       Something like `core>=5.005`, which indicates what Perl version first
  64       included the module.
  65       To see a list of what Perl version included what version of the module,
  66       run `corelist -a <module_name>`.
  67
  68     * Otherwise: `(non-core)`
  69     If your Perl version is too old to support this check, or if the module
  70     name couldn't be determined (when using `-a -v` without operands), you'll
  71     see `(n/a)`.
  72
  73 * `-q, --quiet` suppresses warnings, such as when a module file's package name
  74   cannot be determined, duplicate module files are found, or, on Windows
  75   or OSX, when a case-inexact form of a module name is specified.
  76
  77 ## STANDARD OPTIONS
  78
  79 All standard options provide information only.
  80
  81  * `-h, --help`
  82    Prints the contents of the synopsis chapter to stdout for quick reference.
  83
  84  * `--man`
  85   Displays this manual page, which is a helpful alternative to using `man`
  86   if the manual page is not installed, such as on Windows.
  87
  88  * `--version`
  89    Prints version information.
  90
  91  * `--home`
  92    Opens this utility's home page in the system's default web browser.
  93
  94 ## NOTES
  95
  96 On platforms with case-sensitive filesystems you must specify case-exact
  97 package names, as Perl itself requires; for instance, 'data::dumper' will
  98 not find the 'Data::Dumper' module.
  99 On case-insensitive filesystems, such as on Windows and OS X, you can get
 100 away with specifying a case-inexact package name, but a warning will be
 101 issued.
 102
 103 Note that Perl's search path for modules (`@INC`) typically includes the
 104 current directory (`.`), so you may get different results depending
 105 on which directory `whichpm` is called from.
 106
 107 When using `-a` without module names in combination with `-v`, the package
 108 names have to be extracted by custom-parsing the module file, which may
 109 not succeed in all cases - package declarations may be missed, or false
 110 positives may be found.
 111
 112 ## COMPATIBILITY
 113
 114 Requires Perl v5.4.50 or higher; for core-module status information,
 115 v5.8.9 or higher is required.
 116 Expected to work on Unix-like platforms and Windows.
 117
 118 ## EXAMPLES
 119
 120     # Find and report additional information about the Data::Dumper module,
 121     # then open it in the default text editor.
 122     whichpm -v -e Data::Dumper
 123
 124 ## LICENSE
 125
 126 Copyright (c) 2015 Michael Klement (mklement0@gmail.com), released under
 127 the [MIT license](https://spdx.org/licenses/MIT)