#==========================================================================+ # This source code is public domain, and may be freely distributed, | # modified, and used for any purpose. IT COMES WITH ABSOLUTELY NO | # WARRANTY OF ANY KIND. | #==========================================================================+ DAYPERL2 - PERL INTERFACE TO THE DAYLIGHT TOOLKIT Author: Craig A. James www.modgraph-usa.com CONTENTS * What Is DayPerl2? * Brief History of DayPerl * DayPerl vs. DayPerl2 * Coexistence * The Drawing Library * Documentation * Testing * Support * Release History NOTE: See INSTALL for compile, test and installation directions. What Is Dayperl2? ----------------- DayPerl2 is a Perl module that makes all Daylight Toolkit (tm) functionality available as Perl functions and constants. In addition, DayPerl2 has a built-in "drawing library" that provides direct generation of PNG images using the Daylight Depict toolkit. Brief History of DayPerl ------------------------ Alex Wong (Chiron) wrote the excellent original DayPerl module a while back. Roger Critchlow and Jeremy Yang made further improvements. Roger eventually wrote DaySWIG, a multi-lingual interface to the Daylight Toolkit that include a Perl version. See: http://www.daylight.com/support/contrib/dayperl/ While extremely useful (this author used DayPerl it extensively), several features of DayPerl made it difficult to use newer features of Perl, particularly "strict" error-checking. In addition, the original h2xs(1) and DaySWIG versions proved difficult to maintain. These problems provided the motivation for DayPerl2. DayPerl vs. DayPerl2 -------------------- For a PowerPoint presentation about DayPerl2, see Daylight's MUG 'O4 web site, look for the talk by Craig James: http://www.daylight.com/meetings/mug04/James/index.html The primary motivation for DayPerl2 is that it is more "Perl like" than the original DayPerl: 1. Daylight constants such as NULL_OB were functions in DayPerl, wherease in DayPerl2 they are variables: DayPerl: my $atoms = dt_stream($mol, TYP_ATOM); while (NULL_OB != (my $atom = dt_next($atoms))) { ... } DayPerl2: my $atoms = dt_stream($mol, $TYP_ATOM); while ($NULL_OB != (my $atom = dt_next($atoms))) { ... } This change is particulary important for code quality and debugging, as it allows you to specify the "use 'strict'" directive. In addition, it's a more "natural" look for a Perl program. 2. All return values are in the function's return value; parameters are NOT altered. DayPerl: my $ok = dt_getcoord($depiction, $atom, $x, $y, $z); DayPerl2: my ($ok, $x, $y, $z) = dt_getcoord($depiction, $atom); Note in particular that DayPerl would alter the values of the scalars $x, $y, and $z. The new DayPerl2 syntax has a much more "Perl-like" way to return values. A Perl function is not supposed to alter scalar parameters; DayPerl2 fixes this. 3. The "invalid string" is handled correctly. In DayPerl, you had to put in the special "KLUDGE_INVALID_STRING" constant. In DayPerl2, you simply use "undef" like you'd expect. 4. A built-in drawing library generates PNG images directly, without the need for a separate program or CGI. These changes, while seeming simple, have a dramatic effect on the usability and supportability of DayPerl2 code. Coexistence ----------- DayPerl and DayPerl2 can coexist. Because the package names are different, you can install both at your site. Old programs can be ported from DayPerl to DayPerl2 on an as-needed basis. The Drawing Library ------------------- A great new feature in DayPerl2 is its PNG image generator. PNG images are like GIF images, and are supported by all browsers. But PNG files are not encumbered by any patents or licenses anywhere in the world -- you can compile and use the PNG library freely. An example Perl program, ./examples/depicttest.pl, shows how to generate an image. The Daylight documentation discusses Graphics Attributes (GA's) in more detail. If you're going to compile the PNG drawing library, there are several prerequisite libraries that may or may not be installed on your machine: libpng http://www.libpng.org/ This library is shipped standard on many systems, such as Red Hat Linux. libz http://www.info-zip.org/ Data compression, used by libpng. libgd http://www.boutell.com/gd/ An ANSI C library for creating images. Provides a clean interface to the PNG and JPG library. These libraries are supplied with DayPerl2. When you type "make", the build system will compile these for you automatically. Documentation ------------- There is no separate set of man(1) pages -- use the regular Daylight documentation. Given any C function, you can quickly figure out the Perl syntax: C function Perl function ------------------------------ -------------------------- simple: dt_foo(a, b, ...) dt_foo(a, b, ...) return number: a = dt_foo(b, c, ...) $a = dt_foo(b, c, ...) return string: str = dt_foo(*plen, a, b, ...) $s = dt_foo(a, b, ...) return mult: ok = dt_foo(a, b, &x, &y) ($ok, $x, $y) = dt_foo(a, b) Any C constant defined in the dt_xxx.h files will have a corresponding Perl variable, such as $TYP_ATOM, $NULL_OB, $DX_ATN_Si, and $DX_THOR_CACHE_OFF. Support ------- If you'd like professional help, support and/or training services for DayPerl2, please contact us: Craig A. James Modgraph Consultants LTD http://www.modgraph-usa.com or http://www.modgraph.co.uk Unabashed advertising: We can also provide full application-development services, including expert Perl development. Release History --------------- version 1.0.3 - JPEG support - Separated libgd and swig into separate directories, rather than subdirectories of dayperl2. - Fixed a definition in typemaps.i version 1.0.2 Aug 26, 2002 - Minor fixes to makefile (creates perl "auto" dir if not there) - Commented out freetype stuff in makefiles that's not actually used. - Separated INSTALL stuff from this file version 1.0.1 July 2004 "make install" didn't work right for first-time install version 1.0.0 5 April 2004 First public release of DayPerl2 Pre-1.0.0 Several non-numbered versions were installed at various customer sites.