home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / Kubuntu 8.10 / kubuntu-8.10-desktop-i386.iso / casper / filesystem.squashfs / usr / share / perl5 / Mail / Field.pod < prev    next >
Encoding:
Text File  |  2008-04-14  |  4.9 KB  |  215 lines
  1. =head1 NAME
  2.  
  3. Mail::Field - Base class for manipulation of mail header fields
  4.  
  5. =head1 INHERITANCE
  6.  
  7.  Mail::Field is extended by
  8.    Mail::Field::AddrList
  9.    Mail::Field::Date
  10.    Mail::Field::Generic
  11.  
  12. =head1 SYNOPSIS
  13.  
  14.  use Mail::Field;
  15.     
  16.  my $field = Mail::Field->new('Subject', 'some subject text');
  17.  my $field = Mail::Field->new(Subject => 'some subject text');
  18.  print $field->tag,": ",$field->stringify,"\n";
  19.  
  20.  my $field = Mail::Field->subject('some subject text');
  21.  
  22. =head1 DESCRIPTION
  23.  
  24. C<Mail::Field> creates and manipulates fields in MIME headers, collected
  25. within a L<Mail::Header|Mail::Header> object.  Different field types have their
  26. own sub-class (extension), defining additional useful accessors to the
  27. field content.
  28.  
  29. People are invited to merge their implementation to special fields into
  30. MailTools, to maintain a consistent set of packages and documentation.
  31.  
  32. =head1 METHODS
  33.  
  34. =head2 Constructors
  35.  
  36. Mail::Field (and it's sub-classes) define several methods which return
  37. new objects. These can all be categorized as constructor.
  38.  
  39. Mail::Field-E<gt>B<combine>(FIELDS)
  40.  
  41. =over 4
  42.  
  43. Take a LIST of C<Mail::Field> objects (which should all be of the same
  44. sub-class) and create a new object in that same class.
  45.  
  46. =back
  47.  
  48. Mail::Field-E<gt>B<extract>(TAG, HEAD [, INDEX ])
  49.  
  50. =over 4
  51.  
  52. Takes as arguments the tag name, a C<Mail::Head> object
  53. and optionally an index.
  54.  
  55. If the index argument is given then C<extract> will retrieve the given tag
  56. from the C<Mail::Head> object and create a new C<Mail::Field> based object.
  57. I<undef> will be returned in the field does not exist.
  58.  
  59. If the index argument is not given the the result depends on the context
  60. in which C<extract> is called. If called in a scalar context the result
  61. will be as if C<extract> was called with an index value of zero. If called
  62. in an array context then all tags will be retrieved and a list of
  63. C<Mail::Field> objects will be returned.
  64.  
  65. =back
  66.  
  67. Mail::Field-E<gt>B<new>(TAG [, STRING | OPTIONS])
  68.  
  69. =over 4
  70.  
  71. Create an object in the class which defines the field specified by
  72. the TAG argument.
  73.  
  74. =back
  75.  
  76. =head2 "Fake" constructors
  77.  
  78. $obj-E<gt>B<create>(OPTIONS)
  79.  
  80. =over 4
  81.  
  82. This constructor is used internally with preprocessed field information.
  83. When called on an existing object, its original content will get
  84. replaced.
  85.  
  86. =back
  87.  
  88. $obj-E<gt>B<parse>
  89.  
  90. =over 4
  91.  
  92. Parse a field line.
  93.  
  94. =back
  95.  
  96. =head2 Accessors
  97.  
  98. $obj-E<gt>B<set>(OPTIONS)
  99.  
  100. =over 4
  101.  
  102. Change the settings (the content, but then smart) of this field.
  103.  
  104. =back
  105.  
  106. $obj-E<gt>B<stringify>
  107.  
  108. =over 4
  109.  
  110. Returns the field as a string.
  111.  
  112. =back
  113.  
  114. $obj-E<gt>B<tag>
  115.  
  116. Mail::Field-E<gt>B<tag>
  117.  
  118. =over 4
  119.  
  120. Return the tag (in the correct case) for this item.  Well, actually any
  121. casing is OK, because the field tags are treated case-insentitive; however
  122. people have some preferences.
  123.  
  124. =back
  125.  
  126. =head2 Smart accessors
  127.  
  128. $obj-E<gt>B<text>([STRING])
  129.  
  130. =over 4
  131.  
  132. Without arguments, the field is returned as L<stringify()|Mail::Field/"Accessors"> does.  Otherwise,
  133. the STRING is parsed with L<parse()|Mail::Field/""Fake" constructors"> to replace the object's content.
  134.  
  135. It is more clear to call either L<stringify()|Mail::Field/"Accessors"> or L<parse()|Mail::Field/""Fake" constructors"> directly, because
  136. this method does not add additional processing.
  137.  
  138. =back
  139.  
  140. =head1 DETAILS
  141.  
  142. =head2 SUB-CLASS PACKAGE NAMES
  143.  
  144. All sub-classes should be called Mail::Field::I<name> where I<name> is
  145. derived from the tag using these rules.
  146.  
  147. =over 4
  148.  
  149. =item *
  150.  
  151. Consider a tag as being made up of elements separated by '-'
  152.  
  153. =item *
  154.  
  155. Convert all characters to lowercase except the first in each element, which
  156. should be uppercase.
  157.  
  158. =item *
  159.  
  160. I<name> is then created from these elements by using the first
  161. N characters from each element.
  162.  
  163. =item *
  164.  
  165. N is calculated by using the formula :-
  166.  
  167.     int((7 + #elements) / #elements)
  168.  
  169. =item *
  170.  
  171. I<name> is then limited to a maximum of 8 characters, keeping the first 8
  172. characters.
  173.  
  174. =back
  175.  
  176. For an example of this take a look at the definition of the 
  177. C<_header_pkg_name()> subroutine in C<Mail::Field>
  178.  
  179. =head1 DIAGNOSTICS
  180.  
  181. Error: Undefined subroutine <method> called
  182.  
  183. =over 4
  184.  
  185. Mail::Field objects use autoloading to compile new functionality.
  186. Apparently, the mehod called is not implemented for the specific
  187. class of the field object.
  188.  
  189. =back
  190.  
  191. =head1 SEE ALSO
  192.  
  193. This module is part of the MailTools distribution,
  194. F<http://perl.overmeer.net/mailtools/>.
  195.  
  196. =head1 AUTHORS
  197.  
  198. The MailTools bundle was developed by Graham Barr.  Later, Mark
  199. Overmeer took over maintenance without development.
  200.  
  201. Mail::Cap by Gisle Aas E<lt>aas@oslonett.noE<gt>.
  202. Mail::Field::AddrList by Peter Orbaek E<lt>poe@cit.dkE<gt>.
  203. Mail::Mailer and Mail::Send by Tim Bunce E<lt>Tim.Bunce@ig.co.ukE<gt>.
  204. For other contributors see ChangeLog.
  205.  
  206. =head1 LICENSE
  207.  
  208. Copyrights 1995-2000 Graham Barr E<lt>gbarr@pobox.comE<gt> and
  209. 2001-2007 Mark Overmeer E<lt>perl@overmeer.netE<gt>.
  210.  
  211. This program is free software; you can redistribute it and/or modify it
  212. under the same terms as Perl itself.
  213. See F<http://www.perl.com/perl/misc/Artistic.html>
  214.  
  215.