[basic]
[Basics]
[0]

download(FILE)
downloadUntar(FILE[,env])
downloadUntarzip(FILE[,env])
untarzip(FILE[,env])

These atoms are used to download files to the current working directory.  The <i>FILE</i> argument may be a full URL or a file
specified with SSH syntax or a file specified relative to a symbolic cache name or a local file.  Here are examples all downloading
the same file
<ul>
<li> download ('http://atlas.bu.edu/caches/tarballs/foo.tar.gz')
<li> download ('youssef@atlas.bu.edu:/caches/tarballs/foo.tar.gz')
<li> download ('BU/tarballs/foo.tar.gz')
<li> download ('/atlasgrid/caches/tarballs/foo.tar.gz')
</ul>
The optional <i>env</i> argument causes Pacman to set an environment variable to the full path of the top level untarred directory.
The download atom simply downloads; downloadUntar and downloadUntarZip are identical and both automatically untar and unzip as
necessary. Pacman guarantees that untarring does not overwrite existing files unless you override this feature with <b>-allow
tar-overwrite</b>.  Note that for untarzip(FILE), FILE must be in the current working directory (use cd otherwise to cd to
the right location).


md5check(path, md5string)

md5check <i>(path, md5string)</i> checks if the file at <i>path</i> has md5 checksum-hexstring <i>md5string</i>.


setenv(env, val)
setenvTemp(env, val)
envIsSet(env)
envHasValue(env, value)
envHasValueTemp(env, value)

These atoms let you set and test environment variables:
<ul>
<li> setenv <i>(env, val)</i> assigns environment variable <i>env</i> the value <i>val</i>.  Pacman both guarantees that the environment variable
that you set maintains it's value independent of any other packages and it also guarantees this value in setup scripts that Pacman
generates.
<li> envIsSet <i>(env)</i> requires that the environment variable has been set.
<li> envHasValue <i>(env, value)</i> requires that the environment variable has been set to the value <i>value</i> and guarantees
that this is true
</ul>
setenvTemp and envHasValueTemp differ from their non-temp versions in that they do not guarantee a permanent condition and do not
get put setup scripts.


setenvShell(env, command)

setenvShell <i>(env,command)</i> executes the shell command <i>command</i> and, if the command returns without an
error code, sets environment variable <i>env</i> to the first non-blank line of the shell command output.

setenvShellTemp(env, command)

Same as <i>setenvShell</i> except that the set environment variable is temporary in the same sense as
setenvTemp above.

path(val[,env[,options]])

path <i>(value,[,[env,options]])</i> let's you add directories to standard unix path searching variables like the standard PATH and
LD_LIBRARY_PATH.  <i>env</i> defaults to PATH.  Pacman checks that the directories specified exists and guarantees that executable files 
in directories added this way are consistent.  If, for
example, you do <i>path('/usr/bin/')</i> and <i>path('/usr/local/bin')</i> and both contain the file <i>python</i>, Pacman will report an error.  This
guarantees that as an author of a Pacman package files that you add to paths are maintained independent of other packages.  Sometimes it is useful to 
suppress this checking, in which case you should put the word "no-check" in the optional <i>options</i> argument.  If "back" appears in the <i>options</i> string, 
Pacman adds the path to the end of the path variable list rather than the (default) front.

mkdir(path)
mkdirPersistent(path)

mkdir (<i>path</i>) makes a new directory and checks it's existence over time.  When a package containing mkdir is uninstalled, the
directory and it's contents are removed by Pacman.  mkdirPersistent remains after a package is uninstalled.

message(text)
echo(text)

Either of these prints a message.


cd(path)
cu(username)

cd <i>(path)</i> has the same effect as <b>% cd path</b> as a unix shell command.  cd <i>()</i> undoes the previous cd command.
Similarly, cu <i>(username)</i> changes the username of the installing process and cu <i>()</i> undoes the previous username change.  cu
only works if the installer is the superuser.


yes(question)
no(question)
setenv(env)
choice(option, question, opt1, opt2...)
fail(message)

Atoms <i>yes</i>, <i>no</i>, setenv with one argument and <i>choice</i> let you ask questions at installation time and remember the answers for future
installations.  This is typically used with OR branching to have a package.  For example,
<pre><b><font color="#8B0000"> { yes('Do you want to print "FOO"?'); message('FOO') OR message('not printing FOO') }
</font></pre></b>
shows how to use <i>yes</i> to ask a question and follow the first branch if the answer is 'yes'.  Similarly, <i>no</i> is satisfied as a
logical condition if the answer to the question is 'no'.  You can use choice when there are multiple possibilities as in
<b><pre><font color="#8B0000"> { choice(  'Red','Choose a color','Red','Green','Blue'); message('Red chosen'  ) OR
   choice('Green','Choose a color','Red','Green','Blue'); message('Green chosen') OR 
   choice( 'Blue','Choose a color','Red','Green','Blue'); message('Blue chosen' ) }
</font></pre></b>
Use fail(<i>message</i>) to cause an installation to fail with an error message as in
<b><pre><font color="#8B0000"> { yes('OK to make a new directory?'); mkdir('foo') OR fail('No permission to make foo.') }
</font></pre></b>
If you want to set an environment variable FOO to a value chosen by the installer, simply do
<b><pre><font color="#8B0000"> setenv('FOO')
</font></pre></b>
and Pacman will ask a question and set <b>FOO</b> appropriately.  All of these atoms save and remember the answers provided, so that the answers don't have to be repeated when the
software is updated or removed and re-installed.  The installer can always choose to ignore this saved information
by using <b>-ignore-cookies</b>.


exists(path)

This tests that the file <i>path</i> exists at installation time.


askUntilFileExists(path)

This tests that the file <i>path</i> exists at installation time.  If it does not exist, the installer is asked to put
the file in place and continue.


watch(path)

Tests for the existence of a file or directory tree.  Pacman will record the last modified time of the file or director tree contents.  
If an installer then does
<b><pre><font color="#8B0000">% pacman -verify
</font></pre></b>
Pacman will report an error if any of the files have been modified.

which(filename)

which tests that <i>filename</i> is in the user's standard PATH as in the familiar unix command.


copy(fromPath,toPath)
cp(fromPath,toPath)

Copies files or directory trees.


copyReplace(fromFile,toFile,matchString,replaceString)

Copys a text file with string replacement.


grep(text,path[,comment])

Tests if the file <i>path</i> contains the text <i>text</i>.  Lines beginning with the optional <i>comment</i> (default "#") character
are ignored for the purpose of testing the condition.


freeDisk(freemegs[,path])

Test whether the current working directory is in a file system with at least <i>freemegs</i> megabyte of free space.
This is only tested once at installation time.  The optional <i>path</i> variable let's you test the free space in other parts of the
installer's file system.


cat(path)

Prints a file during installation as with the familiar unix command.


ls(path)

Prints the contents of a directory as with the familiar unix commmand.


softLink(linkFrom,linkTo)

Create a soft link.


insertLine(text,path[,justAfterLineContaining])

Reversibly insert a line of text <i>text</i> into a text file at <i>path</i>.  The optional third argument
lets you insert a text
line just after a line containing the specified text <i>justAfterLineContaining</i>.


textFile(path,lines)

textFile creates a text file containing <i>lines</i>.  The <i>lines</i> argument must be a list of text strings in brackets as in 
<b>textFile ('foo.csh',['#','# - comment','#'])</b>


mail(userEmail[,subject[,body])

Mail sends an email message to <i>userEmail</i> with optional subject <i>subject</i> and optional text body <i>body</i>. 
If the <i>body</i> argument is used, it must be a list of text strings in brackets as in
<b>mail ('youssef@bu.edu','hello',['hi','there'])</b>.

true()
false()

true() is a condition which is guaranteed to always be satisfied and false() is guaranteed never to be satisfied.


launchWebBrowser(url)

Launches a web browser to the indicated page.

