Title
adolist -- Ado package lists
Syntax
+----------------------+ ----+ Package lists at SSC +---------------------------------------------
List available package lists at SSC
adolist ssc
Describe specified package list at SSC
adolist ssc pkl
Install specified package list from SSC
adolist ssc pkl , install [ all replace force adodir(dir) ]
+----------------------------------+ ----+ Package lists at other locations +---------------------------------
Describe specified package list
adolist describe filename [ , from(path) ]
Install specified package list
adolist install filename [ , from(path) all replace force adodir(dir) ]
+-------------------------+ ----+ Installed package lists +------------------------------------------
List all installed package lists
adolist [dir] [, adodir(dir) ]
Describe an installed package list
adolist describe pkl [, adodir(dir) ]
Update an installed package list
adolist update pkl [, keep dropmost dropall all force adodir(dir) ]
Uninstall a previously installed package list
adolist uninstall pkl [, keep dropmost dropall adodir(dir) ]
+-----------------------+ ----+ Create a package list +--------------------------------------------
adolist store filename [, store_options ]
adolist store [packages] using filename [, store_options ]
adolist list [packages] [, store_options ]
store_options description -------------------------------------------------------- nolocal do not include local packages localonly include local packages only nosort do not sort the package list title(str) include a title description(str) include a description author(str) identify package list author help[(strlist)] produce a help file replace overwrite existing files adodir(dir) include packages installed in dir --------------------------------------------------------
In the above commands, pkl denotes the name of the package list, possibly including a suffix (the default suffix is .pkl). filename is like pkl but may also include a file path, which can be a local path on your computer or an URL.
Description
adolist manages lists of user ado packages.
adolist ssc lists, describes, and installs package lists from the SSC archive.
adolist describe describes the contents of a specified package list.
adolist install installs a specified package list.
adolist dir gives an overview of the package lists that are installed on your computer.
adolist update updates a previously installed package list.
adolist uninstall uninstalls from your computer a previously installed package list. The single packages are only uninstalled if they are not part of another package list and if they were not on the system prior to installing the package list.
adolist store creates a package list file (and, optionally, a help file) from the packages that are installed on your computer. packages specifies the packages to be included. You may use the * and ? wildcards in packages. All installed packages are included if packages is omitted. adolist list is like adolist store, but displays the package list instead of storing it to a file. The help option is without effect for adolist list.
Note that packages may also include packages that are not installed on your computer. However, for such packages to be added to the package list, you have to provide the package's URL after the package name and enclose name and URL in double quotes. In fact, the full syntax for packages is
<pkg> [ <pkg> ... ]
where pkg is
name <url> <title> <author> <heading>
and <str> signifies that str must be enclosed in double quotes if it contains spaces (or compound double quote if it contains double quotes). An example would be
"abc http://a.b.c/ ABC-Module" `"xyz c:/x/y/z/ "My XYZ Package""'
url may be SSC to indicate that the package is located in the SSC-Archive. title and author are relevant only for the help file (see the help option). heading, if specified, will be inserted on a separate line before the package's entry in the list and may be used to structure the package list (you may want to specify the nosort option if making use of headings). It affects both, the package list source file and the help file. url and title, if specified, take precedence over the package's URL and title determined from the local system. Packages that are not found on the local system and for which no URL is provided are discarded.
Options for adolist ssc
install causes the specified package list to be installed. The default is to describe the package.
all copies any additional files (ancillary files) in the packages to your current directory (or location determined by net set other).
replace specifies that the downloaded files replace existing files.
force specifies that the downloaded package files replace existing files even if Stata thinks all the files are the same. force implies replace.
adodir(dir) specifies where to install the package list. The default is adodir(PLUS) (see help sysdir).
Options for adolist describe
from(path) specifies the location of the package list, where path may be a local path on your computer or an URL. Alternatively, the path may also be specified as part of filename. If no path is specified, neither as part of filename nor in from(), adolist describe first looks among the installed package lists and then in the current working directory.
adodir(dir) specifies that the package to be described is installed in dir. The default dir is PLUS (see help sysdir).
Options for adolist install
from(path) specifies the location of the package list, where path may be a local path on your computer or an URL. Alternatively, the path may also be specified as part of filename.
all copies any additional files (ancillary files) in the packages to your current directory (or location determined by net set other).
replace specifies that the downloaded files replace existing files.
force specifies that the downloaded package files replace existing files even if Stata thinks all the files are the same. force implies replace.
adodir(dir) specifies where to install the package list. The default is adodir(PLUS) (see help sysdir).
Options for adolist dir
adodir(dir) specifies where the package lists are installed. The default is adodir(PLUS) (see help sysdir).
Options for adolist update
keep causes discontinued packages (packages that are no longer part of the package list) to be kept in the system. The default is to delete these packages unless they were in the system prior to installing the package list or are part of other installed package lists.
dropmost specifies that all discontinued packages be uninstalled, except for packages that are part of other installed package lists. The default is to delete discontinued packages unless they were in the system prior to installing the package list or are part of other installed package lists.
dropall specifies that all discontinued packages be uninstalled, even if some of these packages were in the system prior to installing the package list or are also part of other installed package lists.
all copies any additional files (ancillary files) in the packages to your current directory (or location determined by net set other).
force specifies that the downloaded package files replace existing files even if Stata thinks all the files are the same.
adodir(dir) specifies where where the package list is installed. The default is adodir(PLUS) (see help sysdir).
Options for adolist uninstall
keep causes the single packages to be kept in the system. Use the keep option if you want to drop the package list definition, but keep the packages.
dropmost specifies that all packages in the package list be uninstalled, except for packages that are part of other installed package lists. The default is to uninstall only packages that have not been in the system prior to installing the package list and that are not part of other installed package lists.
dropall specifies that all packages in the package list be uninstalled, even if some of the packages have already been in the system before installing the package list or if some of the packages are also part of other installed package lists. The default is to uninstall only packages that have not been in the system prior to installing the package list and that are not part of other installed package lists.
adodir(dir) specifies where the package list is installed. The default is adodir(PLUS) (see help sysdir).
Options for adolist store and adolist list
nolocal omits packages that have been installed from a local path.
localonly omits packages that have been installed from the net.
nosort omits sorting the package list. The default is to return the list in alphabetical order.
title(str) specifies a title to appear in the header of the package list file (and in the help file).
description(strlist) specifies a description to appear in the header of the package list file (and in the help file). Use double quotes to specify multiple lines (i.e. "line 1" "line 2" etc.).
author(str) specifies information on the "author" of the package list to appear in the header of the package list file (and in the help file).
help generates a Stata help file for the package list. help has no effect if specified with adolist list. The help file will contain the list of packages and also include the title, description, and author information. Additional text to be added to the help file can be specified as help(strlist). The text will be inserted as is after the section containing the list of packages. Use double quotes and SMCL directives to format the text. For example "" inserts an empty line, {title:...} creates a new help file section, and {pstd} inserts a standard help file paragraph:
. adolist ..., help("" "{title:Remarks}" "" "{pstd} blah etc." "")
replace permits adolist to overwrite existing files.
adodir(dir) specifies where the packages to be stored are installed. The default is adodir(PLUS) (see help sysdir).
Examples
The following command produces a package list of all installed user ado's on your system and stores the list file in the working directory:
. adolist store myadosystem (myadosystem.pkl created; containing 99 packages)
To install the same set of ado packages on an another computer, copy "myadosystem.pkl" to, say "C:\temp" on this computer and run
. adolist install C:\temp\myadosystem (output omitted)
Conventions for package list files
The adolist store command is a convenient tool to produce a package list, but it also has its limitations. Fortunately, it is easy to produce a package list file "by hand" or edit an existing package file. Here are the details:
1. The first line of a package list file must start with
*! Stata package list
2. Lines containing comments must start with *. For example, the header of a package list file might read:
*! Stata package list 21aug2007 * My favorite packages
The second line of the file is assumed to contain the title of the package list, if it is a comment line. Consecutive comment lines, up to the first line that contains a package entry or that is entirely blank, are assumed to contain the description and author information. Example:
*! Stata package list 21aug2007 * My favorite packages * This list contains * my favorite packages. * * Assembled by: me
3. A package list entry is a line containing a package name (with an optional .pkg suffix), followed by a path or URL indicating the location of the package, followed by an optional title. Use double quotes if a path or title contains spaces. Example:
*! Stata package list 21aug2007 * My favorite packages * This list contains * my favorite packages. * * Assembled by: me estout.pkg http://fmwww.bc.edu/repec/bocode/e "a title" moremata.pkg http://fmwww.bc.edu/repec/bocode/m
4. Empty lines or comment lines may be inserted between package list entries. Example:
*! Stata package list 21aug2007 * My favorite packages * This list contains * my favorite packages. * * Assembled by: me *! some packages estout.pkg http://fmwww.bc.edu/repec/bocode/e "a title" moremata.pkg http://fmwww.bc.edu/repec/bocode/m *! some more packages center.pkg http://fmwww.bc.edu/repec/bocode/c
Note that comment lines are printed by adolist describe if they start with "*!".
5. The recommended suffix for a package list file is .pkl (although this is not a strict requirement).
Returned results
adolist describe returns in macro r(names) the names of the contained packages.
adolist install returns in macro r(installed) the names of the successfully installed packages and in macro r(omitted) the names of the omitted packages due to, say, network problems.
adolist update returns in macro r(installed) the names of the successfully installed/updated packages, in macro r(omitted) the names of the omitted packages due to, say, network problems, and in r(uninstalled) the names of the uninstalled packages.
adolist uninstall returns in macro r(names) the names of the uninstalled packages.
adolist dir returns in macro r(names) the names of the installed package lists.
adolist store and adolist list return in macro r(names) the names of the included packages.
Authors
Ben Jann, ETH Zurich, jann@soz.gess.ethz.ch
Stefan Wehrli, ETH Zurich, wehrli@soz.gess.ethz.ch
Also see