This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Astro/MoonPhase, Next: Astro/SLA, Prev: Astro/Misc, Up: Module List Information about the phase of the moon *************************************** NAME ==== MoonPhase - Information about the phase of the moon SYNOPSIS ======== use MoonPhase; ( $MoonPhase, $MoonIllum, $MoonAge, $MoonDist, $MoonAng, $SunDist, $SunAng ) = phase($seconds_since_1970); @phases = phasehunt($seconds_since_1970); DESCRIPTION =========== MoonPhase calculates information about the phase of the moon at a given time. FUNCTIONS ========= phase() ------- ( $MoonPhase, $MoonIllum, $MoonAge, $MoonDist, $MoonAng, $SunDist, $SunAng ) = phase($seconds_since_1970); $MoonPhase = phase($seconds_since_1970); The argument is the time for which the phase is requested, expressed as a time returned by the time function. If `$seconds_since_1970' is omitted, it does `phase(time)'. Return value in scalar context is $MoonPhase, the terminator phase angle as a percentage of a full circle (i.e., 0 to 1). *Return values in array context:* $MoonPhase: the terminator phase angle as a percentage of a full circle (i.e., 0 to 1) $MoonIllum: the illuminated fraction of the Moon's disc $MoonAge: the Moon's age in days and fraction $MoonDist: the distance of the Moon from the centre of the Earth $MoonAng: the angular diameter subtended by the Moon as seen by an observer at the centre of the Earth. $SunDist: the distance from the Sun in km $SunAng: the angular size of Sun in degrees Example: ( $MoonPhase, $MoonIllum, $MoonAge, $MoonDist, $MoonAng, $SunDist, $SunAng ) = phase(); print "MoonPhase = $MoonPhase\n"; print "MoonIllum = $MoonIllum\n"; print "MoonAge = $MoonAge\n"; print "MoonDist = $MoonDist\n"; print "MoonAng = $MoonAng\n"; print "SunDist = $SunDist\n"; print "SunAng = $SunAng\n";> could print something like this: MoonPhase = 0.598939375319023 MoonIllum = 0.906458030827876 MoonAge = 17.6870323368022 MoonDist = 372479.357420033 MoonAng = 0.534682403555093 SunDist = 152078368.820205 SunAng = 0.524434538105092 phasehunt() ----------- @phases = phasehunt($seconds_since_1970); Finds time of phases of the moon which surround the given date. Five phases are found, starting and ending with the new moons which bound the current lunation. The argument is the time, expressed as a time returned by the time function. If `$seconds_since_1970' is omitted, it does `phasehunt(time)'. Example: @phases = phasehunt(); print "New Moon = ", scalar(localtime($phases[0])), "\n"; print "First quarter = ", scalar(localtime($phases[1])), "\n"; print "Full moon = ", scalar(localtime($phases[2])), "\n"; print "Last quarter = ", scalar(localtime($phases[3])), "\n"; print "New Moon = ", scalar(localtime($phases[4])), "\n"; could print something like this: New Moon = Wed Jun 24 06:51:47 1998 First quarter = Wed Jul 1 21:42:19 1998 Full moon = Thu Jul 9 19:02:47 1998 Last quarter = Thu Jul 16 18:15:18 1998 New Moon = Thu Jul 23 16:45:01 1998 ABOUT THE ALGORITHMS ==================== The algorithms used in this program to calculate the positions of Sun and Moon as seen from the Earth are given in the book *Practical Astronomy With Your Calculator* by *Peter Duffett-Smith, Second Edition, Cambridge University Press, 1981*. Ignore the word "Calculator" in the title; this is an essential reference if you're interested in developing software which calculates planetary positions, orbits, eclipses, and the like. If you're interested in pursuing such programming, you should also obtain: *Astronomical Formulae for Calculators* by *Jean Meeus, Third Edition, Willmann-Bell, 1985*. A must-have. *Planetary Programs and Tables from -4000 to +2800* by *Pierre Bretagnon and Jean-Louis Simon, Willmann-Bell, 1986*. If you want the utmost (outside of JPL) accuracy for the planets, it's here. *Celestial BASIC* by *Eric Burgess, Revised Edition, Sybex, 1985*. Very cookbook oriented, and many of the algorithms are hard to dig out of the turgid BASIC code, but you'll probably want it anyway. Many of these references can be obtained from Willmann-Bell, P.O. Box 35025, Richmond, VA 23235, USA. Phone: (804) 320-7016. In addition to their own publications, they stock most of the standard references for mathematical and positional astronomy. LICENCE ======= This program is in the public domain: "Do what thou wilt shall be the whole of the law". AUTHORS ======= the moontool.c: A Moon for the Sun Release 2.0 Designed and implemented by John Walker in December 1987, revised and updated in February of 1988. Perl transcription: Raino Pikkarainen, 1998 raino.pikkarainen@saunalahti.fi  File: pm.info, Node: Astro/SLA, Next: Astro/Time, Prev: Astro/MoonPhase, Up: Module List perl interface to SLAlib positional astronomy library ***************************************************** NAME ==== Astro::SLA - perl interface to SLAlib positional astronomy library SYNOPSIS ======== use SLA; use SLA qw(:constants :sla); slaFk45z($ra, $dec, 1950.0, $ra2000, $dec2000); slaCldj($yy, $mn, $dd, $mjd, $status); ($lst, $mjd) = lstnow($long); ($lst, $mjd) = ut2lst_tel($yy,$mn,$dd,$hh,$mm,$ss,'JCMT'); DESCRIPTION =========== This modules provides a perl interface to the C version of the SLALIB astrometry library written by Pat Wallace. In general the single precision routines have not been implemented since perl can work in double precision. The SLALIB constants (as provided in slamac.h) are available. In addition small utility subroutines are provided that do useful tasks (from the author's point of view) - specifically routines for calculating the Local Sidereal Time. It may be that this part of the module should be moved into an accompanying module - Astro::SLA::Extras. Routines ======== There are 3 distinct groups of routines that can be imported into the namespace via tags: sla - import just the SLALIB routines constants - import the SLALIB constants funcs - import the extra routines Each group will be discussed in turn. sla --- All the double precision SLA routines are implemented except for slaPxy, slaDmat, slaSvd, slaSvdcov, slaSvdsol (I may do these some other time - although they should be done in `PDL'). The implemented routines are: sla524 slaAddet slaAfin slaAirmas slaAmp slaAmpqk slaAop slaAoppa slaAoppat slaAopqk slaAtmdsp slaAv2m slaBear slaCaf2r slaCaldj slaCalyd slaCc2s slaCc62s slaCd2tf slaCldj slaClyd slaCr2af slaCr2tf slaCs2c6 slaDaf2r slaDafin slaDat slaDav2m slaDbear slaDbjin slaDc62s slaDcc2s slaDcmpf slaDcs2c slaDd2tf slaDe2h slaDeuler slaDfltin slaDh2e slaDimxv slaDjcal slaDjcl slaDm2av slaDmoon slaDmxm slaDmxv slaDpav slaDr2af slaDr2tf slaDrange slaDranrm slaDs2c6 slaDs2tp slaDsep slaDtf2d slaDtf2r slaDtp2s slaDtp2v slaDtps2c slaDtpv2c slaDtt slaDv2tp slaDvdv slaDvn slaDvxv slaE2h slaEarth slaEcleq slaEcmat slaEcor slaEg50 slaEpb slaEpb2d slaEpco slaEpj slaEpj2d slaEqecl slaEqeqx slaEqgal slaEtrms slaEuler slaEvp slaFk425 slaFk45z slaFk54z slaFloatin slaGaleq slaGalsup slaGe50 slaGeoc slaGmst slaGmsta slaGresid slaH2e slaImxv slaInvf slaKbj slaM2av slaMap slaMappa slaMapqk slaMapqkz slaMoon slaMxm slaMxv slaNut slaNutc slaOap slaOapqk slaObs slaPa slaPav slaPcd slaPda2h slaPdq2h slaPlanel slaPlanet slaPlante slaPm slaPolmo slaPrebn slaPrec slaPreces slaPrecl slaPrenut slaPvobs slaRandom slaRange slaRanorm slaRcc slaRdplan slaRefco slaRefcoq slaRefv slaRefz slaRverot slaRvgalc slaRvlg slaRvlsrd slaRvlsrk slaS2tp slaSep slaSubet slaSupgal slaTp2s slaTp2v slaTps2c slaTpv2c slaUnpcd slaV2tp slaVdv slaVxv slaWait slaXy2xy slaZd Also, slaGresid and slaRandom are not in the C library (although they are in the Fortran version). slaWait is implemented using the perl 'select(ready file descriptors)' command. In general single precision routines are simply aliases of the double precision equivalents. For more information on the SLALIB routines consult the Starlink documentation (Starlink User Note 67 (SUN/67)). This document is available from the Starlink web site (http://star-www.rl.ac.uk/) [SUN67 avialable from: http://star-www.rl.ac.uk/cgi-bin/htxserver/sun67.htx/sun67.html]] Constants --------- Constants supplied by this module (note that they are implemented via the *Note Constant: constant, pragma): DPI - Pi D2PI - 2 * Pi D1B2PI - 1 / (2 * Pi) D4PI - 4 * Pi D1B4PI - 1 / (4 * Pi) DPISQ - Pi ** 2 (Pi squared) DSQRPI - sqrt(Pi) DPIBY2 - Pi / 2: 90 degrees in radians DD2R - Pi / 180: degrees to radians DR2D - 180/Pi: radians to degrees DAS2R - pi/(180*3600): arcseconds to radians DR2AS - 180*3600/pi: radians to arcseconds DH2R - pi/12: hours to radians DR2H - 12/pi: radians to hours DS2R - pi / (12*3600): seconds of time to radians DR2S - 12*3600/pi: radians to seconds of time D15B2PI - 15/(2*pi): hours to degrees * radians to turns Extra functions (using the 'funcs' tag) --------------------------------------- lstnow_tel Return current LST (in radians) and MJD for a given telescope. The telescope identifiers should match those present in slaObs. The supplied telescope name is converted to upper case. ($lst, $mjd) = lstnow_tel($tel); Aborts if telescope name is unknown. lstnow Return current LST (in radians) and MJD (days) Longitude should be negative if degrees west and in radians. ($lst, $mjd) = lstnow($long); ut2lst Given the UT time, calculate the Modified Julian date and the local sidereal time (radians) for the specified longitude. ($lst, $mjd) = ut2lst(yy, mn, dd, hh, mm, ss, long) Longitude should be negative if degrees west and in radians. ut2lst_tel Given the UT time, calculate the Modified Julian date and the local sidereal time (radians) for the specified telescope. ($lst, $mjd) = ut2lst_tel(yy, mn, dd, hh, mm, ss, tel) AUTHOR ====== Tim Jenness (t.jenness@jach.hawaii.edu) REQUIREMENTS ============ This module has been tested with the May 1998 release of SLALIB. The C version of the library is required for this module to be built. COPYRIGHT ========= This module is copyright (C) 1998,1999 Tim Jenness and PPARC. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The SLALIB library (C version) is proprietary. Please contact Patrick Wallace (ptw@tpsoft.demon.co.uk) if you would like to obtain a copy.  File: pm.info, Node: Astro/Time, Next: Async, Prev: Astro/SLA, Up: Module List Time based astronomical routines ******************************** NAME ==== Astro::Time - Time based astronomical routines SYNOPSIS ======== use Astro::Time; $dayno = cal2dayno($day, $month, $year); print "It's a leap year!\n" if (leap($year)); $lmst = mjd2lst($mjd, $longitude, $dUT1); $turns = str2turn($string, 'H'); $str = turn2str($turn, 'D', $sig); DESCRIPTION =========== Astro::Time contains an assorted set Perl routines for time based conversions, such as conversion between calendar dates and Modified Julian day and conversion of UT to local sidereal time. Include are routines for conversion between numerical and string representation of angles. AUTHOR ====== Chris Phillips phillips@jive.nfra.nl FUNCTIONS ========= turn2str $str = turn2str($turn, $mode, $sig); $str = turn2str($turn, $mode, $sig, $strsep); Convert fraction of a turn into string representation $turn Angle in turns $mode Mode of string to convert to: 'H' for hours 'D' for degrees $sig number of significant figures $strsep String separator (override for default $Astro::Time::StrSep) Note: The behavior can be modified by the following two variables: $Astro::Time::ZeroStr Minimum number of leading digits (zero padded if needed) $Astro::Time::StrSep (Overridden by optional fourth argument) Deliminator used in string (Default ':') This may also equal one of a number of special values: 'HMS' 12H45M12.3S or 170D34M56.2S 'hms' 12h45m12.3s or 170d34m56.2s 'deg' 170d34'56.2" deg2str $str=deg2str($deg, $mode, $sig); Convert degrees into string representation $deg angle in degrees $mode mode of string to convert to: 'H' for hours 'D' for degrees $sig number of significant figures See note for turn2str rad2str $str=rad2str($rad, $mode, $sig); Convert radians into string representation $rad angle in radians $mode mode of string to convert to: 'H' for hours 'D' for degrees $sig is number of significant figures See note for turn2str str2turn $turns = str2turn($string,$mode); Convert angle from string representation into fraction of a turn $string a : or space delimited angle $mode type of angle 'H' if $string is in hours,min,sec 'D' if $string is in deg,arcmin,arcsec The format of $string can be fairly flexible e.g.: 12.2 12:34 12:34:45.1 -23 34 12.3 -34 34.3 Note: You cannot mix spaces and : str2deg $degrees=str2deg($string,$mode); Convert angle from string representation into degrees $string a : or space delimited angle $mode 'H' if $string is in hours,min,sec 'D' if $string is in deg,arcmin,arcsec See note for str2turn str2rad $radians=str2rad($string,$mode); Convert angle from string representation into radians $string a : or space delimited angle $mode 'H' if $string is in hours,min,sec 'D' if $string is in deg,arcmin,arcsec See note for str2turn hms2time ($time) = hms2time($hour, $minute, $second); ($time) = hms2time($hour, $minute, $second, $mode); Returns the day fraction given hours minutes and seconds (or degrees) $time Day fraction $hour Hours $minutes Minutes $second Seconds $mode 'H' or 'D' to interpret as hours or degrees (default hours) time2hms ($sign, $hour, $minute, $second) = time2hms($time, $mode, $sig); Returns hours (or degrees), minutes and seconds given the day fraction $sign Sign of angle ('+' or '-') $hour Hours $minutes Minutes $second Seconds $time Day fraction $mode Return degrees or Hours? 'H' for hours 'D' for degrees $sig Number of significant digits for $second deg2rad $rad=deg2rad($deg); Convert degrees to radians rad2deg $deg=rad2deg($rad); Convert radians to degrees turn2rad $rad=turn2rad($turn); Convert turns to radians rad2turn $turn=rad2turn($rad); Convert radians to turns turn2deg $deg=turn2deg($turn); Convert turns to radians deg2turn $turn=deg2turn($deg); Convert degrees to turns cal2dayno $dayno = cal2dayno($day, $month, $year); Returns the day number corresponding to $day of $month in $year. dayno2cal ($day, $month) = dayno2cal($dayno, $year); Return the $day and $month corresponding to $dayno of $year. leap $isleapyear = leap($year); Returns true if $year is a leap year. $year year in full yesterday ($dayno, $year) = yesterday($dayno, $year); ($day, $month, $year) = yesterday($day, $month, $year); Winds back the day number by one, taking account of year wraps. $dayno Day number of year $year Year $month Month $day Day of month tomorrow ($dayno, $year) = tomorrow($dayno, $year); ($day, $month, $year) = tomorrow($day, $month, $year); Advances the day number by one, taking account of year wraps. $dayno Day number of year $year Year $month Month $day Day of month mjd2cal ($day, $month, $year, $ut) = mjd2cal($mjd); Converts a modified Julian day number into calendar date (universal time). (based on the slalib routine sla_djcl). $mjd Modified Julian day (JD-2400000.5) $day Day of the month. $month Month of the year. $year Year $ut UT day fraction cal2mjd $mjd = cal2mjd($day, $month, $year, $ut); Converts a calendar date (universal time) into modified Julian day number. $day Day of the month. $month Month of the year. $year Year $ut UT dayfraction $mjd Modified Julian day (JD-2400000.5) mjd2dayno ($dayno, $year, $ut) = mjd2dayno($mjd); Converts a modified Julian day number into year and dayno (universal time). $mjd Modified Julian day (JD-2400000.5) $year Year $dayno Dayno of year dayno2mjd $mjd = dayno2mjd($dayno, $year, $ut); Converts a dayno and year to modified Julian day $mjd Modified Julian day (JD-2400000.5) $year Year $dayno Dayno of year now2mjd $mjd = now2mjd() jd2mjd $mjd = jd2mjd($jd); Converts a Julian day to Modified Julian day $jd Julian day $mjd Modified Julian day mjd2jd $jd = mjd2jd($mjd); Converts a Modified Julian day to Julian day $mjd Modified Julian day $jd Julian day gst $gst = gmst($mjd); $gmst = gmst($mjd, $dUT1); $gtst = gmst($mjd, $dUT1, $eqenx); Converts a modified Julian day number to Greenwich sidereal time $mjd modified Julian day (JD-2400000.5) $dUT1 difference between UTC and UT1 (UT1 = UTC + dUT1) (seconds) $eqenx Equation of the equinoxes (not yet supported) $gst Greenwich sidereal time (turns) $gmst Greenwich mean sidereal time (turns) $gtst Greenwich true sidereal time (turns) mjd2lst $lst = mjd2lst($mjd, $longitude); $lmst = mjd2lst($mjd, $longitude, $dUT1); $ltst = mjd2lst($mjd, $longitude, $dUT1, $eqenx); Converts a modified Julian day number into local sidereal time (lst), local mean sidereal time (lmst) or local true sidereal time (ltst). Unless high precisions is required dUT1 can be omitted (it will always be in the range -0.5 to 0.5 seconds). $mjd Modified Julian day (JD-2400000.5) $longitude Longitude for which the LST is required (turns) $dUT1 Difference between UTC and UT1 (UT1 = UTC + dUT1)(seconds) $eqenx Equation of the equinoxes (not yet supported) $lst Local sidereal time (turns) $lmst Local mean sidereal time (turns) $ltst Local true sidereal time (turns) cal2lst $lst = cal2lst($day, $month, $year, $ut, $longitude); $lmst = cal2lst($day, $month, $year, $ut, $longitude, $dUT1); $ltst = cal2lst($day, $month, $year, $ut, $longitude, $dUT1, $eqenx); Wrapper to mjd2lst using calendar date rather than mjd dayno2lst $lst = dayno2lst($dayno, $year, $ut, $longitude); $lmst = dayno2lst($dayno, $year, $ut, $longitude, $dUT1); $ltst = dayno2lst($dayno, $year, $ut, $longitude, $dUT1, $eqenx); Wrapper to mjd2lst using calendar date rather than mjd rise ($lst_rise, $lst_set) = rise($ra, $dec, $obslat, $el_limit); Return the lst rise and set time of the given source $lst_rise, $lst_set Rise and set time (turns) $ra, $dec RA and Dec of source (turns) $obslat Latitude of observatory (turns) $el_limit Elevation limit of observatory (turns, 0 horizontal) Returns 'Circumpolar' if source circumpolar Returns undef if source never rises Uses the formula: cos $z_limit = sin $obslat * sin $dec + cos $obslat * cos $dec * cos $HA where: $z_limit is the zenith angle limit corresponding to $el_limit $HA is the Hour Angle of the source NOTE: For maximum accuracy source coordinated should be precessed to the current date. lst2mjd $mjd = lst2mjd($lmst, $dayno, $year, $longitude); $mjd = lst2mjd($lmst, $dayno, $year, $longitude, $dUT1); This routine calculates the modified Julian day number corresponding to the local mean sidereal time $lmst at $longitude, on a given UT day number ($dayno). Unless high precision is required dUT1 can be omitted. The required inputs are : $lmst - The local mean sidereal time (turns) $dayno - The UT day of year for which to do the conversion $year - The year for which to do the conversion $longitude - The longitude of the observatory (turns) $dUT1 - Difference between UTC and UT1 (UT1 = UTC + dUT1) (seconds) $mjd The modified Julian day corresponding to $lmst on $dayno  File: pm.info, Node: Async, Next: Async/Group, Prev: Astro/Time, Up: Module List Asynchronous evaluation of Perl code (with optional timeouts) ************************************************************* NAME ==== Async - Asynchronous evaluation of Perl code (with optional timeouts) SYNOPSIS ======== my $proc = Async->new(sub { any perl code you want executed }); if ($proc->ready) { # the code has finished executing if ($proc->error) { # something went wrong } else { $result = $proc->result; # The return value of the code } } # or: $result = $proc->result('force completion'); # wait for it to finish DESCRIPTION =========== Async executes some code in a separate process and retrieves the result. Since the code is running in a separate process, your main program can continue with whatever it was doing while the separate code is executing. This separate code is called an `asynchronous computation'. When your program wants to check to see if the asynchronous computation is complete, it can call the `ready()' method, which returns true if so, and false if it is still running. After the asynchronous computation is complete, you should call the error() method to make sure that everything went all right. error() will return undef if the computation completed normally, and an error message otherwise. Data returned by the computation can be retrieved with the result() method. The data must be a single string; any non-string value returned by the computation will be stringized. (See AsyncData below for how to avoid this.) If the computation has not completed yet, result() will return an undefined value. result() takes an optional parameter, $force. If $force is true, then the calling process will wait until the asynchronous computation is complete before returning. `AsyncTimeout' -------------- use Async; $proc = AsyncTimeout->new(sub {...}, $timeout, $special); `Async::Timeout' implements a version of Async that has an automatic timeout. If the asynchronous computation does not complete before $timeout seconds have elapsed, it is forcibly terminated and returns a special value `$special'. The default special value is the string "Timed out\n". All the other methods for `AsyncTimeout' are exactly the same as for Async. `AsyncData' ----------- use Async; $proc = AsyncData->new(sub {...}); `AsyncData' is just like Async except that instead of returning a string, the asynchronous computation may return any scalar value. If the scalar value is a reference, the result() method will yield a refernce to a copy of this data structure. The `AsyncData' module requires that Storable be installed. `AsyncData::new' will die if Storable is unavailable. All the other methods for `AsyncData' are exactly the same as for Async. WARNINGS FOR THE PROGRAMMER =========================== The asynchronous computation takes place in a separate process, so nothing it does can affect the main program. For example, if it modifies global variables, changes the current directory, opens and closes filehandles, or calls die, the parent process will be unaware of these things. However, the asynchronous computatin does inherit the main program's file handles, so if it reads data from files that the main program had open, that data will not be availble to the main program; similarly the asynchronous computation can write data to the same file as the main program if it inherits an open filehandle for that file. ERRORS ====== The errors that are reported by the error() mechanism are: those that are internal to Async itself: Couldn't make pipe: (reason) Couldn't fork: (reason) Read error: (reason) If your asynchronous computation dies for any reason, that is not considered to be an `error'; that is the normal termination of the process. Any messages written to `STDERR' will go to the computation's `STDERR', which is normally inherited from the main program, and the result() will be the empty string. EXAMPLE ======= use Async; sub long_running_computation { # This function simulates a computation that takes a long time to run my ($x) = @_; sleep 5; return $x+2; # Eureka! } # Main program: my $proc = Async->new(sub {long_running_computation(2)}) or die; # The long-running computation is now executing. # while (1) { print "Main program: The time is now ", scalar(localtime), "\n"; my $e; if ($proc->ready) { if ($e = $proc->error) { print "Something went wrong. The error was: $e\n"; } else { print "The result of the computation is: ", $proc->result, "\n"; } undef $proc; } # The result is not ready; we can go off and do something else here. sleep 1; # One thing we could do is to take nap. } AUTHOR ====== Mark-Jason Dominus `mjd-perl-async+@plover.com'.  File: pm.info, Node: Async/Group, Next: AtExit, Prev: Async, Up: Module List Perl class to deal with simultaneous asynchronous calls ******************************************************* NAME ==== Async::Group - Perl class to deal with simultaneous asynchronous calls SYNOPSIS ======== use Async::Group ; use strict ; sub sub1 { print "Dummy subroutine \n"; my $dummy = shift ; my $cb = shift ; &$cb(1); } sub allDone { print "All done, result is ", shift ,"\n" ; } my $a = Async::Group->new(name => 'aTest', test => 1) ; $a->run(set => [ sub {&sub1( callback => sub {$a->callDone(@_)} )}, sub {&sub1( callback => sub {$a->callDone(@_)} )} ], callback => \&allDone ) # or another way which avoids the clumsy nested subs my $cb = $a->getCbRef(); $a->run(set => [ sub {&sub1( callback => $cb)}, sub {&nsub1( callback => $cb )} ], callback => \&allDone ) DESCRIPTION =========== If you sometimes have to launch several asynchronous calls in parrallel and want to call one call-back function when all these calls are finished, this module may be for you. Async::Group is a class which enables you to call several asynchronous routines. Each routine may have their own callback. When all the routine are over (i.e. all their callback were called), Async::Group will call the global callback given by the user. Note that one Async::Group objects must be created for each group of parrallel calls. This object may be destroyed (or will vanish itself) once the global callback is called. Note also that Async::Group does not perform any fork or other system calls. It just run the passed subroutines and keep count of the call-back functions called by the aforementionned subroutines. When all these subs are finished, it calls another call-back (passed by the user) to perform whatever function required by the user. Using fork or threads or whatever is left to the user. Methods ======= new( set => [sub, sub, ...], [test => 1] ) ------------------------------------------ Creates a new Async::Group object. parameters are : - name: name of the group. The name has no special meaning but it can be helpfull for debugging. - test: will print on STDERR what's going on run ('set' => [ sub { } ,... ], 'callback' => sub{ ...} ) ------------------------------------------------------------ - set: array ref of a set of subroutine reference that will be called in parrallel - callback : global user callback function callDone(result, [string]) -------------------------- Function to be called back each time an asynchronous call is finished. When all function calls are over (i.e. all call-back were performed) all the returned results are logically 'anded', the passed strings are concatenated and the resulting result is passed to the global user call-back function passed with the run() method. getCbRef() ---------- Syntactic sugar to avoid nested subs when defining the set of routines that must be run in parrallel. This function will return a sub ref that can be used as a callback function by the user's routine. So you may call run() with the following sequence : my $cb = $a->getCbRef(); $a->run(set => [ sub {&sub1( callback => $cb)}, sub {&nsub1( callback => $cb )} ], callback => \&allDone ) AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1)  File: pm.info, Node: AtExit, Next: Audio/CD, Prev: Async/Group, Up: Module List perform exit processing for a program or object *********************************************** NAME ==== atexit, *AtExit* - perform exit processing for a program or object SYNOPSIS ======== use AtExit; sub cleanup { my @args = @_; print "cleanup() executing: args = @args\n"; } ## Register subroutines to be called when this program exits $_ = atexit(\&cleanup, "This call was registered first"); print "first call to atexit() returned $_\n"; $_ = atexit("cleanup", "This call was registered second"); print "second call to atexit() returned $_\n"; $_ = atexit("cleanup", "This call should've been unregistered by rmexit"); rmexit($_) or warn "couldnt' unregister exit-sub $_!"; if (@ARGV == 0) { ## Register subroutines to be called when this lexical scope is exited my $scope1 = AtExit->new( \&cleanup, "Scope 1, Callback 1" ); { ## Do the same for this nested scope my $scope2 = AtExit->new; $_ = $scope2->atexit( \&cleanup, "Scope 2, Callback 1" ); $scope1->atexit( \&cleanup, "Scope 1, Callback 2"); $scope2->atexit( \&cleanup, "Scope 2, Callback 2" ); $scope2->rmexit($_) or warn "couldn't unregister exit-sub $_!"; print "*** Leaving Scope 2 ***\n"; } print "*** Finished Scope 2 ***\n"; print "*** Leaving Scope 1 ***\n"; } print "*** Finished Scope 1 ***\n" if (@ARGV == 0); END { print "*** Now performing program-exit processing ***\n"; } DESCRIPTION =========== The *AtExit* module provides ANSI-C style exit processing modeled after the atexit function in the standard C library (see `atexit(3C)' in this node). Various exit processing routines may be registered by calling atexit and passing it the desired subroutine along with any desired arguments. Then, at program-exit time, the subroutines registered with atexit are invoked with their given arguments in the reverse order of registration (last one registered is invoked first). Registering the same subroutine more than once will cause that subroutine to be invoked once for each registration. An *AtExit* object can be created in any scope. When invoked as a function, atexit registers callbacks to be executed at *program-exit* time. But when invoked as an object-method (using the `$object->method_name' syntax), callbacks registered with an *AtExit* object are executed at *object-destruction time*! The rules for order of execution of the registered subroutines are the same for objects during object-destruction, as for the program during program-termination. The atexit function/method should be passed a subroutine name or reference, optionally followed by the list of arguments with which to invoke it at program/object exit time. Anonymous subroutine references passed to atexit act as "closures" (which are described in *Note Perlref: (perl.info)perlref,). If a subroutine name is specified (as opposed to a subroutine reference) then, unless the subroutine name has an explicit package prefix, it is assumed to be the name of a subroutine in the caller's current package. A reference to the specified subroutine is obtained, and, if invocation arguments were specified, it is "wrapped up" in a closure which invokes the subroutine with the specified arguments. The resulting subroutine reference is added to the front of the list of exit-handling subroutines for the program (atexit) or the *AtExit* object (`$exitObject->atexit') and the reference is then returned to the caller (just in case you might want to unregister it later using *rmexit*. If the given subroutine could not be registered, then the value zero is returned. The *rmexit* function/method should be passed one or more subroutine references, each of which was returned by a previous call to atexit. For each argument given, *rmexit* will look in the list of exit-handling subroutines for the program (*rmexit*) or the *AtExit* object (`$exitObject->rmexit') and remove the first matching entry from the list. If no arguments are given, *then all program or object exit-handlers are unregistered!* The value returned will be the number of subroutines that were successfully unregistered. At object destruction time, the `DESTROY{}' subroutine in the *AtExit* module iterates over the subroutine references in the *AtExit* object and invokes each one in turn (each subroutine is removed from the front of the queue immediately before it is invoked). At program-exit time, the `END{}' block in the *AtExit* module iterates over the subroutines in the array returned by the *exit_subs* method and invokes each one in turn (each subroutine is removed from the front of the queue immediately before it is invoked). Note that in both cases (program-exit, and object-destruction) the subroutines in this queue are invoked in first-to-last order (the reverse order in which they were registered with atexit). Adding and removing callbacks during exit/destruction time. ----------------------------------------------------------- The method *ignore_when_exiting* specifies how exit-callback registration and unregistration will be handled during program-exit or object-destruction time, while exit-callbacks are in process of being invoked. When invoked as a class method (e.g., `AtExit->ignore_when_exiting'), *ignore_when_exiting* corresponds to the handling of calls to atexit and *rmexit* during program-termination. But when invoked as an object method (e.g., `$exitObject->ignore_when_exiting'), then *ignore_when_exiting* corresponds to the handling of calls to atexit and *rmexit* during *object-destruction* for the particular object. By default, *ignore_when_exiting* returns a non-zero value, which causes atexit to *ignore* any calls made to it during this time (a value of zero will be returned). This behavior is consistent with that of the standard C library function of the same name. If desired however, the user may enable the registration of subroutines by atexit during this time by invoking *ignore_when_exiting* and passing it an argument of 0, "", or undef (for example, `AtExit->ignore_when_exiting(0)' or `$exitObject->ignore_when_exiting(0)', Just remember that any subroutines registered with atexit be placed at the *front* of the queue of yet-to-be-invoked exit-processing subroutines for the program (atexit) or the *AtExit* object (`$exitObject->atexit'). Regardless of when it is invoked, *rmexit* will always attempt to unregister the given subroutines (even when called during program/object exit processing). Keep in mind however that if it is invoked during program/object exit then it will fail to unregister any subroutines that have *already been invoked* (since those subroutine calls have already been removed from the corresponding list of exit-handling subroutines). The method *is_exiting* may consulted examined to determine if routines registered using atexit are currently in the process of being invoked. It will be non-zero if they are and zero otherwise. When invoked as a class method (e.g., `AtExit->is_exiting'), the return value will correspond to program-exit processing; but when invoked as an object method (e.g., `$exitObject->is_exiting') the return value will correspond to object-destruction processing for the given object. If, for any reason, the list of registered callback needs to be directly accessed or manipulated, the *exit_subs* function will return a reference to the list of program-exit callbacks. When invoked as a method, *exit_subs* will return a reference to the list of object-destruction callbacks for the corresponding object. EXPORTS ======= For backward compatibility, atexit and *rmexit* are exported by default. Note however that *exit_subs*, *is_exiting*, and *ignore_when_exiting* are not exported by default, and should be invoked as class methods (e.g. `AtExit->is_exiting') if they are to manipulate program-exit information (rather than object-destruction) and not explicitly imported. CAVEATS ======= Program-termination and Object-destruction ========================================== The usual Perl way of doing program/module-exit processing is through the use of `END{}' blocks (see `"Package Constructors and Destructors"', *Note Perlmod: (perl.info)perlmod,). The *AtExit* module implements its program-exit processing with with an `END{}' block that invokes all the subroutines registered by atexit in the array whose referenced is returned by `exit_subs'. For an object, object-destruction processing is implemented by having the DESTROY method for the object invoke all the subroutines registered by `$exitObject->atexit'. This occurs when the object loses it's last reference, which is not necessarily at program end time. For objects defined in the global context, if any other `END{}' block processing is specified in the user's code or in any other packages it uses, then the order in which the exit processing takes place is subject to Perl's rules for the order in which objects loose their last references and `END{}' blocks are processed. This may affect when subroutines registered with atexit are invoked with respect to other exit processing that is to be performed. In particular, if *rmexit* is invoked from within an `END{}' block that executes after the *AtExit* object was destroyed, then the corresponding subroutine will not be registered and will never be invoked by the *AtExit* module's destructor code. `END{}' block processing order ============================== `END{}' blocks, including those in other packages, get called in the reverse order in which they appear in the code. (atexit subroutines get called in the reverse order in which they are registered.) If a package gets read via "use", it will act as if the `END{}' block was defined at that particular part of the "main" code. Packages read via "require" will be executed after the code of "main" has been parsed and will be seen last so will execute first (they get executed in the context of the package in which they exist). It is important to note that `END{}' blocks and object destruction only get called on normal termination (which includes calls to die or *Carp::croak*). They do not get called when the program terminates *abnormally* (due to a signal for example) unless special arrangements have been made by the programmer (e.g. using a signal handler - see `"%SIG{expr}"', *Note Perlvar: (perl.info)perlvar,). SEE ALSO ======== `atexit(3C)' in this node describes the atexit function for the standard C library (the actual Unix manual section in which it appears may differ from platform to platform - try sections 3C, 3, 2C, and 2). Further information on anonymous subroutines ("closures") may be found in *Note Perlref: (perl.info)perlref,. For more information on `END{}' blocks, see `"Package Constructors and Destructors"', *Note Perlmod: (perl.info)perlmod,. See `"%SIG{expr}"', *Note Perlvar: (perl.info)perlvar, for handling abnormal program termination. AUTHOR ====== Andrew Langmead (initial draft). Brad Appleton (Version 1.02 and 2.00). Michael A. Chase (Version 2.00).  File: pm.info, Node: Audio/CD, Next: Audio/CoolEdit, Prev: AtExit, Up: Module List Perl interface to libcdaudio (cd + cddb) **************************************** NAME ==== Audio::CD - Perl interface to libcdaudio (cd + cddb) SYNOPSIS ======== use Audio::CD (); my $cd = Audio::CD->init; DESCRIPTION =========== Audio::CD provides a Perl interface to libcdaudio by Tony Arcieri, available from http://cdcd.undergrid.net/ Several classes provide glue for the libcdaudio functions and data structures. Audio::CD Class =============== init Initialize the Audio::CD object: my $cd = Audio::CD->init; stat Stat the *Audio::CD* object, returns an *Audio::CD::Info* object. my $info = $cd->stat; cddb Returns an *Audio::CDDB* object. my $cddb = $cd->cddb; play Play the given cd track (defaults to 1). $cd->play(1); stop Stop the cd. $cd->stop; pause Pause the cd. $cd->pause; resume Resume the cd. $cd->resume; eject Eject the cd. $cd->eject; close Close the cd tray. $cd->close; play_frames $cd->play_frames($startframe, $endframe); play_track_pos $cd->play_track_pos($strarttrack, $endtrack, $startpos); play_track $cd->play_track($strarttrack, $endtrack); track_advance $cd->track_advance($endtrack, $minutes, $seconds); advance $cd->advance($minutes, $seconds); get_volume Returns an *Audio::CD::Volume* object. my $vol = $cd->get_volume; set_volume $cd->set_volume($vol); Audio::CDDB Class ================= discid my $id = $cddb->discid; lookup Does a cddb lookup and returns an Audio::CD::Data object. my $data = $cddb->lookup; Audio::CD::Data Class artist my $artist = $data->artist; title my $title = $data->title; genre my $genre = $data->genre; tracks Returns an array reference of *Audio::CD::Track* objects. Audio::CD::Track Class ====================== name my $name = $track->name; Audio::CD::Info Class ===================== mode Returns the CD mode, one of PLAYING, PAUSED, COMPLETED, NOSTATUS; my $track = $info->mode; print "playing" if $info->mode == Audio::CD::PLAYING; total_tracks Returns the total number of tracks on the cd. my $track = $info->total_tracks; track_time Returns the current track play time: my($minutes, $seconds) = $info->track_time; time Returns the current disc play time: my($minutes, $seconds) = $info->time; length Returns the disc length time: my($minutes, $seconds) = $info->length; tracks Returns an array reference of *Audio::CD::Info::Track* objects. Audio::CD::Info::Track Class ============================ length Returns the track length time: my($minutes, $seconds) = $tinfo->length; pos Returns the track position on the CD: my($minutes, $seconds) = $tinfo->pos; type Returns the track type (either TRACK_AUDIO or TRACK_DATA): if ($tinfo->type == Audio::CD::TRACK_AUDIO) { print "audio track\n"; } elsif ($tinfo->type == Audio::CD::TRACK_DATA) { print "data track\n"; } is_audio Returns true if the track is an audio track; equivalent to the test: $tinfo->type == Audio::CD::TRACK_AUDIO ? 1 : 0 is_data Returns true if the track is a data track; equivalent to the test: $tinfo->type == Audio::CD::TRACK_DATA ? 1 : 0 SEE ALSO ======== Xmms(3) AUTHOR ====== Perl interface by Doug MacEachern libcdaudio and cddb_lookup.c by Tony Arcieri  File: pm.info, Node: Audio/CoolEdit, Next: Audio/CoolEdit/Read, Prev: Audio/CD, Up: Module List Modules for reading & writing Syntrillium CoolEdit Pro .ses files. ****************************************************************** NAME ==== Audio::CoolEdit - Modules for reading & writing Syntrillium CoolEdit Pro .ses files. SYNOPSIS ======== use Audio::CoolEdit; my $cool = new Audio::CoolEdit; my $test_out = './test'; my $details = { 'bits_sample' => 16, 'sample_rate' => 44100, }; my $write = $cool -> write( $test_out, $details ); $write -> add_file( { 'file' => './t/testout.wav', 'title' => "song 1", } ); $write -> add_file( { 'file' => './t/testout.wav', 'title' => "song 2", } ); $write -> finish(); my $read = $cool -> read( $test_out ); print Data::Dumper->Dump([ $read -> dump() ]); DESCRIPTION =========== Syntrillium's CoolEdit Pro (http://www.syntrillium.com) is a MSWin32 based multitrack capable sound editor. This module reads/ writes the .ses (session) file format enabling you to place audio files in a vitual track at a given offset. The write module is a lot more developed than the read module as this has been developed to be used with Audio::Mix NOTES ===== All sample positions used are in byte offsets (*Note Audio/Tools/Time: Audio/Tools/Time, for conversion utilities) AUTHOR ====== Nick Peskett - nick@soup.demon.co.uk SEE ALSO ======== L L L L METHODS ======= new --- Returns a blessed Audio::CoolEdit object. my $cool = new Audio::CoolEdit; write ----- Returns a blessed Audio::CoolEdit::Write object. my $details = { 'bits_sample' => 16, 'sample_rate' => 44100, }; my $write = $cool -> write( './test', $details ); See *Note Audio/CoolEdit/Write: Audio/CoolEdit/Write, for methods. read ---- Returns a blessed Audio::CoolEdit::Read object. my $read = $cool -> read( './test.ses' ); See *Note Audio/CoolEdit/Read: Audio/CoolEdit/Read, for methods.  File: pm.info, Node: Audio/CoolEdit/Read, Next: Audio/CoolEdit/Write, Prev: Audio/CoolEdit, Up: Module List Methods for reading Syntrillium CoolEdit Pro .ses files. ******************************************************** NAME ==== Audio::CoolEdit::Read - Methods for reading Syntrillium CoolEdit Pro .ses files. SYNOPSIS ======== use Audio::CoolEdit; my $cool = new Audio::CoolEdit; my $read = $cool -> read( './testfile.ses' ); NOTES ===== This module shouldn't be used directly, a blessed object can be returned from *Note Audio/CoolEdit: Audio/CoolEdit,. AUTHOR ====== Nick Peskett - nick@soup.demon.co.uk SEE ALSO ======== L L METHODS ======= dump ---- The only method, returns a complex reference to a hash with all sorts of stuff in it. :-) print Data::Dumper->Dump([ $cool -> dump() ]);