Provided by: libchemistry-elements-perl_1.07-2_all bug

NAME

       Chemistry::Elements - Perl extension for working with Chemical Elements

SYNOPSIS

         use Chemistry::Elements qw(get_name get_Z get_symbol);

         # the constructor can use different input
         $element = Chemistry::Elements->new( $atomic_number   );
         $element = Chemistry::Elements->new( $chemical_symbol );
         $element = Chemistry::Elements->new( $element_name    );

         # you can make up your own attributes by specifying
         # a method (which is really AUTOLOAD)
               $element->molar_mass(22.989) #sets the attribute
         $MM = $element->molar_mass         #retrieves the value

DESCRIPTION

       There are two parts to the module:  the object stuff and the exportable functions for use
       outside of the object stuff.  The exportable functions are discussed in EXPORTABLE
       FUNCTIONS.

       Chemistry::Elements provides an easy, object-oriented way to keep track of your chemical
       data.  Using either the atomic number, chemical symbol, or element name you can construct
       an Element object.  Once you have an element object, you can associate your data with the
       object by making up your own methods, which the AUTOLOAD function handles.  Since each
       chemist is likely to want to use his or her own data, or data for some unforesee-able
       property, this module does not try to be a repository for chemical data.

       The Element object constructor tries to be as flexible as possible - pass it an atomic
       number, chemical symbol, or element name and it tries to create the object.

         # the constructor can use different input
         $element = Chemistry::Elements->new( $atomic_number );
         $element = Chemistry::Elements->new( $chemical_symbol );
         $element = Chemistry::Elements->new( $element_name );

       once you have the object, you can define your own methods simply by using them.  Giving
       the method an argument (others will be ignored) creates an attribute with the method's
       name and the argument's value.

         # you can make up your own attributes by specifying
         # a method (which is really AUTOLOAD)
               $element->molar_mass(22.989) #sets the attribute
         $MM = $element->molar_mass         #retrieves the value

       The atomic number, chemical symbol, and element name can be retrieved in the same way.

          $atomic_number = $element->Z;
          $name          = $element->name;
          $symbol        = $element->symbol;

       These methods can also be used to set values, although changing any of the three affects
       the other two.

          $element       = Chemistry::Elements->new('Lead');

          $atomic_number = $element->Z;    # $atomic_number is 82

          $element->Z(79);

          $name          = $element->name; # $name is 'Gold'

   Instance methods
       new( Z | SYMBOL | NAME )
           Create a new instance from either the atomic number, symbol, or element name.

       can( METHOD [, METHOD ... ] )
           Returns true if the package or object can respond to METHOD. This distinguishes
           between class and instance methods.

       Z   Return the atomic number of the element.

       name
           Return the name of the element.

       symbol
           Return the symbol of the element.

   Exportable functions
       These functions can be exported.  They are not exported by default. At the moment, only
       the functional interface supports multi-language names.

       get_symbol( NAME|Z )
           This function attempts to return the symbol of the chemical element given either the
           chemical symbol, element name, or atmoic number.  The function does its best to
           interpret inconsistent input data (e.g.  chemcial symbols of mixed and single case).

                   use Chemistry::Elements qw(get_symbol);

                   $name = get_symbol('Fe');     #$name is 'Fe'
                   $name = get_symbol('fe');     #$name is 'Fe'
                   $name = get_symbol(26);       #$name is 'Fe'
                   $name = get_symbol('Iron');   #$name is 'Fe'
                   $name = get_symbol('iron');   #$name is 'Fe'

           If no symbol can be found, nothing is returned.

           Since this function will return the symbol if it is given a symbol, you can use it to
           test whether a string is a chemical symbol (although you have to play some tricks with
           case since get_symbol will try its best despite the case of the input data).

                   if( lc($string) eq lc( get_symbol($string) ) )
                           {
                           #stuff
                           }

           You can modify the symbols (e.g. you work for UCal ;) ) by changing the data at the
           end of this module.

       get_name( SYMBOL|NAME|Z [, LANGUAGE] )
           This function attempts to return the name the chemical element given either the
           chemical symbol, element name, or atomic number.  The function does its best to
           interpret inconsistent input data (e.g.  chemcial symbols of mixed and single case).

                   $name = get_name('Fe');     #$name is 'Iron'
                   $name = get_name('fe');     #$name is 'Iron'
                   $name = get_name(26);       #$name is 'Iron'
                   $name = get_name('Iron');   #$name is 'Iron'
                   $name = get_name('iron');   #$name is 'Iron'

           If there is no Z can be found, nothing is returned.

           Since this function will return the name if it is given a name, you can use it to test
           whether a string is a chemical element name (although you have to play some tricks
           with case since get_name will try its best despite the case of the input data).

                   if( lc($string) eq lc( get_name($string) ) )
                           {
                           #stuff
                           }

           You can modify the names (e.g. for different languages) by changing the data at the
           end of this module.

       get_Z( SYMBOL|NAME|Z )
           This function attempts to return the atomic number of the chemical element given
           either the chemical symbol, element name, or atomic number.  The function does its
           best to interpret inconsistent input data (e.g. chemcial symbols of mixed and single
           case).

                   $name = get_Z('Fe');     #$name is 26
                   $name = get_Z('fe');     #$name is 26
                   $name = get_Z(26);       #$name is 26
                   $name = get_Z('Iron');   #$name is 26
                   $name = get_Z('iron');   #$name is 26

           If there is no Z can be found, nothing is returned.

           Since this function will return the Z if it is given a Z, you can use it to test
           whether a string is an atomic number.  You might want to use the string comparison in
           case the $string is not a number (in which case the comparison will be false save for
           the case when $string is undefined).

                   if( $string eq get_Z($string) )
                           {
                           #stuff
                           }

       The package constructor automatically finds the largest defined atomic number (in case you
       add your own heavy elements).

   AUTOLOADing methods
       You can pseudo-define additional methods to associate data with objects.  For instance, if
       you wanted to add a molar mass attribute, you simply pretend that there is a molar_mass
       method:

               $element->molar_mass($MM); #add molar mass datum in $MM to object

       Similiarly, you can retrieve previously set values by not specifying an argument to your
       pretend method:

               $datum = $element->molar_mass();

               #or without the parentheses
               $datum = $element->molar_mass;

       If a value has not been associated with the pretend method and the object, the pretend
       method returns nothing.

       I had thought about providing basic data for the elements, but thought that anyone using
       this module would probably have their own data.  If there is an interest in canned data,
       perhaps I can provide mine :)

   Localization support
       XXX: Fill this stuff in later. For now see the test suite

TO DO

       I would like make this module easily localizable so that one could specify other names or
       symbols for the elements (i.e. a different language or a different perspective on the
       heavy elements).  If anyone should make changes to the data, i would like to get a copy so
       that i can include it in future releases :)

SOURCE AVAILABILITY

       The source for this module is in Github:

               git://github.com/briandfoy/chemistry--elements.git

AUTHOR

       brian d foy, "<bdfoy@cpan.org>"

COPYRIGHT AND LICENSE

       Copyright (c) 2000-2008 brian d foy. All rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.