diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlfaq9.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlfaq9.1 | 480 |
1 files changed, 480 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlfaq9.1 b/upstream/mageia-cauldron/man1/perlfaq9.1 new file mode 100644 index 00000000..799553d8 --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlfaq9.1 @@ -0,0 +1,480 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLFAQ9 1" +.TH PERLFAQ9 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlfaq9 \- Web, Email and Networking +.SH VERSION +.IX Header "VERSION" +version 5.20210520 +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This section deals with questions related to running web sites, +sending and receiving email as well as general networking. +.SS "Should I use a web framework?" +.IX Subsection "Should I use a web framework?" +Yes. If you are building a web site with any level of interactivity +(forms / users / databases), you +will want to use a framework to make handling requests +and responses easier. +.PP +If there is no interactivity then you may still want +to look at using something like Template Toolkit <https://metacpan.org/module/Template> +or Plack::Middleware::TemplateToolkit +so maintenance of your HTML files (and other assets) is easier. +.SS "Which web framework should I use?" +.IX Xref "framework CGI.pm CGI Catalyst Dancer" +.IX Subsection "Which web framework should I use?" +There is no simple answer to this question. Perl frameworks can run everything +from basic file servers and small scale intranets to massive multinational +multilingual websites that are the core to international businesses. +.PP +Below is a list of a few frameworks with comments which might help you in +making a decision, depending on your specific requirements. Start by reading +the docs, then ask questions on the relevant mailing list or IRC channel. +.IP Catalyst 4 +.IX Item "Catalyst" +Strongly object-oriented and fully-featured with a long development history and +a large community and addon ecosystem. It is excellent for large and complex +applications, where you have full control over the server. +.IP Dancer2 4 +.IX Item "Dancer2" +Free of legacy weight, providing a lightweight and easy to learn API. +Has a growing addon ecosystem. It is best used for smaller projects and +very easy to learn for beginners. +.IP Mojolicious 4 +.IX Item "Mojolicious" +Self-contained and powerful for both small and larger projects, +with a focus on HTML5 and real-time web technologies such as WebSockets. +.IP Web::Simple 4 +.IX Item "Web::Simple" +Strongly object-oriented and minimal, built for speed and intended +as a toolkit for building micro web apps, custom frameworks or for tieing +together existing Plack-compatible web applications with one central dispatcher. +.PP +All of these interact with or use Plack which is worth understanding +the basics of when building a website in Perl (there is a lot of useful +Plack::Middleware <https://metacpan.org/search?q=plack%3A%3Amiddleware>). +.SS "What is Plack and PSGI?" +.IX Subsection "What is Plack and PSGI?" +PSGI is the Perl Web Server Gateway Interface Specification, it is +a standard that many Perl web frameworks use, you should not need to +understand it to build a web site, the part you might want to use is Plack. +.PP +Plack is a set of tools for using the PSGI stack. It contains +middleware <https://metacpan.org/search?q=plack%3A%3Amiddleware> +components, a reference server and utilities for Web application frameworks. +Plack is like Ruby's Rack or Python's Paste for WSGI. +.PP +You could build a web site using Plack and your own code, +but for anything other than a very basic web site, using a web framework +(that uses <https://plackperl.org>) is a better option. +.SS "How do I remove HTML from a string?" +.IX Subsection "How do I remove HTML from a string?" +Use HTML::Strip, or HTML::FormatText which not only removes HTML +but also attempts to do a little simple formatting of the resulting +plain text. +.SS "How do I extract URLs?" +.IX Subsection "How do I extract URLs?" +HTML::SimpleLinkExtor will extract URLs from HTML, it handles anchors, +images, objects, frames, and many other tags that can contain a URL. +If you need anything more complex, you can create your own subclass of +HTML::LinkExtor or HTML::Parser. You might even use +HTML::SimpleLinkExtor as an example for something specifically +suited to your needs. +.PP +You can use URI::Find or URL::Search to extract URLs from an +arbitrary text document. +.SS "How do I fetch an HTML file?" +.IX Subsection "How do I fetch an HTML file?" +(contributed by brian d foy) +.PP +The core HTTP::Tiny module can fetch web resources and give their +content back to you as a string: +.PP +.Vb 1 +\& use HTTP::Tiny; +\& +\& my $ua = HTTP::Tiny\->new; +\& my $html = $ua\->get( "http://www.example.com/index.html" )\->{content}; +.Ve +.PP +It can also store the resource directly in a file: +.PP +.Vb 1 +\& $ua\->mirror( "http://www.example.com/index.html", "foo.html" ); +.Ve +.PP +If you need to do something more complicated, the HTTP::Tiny object can +be customized by setting attributes, or you can use LWP::UserAgent from +the libwww-perl distribution or Mojo::UserAgent from the Mojolicious +distribution to make common tasks easier. If you want to simulate an +interactive web browser, you can use the WWW::Mechanize module. +.SS "How do I automate an HTML form submission?" +.IX Subsection "How do I automate an HTML form submission?" +If you are doing something complex, such as moving through many pages +and forms or a web site, you can use WWW::Mechanize. See its +documentation for all the details. +.PP +If you're submitting values using the GET method, create a URL and encode +the form using the \f(CW\*(C`www_form_urlencode\*(C'\fR method from HTTP::Tiny: +.PP +.Vb 1 +\& use HTTP::Tiny; +\& +\& my $ua = HTTP::Tiny\->new; +\& +\& my $query = $ua\->www_form_urlencode([ q => \*(AqDB_File\*(Aq, lucky => 1 ]); +\& my $url = "https://metacpan.org/search?$query"; +\& my $content = $ua\->get($url)\->{content}; +.Ve +.PP +If you're using the POST method, the \f(CW\*(C`post_form\*(C'\fR method will encode the +content appropriately. +.PP +.Vb 1 +\& use HTTP::Tiny; +\& +\& my $ua = HTTP::Tiny\->new; +\& +\& my $url = \*(Aqhttps://metacpan.org/search\*(Aq; +\& my $form = [ q => \*(AqDB_File\*(Aq, lucky => 1 ]; +\& my $content = $ua\->post_form($url, $form)\->{content}; +.Ve +.SS "How do I decode or create those %\-encodings on the web?" +.IX Xref "URI URI::Escape RFC 2396" +.IX Subsection "How do I decode or create those %-encodings on the web?" +Most of the time you should not need to do this as +your web framework, or if you are making a request, +the LWP or other module would handle it for you. +.PP +To encode a string yourself, use the URI::Escape module. The \f(CW\*(C`uri_escape\*(C'\fR +function returns the escaped string: +.PP +.Vb 1 +\& my $original = "Colon : Hash # Percent %"; +\& +\& my $escaped = uri_escape( $original ); +\& +\& print "$escaped\en"; # \*(AqColon%20%3A%20Hash%20%23%20Percent%20%25\*(Aq +.Ve +.PP +To decode the string, use the \f(CW\*(C`uri_unescape\*(C'\fR function: +.PP +.Vb 1 +\& my $unescaped = uri_unescape( $escaped ); +\& +\& print $unescaped; # back to original +.Ve +.PP +Remember not to encode a full URI, you need to escape each +component separately and then join them together. +.SS "How do I redirect to another page?" +.IX Subsection "How do I redirect to another page?" +Most Perl Web Frameworks will have a mechanism for doing this, +using the Catalyst framework it would be: +.PP +.Vb 2 +\& $c\->res\->redirect($url); +\& $c\->detach(); +.Ve +.PP +If you are using Plack (which most frameworks do), then +Plack::Middleware::Rewrite is worth looking at if you +are migrating from Apache or have URL's you want to always +redirect. +.SS "How do I put a password on my web pages?" +.IX Subsection "How do I put a password on my web pages?" +See if the web framework you are using has an +authentication system and if that fits your needs. +.PP +Alternativly look at Plack::Middleware::Auth::Basic, +or one of the other Plack authentication <https://metacpan.org/search?q=plack+auth> +options. +.SS "How do I make sure users can't enter values into a form that causes my CGI script to do bad things?" +.IX Subsection "How do I make sure users can't enter values into a form that causes my CGI script to do bad things?" +(contributed by brian d foy) +.PP +You can't prevent people from sending your script bad data. Even if +you add some client-side checks, people may disable them or bypass +them completely. For instance, someone might use a module such as +LWP to submit to your web site. If you want to prevent data that +try to use SQL injection or other sorts of attacks (and you should +want to), you have to not trust any data that enter your program. +.PP +The perlsec documentation has general advice about data security. +If you are using the DBI module, use placeholder to fill in data. +If you are running external programs with \f(CW\*(C`system\*(C'\fR or \f(CW\*(C`exec\*(C'\fR, use +the list forms. There are many other precautions that you should take, +too many to list here, and most of them fall under the category of not +using any data that you don't intend to use. Trust no one. +.SS "How do I parse a mail header?" +.IX Subsection "How do I parse a mail header?" +Use the Email::MIME module. It's well-tested and supports all the +craziness that you'll see in the real world (comment-folding whitespace, +encodings, comments, etc.). +.PP +.Vb 1 +\& use Email::MIME; +\& +\& my $message = Email::MIME\->new($rfc2822); +\& my $subject = $message\->header(\*(AqSubject\*(Aq); +\& my $from = $message\->header(\*(AqFrom\*(Aq); +.Ve +.PP +If you've already got some other kind of email object, consider passing +it to Email::Abstract and then using its cast method to get an +Email::MIME object: +.PP +.Vb 2 +\& my $abstract = Email::Abstract\->new($mail_message_object); +\& my $email_mime_object = $abstract\->cast(\*(AqEmail::MIME\*(Aq); +.Ve +.SS "How do I check a valid mail address?" +.IX Subsection "How do I check a valid mail address?" +(partly contributed by Aaron Sherman) +.PP +This isn't as simple a question as it sounds. There are two parts: +.PP +a) How do I verify that an email address is correctly formatted? +.PP +b) How do I verify that an email address targets a valid recipient? +.PP +Without sending mail to the address and seeing whether there's a human +on the other end to answer you, you cannot fully answer part \fIb\fR, but +the Email::Valid module will do both part \fIa\fR and part \fIb\fR as far +as you can in real-time. +.PP +Our best advice for verifying a person's mail address is to have them +enter their address twice, just as you normally do to change a +password. This usually weeds out typos. If both versions match, send +mail to that address with a personal message. If you get the message +back and they've followed your directions, you can be reasonably +assured that it's real. +.PP +A related strategy that's less open to forgery is to give them a PIN +(personal ID number). Record the address and PIN (best that it be a +random one) for later processing. In the mail you send, include a link to +your site with the PIN included. If the mail bounces, you know it's not +valid. If they don't click on the link, either they forged the address or +(assuming they got the message) following through wasn't important so you +don't need to worry about it. +.SS "How do I decode a MIME/BASE64 string?" +.IX Subsection "How do I decode a MIME/BASE64 string?" +The MIME::Base64 package handles this as well as the MIME/QP encoding. +Decoding base 64 becomes as simple as: +.PP +.Vb 2 +\& use MIME::Base64; +\& my $decoded = decode_base64($encoded); +.Ve +.PP +The Email::MIME module can decode base 64\-encoded email message parts +transparently so the developer doesn't need to worry about it. +.SS "How do I find the user's mail address?" +.IX Subsection "How do I find the user's mail address?" +Ask them for it. There are so many email providers available that it's +unlikely the local system has any idea how to determine a user's email address. +.PP +The exception is for organization-specific email (e.g. foo@yourcompany.com) +where policy can be codified in your program. In that case, you could look at +\&\f(CW$ENV\fR{USER}, \f(CW$ENV\fR{LOGNAME}, and getpwuid($<) in scalar context, like so: +.PP +.Vb 1 +\& my $user_name = getpwuid($<) +.Ve +.PP +But you still cannot make assumptions about whether this is correct, unless +your policy says it is. You really are best off asking the user. +.SS "How do I send email?" +.IX Subsection "How do I send email?" +Use the Email::Stuffer module, like so: +.PP +.Vb 5 +\& # first, create your message +\& my $message = Email::Stuffer\->from(\*(Aqyou@example.com\*(Aq) +\& \->to(\*(Aqfriend@example.com\*(Aq) +\& \->subject(\*(AqHappy birthday!\*(Aq) +\& \->text_body("Happy birthday to you!\en"); +\& +\& $message\->send_or_die; +.Ve +.PP +By default, Email::Sender::Simple (the \f(CW\*(C`send\*(C'\fR and \f(CW\*(C`send_or_die\*(C'\fR methods +use this under the hood) will try \f(CW\*(C`sendmail\*(C'\fR first, if it exists +in your \f(CW$PATH\fR. This generally isn't the case. If there's a remote mail +server you use to send mail, consider investigating one of the Transport +classes. At time of writing, the available transports include: +.IP Email::Sender::Transport::Sendmail 4 +.IX Item "Email::Sender::Transport::Sendmail" +This is the default. If you can use the \fBmail\fR\|(1) or \fBmailx\fR\|(1) +program to send mail from the machine where your code runs, you should +be able to use this. +.IP Email::Sender::Transport::SMTP 4 +.IX Item "Email::Sender::Transport::SMTP" +This transport contacts a remote SMTP server over TCP. It optionally +uses TLS or SSL and can authenticate to the server via SASL. +.PP +Telling Email::Stuffer to use your transport is straightforward. +.PP +.Vb 1 +\& $message\->transport($email_sender_transport_object)\->send_or_die; +.Ve +.SS "How do I use MIME to make an attachment to a mail message?" +.IX Subsection "How do I use MIME to make an attachment to a mail message?" +Email::MIME directly supports multipart messages. Email::MIME +objects themselves are parts and can be attached to other Email::MIME +objects. Consult the Email::MIME documentation for more information, +including all of the supported methods and examples of their use. +.PP +Email::Stuffer uses Email::MIME under the hood to construct +messages, and wraps the most common attachment tasks with the simple +\&\f(CW\*(C`attach\*(C'\fR and \f(CW\*(C`attach_file\*(C'\fR methods. +.PP +.Vb 4 +\& Email::Stuffer\->to(\*(Aqfriend@example.com\*(Aq) +\& \->subject(\*(AqThe file\*(Aq) +\& \->attach_file(\*(Aqstuff.csv\*(Aq) +\& \->send_or_die; +.Ve +.SS "How do I read email?" +.IX Subsection "How do I read email?" +Use the Email::Folder module, like so: +.PP +.Vb 1 +\& use Email::Folder; +\& +\& my $folder = Email::Folder\->new(\*(Aq/path/to/email/folder\*(Aq); +\& while(my $message = $folder\->next_message) { +\& # next_message returns Email::Simple objects, but we want +\& # Email::MIME objects as they\*(Aqre more robust +\& my $mime = Email::MIME\->new($message\->as_string); +\& } +.Ve +.PP +There are different classes in the Email::Folder namespace for +supporting various mailbox types. Note that these modules are generally +rather limited and only support \fBreading\fR rather than writing. +.SS "How do I find out my hostname, domainname, or IP address?" +.IX Xref "hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa, gethostbyname, Socket, Net::Domain, Sys::Hostname" +.IX Subsection "How do I find out my hostname, domainname, or IP address?" +(contributed by brian d foy) +.PP +The Net::Domain module, which is part of the Standard Library starting +in Perl 5.7.3, can get you the fully qualified domain name (FQDN), the host +name, or the domain name. +.PP +.Vb 1 +\& use Net::Domain qw(hostname hostfqdn hostdomain); +\& +\& my $host = hostfqdn(); +.Ve +.PP +The Sys::Hostname module, part of the Standard Library, can also get the +hostname: +.PP +.Vb 1 +\& use Sys::Hostname; +\& +\& $host = hostname(); +.Ve +.PP +The Sys::Hostname::Long module takes a different approach and tries +harder to return the fully qualified hostname: +.PP +.Vb 1 +\& use Sys::Hostname::Long \*(Aqhostname_long\*(Aq; +\& +\& my $hostname = hostname_long(); +.Ve +.PP +To get the IP address, you can use the \f(CW\*(C`gethostbyname\*(C'\fR built-in function +to turn the name into a number. To turn that number into the dotted octet +form (a.b.c.d) that most people expect, use the \f(CW\*(C`inet_ntoa\*(C'\fR function +from the Socket module, which also comes with perl. +.PP +.Vb 1 +\& use Socket; +\& +\& my $address = inet_ntoa( +\& scalar gethostbyname( $host || \*(Aqlocalhost\*(Aq ) +\& ); +.Ve +.SS "How do I fetch/put an (S)FTP file?" +.IX Subsection "How do I fetch/put an (S)FTP file?" +Net::FTP, and Net::SFTP allow you to interact with FTP and SFTP (Secure +FTP) servers. +.SS "How can I do RPC in Perl?" +.IX Subsection "How can I do RPC in Perl?" +Use one of the RPC modules( <https://metacpan.org/search?q=RPC> ). +.SH "AUTHOR AND COPYRIGHT" +.IX Header "AUTHOR AND COPYRIGHT" +Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. +.PP +This documentation is free; you can redistribute it and/or modify it +under the same terms as Perl itself. +.PP +Irrespective of its distribution, all code examples in this file +are hereby placed into the public domain. You are permitted and +encouraged to use this code in your own programs for fun +or for profit as you see fit. A simple comment in the code giving +credit would be courteous but is not required. |