General: ======= Path Manager helps manage your path. It allows you to add or remove elements from a PATH-like variable including the bulk addition or removal of path elements. There are two main advantage of this script over sourcing a shell script. First, pathmgr lets you remove elements from the path. This is something that requires some work in most shells. Specifically, if you are using an XML configuration file, pathmgr lets you easily undo bulk addition of path elements. Second, pathmgr is portable. This lets you specify the path you want using a single XML configuration, generate the new path using pathmgr, and pick up the changes using any shell, even CMD.EXE. Usage: ===== python pathmgr [] [ ...] Options: ======= -a= --after= --append= Add the path element to the path after all other path elements. This option can be specified more than once. --anchor= The anchor is the directory to which relative paths are anchored. It is not necessary to use this option, but it can be convenient. The reason pathmgr needs to know exactly where relative paths are anchored is so it can add (or remove) normalized path elements if --normalize=on is set, and the only way it can normalize path elements is if it knows exactly where they reside. Anchors specified using a relative path are themselves relative to the "anchor base." For command-line options, the anchor base is the current working directory. For "sourced" XML configuration files, the anchor base is inherited from the caller. For XML configuration files specified with --include, the anchor base is the directory containing the XML configuration file (c.f. --source). Roughly speaking, the path elements to be added or removed are formed as follows from a given relative path: (--normalize=off) => anchor + relative_path (--normalize=on) => anchor_base + anchor + relative_path Roughly speaking, XML configuration files specified with --include= are relative only to the "anchor base" and ignore an explicitly set "anchor": xml_config_file = anchor_base + relative_path Thus for XML configuration files specified with --include, the "anchor base" is the directory where the file resides irrespective of whether the user has set an explict anchor. Thus, explicitly set anchors only affect path elements that are being added or removed from the path. They do not affect loading of XML configuration files. -b= --before= --prepend= Add the path element to the path before all other path elements. This option can be specified more than once. -c --clean --clean-only Clean the path by removing path elements instead of adding them. To restore your path to the value it had before the previous run of this script, run pathmgr with the exact same command as before except add the --clean option to the front of the command. This will cause --append and --prepend to remove path elements instead of adding them. This option can be specified more than once allowing path elements to be processed with different values for this option. Use -c (or -c=on) and -c=off to explicitly enable or disable this option. --default== Define the default value of a variable. This is mostly used in XML configuration files in order to provide a default if the user does not explicitly override the value on the command line with the --define option. To use a variable, just add ${variable} to any path element and it will be replaced with the value of the variable. This option can be specified more than once allowing path elements to be processed with different values for this option. -D== --def== --define== Define the value of a variable overriding any default value set up by the --default option. This is mostly used on the command line to override default values set up in XML configuration files. To use a variable, just add ${variable} to any path element and it will be replaced with the value of the variable. This option can be specified more than once allowing path elements to be processed with different values for this option. Also see the --undefine option. -d= --delete= Delete the path element from the path. If you need to remove a specific path, it is usually a good idea to set --normalize=off before using this option so that the exact path specified is the one pathmgr tries to remove. This option can be specified more than once. This is a synonym for --remove. --dups --duplicates --allow-duplicates By default, new path elements that duplicate existing path elements are not added to the path. By setting --dups=on, new path elements will always be added even if they duplicate an existing path element. This option can be specified more than once allowing path elements to be processed with different values for this option. Use -dups=on and -dups=off to explicitly enable or disable this option. -f=off --force=off By default, path elements are forced onto the path even if the underlying directory is missing from the file system. By setting --force=off, path elements will be added to the path only if they actually exist. This option can be specified more than once allowing path elements to be processed with different values for this option. Use -f (or -f=on) and -f=off to explicitly enable or disable this option. -h --help Print this help message and exit. --include= Process the XML configuration file in local scope which means any changes to the context made by the XML file are local to that file and are not seen by the caller. If you want an XML configuration file to change the caller's context, use the --source= option instead. This is the default way XML configuration files are processed. This option can be specified more than once. Note that this option is also available in XML configuration files allowing you to include other XML files. Options specified in the XML configuration file are not effective until the file is processed in sequence with other processing. If an "anchor base" is already set, it is automatically overridden during processing of with the parent directory of serving as the new anchor base. The original anchor base is restored when processing of completes. Thus, by default, all relative paths specified in an included XML configuration file are relative to the directory where the file resides. [Also see --source=.] --license Print the license and exit. -l -l= --list --list= List the existing path with one directory per line instead of printing the path with its embedded delimiters. This option lists the path as it exists at that point in the command pipeline. To see the final result, the --list option must be specified as pathmgr's last command-line option. This option can be specified more than once. This is useful for debugging. If a non-empty separator is specified, it will be printed after the listing to provide a visual separator between listings. This option implies --quiet=on. Add a trailing --quiet=off to override. --log-to-stderr By default, the help message, the version message, and log messages all go to standard output. If this option is set, they will go to standard error instead. This is mostly used when a shell sets the PATH directly from the output of the pathmgr.py Python script. Without this option set in these circumstances, help output would not be seen by the user because it would be used to overwrite the PATH variable neither of which is good. This option can only be specified once and only on the command line (because it needs to be used very early). If it is specified more than once, the last value specified is used. Use --log-to-stderr (or --log-to-stderr=on) and --log-to-stderr=off to explicitly enable or disable this option. -n=off --normalize=off By default, path elements are normalized before they are added to the path. By disabling normalization, the path elements will be added to the path literally. This option can be specified more than once allowing path elements to be processed with different values for this option. Use -n (or -n=on) and -n=off to explicitly enable or disable this option. Note that the shell used by MinGW normalizes both command-line parameters and environment variables (like PATH) before passing them to native applications like the Python interpreter that runs the pathmgr script! This can make it *appear* as though pathmgr is not honoring --normalize=off. The solution to the MinGW problem is two fold. First, use an XML configuration file to pass paths to pathmgr to avoid MinGW's normalization of command-line parameters. For example: off /c/foo/bar/baz Second, pipe the PATH into pathmgr instead of passing it through the environment to avoid MinGW's normalization of environment variables. For example: printf "$PATH" | pathmgr --origin=- --sep=: --uds=off foo.xml To make this more convient, the "pathmgr-mingw" script is provided which can be executed as follows: pathmgr-mingw foo.xml To learn more about MinGW's normalization of command-line parameters and environment variables, visit the following URL: http://www.mingw.org/wiki/Posix_path_conversion --origin= The origin of the path being modified. This can be either the name of an environment variable or the special string "-" which means the origin is taken from standard input. By default, the origin is the PATH environment variable. This option be specified only on the command line (because it needs to be used very early). If it is specified more than once, the last value is used. --print-state Print the current state. This option can be specified more than once. -q --quiet Do not print the final result. -r= --remove= Remove the path element from the path. If you need to remove a specific path, it is usually a good idea to set --normalize=off before using this option so that the exact path specified is the one pathmgr tries to remove. This option can be specified more than once. This is a synonym for --delete. --rmdups --remove-duplicates Remove all duplicates from the path. To specify this option in an XML configuration file use one of the following empty XML elements: or . If normalization is on, path elements are considered to be duplicates if their normalized values are the same. If normalization is off, path elements are considered to be duplicates if their nominal values are the same. (See --normalize.) --sep= --separator= Path separator. Defaults to ':' on Unix and ';' on Windows. This option can only be specified once and only on the command line (because it needs to be used very early). If it is specified more than once, the last value specified is used. --source= Process the XML configuration file in the same context as the caller. This allows to change the caller's context. When --source is used from the command line, any change made by affects the global context (which is the primary reason one would use --source instead of --include). Note that this option is also available in XML configuration files allowing you to "source" other XML files. Note that because the file is being processed in the caller's context it shares the same "anchor base" as the caller. This means that XML configuration files included by that are specified by relative path are not necessary relative to the directory where resides (c.f., --include). This option can be specified more than once. Options specified in the XML configuration file are not effective until the file is processed in sequence with other processing. [Also see --include=.] --tilde=off --tilde-expansion=off By default, leading "~" or "~user" characters will be expanded to the equivalent of the user's HOME directory. This option can be specified more than once allowing path elements to be processed with different values for this option. Use --tilde (or --tilde=on) and --tilde=off to explicitly enable or disable this option. If you enable the --univ-dir-seps=on option (the default), tilde expansion will be consistent across platforms. However, with --univ-dir-seps=off, the situation is a little complicated. On Linux "~\foo" will not expand because backslash is not a directory separator on Linux meaning "~\foo" is interpreted as "~user" where user="\foo". Because there is no "\foo" user, there is no tilde expansion. On Windows, both "~\foo" and "~/foo" will expand because Windows treats both the backslash and the slash as directory separators. -U= --undef= --undefine= Undefine the "--defined" value of a variable restoring any "--default" value. This option can be specified more than once allowing path elements to be processed with different values for this option. Also see the --define option. --uds=off --univ-dir-seps=off --universal-directory-separators=off By default, universal directory separators are enabled. This means slashes or backslashes that appear in path elements get converted to native directory separators. This option can be specified more than once allowing path elements to be processed with different values for this option. Use --univ-dir-seps (or --univ-dir-seps=on) and --univ-dir-seps=off to explicitly enable or disable this option. -v --verbose Enable verbose output. This option can be specified more than once allowing path elements to be processed with different values for this option. Use -v (or -v=on) and -v=off to explicitly enable or disable this option. -V --version Print the version and exit. -w= --which= List each executable in your PATH (or delimited list specified by the --origin option) that matches the regular expression. This option implies --quiet=on. To override, add a trailing --quiet=off. This option is only valid from the command line. XML Configuration Files: ======================= Instead of listing the path elements on the command line, they can be specified in the XML configuration files. The basic format for each file is just XML with and tags that control whether the directory is prepended or appended respectively: /home/spam/eggs /home/foo/bar /home/foo/baz Note that by default any options set in an XML configuration file is only within scope while that XML file is being processed. For more, see the --include and --source options above. Almost all of the options above that start with "--" are valid XML tags. They can be mixed with , , , etc., or they can be placed in their own XML file to serve as basic configuration: off Examples: ======== Unix Bourne Shell: ----------------- PATH=`python pathmgr.py ...` export PATH Windows CMD.EXE: --------------- REM Use the provided pathmgr.bat wrapper. pathmgr.bat ... REM Alternatively, use "clip" then paste the result as follows: python pathmgr.py ... | clip set path=