This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Persistent/Base, Next: Persistent/DBM, Prev: Persistent, Up: Module List An Abstract Persistent Base Class ********************************* NAME ==== Persistent::Base - An Abstract Persistent Base Class SYNOPSIS ======== ### we are a subclass of ... ### use Persistent::Base; @ISA = qw(Persistent::Base); ABSTRACT ======== This is an abstract class used by the Persistent framework of classes to implement persistence with various types of data stores. This class provides the methods and interface for implementing Persistent classes. Refer to the *Note Persistent: Persistent, documentation for a very thorough introduction to using the Persistent framework of classes. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. ABSTRACT METHODS THAT NEED TO BE OVERRIDDEN IN THE SUBCLASS =========================================================== datastore - Sets/Returns the Data Store Parameters -------------------------------------------------- eval { ### set the data store ### $person->datastore(@args); ### get the data store ### $href = $person->datastore(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the data store of the object. This method throws Perl execeptions so use it with an eval block. Setting the data store can involve anything from initializing a connection to opening a file. Getting a data store usually means returning information pertaining to the data store in a useful form, such as a connection to a database or a location of a file. This method requires implementing. Parameters: Varies by implementation. Returns: Varies by implementation. insert - Insert an Object into the Data Store --------------------------------------------- eval { $person->insert(); }; croak "Exception caught: $@" if $@; Inserts an object into the data store. This method throws Perl execeptions so use it with an eval block. This method requires implementing. Parameters: None. Returns: None. See the *Note Persistent: Persistent, documentation for more information. delete - Delete an Object from the Data Store --------------------------------------------- eval { $person->delete(); }; croak "Exception caught: $@" if $@; Deletes an object from the data store. This method throws Perl execeptions so use it with an eval block. This method requires implementing. Parameters: *@id* Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default. Returns: $flag A true value if the object previously existed in the data store (it was deleted), and a false value if not (nothing to delete). See the *Note Persistent: Persistent, documentation for more information. restore_where - Conditionally Restoring Objects ----------------------------------------------- use Persistent::File; eval { my $person = new Persistent::File('people.txt', '|'); $person->restore_where( "lastname = 'Flintstone' and telnum =~ /^[(]?650/", "lastname, firstname, telnum DESC" ); while ($person->restore_next()) { print "Restored: "; print_person($person); } }; croak "Exception caught: $@" if $@; Restores objects from the data store that meet the specified conditions. The objects are returned one at a time by using the *restore_next* method and in a sorted order if specified. This method throws Perl execeptions so use it with an eval block. Since this is a Perl implemented Persistent class, the *restore_where* method expects all patterm matching to use Perl regular expressions. This method requires implementing. Parameters: $where Conditional expression for the requested objects. The format of this expression is similar to a SQL WHERE clause. This argument is optional. $order_by Sort expression for the requested objects. The format of this expression is similar to a SQL ORDER BY clause. This argument is optional. Returns: $num_of_objs The number of objects that match the conditions. See the *Note Persistent: Persistent, documentation for more information. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/Base: Persistent/Base,, *Note Persistent/DBM: Persistent/DBM,, *Note Persistent/File: Persistent/File,, *Note Persistent/Memory: Persistent/Memory, BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Persistent/DBM, Next: Persistent/DataType/Base, Prev: Persistent/Base, Up: Module List A Persistent Class implemented using a DBM File *********************************************** NAME ==== Persistent::DBM - A Persistent Class implemented using a DBM File SYNOPSIS ======== use Persistent::DBM; use English; # import readable variable names like $EVAL_ERROR eval { ### in case an exception is thrown ### ### allocate a persistent object ### my $person = new Persistent::DBM('people.dbm'); ### define attributes of the object ### $person->add_attribute('firstname', 'ID', 'VarChar', undef, 10); $person->add_attribute('lastname', 'ID', 'VarChar', undef, 20); $person->add_attribute('telnum', 'Persistent', 'VarChar', undef, 15); $person->add_attribute('bday', 'Persistent', 'DateTime', undef); $person->add_attribute('age', 'Transient', 'Number', undef, 2); ### query the datastore for some objects ### $person->restore_where(qq{ lastname = 'Flintstone' and telnum =~ /^[(]?650/ }); while ($person->restore_next()) { printf "name = %s, tel# = %s\n", $person->firstname . ' ' . $person->lastname, $person->telnum; } }; if ($EVAL_ERROR) { ### catch those exceptions! ### print "An error occurred: $EVAL_ERROR\n"; } ABSTRACT ======== This is a Persistent class that uses DBM files to store and retrieve objects. This class can be instantiated directly or subclassed. The methods described below are unique to this class, and all other methods that are provided by this class are documented in the *Note Persistent: Persistent, documentation. The *Note Persistent: Persistent, documentation has a very thorough introduction to using the Persistent framework of classes. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= new - Object Constructor ------------------------ use Persistent::DBM; eval { my $obj = new Persistent::DBM($file, $field_delimiter, $type); }; croak "Exception caught: $@" if $@; Allocates an object. This method throws Perl execeptions so use it with an eval block. Parameters: These are the same as for the *datastore* method below. datastore - Sets/Returns the Data Store Parameters -------------------------------------------------- eval { ### set the data store ### $obj->datastore($file, $field_delimiter, $type); ### get the data store ### $file = $obj->datastore(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the data store of the object. This method throws Perl execeptions so use it with an eval block. Parameters: $file File to use as the data store. $field_delimiter Delimiter used to separate the attributes of the object in the data store. This argument is optional and will be initialized to the value of the special Perl variable $; (or $SUBSCRIPT_SEPARATOR if you are using the English module) as a default or if set to undef. $type Type of DBM file to use. This is probably one of these: NDBM_File, DB_File, GDBM_File, SDBM_File, or ODBM_File. This argument is optional and will default to AnyDBM_File. See the AnyDBM_File documentation for more information. Returns: $file File used as the data store. insert - Insert an Object into the Data Store --------------------------------------------- eval { $obj->insert(); }; croak "Exception caught: $@" if $@; Inserts an object into the data store. This method throws Perl execeptions so use it with an eval block. Parameters: None. Returns: None. See the *Note Persistent: Persistent, documentation for more information. update - Update an Object in the Data Store ------------------------------------------- eval { $obj->update(); }; croak "Exception caught: $@" if $@; Updates an object in the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default. This argument is useful if you are updating the Identity attributes of the object and you already have all of the attribute values so you do not need to restore the object (like a CGI request with hidden fields, maybe). So you can just set the Identity attributes of the object to the new values and then pass the old Identity values as arguments to the update method. For example, if Pebbles Flintstone married Bam Bam Rubble, then you could update her last name like this: ### Pebbles already exists in the data store, but we don't ### ### want to do an extra restore because we already have ### ### all of the attribute values ### $person->lastname('Rubble'); $person->firstname('Pebbles'); ### set the rest of the attributes ... ### $person->update('Flintstone', 'Pebbles'); Or, if don't want to set all of the object's attributes, you can just restore it and then update it like this: ### restore object from data store ### if ($person->restore('Flintstone', 'Pebbles')) { $person->lastname('Rubble'); $person->update(); } Returns: $flag A true value if the object previously existed in the data store (it was updated), and a false value if not (it was inserted). See the *Note Persistent: Persistent, documentation for more information. save - Save an Object to the Data Store --------------------------------------- eval { $person->save(); }; croak "Exception caught: $@" if $@; Saves an object to the data store. The object is inserted if it does not already exist in the data store, otherwise, it is updated. This method throws Perl execeptions so use it with an eval block. Parameters: None. Returns: $flag A true value if the object previously existed in the data store (it was updated), and a false value if not (it was inserted). See the *Note Persistent: Persistent, documentation for more information. delete - Delete an Object from the Data Store --------------------------------------------- eval { $obj->delete(); ### or ### $obj->delete(@id); }; croak "Exception caught: $@" if $@; Deletes an object from the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default. Returns: $flag A true value if the object previously existed in the data store (it was deleted), and a false value if not (nothing to delete). See the *Note Persistent: Persistent, documentation for more information. restore - Restore an Object from the Data Store ----------------------------------------------- eval { $obj->restore(@id); }; croak "Exception caught: $@" if $@; Restores an object from the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This method throws Perl execeptions so use it with an eval block. Returns: $flag A true value if the object previously existed in the data store (it was restored), and a false value if not (nothing to restore). See the *Note Persistent: Persistent, documentation for more information. restore_where - Conditionally Restoring Objects ----------------------------------------------- use Persistent::DBM; eval { my $person = new Persistent::DBM('people.dbm', '|', 'NDBM_File'); $person->restore_where( "lastname = 'Flintstone' and telnum =~ /^[(]?650/", "lastname, firstname, telnum DESC" ); while ($person->restore_next()) { print "Restored: "; print_person($person); } }; croak "Exception caught: $@" if $@; Restores objects from the data store that meet the specified conditions. The objects are returned one at a time by using the *restore_next* method and in a sorted order if specified. This method throws Perl execeptions so use it with an eval block. Since this is a Perl based Persistent class, the *restore_where* method expects the $where argument to use Perl expressions. Parameters: $where Conditional expression for the requested objects. The format of this expression is similar to a SQL WHERE clause. This argument is optional. $order_by Sort expression for the requested objects. The format of this expression is similar to a SQL ORDER BY clause. This argument is optional. Returns: $num_of_objs The number of objects that match the conditions. See the *Note Persistent: Persistent, documentation for more information. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/Base: Persistent/Base,, *Note Persistent/File: Persistent/File,, *Note Persistent/Memory: Persistent/Memory, NOTES ===== You may notice some lock files (with a '.lock' extension) in the same directory as your data files. These are used to control access to the data files. BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Persistent/DataType/Base, Next: Persistent/DataType/Char, Prev: Persistent/DBM, Up: Module List An Abstract DataType Base Class ******************************* NAME ==== Persistent::DataType::Base - An Abstract DataType Base Class SYNOPSIS ======== ### we are a subclass of ... ### use Persistent::DataType::Base; @ISA = qw(Persistent::DataType::Base); ABSTRACT ======== This is an abstract base class used by the Persistent framework of classes to implement the attributes of objects. This class provides methods for implementing data types. This class is not instantiated. Instead, it is inherited from or subclassed by DataType classes. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= debug - Accesses the Debugging Flag ----------------------------------- ### set the debugging flag ### $object->debug($flag); ### get the debugging flag ### $flag = $object->debug(); Returns (and optionally sets) the debugging flag of an object. This method does not throw Perl execeptions. Parameters: $flag If set to a true value then debugging is on, otherwise, a false value means off. Constructor - Creates a DataType Object --------------------------------------- eval { my $datatype = new Persistent::DataType::Object(@args); }; croak "Exception caught: $@" if $@; Initializes a data type object. This method throws Perl execeptions so use it with an eval block. This method is abstract and needs implementing. value - Accesses the Value of the DataType ------------------------------------------ eval { ### set the value ### $datatype->value($new_value); ### get the value ### $value = $datatype->value(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the value of a DataType object. This method throws Perl execeptions so use it with an eval block. This method is abstract and needs implementing. get_compare_op - Returns the Comparison Operator ------------------------------------------------ $cmp_op = $obj->get_compare_op(); Returns the comparison operator of a DataType object. This method does not throw Perl execeptions. This method is abstract and needs implementing. Can return a couple of different comparison operators: 'cmp' if the value of the object should be compared as a string. '<=>' if the value of the object should be compared as a number. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/DataType/Char: Persistent/DataType/Char,, *Note Persistent/DataType/DateTime: Persistent/DataType/DateTime,, *Note Persistent/DataType/Number: Persistent/DataType/Number,, *Note Persistent/DataType/String: Persistent/DataType/String,, *Note Persistent/DataType/VarChar: Persistent/DataType/VarChar, BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent::DataType Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Persistent/DataType/Char, Next: Persistent/DataType/DateTime, Prev: Persistent/DataType/Base, Up: Module List A Fixed Length Character String Class ************************************* NAME ==== Persistent::DataType::Char - A Fixed Length Character String Class SYNOPSIS ======== use Persistent::DataType::Char; use English; eval { ### in case an exception is thrown ### ### allocate a string ### my $string = new Persistent::DataType::Char($value, $max_length); ### get/set value of string ### $value = $string->value($new_value); ### get length of string ### my $length = $string->length(); ### get/set maximum length of string ### my $max = $string->max_length($new_max); ### returns 'eq' for strings ### my $cmp_op = $string->get_compare_op(); }; if ($EVAL_ERROR) { ### catch those exceptions! ### print "An error occurred: $EVAL_ERROR\n"; } ABSTRACT ======== This is a fixed length character string class used by the Persistent framework of classes to implement the attributes of objects. This class provides methods for accessing the value, length, maximum length, and comparison operator of a fixed length character string. A fixed length string (Char) always has a finite maximum length that can not be exceeded. If the string is shorter than this maximum length, then the string is padded with spaces on the trailing end. This is different from a character string (String) which can have an unlimited maximum length and a variable length string (VarChar) which is not padded. This class is usually not invoked directly, at least not when used with the Persistent framework of classes. However, the constructor arguments of this class are usually of interest when defining the attributes of a Persistent object since the *add_attribute* method of the Persistent classes instantiates this class directly. Also, the arguments to the value method are of interest when dealing with the accessor methods of the Persistent classes since the accessor methods pass their arguments to the value method and return the string value from the value method. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= Constructor - Creates the Char Object ------------------------------------- eval { my $string = new Persistent::DataType::Char($value, $max_length); }; croak "Exception caught: $@" if $@; Initializes a fixed length character string object. This method throws Perl execeptions so use it with an eval block. Parameters: $value Actual value of the string. This argument is optional and may be set to undef. $max_length Maximum length of the string value. This argument is optional and will be initialized to the length of the $value as a default or 1 if no $value argument is passed. value - Accesses the Value of the String ---------------------------------------- eval { ### set the value ### $string->value($value); ### get the value ### $value = $string->value(); }; croak "Exception caught: $@" if $@; Sets the value of the string and/or returns the value. This method throws Perl execeptions so use it with an eval block. Parameters: $value Actual value of the string. This argument is optional and may be set to undef. The value returned will be padded with spaces if the length is less than the maximum length. length - Returns the Length of the String ----------------------------------------- eval { $value = $string->length(); }; croak "Exception caught: $@" if $@; Returns the length of the string which is always the same as the maximum length for a fixed length string. This method throws Perl execeptions so use it with an eval block. Parameters: None max_length - Accesses the Maximum Length of the String ------------------------------------------------------ eval { ### set the maximum length ### $string->max_length($new_max); ### get the maximum length ### $max_length = $string->max_length(); }; croak "Exception caught: $@" if $@; Sets the maximum length of the string and/or returns it. This method throws Perl execeptions so use it with an eval block. Parameters: $max_length Maximum length of the string value. The maximum length must be greater than zero, otherwise, an exception is thrown. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/DataType/DateTime: Persistent/DataType/DateTime,, *Note Persistent/DataType/Number: Persistent/DataType/Number,, *Note Persistent/DataType/String: Persistent/DataType/String,, *Note Persistent/DataType/VarChar: Persistent/DataType/VarChar, BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Persistent/DataType/DateTime, Next: Persistent/DataType/Number, Prev: Persistent/DataType/Char, Up: Module List A Date and Time Class ********************* NAME ==== Persistent::DataType::DateTime - A Date and Time Class SYNOPSIS ======== use Persistent::DataType::DateTime; use English; eval { ### in case an exception is thrown ### ### allocate a date ### my $date = new Persistent::DataType::DateTime(localtime); ### get/set value of date ### $value = $date->value($year, $month, $day, $hours, $minutes, $seconds); ### get/set year of the date ### $year = $date->year($new_year); ### get/set month of the date ### $month = $date->month($new_month); ### get/set day of the date ### $day = $date->day($new_day); ### get/set hours of the date ### $hours = $date->hours($new_hours); ### get/set minutes of the date ### $minutes = $date->minutes($new_minutes); ### get/set seconds of the date ### $seconds = $date->seconds($new_seconds); ### returns 'cmp' for dates ### my $cmp_op = $date->get_compare_op(); }; if ($EVAL_ERROR) { ### catch those exceptions! ### print "An error occurred: $EVAL_ERROR\n"; } ABSTRACT ======== This is a date and time class used by the Persistent framework of classes to implement the attributes of objects. This class provides methods for accessing a date in a variety of formats. This class is usually not invoked directly, at least not when used with the Persistent framework of classes. However, the constructor arguments of this class are usually of interest when defining the attributes of a Persistent object since the *add_attribute* method of the Persistent classes instantiates this class directly. Also, the arguments to the value method are of interest when dealing with the accessor methods of the Persistent classes since the accessor methods pass their arguments to the value method and return the string value from the value method. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= Constructor - Create a New DateTime Object ------------------------------------------ use Persistent::DataType::DateTime; eval { $date = new Persistent::DataType::DateTime($datestring); $date = new Persistent::DataType::DateTime('now'); $date = new Persistent::DataType::DateTime(''); $date = new Persistent::DataType::DateTime(undef); $date = new Persistent::DataType::DateTime($year, $month, $day, $hour, $min, $sec); $date = new Persistent::DataType::DateTime(localtime); }; croak "Exception caught: $@" if $@; Initializes a DateTime object. This method throws Perl execeptions so use it with an eval block. This constructor accepts several forms of arguments: $datestring If the sole argument is a string, it is assumed to contain the date and time in the following format: YYYY-MM-DD hh:mm:ss or YYYY/MM/DD hh:mm:ss This is also the format that is returned by the value method of this object. Another valid format to pass is the following: DD-Mon-YYYY where Mon is the three letter abbreviation for the month. The case of the letters is not sensitive (i.e. jan or Jan or JAN is alright). 'now' If the sole argument is the word 'now', then the current date and time are used. undef or *the empty string (")* If the sole argument is undef or the empty string ("), then the date and time are set to undef. *$year, $month, $day, $hour, $min, $sec* If more than one argument is given (and less than 7), it is assumed that the date and time are being given as a series of integers in the above order where their formats are the following: $year = 0 .. 9999 ### 4 digit year ### $month = 1 .. 12 $day = 1 .. 31 $hours = 0 .. 23 $minutes = 0 .. 59 $seconds = 0 .. 59 *$sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst* If more than six arguments are passed, it is assumed that the date and time are being given as a series of integers in the above order, which happens to be the same order as the array that the Perl built-ins, localtime and gmtime, return. See the *perlfunc* manpage for more information. value - Accesses the Value of the Date -------------------------------------- eval { $date_string = $date->value($datestring); $date_string = $date->value('now'); $date_string = $date->value(''); $date_string = $date->value(undef); $date_string = $date->value($year, $month, $day, $hour, $min, $sec); $date_string = $date->value(localtime); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the value of the DateTime object. This method throws Perl execeptions so use it with an eval block. The arguments are as described above in `"Constructor -- Create a New DateTime Object"' in this node. get_compare_op - Returns the Comparison Operator for DateTime ------------------------------------------------------------- $cmp_op = $date->get_compare_op(); Returns the comparison operator for the DateTime class which is 'cmp'. This method does not throw execeptions. Parameters: None year - Accesses the Year of the Date ------------------------------------ eval { ### set the year ### $date->year($new_year); ### get the year ### $year = $date->year(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the year of the DateTime object. This method throws Perl execeptions so use it with an eval block. Parameters: $year A 4-digit year. The year must be >= 0 and <= 9999. If it is undef then the year will be set to undef. month - Accesses the Month of the Date -------------------------------------- eval { ### set the month ### $date->month($new_month); ### get the month ### $month = $date->month(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the month of the DateTime object. This method throws Perl execeptions so use it with an eval block. Parameters: $month The month must be >= 1 and <= 12. If it is undef then the month will be set to undef. day - Accesses the Day of the Date ---------------------------------- eval { ### set the day ### $date->day($new_day); ### get the day ### $day = $date->day(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the day of the DateTime object. This method throws Perl execeptions so use it with an eval block. Parameters: $day The day must be >= 1 and <= 31. If it is undef then the day will be set to undef. hours - Accesses the Hours of the Date -------------------------------------- eval { ### set the hours ### $date->hours($new_hours); ### get the hours ### $hours = $date->hours(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the hours of the DateTime object. This method throws Perl execeptions so use it with an eval block. Parameters: $hours The hours must be >= 0 and <= 23. If it is undef then the hours will be set to undef. minutes - Accesses the Minutes of the Date ------------------------------------------ eval { ### set the minutes ### $date->minutes($new_minutes); ### get the minutes ### $minutes = $date->minutes(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the minutes of the DateTime object. This method throws Perl execeptions so use it with an eval block. Parameters: $minutes The minutes must be >= 1 and <= 59. If it is undef then the minutes will be set to undef. seconds - Accesses the Seconds of the Date ------------------------------------------ eval { ### set the seconds ### $date->seconds($new_seconds); ### get the seconds ### $seconds = $date->seconds(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the seconds of the DateTime object. This method throws Perl execeptions so use it with an eval block. Parameters: $seconds The seconds must be >= 0 and <= 59. If it is undef then the seconds will be set to undef. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/DataType/Char: Persistent/DataType/Char,, *Note Persistent/DataType/Number: Persistent/DataType/Number,, *Note Persistent/DataType/String: Persistent/DataType/String,, *Note Persistent/DataType/VarChar: Persistent/DataType/VarChar, BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Persistent/DataType/Number, Next: Persistent/DataType/String, Prev: Persistent/DataType/DateTime, Up: Module List A Floating Point and Integer Class ********************************** NAME ==== Persistent::DataType::Number - A Floating Point and Integer Class SYNOPSIS ======== use Persistent::DataType::Number; use English; eval { ### in case an exception is thrown ### ### allocate a number ### my $number = new Persistent::DataType::Number($value, $precision, $scale); ### get/set value of number ### $value = $number->value($new_value); ### get/set precision of the number ### $precision = $number->precision($new_precision); ### get/set scale of number ### $scale = $number->scale($new_scale); ### returns '<=>' for numbers ### my $cmp_op = $number->get_compare_op(); }; if ($EVAL_ERROR) { ### catch those exceptions! ### print "An error occurred: $EVAL_ERROR\n"; } ABSTRACT ======== This is a floating point and integer class used by the Persistent framework of classes to implement the attributes of objects. This class provides methods for accessing the value, precision, scale, and comparison operator of a number. This class is usually not invoked directly, at least not when used with the Persistent framework of classes. However, the constructor arguments of this class are usually of interest when defining the attributes of a Persistent object since the *add_attribute* method of the Persistent classes instantiates this class directly. Also, the arguments to the value method are of interest when dealing with the accessor methods of the Persistent classes since the accessor methods pass their arguments to the value method and return the string value from the value method. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= Constructor - Creates the Number Object --------------------------------------- eval { my $number = new Persistent::DataType::Number($value, $precision, $scale); }; croak "Exception caught: $@" if $@; Initializes a number object. This method throws Perl execeptions so use it with an eval block. Parameters: $value Actual value of the number; this may be a floating point or integer. This argument is optional and may be set to undef. $precision The number of digits in the number not including the decimal point or the sign. This argument is optional and will be initialized to the precision of the $value argument as a default. $scale The number of digits after the decimal point. This argument is optional and will be initialized to the scale of the $value argument as a default. value - Accesses the Value of the Number ---------------------------------------- eval { ### set the value ### $number->value($value); ### get the value ### $value = $number->value(); }; croak "Exception caught: $@" if $@; Sets the value of the number and/or returns the value. This method throws Perl execeptions so use it with an eval block. Parameters: $value Actual value of the number; this may be a floating point or integer. This argument is optional and may be set to undef. get_compare_op - Returns the Comparison Operator ------------------------------------------------ $cmp_op = $number->get_compare_op(); Returns the comparison operator for the Number class which is '<=>'. This method does not throw execeptions. Parameters: None precision - Accesses the Precision of the Number ------------------------------------------------ eval { ### set the precision ### $number->precision($new_precision); ### get the precision ### $precision = $number->precision(); }; croak "Exception caught: $@" if $@; Sets the precision of the number and/or returns it. This method throws Perl execeptions so use it with an eval block. Parameters: $precision The number of digits in the number not including the decimal point or the sign. The precision must be >= 0. If it is undef or the empty string ("), then it is set to 0. scale - Accesses the Scale of the Number ---------------------------------------- eval { ### set the scale ### $number->scale($new_scale); ### get the scale ### $scale = $number->scale(); }; croak "Exception caught: $@" if $@; Sets the scale of the number and/or returns it. This method throws Perl execeptions so use it with an eval block. Parameters: $scale The number of digits after the decimal point. The scale must be >= 0. If it is undef or the empty string ("), then it is set to 0. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/DataType/Char: Persistent/DataType/Char,, *Note Persistent/DataType/DateTime: Persistent/DataType/DateTime,, *Note Persistent/DataType/String: Persistent/DataType/String,, *Note Persistent/DataType/VarChar: Persistent/DataType/VarChar, BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Persistent/DataType/String, Next: Persistent/DataType/VarChar, Prev: Persistent/DataType/Number, Up: Module List A Character String Class ************************ NAME ==== Persistent::DataType::String - A Character String Class SYNOPSIS ======== use Persistent::DataType::String; use English; eval { ### in case an exception is thrown ### ### allocate a string ### my $string = new Persistent::DataType::String($value, $max_length); ### get/set value of string ### $value = $string->value($new_value); ### get length of string ### my $length = $string->length(); ### get/set maximum length of string ### my $max = $string->max_length($new_max); ### returns 'eq' for strings ### my $cmp_op = $string->get_compare_op(); }; if ($EVAL_ERROR) { ### catch those exceptions! ### print "An error occurred: $EVAL_ERROR\n"; } ABSTRACT ======== This is a character string class used by the Persistent framework of classes to implement the attributes of objects. This class provides methods for accessing the value, length, maximum length, and comparison operator of a character string. This class is usually not invoked directly, at least not when used with the Persistent framework of classes. However, the constructor arguments of this class are usually of interest when defining the attributes of a Persistent object since the *add_attribute* method of the Persistent classes instantiates this class directly. Also, the arguments to the value method are of interest when dealing with the accessor methods of the Persistent classes since the accessor methods pass their arguments to the value method and return the string value from the value method. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= Constructor - Creates the String Object --------------------------------------- eval { my $string = new Persistent::DataType::String($value, $max_length); }; croak "Exception caught: $@" if $@; Initializes a character string object. This method throws Perl execeptions so use it with an eval block. Parameters: $value Actual value of the string. This argument is optional and may be set to undef. $max_length Maximum length of the string value. This argument is optional and will be initialized to an unlimitied length (0) as a default. value - Accesses the Value of the String ---------------------------------------- eval { ### set the value ### $string->value($value); ### get the value ### $value = $string->value(); }; croak "Exception caught: $@" if $@; Sets the value of the string and/or returns the value. This method throws Perl execeptions so use it with an eval block. Parameters: $value Actual value of the string. This argument is optional and may be set to undef. get_compare_op - Returns the Comparison Operator ------------------------------------------------ $cmp_op = $string->get_compare_op(); Returns the comparison operator for the String class which is 'cmp'. This method does not throw execeptions. Parameters: None length - Returns the Length of the String ----------------------------------------- eval { $value = $string->length(); }; croak "Exception caught: $@" if $@; Returns the length of the string. This method throws Perl execeptions so use it with an eval block. Parameters: None max_length - Accesses the Maximum Length of the String ------------------------------------------------------ eval { ### set the maximum length ### $string->max_length($new_max); ### get the maximum length ### $max_length = $string->max_length(); }; croak "Exception caught: $@" if $@; Sets the maximum length of the string and/or returns it. This method throws Perl execeptions so use it with an eval block. Parameters: $max_length Maximum length of the string value. If the maximum length is set to undef, the empty string ("), or 0, then the string has an unlimited maximum length. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/DataType/Char: Persistent/DataType/Char,, *Note Persistent/DataType/DateTime: Persistent/DataType/DateTime,, *Note Persistent/DataType/Number: Persistent/DataType/Number,, *Note Persistent/DataType/VarChar: Persistent/DataType/VarChar, BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Persistent/DataType/VarChar, Next: Persistent/File, Prev: Persistent/DataType/String, Up: Module List A Variable Length Character String Class **************************************** NAME ==== Persistent::DataType::VarChar - A Variable Length Character String Class SYNOPSIS ======== use Persistent::DataType::VarChar; use English; eval { ### in case an exception is thrown ### ### allocate a string ### my $string = new Persistent::DataType::VarChar($value, $max_length); ### get/set value of string ### $value = $string->value($new_value); ### get length of string ### my $length = $string->length(); ### get/set maximum length of string ### my $max = $string->max_length($new_max); ### returns 'eq' for strings ### my $cmp_op = $string->get_compare_op(); }; if ($EVAL_ERROR) { ### catch those exceptions! ### print "An error occurred: $EVAL_ERROR\n"; } ABSTRACT ======== This is a variable length character string class used by the Persistent framework of classes to implement the attributes of objects. This class provides methods for accessing the value, length, maximum length, and comparison operator of a variable length character string. A variable length string (VarChar) always has a finite maximum length that can not be exceeded. This is different from a character string (String) which can have an unlimited maximum length. This class is usually not invoked directly, at least not when used with the Persistent framework of classes. However, the constructor arguments of this class are usually of interest when defining the attributes of a Persistent object since the *add_attribute* method of the Persistent classes instantiates this class directly. Also, the arguments to the value method are of interest when dealing with the accessor methods of the Persistent classes since the accessor methods pass their arguments to the value method and return the string value from the value method. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= Constructor - Creates the VarChar Object ---------------------------------------- eval { my $string = new Persistent::DataType::VarChar($value, $max_length); }; croak "Exception caught: $@" if $@; Initializes a variable length character string object. This method throws Perl execeptions so use it with an eval block. Parameters: $value Actual value of the string. This argument is optional and may be set to undef. $max_length Maximum length of the string value. This argument is optional and will be initialized to the length of the $value as a default or 1 if no $value argument is passed. max_length - Accesses the Maximum Length of the String ------------------------------------------------------ eval { ### set the maximum length ### $string->max_length($new_max); ### get the maximum length ### $max_length = $string->max_length(); }; croak "Exception caught: $@" if $@; Sets the maximum length of the string and/or returns it. This method throws Perl execeptions so use it with an eval block. Parameters: $max_length Maximum length of the string value. The maximum length must be greater than zero, otherwise, an exception is thrown. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/DataType/Char: Persistent/DataType/Char,, *Note Persistent/DataType/DateTime: Persistent/DataType/DateTime,, *Note Persistent/DataType/Number: Persistent/DataType/Number,, *Note Persistent/DataType/String: Persistent/DataType/String, BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.