chagenbu Sat Mar 3 14:36:42 2001 EDT
Modified files:
/php4/pear/Mail RFC822.php
Log:
documentation/whitespace
Index: php4/pear/Mail/RFC822.php
diff -u php4/pear/Mail/RFC822.php:1.4 php4/pear/Mail/RFC822.php:1.5
--- php4/pear/Mail/RFC822.php:1.4 Sat Mar 3 14:06:42 2001
+++ php4/pear/Mail/RFC822.php Sat Mar 3 14:36:42 2001
@@ -22,20 +22,70 @@
*
* @author Richard Heyes <[EMAIL PROTECTED]>
* @author Chuck Hagenbuch <[EMAIL PROTECTED]>
- * @version $Revision: 1.4 $
+ * @version $Revision: 1.5 $
*/
class Mail_RFC822 {
- // Properties (All private)
- var $address = null;
- var $default_host = 'localhost';
+ /**
+ * The address being parsed by the RFC822 object.
+ * @var string $address
+ */
+ var $address = '';
+
+ /**
+ * The default domain to use for unqualified addresses.
+ * @var string $default_domain
+ */
+ var $default_domain = 'localhost';
+
+ /**
+ * Should we return a nested array showing groups, or flatten everything?
+ * @var boolean $nestGroups
+ */
var $nestGroups = true;
+
+ /**
+ * Whether or not to validate atoms for non-ascii characters.
+ * @var boolean $validate
+ */
var $validate = true;
+
+ /**
+ * The array of raw addresses built up as we parse.
+ * @var array $addresses
+ */
var $addresses = array();
+
+ /**
+ * The final array of parsed address information that we build up.
+ * @var array $structure
+ */
var $structure = array();
+
+ /**
+ * The current error message, if any.
+ * @var string $error
+ */
var $error = null;
+
+ /**
+ * An internal counter/pointer.
+ * @var integer $index
+ */
var $index = null;
+
+ /**
+ * The number of groups that have been found in the address list.
+ * @var integer $num_groups
+ * @access public
+ */
var $num_groups = 0;
+
+ /**
+ * A variable so that we can tell whether or not we're inside a
+ * Mail_RFC822 object.
+ * @var boolean $mailRFC822
+ */
var $mailRFC822 = true;
@@ -45,16 +95,18 @@
*
* @access public
* @param $address The address(es) to validate.
- * @param $default_host (Optional) Default domain/host etc. If not supplied,
will be set to localhost.
+ * @param $default_domain (Optional) Default domain/host etc. If not supplied,
+will be set to localhost.
* @param $nest_groups (Optional) Whether to return the structure with groups
nested for easier viewing.
* @param $validate (Optional) Whether to validate atoms. Turn this off if
you need to run addresses through before encoding the personal names, for instance.
+ *
+ * @return object Mail_RFC822 A new Mail_RFC822 object.
*/
- function Mail_RFC822($address = null, $default_host = null, $nest_groups = null,
$validate = null)
+ function Mail_RFC822($address = null, $default_domain = null, $nest_groups =
+null, $validate = null)
{
- if (isset($address)) $this->address = $address;
- if (isset($default_host)) $this->default_host = $default_host;
- if (isset($nest_groups)) $this->nestGroups = $nest_groups;
- if (isset($validate)) $this->validate = $validate;
+ if (isset($address)) $this->address = $address;
+ if (isset($default_domain)) $this->default_domain = $default_domain;
+ if (isset($nest_groups)) $this->nestGroups = $nest_groups;
+ if (isset($validate)) $this->validate = $validate;
}
@@ -64,21 +116,23 @@
*
* @access public
* @param $address The address(es) to validate.
- * @param $default_host (Optional) Default domain/host etc.
+ * @param $default_domain (Optional) Default domain/host etc.
* @param $nest_groups (Optional) Whether to return the structure with groups
nested for easier viewing.
* @param $validate (Optional) Whether to validate atoms. Turn this off if
you need to run addresses through before encoding the personal names, for instance.
+ *
+ * @return array A structured array of addresses.
*/
- function parseAddressList($address = null, $default_host = null, $nest_groups =
null, $validate = null)
+ function parseAddressList($address = null, $default_domain = null, $nest_groups =
+null, $validate = null)
{
if (!isset($this->mailRFC822)) {
- $obj = new Mail_RFC822($address, $default_host, $nest_groups, $validate);
+ $obj = new Mail_RFC822($address, $default_domain, $nest_groups,
+$validate);
return $obj->parseAddressList();
}
- if (isset($address)) $this->address = $address;
- if (isset($default_host)) $this->default_host = $default_host;
- if (isset($nest_groups)) $this->nestGroups = $nest_groups;
- if (isset($validate)) $this->validate = $validate;
+ if (isset($address)) $this->address = $address;
+ if (isset($default_domain)) $this->default_domain = $default_domain;
+ if (isset($nest_groups)) $this->nestGroups = $nest_groups;
+ if (isset($validate)) $this->validate = $validate;
$this->structure = array();
$this->addresses = array();
@@ -110,6 +164,7 @@
*
* @access private
* @param $address The addresses to split.
+ * @return boolean Success or failure.
*/
function splitAddresses($address = '')
{
@@ -182,6 +237,7 @@
*
* @access private
* @param $address The address to check.
+ * @return boolean Whether or not there is a group at the start of the string.
*/
function isGroup($address)
{
@@ -206,6 +262,7 @@
* @access private
* @param $parts The exloded string.
* @param $char The char that was exploded on.
+ * @return mixed False if the string contains unclosed quotes/brackets, or the
+string on success.
*/
function splitCheck($parts, $char)
{
@@ -236,6 +293,7 @@
*
* @access private
* @param $string The string to check.
+ * @return boolean True if there are unclosed quotes inside the string, false
+otherwise.
*/
function hasUnclosedQuotes($string)
{
@@ -256,6 +314,7 @@
* @access private
* @param $string The string to check.
* @param $chars The characters to check for.
+ * @return boolean True if there are unclosed brackets inside the string, false
+otherwise.
*/
function hasUnclosedBrackets($string, $chars)
{
@@ -280,6 +339,7 @@
* @param $string The string to check.
* @param $num The number of occurences.
* @param $char The character to count.
+ * @return integer The number of occurences of $char in $string, adjusted for
+backslashes.
*/
function hasUnclosedBracketsSub($string, &$num, $char)
{
@@ -299,6 +359,7 @@
*
* @access private
* @param $address The address to validate.
+ * @return mixed False on failure, or a structured array of address information
+on success.
*/
function validateAddress($address)
{
@@ -384,6 +445,7 @@
*
* @access private
* @param $phrase The phrase to check.
+ * @return boolean Success or failure.
*/
function validatePhrase($phrase)
{
@@ -423,28 +485,29 @@
*
* @access private
* @param $atom The string to check.
+ * @return boolean Success or failure.
*/
function validateAtom($atom)
{
- if (!$this->validate) {
- // Validation has been turned off; assume the atom is okay.
- return true;
- }
-
+ if (!$this->validate) {
+ // Validation has been turned off; assume the atom is okay.
+ return true;
+ }
+
// Check for any char from ASCII 0 - ASCII 127
if (!preg_match('/^[\\x00-\\x7E]+$/i', $atom, $matches)) {
return false;
- }
+ }
// Check for specials:
if (preg_match('/[][()<>@,;\\:". ]/', $atom)) {
return false;
- }
+ }
// Check for control characters (ASCII 0-31):
if (preg_match('/[\\x00-\\x1F]+/', $atom)) {
return false;
- }
+ }
return true;
}
@@ -454,7 +517,8 @@
* quoted-string = <"> *(qtext/quoted-pair) <">
*
* @access private
- * @param $qstring The string to check.
+ * @param $qstring The string to check
+ * @return boolean Success or failure.
*/
function validateQuotedString($qstring)
{
@@ -472,6 +536,7 @@
*
* @access private
* @param $mailbox The string to check.
+ * @return boolean Success or failure.
*/
function validateMailbox(&$mailbox)
{
@@ -515,6 +580,7 @@
}
$mailbox = $mbox;
+ return true;
}
/**
@@ -526,6 +592,7 @@
*
* @access private
* @param $route_addr The string to check.
+ * @return mixed False on failure, or an array containing validated address/route
+information on success.
*/
function validateRouteAddr($route_addr)
{
@@ -575,6 +642,7 @@
*
* @access private
* @param $route The string to check.
+ * @return mixed False on failure, or the validated $route on success.
*/
function validateRoute($route)
{
@@ -597,6 +665,7 @@
*
* @access private
* @param $domain The string to check.
+ * @return mixed False on failure, or the validated domain on success.
*/
function validateDomain($domain)
{
@@ -624,6 +693,7 @@
*
* @access private
* @param $subdomain The string to check.
+ * @return boolean Success or failure.
*/
function validateSubdomain($subdomain)
{
@@ -643,6 +713,7 @@
*
* @access private
* @param $dliteral The string to check.
+ * @return boolean Success or failure.
*/
function validateDliteral($dliteral)
{
@@ -656,6 +727,7 @@
*
* @access private
* @param $addr_spec The string to check.
+ * @return mixed False on failure, or the validated addr-spec on success.
*/
function validateAddrSpec($addr_spec)
{
@@ -670,7 +742,7 @@
// No @ sign so assume the default domain.
} else {
$local_part = $addr_spec;
- $domain = $this->default_host;
+ $domain = $this->default_domain;
}
if (($local_part = $this->validateLocalPart($local_part)) === false) return
false;
@@ -686,6 +758,7 @@
*
* @access private
* @param $local_part
+ * @return mixed False on failure, or the validated local part on success.
*/
function validateLocalPart($local_part)
{
--
PHP CVS Mailing List (http://www.php.net/)
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
To contact the list administrators, e-mail: [EMAIL PROTECTED]
