| If you've started using Unix a lot, there is a good chance you will also use Perl a lot. Perl is a powerful and easy-to-learn language that's well suited for both large and small programming tasks . A beginner can learn how to write a simple Perl script in a day, and an experienced programmer can use Perl to solve complex problems efficiently . One of the things that make Perl so powerful is CPAN (Comprehensive Perl Archive Network). CPAN is a truly amazing collection of freely available Perl modules (we'll tell you where to find out more about CPAN later in the chapter). A Perl module is a piece of software that adds features to Perl, such as the ability to do date and time arithmetic, to connect to databases, or to use strong encryption. Perl modules can be written in Perl, C, and other languages; most are written in C and/or Perl. The version of Perl installed with Mac OS X comes with more than 250 modules (the "standard modules") already installed. The CPAN system provides more than a thousand more. You can download and build Perl modules using a series of steps very similar to the steps described above. The main difference is that instead of running a shell script ( ./configure ) to build the makefile and configure the software for compilation, you run a Perl script by using the command line perl Makefile.PL . Also, Perl modules almost always come with tests that run when you do make test . But waitthere's more. One of the standard modules included with Perl on Mac OS X is the CPAN moduleessentially the Perl version of Fink (in fact, the CPAN module predates Fink by several years ). As with Fink, your computer must be connected to the Internet to use the CPAN module. Using the Perl CPAN module, you can easily install Perl modules in a couple of steps. The first time you use the CPAN module, you must configure it.  Also, in order to use CPAN from Mac OS X, you need to set your FTP_PASSIVE environment variable to a true (that is, nonzero) value. This will tell the FTP software used by the CPAN module (the Perl libnet module) to use passive mode , which will enable FTP connections to work even with the Mac OS X firewall software on (see Chapter 12, "Security"). Chapter 7 covers more on setting environment variables , but here's a quick task. When Things Go Wrong Sometimes running ./configure doesn't work smoothly. Usually, if something goes wrong with configure , it is because the script could not find something on your system that it needs. Sometimes configure works, but compilation fails when you run make . As you gain experience with compiling software, you may be able to fix the problem yourself, perhaps by installing a piece of software required by the one that didn't compile. The first place to look for help is in the README and INSTALL files. Make sure you have read anything pertaining to Mac OS X or Darwin mentioned in those files. Look for references to other help resources, such as a Web site or mailing list. If you send a message to someone asking for help, be very respectful of his or her time. Make sure to include an exact copy of any error messages you received and any options you used when running configure . |
To set your FTP_PASSIVE environment variable to "true": - export FTP_PASSIVE=1
That works for the bash shell; if you are using the tcsh shell, the command line is
setenv FTP_PASSIVE 1
You really should make the setting part of your shell configuration (again, see Chapter 7) by adding the command line to the .bash_profile in your home directory (or .tcshrc , for tcsh users).
To configure CPAN: | 1. | sudo cpan Here you are running the cpan command as root. The cpan command is a small script that basically is a shortcut for running the following command line: perl -MCPAN -e shell The CPAN module provides its own little shell interfaceits prompt is cpan> , and it takes commands to search for and install Perl modules. You use sudo because the CPAN module will be making changes in system directories (it will save its configuration in /System/Library/Perl/5.8.6/CPAN/Config.pm and will install new modules in various subdirectories of /Library/Perl ). Note that the "5.8.6" in that path refers to a specific version of Perl (the one installed in Mac OS X 10.4) and will change in the future. If this is the first time you have used the CPAN module, it will ask you to configure it ( Figure 13.31 ). Figure 13.31. Running the cpan command for the first time starts a configuration process. localhost:~ vanilla$ sudo cpan Password: /System/Library/Perl/5.8.6/CPAN/Config.pm initialized. CPAN is the world-wide archive of perl resources. It consists of about 100 sites that all replicate the same contents all around the globe. Many countries have at least one CPAN site already. The resources found on CPAN are easily accessible with the CPAN.pm module. If you want to use CPAN.pm, you have to configure it properly. If you do not want to enter a dialog now, you can answer 'no' to this question and I'll try to autoconfigure. (Note: you can revisit this dialog anytime later by typing 'o conf init' at the cpan prompt.) Are you ready for manual configuration? [yes] (Make sure you have set your FTP_PASSIVE environment variable to 1 ; see the previous task.) | | 2. | Enter your password if asked.
The CPAN module asks if you are ready to do a manual configuration.
| | 3. | Accept the default ( yes ) by pressing  . The CPAN module asks you for the name of a directory where it will store files during installation ( Figure 13.32 ). Figure 13.32. Setting the directory that CPAN will use to download and build Perl modules, overriding the default by entering /usr/local/CPAN . The following questions are intended to help you with the configuration. The CPAN module needs a directory of its own to cache important index files and maybe keep a temporary mirror of CPAN files. This may be a site-wide directory or a personal directory. First of all, I'd like to create this directory. Where? CPAN build and cache directory? [/Users/vanilla/.cpan] /usr/local/CPAN | | 4. | /usr/local/CPAN This is one of the few places where you will enter something different from the default. The CPAN module will create the directory if it doesn't exist. If you make a mistake while typing, you can erase the whole line you have entered by pressing  . The module now asks about the size of the cache it will keep of files used during installations. The default of 10 MB is a good choice ( Figure 13.33 ). Figure 13.33. Selecting the size of the CPAN cache. How big should the disk cache be for keeping the build directories with all the intermediate files? Cache size for build directory (in MB)? [10] | | 5. | Accept the default ( 10 ) by pressing . The module now asks if it should check the size of the cache when it starts up. The default ( atstart ) is what you want ( Figure 13.34 ). Figure 13.34. The CPAN module asks when to scan the cache to limit its size. By default, each time the CPAN module is started, cache scanning is performed to keep the cache size in sync. To prevent this, disable the cache scanning with 'never'. Perform cache scanning (atstart or never)? [atstart] | | 6. | Accept the default by pressing . The module asks if it should try to keep an index of information about modules (using another module called Storable ). Again, accept the default ( yes ) ( Figure 13.35 ). Figure 13.35. The CPAN module asks if it should try to keep an index of information to speed startup. To considerably speed up the initial CPAN shell startup, it is possible to use Storable to create a cache of metadata. If Storable is not available, the normal index mechanism will be used. Cache metadata (yes/no)? [yes] | | 7. | Press to accept the default. The module asks you about the character set supported by your terminal. Unless you are sure you know what you are doing, you should accept the default ( yes indicates ISO-8859-1, the standard English character set) ( Figure 13.36 ). Figure 13.36. The CPAN module asks about the character set supported by your terminal. The next option deals with the charset your terminal supports. In general CPAN is English speaking territory, thus the charset does not matter much, but some of the aliens out there who upload their software to CPAN bear names that are outside the ASCII range. If your terminal supports UTF-8, you say no to the next question, if it supports ISO-8859-1 (also known as LATIN1) then you say yes, and if it supports neither nor, your answer does not matter, you will not be able to read the names of some authors anyway. If you answer no, nmes will be output in UTF-8. Your terminal expects ISO-8859-1 (yes/no)? [yes] | | 8. | Press to accept the default. The module explains that it can create a file that provides command history in the CPAN shell interface, and then asks you for the filename and the number of lines to store ( Figure 13.37) . We suggest accepting the default values. Figure 13.37. The module asks two questions (filename and number of lines) about a file to store a command history for the CPAN shell interface. If you have one of the readline packages (Term::ReadLine::Perl, Term::ReadLine::Gnu, possibly others) installed, the interactive CPAN shell will have history support. The next two questions deal with the filename of the history file and with its size. If you do not want to set this variable, please hit SPACE RETURN to the following question. File to save your history? [/usr/local/CPAN/histfile] Number of lines to save? [100] | | 9. | Press twice to accept the default for both questions. The next question deals with the fact that some modules depend on others' having already been installed. You can instruct the module to ask you before installing prerequisite modules ( ask ), to ignore prerequisites (not recommended), or to "follow" the requirements and install prerequisites when discovered . The default is to ask before installing, but we suggest you change that to follow ( Figure 13.38 ). Figure 13.38. The CPAN module asks for your policy on building prerequisite modules. You tell it to "follow." The CPAN module can detect when a module that which you are trying to build depends on prerequisites. If this happens, it can build the prerequisites for you automatically ('follow'), ask you for confirmation ('ask'), or just ignore them ('ignore'). Please set your policy to one of the three values. Policy on building prerequisites (follow, ask or ignore)? [ask] follow The module then asks about a series of programs that it uses. You should accept the default for each of them by pressing . | | 10. | Press for each program shown in Figure 13.39 . Figure 13.39. The CPAN module asks about a series of programs it wants to use. You accept the default for each question. (Your list might differ a bit.) The CPAN module will need a few external programs to work properly. Please correct me, if I guess the wrong path for a program. Don't panic if you do not have some of them, just press ENTER for those. To disable the use of a download program, you can type a space followed by ENTER. Where is your gzip program? [/sw/bin/gzip] Where is your tar program? [/sw/bin/tar] Where is your unzip program? [/usr/bin/unzip] Where is your make program? [/usr/bin/make] Warning: lynx not found in PATH Where is your lynx program? [] Where is your wget program? [/sw/bin/wget] Warning: ncftpget not found in PATH Where is your ncftpget program? [] Where is your ncftp program? [/usr/bin/ncftp] Where is your ftp program? [/usr/bin/ftp] What is your favorite pager program? [/usr/bin/less] What is your favorite shell? [/bin/tcsh] (Notice the wget programyou installed that using wget earlier in this chapter. You can also install lynx using Fink, if you like.) (Don't worry if the lynx and ncftpget programs are not foundthe module will work without them.) The module now asks about parameters for the perl Makefile.PL command ( Figure 13.40 ). Figure 13.40. The CPAN module asks about options for the perl Makefile.PL command. You just press . Every Makefile.PL is run by perl in a separate process. Likewise we run 'make' and 'make install' in processes. If you have any parameters (e.g. PREFIX, LIB, UNINST or the like) you want to pass to the calls, please specify them here. If you don't understand this question, just press ENTER. Parameters for the 'perl Makefile.PL' command? Typical frequently used settings: POLLUTE=1 increasing backwards compatibility LIB=~/perl non-root users (please see manual for more hints) Your choice: [] | | 11. | Don't supply any extra parameters; just accept the default by pressing . The module asks for parameters for the make command ( Figure 13.41 ). Figure 13.41. Options for the make command. Enter -j3 if you have a dual-processor machine; otherwise , don't enter anything. Parameters for the 'make' command? Typical frequently used setting: -j3 dual processor system Your choice: [] If you have a dual-processor machine, enter -j3 Otherwise, don't enter anything. | | 12. | Press You are asked about options for the make install command. The CPAN module offers an option to try to uninstall potentially conflicting packages, which is a good idea ( Figure 13.42 ). Figure 13.42. Options for the make install command. Enter UNINST=1 . Parameters for the 'make install' command? Typical frequently used setting: UNINST=1 to always uninstall potentially conflicting files Your choice: [] UNINST=1 | | 13. | UNINST=1 The installation process for many modules involves asking you questions. You can tell the CPAN module how long to wait for an answer (in seconds) before stopping an installation process. The CPAN module recommends a setting of 0, which means "wait forever," so if you walk away from your computer during an installation, the module will wait until you come back ( Figure 13.43 ). Figure 13.43. Setting the time-out period. The default ( for "wait forever") is a good choice. Sometimes you may wish to leave the processes run by CPAN alone without caring about them. As sometimes the Makefile.PL contains question you're expected to answer, you can set a timer that will kill a 'perl Makefile.PL' process after the specified time in seconds. If you set this value to 0, these processes will wait forever. This is the default and recommended setting. Timeout for inactivity during Makefile.PL? [0] | | 14. | Press to accept the default ( ). The module now asks you about proxy servers. If your computer is set up behind a firewall, there may be one or more proxy servers you must use to access Web sites or FTP sites on the Internet. Ask your network administrator if you are not sure. If you don't have a network administrator, then you almost certainly don't have proxy servers, so just accept the default (nothing) for each of the next three questions ( Figure 13.44 ). Figure 13.44. Press to accept the default (which is nothingan empty value) for the proxy-server questions. If you're accessing the net via proxies, you can specify them in the CPAN configuration or via environment variables. The variable in the $CPAN::Config takes precedence. Your ftp_proxy? Your http_proxy? Your no_proxy? If you have a proxy server, enter it in the form of a URL: http://proxy. paranoid .sf.ca.us/ | | 15. | Press three times to accept the default for each of the proxy-server questions. For the next step, the module needs to download a list of servers. The download process can sometimes take a long time to begin. If you see that the CPAN module is "stuck" retrying the download process over and over, you can get it to try a different method of connecting to the remote system and/or try a different server by pressing  ( Figure 13.45 ). If you press twice quickly, it will abort the entire process. Figure 13.45. The CPAN module had problems downloading a file and kept retrying. Pressing causes the module to attempt a different method, which worked in this case. You have no /usr/local/CPAN/sources/MIRRORED.BY I'm trying to fetch one LWP not available CPAN: Net::FTP loaded ok Fetching with Net::FTP: ftp://ftp.perl.org/pub/CPAN/MIRRORED.BY Couldn't fetch MIRRORED.BY from ftp.perl.org Fetching with Net::FTP ftp://ftp.perl.org/pub/CPAN/MIRRORED.BY.gz Couldn't fetch MIRRORED.BY.gz from ftp.perl.org Trying with "/sw/bin/wget -O -" to get ftp://ftp.perl.org/pub/CPAN/MIRRORED.BY 08:04:16 ftp://ftp.perl.org/pub/CPAN/MIRRORED.BY => `-' Resolving ftp.perl.org... done. Connecting to ftp.perl.org[204.152.191.7]:21... connected. Logging in as anonymous ... Logged in! ==> SYST ... done. ==> PWD ... done. ==> TYPE I ... done. ==> CWD /pub/CPAN ... done. ==> PORT ... done. ==> RETR MIRRORED.BY ... Error in server response, closing control connection. Retrying. . . . nine retries omitted . . . 08:14:05 ftp://ftp.perl.org/pub/CPAN/MIRRORED.BY (try:10) => `-' Connecting to ftp.perl.org[204.152.191.7]:21... connected. Logging in as anonymous ... Logged in! ==> SYST ... done. ==> PWD ... done. ==> TYPE I ... done. ==> CWD /pub/CPAN ... done. ==> PORT ... done. ==> RETR MIRRORED.BY ...  User pressed Trying with "/sw/bin/wget -O -" to get ftp://ftp.perl.org/pub/CPAN/MIRRORED.BY.gz 08:14:06 ftp://ftp.perl.org/pub/CPAN/MIRRORED.BY.gz => `-' Resolving ftp.perl.org... done. Connecting to ftp.perl.org[207.45.221.24]:21... connected. Logging in as anonymous ... Logged in! ==> SYST ... done. ==> PWD ... done. ==> TYPE I ... done. ==> CWD /pub/CPAN ... done. ==> PORT ... done. ==> RETR MIRRORED.BY.gz ... No such file `MIRRORED.BY.gz'. Issuing "/usr/bin/ftp -n" Trying 207.45.221.24... Connected to ftp.cpan.ddns.develooper.com. 220 mirror.teleglobe.net server ready 331 Anonymous login ok, send your complete email address as your password. 230-******************************************************************** 230- mirror.teleglobe.net hosted in Newark, NJ 230- 230- You are connection 18. Total connections allowed is 1000. . . . omitting several lines of comments . . . 230 Guest access granted for anonymous. Remote system type is UNIX. Using binary mode to transfer files. Local directory now /usr/local/CPAN/sources 250 CWD command successful. 250 CWD command successful. 250-The Comprehensive Perl Archive Network (http://www.cpan.org/) 250-master site has been from the very beginning (1995) hosted at FUNET, 250-the Finnish University NETwork. 250- 250- 250 CWD command successful. 200 Type set to I. local: MIRRORED.BY remote: MIRRORED.BY 500 EPSV not understood. 227 Entering Passive Mode (207,45,221,24,216,67). 150 Opening BINARY mode data connection for MIRRORED.BY (147970 bytes) 100% ************************************* 144 KB 78.05 KB/s 00:01 226 Transfer complete. 147970 bytes received in 00:01 (74.42 KB/s) 221-Goodbye from mirror.teleglobe.net hosted in Newark, NJ 221 GOT /usr/local/CPAN/sources/MIRRORED.BY Once the module has the list of servers (see the MIRRORED.BY file mentioned in Figure 13.45), it asks you about the sites from which it will download source code for Perl modules ( Figure 13.46 ). Figure 13.46. Telling the CPAN module what part of the world you are in. Now we need to know where your favorite CPAN sites are located. Push a few sites onto the array (just in case the first on the array won't work). If you are mirroring CPAN to your local workstation, specify a file: URL. First, pick a nearby continent and country (you can pick several of each, separated by spaces, or none if you just want to keep your existing selections). Then, you will be presented with a list of URLs of CPAN mirrors in the countries you selected, along with previously selected URLs. Select some of those URLs, or just keep the old list. Finally, you will be prompted for any extra URLs file:, ftp:, or http: that host a CPAN mirror. (1) Africa (2) Asia (3) Central America (4) Europe (5) North America (6) Oceania (7) South America Select your continent (or several nearby continents) [] 5 | | 16. | Enter a number corresponding to the area of the world you are in so that you will download from servers closest to you. Figure 13.46 shows 5 entered for North America. The module gives you a list of countries to choose from ( Figure 13.47 ). Figure 13.47. The CPAN module asks you to choose from a list of countries. (1) Canada (2) Mexico (3) Puerto Rico (4) United States Select your country (or several nearby countries) [] 2 4 | | 17. | Enter one or more numbers separated by spaces. In Figure 13.47, we entered 2 and 4 for Mexico and the United States. You see a list of CPAN sites from your chosen countries, from which you are asked to select as many sites as you like ( Figure 13.48 ). If the list is longer than what fits in your Terminal window, you can use the scroll bar to see the sites that scrolled off the top. Figure 13.48. You are asked to choose sites from which to download modules. (1) ftp://cpan.upn.mx/pub/CPAN (Mexico) (2) ftp://ftp.msg.com.mx/pub/CPAN/ (Mexico) (3) ftp://archive.progeny.com/CPAN/ (United States) (4) ftp://carroll.cac.psu.edu/pub/CPAN/ (United States) (5) ftp://cpan-du.viaverio.com/pub/CPAN/ (United States) (6) ftp://cpan.calvin.edu/pub/CPAN (United States) (7) ftp://cpan.cs.utah.edu/pub/CPAN/ (United States) (8) ftp://cpan.erlbaum.net/ (United States) (9) ftp://cpan.llarian.net/pub/CPAN/ (United States) (10) ftp://cpan.mirrors.redwire.net/pub/CPAN/ (United States) (11) ftp://cpan.mirrors.tds.net/pub/CPAN (United States) (12) ftp://cpan.netnitco.net/pub/mirrors/CPAN/ (United States) (13) ftp://cpan.teleglobe.net/pub/CPAN (United States) (14) ftp://cpan.thepirtgroup.com/ (United States) (15) ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN (United States) (16) ftp://ftp-mirror.internap.com/pub/CPAN/ (United States) 44 more items, hit SPACE RETURN to show them Select as many URLs as you like, put them on one line, separated by blanks [ ] 5 2 14 | | 18. | Enter three numbers separated by spaces. In Figure 13.48, we entered 5 2 14 . Do not enter commas; just separate the numbers with spaces. You might try opening a different Terminal window and using ping and TRaceroute (see Chapter 4) to the hostnames of some sites to see which are most easily reachable from your network. You can enter as few as one and as many as you like. Three is a good number. The CPAN module tries the first site first, and if it gets no answer, it tries the second, and so on. The module then asks if you want to enter more sites ( Figure 13.49 ). Figure 13.49. You are given a chance to enter more sites if you want to. Enter another URL or RETURN to quit: [ ] | | 19. | Press to move on. The CPAN module is now configured ( Figure 13.50 ). Figure 13.50. The CPAN module shows the sites you picked and where it saved your configuration: /System/Library/Perl/5.8.6/CPAN/Config.pm . New set of picks: ftp://cpan-du.viaverio.com/pub/CPAN/ ftp://ftp.msg.com.mx/pub/CPAN/ ftp://cpan.thepirtgroup.com/ commit: wrote /System/Library/Perl/5.8.6/CPAN/Config.pm cpan shell CPAN exploration and modules installation (v1.7601) ReadLine support available (try 'install Bundle::CPAN') cpan> The module writes the configuration to /System/Library/Perl/5.8.6/CPAN/  Config.pm (which is a text fileyou can examine it if you are curious ). | | 20. | quit This quits the CPAN shell and returns you to your Unix shell ( Figure 13.51 ). Figure 13.51. Quitting the CPAN module and returning to your Unix shell prompt. cpan> quit Lockfile removed. localhost:~ vanilla$ You have been using the CPAN module's shell interfacethe cpan> at the end of Figure 13.50 is the CPAN module shell prompt, not to be confused with the shell prompt from your Unix shell. |  Tip -
You can rerun the configuration process in the future by starting the CPAN shell and then, at the cpan> prompt, giving the command o conf init The old configuration file will be saved as Config.pm~ , so if you look in /System/Library/Perl/5.8.6/CPAN/ you will see both Config.pm and Config.pm~ .
Now that you have configured the CPAN module, you can use it to install Perl modules. To start the CPAN module: | 1. | sudo cpan
| | 2. | Enter your password if asked.
You get the CPAN shell prompt:
cpan>
| Tip The following tasks assume that you have started the CPAN module and are at a cpan> prompt.
To search for a Perl module: | 1. | m /^Date::/ The m is a cpan shell command meaning "search for Module names." Other search commands are a (authors), b (bundlesgroups of related modules), d (distributions, like bundles), and i (anything: author, bundle, distribution, modulebut the i command usually finds too much stuff). This searches module names that begin with Date:: . (The search is not case sensitive.) CPAN modules are named in a hierarchical fashion, using the double colon ( :: ) as the separator. So there is Date::Calc , Date::Calc::Iterator , and so on. Often, installing a module will also install one or more modules "below" it in the hierarchy. You may recognize the search pattern as a regular expression . The ^ means "search for this at the beginning of the string." Review Chapter 4 for more details. So to search for (the several dozen ) modules that have the string google in their names: m /google/ Upgrading the CPAN Module When you start up the CPAN module, you may see a notice recommending that you upgrade the module to a newer version. Do this by typing install Bundle::CPAN at a cpan> prompt. In some cases, this process may take a very long time, so don't do this unless you are prepared to let the process run for an hour or possibly more (depending on the speed of your Mac and your Internet connection). Usually it takes only a few minutes on a fast Internet connection. Furthermore, you may be asked to go through the CPAN configuration process again after an upgrade if new features have been added. The CPAN module generally remembers your previous configuration choices and presents them as defaults. | In the case of the /^Date::/ example, you get a rather long list ( Figure 13.52 ). Figure 13.52. Searching for all the Date:: modules (abridged output). cpan> m /^Date::/ Module Date::Baha::i (G/GE/GENE/Date-Baha-i-0.16.tar.gz) Module Date::Business (D/DE/DESIMINER/Date-Business-1.2.tar.gz) Module Date::Calc (S/ST/STBEY/Date-Calc-5.4.tar.gz) Module Date::Calc::Iterator (B/BR/BRONTO/Date-Calc-Iterator-1.00.tar.gz) Module Date::Calc::Object (S/ST/STBEY/Date-Calc-5.4.tar.gz) Module Date::Calendar (S/ST/STBEY/Date-Calc-5.4.tar.gz) Module Date::Calendar::Profiles (S/ST/STBEY/Date-Calc-5.4.tar.gz) Module Date::Calendar::Year (S/ST/STBEY/Date-Calc-5.4.tar.gz) Module Date::Chinese (R/RB/RBOW/Date-Chinese-1.03.tar.gz) Module Date::Christmas (H/HF/HFB/Date-Christmas-1.02.tar.gz) Module Date::Convert (M/MO/MORTY/DateConvert-0.16.tar.gz) . . . omitted many entries . . . Module Date::Tie (F/FG/FGLOCK/Date-Tie-0.17.tar.gz) Module Date::Time (Contact Author Tobias Brox <tobix@irctos.org>) Module Date::Tolkien::Shire (T/TB/TBRAUN/Date-Tolkien-Shire-1.12.tar.gz) Module Date::Transform (C/CT/CTBROWN/Date-Transform-0.11.tar.gz) Module Date::Transform::Closures (C/CT/CTBROWN/Date-Transform-0.11.tar.gz) Module Date::Transform::Constants (C/CT/CTBROWN/Date-Transform-0.11.tar.gz) Module Date::Transform::Extensions (C/CT/CTBROWN/Date-Transform-0.11.tar.gz) Module Date::Transform::Functions (C/CT/CTBROWN/Date-Transform-0.11.tar.gz) Module Date::WeekOfYear (G/GN/GNG/Date-WeekOfYear-1.01.tar.gz) 137 items found cpan> Let's assume that you know you want something to do date calculations, so the module Date::Calc seems appropriate. You can get more information about the module with the next step. | | 2. | m Date::Calc From the description of the module ( Figure 13.53 ), it looks as if we might want this one. Figure 13.53. Getting information about specific modules by name. cpan> m Date::Calc Module id = Date::Calc DESCRIPTION Gregorian calendar date calculations CPAN_USERID STBEY (Steffen Beyer <sb@engelschall.com>) CPAN_VERSION 5.4 CPAN_FILE S/ST/STBEY/Date-Calc-.4.tar.gz DSLI_STATUS Mdch (mature,developer,C,hybrid) INST_FILE (not installed) cpan> m Date::Tolkien::Shire Module id = Date::Tolkien::Shire DESCRIPTION J.R.R. Tolkien's hobbit calendar CPAN_USERID TBRAUN (Tom Braun <tbraun@pobox.com>) CPAN_VERSION 1.12 CPAN_FILE T/TB/TBRAUN/Date-Tolkien-Shire-1.12.tar.gz DSLI_STATUS RdpO (released,developer,perl,object-oriented) INST_FILE (not installed) cpan> (Note: The cpan shell command m Date::Calc is different from m /Date::Calc/ The first gets information about one specific module; the second searches using a regular expression.) You can look at the README file for any module available through CPAN (even modules you have not installed), with the readme command. | | 3. | readme Date::Calc This retrieves the README file and displays it (using the less pager command described in Chapter 5) ( Figure 13.54 ). Figure 13.54. Seeing a module's README file. cpan> readme Date::Calc Running readme for module Date::Calc LWP not available CPAN: Net::FTP loaded ok Fetching with Net::FTP: ftp://cpan-sj.viaverio.com/pub/CPAN/authors/id/S/ST/STBEY/Date-Calc-5.4.readme Displaying file /usr/local/CPAN/sources/authors/id/S/ST/STBEY/Date-Calc-5.4.readme with pager "/usr/bin/less" ==================================== Package "Date::Calc" Version 5.4 ==================================== This package is available for download either from my web site at http://www.engelschall.com/u/sb/download/ or from any CPAN (= "Comprehensive Perl Archive Network") mirror server: http://www.perl.com/CPAN/authors/id/S/ST/STBEY/ Abstract: - This package consists of a C library (intended to make life easier for C developers) and a Perl module to access this library from Perl. . . . output abridged . . . | The next step is to install the module. Again, to perform the following task, have your FTP_PASSIVE environment variable set to 1 . To install a Perl module from the cpan shell prompt: - install ModuleName
For example:
install Date::Calc
That's all there is to it.
You can do the same thing from your Unix shell prompt with
sudo cpan -i Date::Calc
You will see a great deal of output as the install process proceeds (an abridged example is shown in Figure 13.55 ).
Figure 13.55. Installing a module (abridged output). Notice how additional required modules were installed because we configured CPAN to "follow" dependencies (see Figure 13.38). cpan> install Date::Calc CPAN: Storable loaded ok Going to read /usr/local/CPAN/Metadata Database was generated on Sat, 02 Jul 2005 11:58:14 GMT Running install for module Date::Calc Running make for S/ST/STBEY/Date-Calc-5.4.tar.gz . . . output abridged . . . Fetching with Net::FTP: ftp://cpan-sj.viaverio.com/pub/CPAN/authors/id/S/ST/STBEY/CHECKSUMS CPAN: Compress::Zlib loaded ok Checksum for /usr/local/CPAN/sources/authors/id/S/ST/STBEY/Date-Calc-5.4.tar.gz ok Scanning cache /usr/local/CPAN/build for sizes Date-Calc-5.4/ Date-Calc-5.4/t/ . . . output abridged . . . Unsatisfied dependencies detected during [S/ST/STBEY/Date-Calc-5.4.tar.gz] - Bit::Vector Carp::Clan . . . output abridged . . . CPAN.pm: Going to build S/ST/STBEY/Bit-Vector-6.4.tar.gz . . . output abridged . . . CPAN.pm: Going to build S/ST/STBEY/Carp-Clan-5.3.tar.gz . . . output abridged . . . Running make for S/ST/STBEY/Date-Calc-5.4.tar.gz Is already unwrapped into directory /usr/local/CPAN/build/Date-Calc-5.4 CPAN.pm: Going to build S/ST/STBEY/Date-Calc-5.4.tar.gz . . . output abridged . . . Running make test PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t t/f000 ok t/f001 ok t/f002 ok . . . output abridged . . . All tests successful, 4 tests skipped. Files=48, Tests=2436, 12 wallclock secs ( 6.43 cusr + 1.48 csys = 7.91 CPU) /usr/bin/make test OK Running make install . . . output abridged . . . /usr/bin/make install UNINST=1 OK cpan>
Tips -
See the sidebar "Using the Date::Calc Module" for an example of using this module. -
Perl modules have documentation built into their source code (which is different from how Unix man pages work). To read the documentation for an installed Perl module, use the perldoc command from a shell prompt (not from the cpan> prompt): perldoc Date::Calc In fact, on some Unix systems, including Mac OS X, you can also use the man command to read the documentation for Perl modules: man Date::Calc
Learning More About CPAN If you are going to do any Perl programming beyond the most basic level, you should know how to find out more about CPAN. Like all Perl modules, CPAN has built-in documentation; read it with perldoc CPAN . The main CPAN Web site is at www.cpan.org. The CPAN Frequently Asked Questions document (www.cpan.org/misc/cpan-faq.html) answers many questions, including "What is Perl?" and "What is CPAN?" |
Using the Date::Calc Module Since you've gone to the trouble of installing it, here's a little script that uses the Date::Calc module. The code listing shown in Figure 13.56 will prompt you for a date in U.S. format (for example, July 15, 2004) and a number of days to add, and will display the new date. To try the script, create a file, enter the text from Figure 13.56, make the file executable, and run the script. (You'll need the skills you learned in Chapter 5 and Chapter 8, "Working with Permissions and Ownership," to create the file and make it executable.) Figure 13.56. Code listing of a Perl script that uses the Date::Calc module. #!/usr/bin/perl # # Add days to a date. Get a date back. ############################################# use Date::Calc qw( Decode_Date_US Add_Delta_Days Date_to_Text_Long ); print "Enter a date in any US format (month, day, year): "; $date = <STDIN>; # get input from user chop $date; # remove the newline character ( $y, $m, $d ) = Decode_Date_US( $date ); print "How many days to add? "; $add_days = <STDIN>; chop $add_days; ( $y, $m, $d ) = Add_Delta_Days( $y,$m,$d,$add_days ); $new_date = Date_to_Text_Long($y,$m,$d); print "New date is $new_date\n";
|
To see a list of installed modules with new versions available: Tips -
You can install all the available new versions with one command, from your Unix shell prompt: sudo cpan -r This could take a while, so be patient. Also, you may be prompted by the install script to answer questions for some modules, so you can't just let this run and go to lunch . You need to stick around to answer the questions if they arise. -
It bears repeating that you can read the documentation for any installed Perl module with perldoc ModuleName (Remember that the module name usually includes one or more pairs of colonsfor example, Test::Harness .)
|
