bionic (3) Perl6::Say.3pm.gz

Provided by: libperl6-say-perl_0.16-1_all bug

NAME

       Perl6::Say - "print()", but no newline needed

SYNOPSIS

           # Perl 5 code...

           use Perl6::Say;

           say 'boo';             # same as:  print 'boo', "\n"

           say STDERR 'boo';      # same as:  print STDERR 'boo', "\n"

           STDERR->say('boo');    # same as:  print STDERR 'boo', \n"

           $fh->say('boo');       # same as:  print $fh 'boo', "\n";

           say();                 # same as:  print "$_\n";

           say undef;             # same as:  print "\n";

DESCRIPTION

   Note for Users of Perl 5.10
       You don't need this module.  The Perl 6 "say" function is available in Perl 5.10 by saying
       "use feature 'say';".  Hence, this module is of interest only to users of Perl 5.6 and
       5.8.

       If you have Perl 5.10 installed, see the 510/ directory in this distribution for some
       elementary examples of "say" taken from "perldoc feature".

   General
       Implements a close simulation of the "say" function in Perl 6, which acts like "print" but
       automatically appends a newline.

       Use it just like "print" (except that it only supports the indirect object syntax when the
       stream is a bareword). That is, assuming the relevant filehandles are open for output, you
       can use any of these:

           say @data;
           say FH @data;
           FH->say(@data);
           *FH->say(@data);
           (\*FH)->say(@data);
           say $fh, @data;
           $fh->say(@data);

       but not any of these:

           say {FH} @data;
           say {*FH} @data;
           say {\*FH} @data;
           say $fh @data;
           say {$fh} @data;

   Additional Permitted Usages
       As demonstrated in the test suite accompanying this distribution, "Perl6::Say::say()" can
       be used in all the following situations.

           $string = q{};
           open FH, ">", \$string;
           say FH qq{Hello World};            # print to a string
           close FH;                          # requires Perl 5.8.0 or later

           use FileHandle;
           $fh = FileHandle->new($file, 'w');
           if (defined $fh) {
               say $fh, qq{Hello World};
               $fh->close;
           }

           use IO::File;
           $fh = IO::File->new($file, 'w');
           if (defined $fh) {
               say $fh, qq{Hello World};
               $fh->close;
           }

           $string = q{};
           open FH, ">", \$string;             # requires Perl 5.8.0 or later
           select(FH);
           say qq{Hello World};
           close FH;

   Interaction with Output Record Separator
       In Perl 6, "say @stuff" is exactly equivalent to "Core::print @stuff, "\n"".

       That means that a call to "say" appends any output record separator (ORS) after the added
       newline (though in Perl 6, the ORS is an attribute of the filehandle being used, rather
       than a global $/ variable).

   "IO::Handle::say()"
       IO::Handle version 1.27 or later (which, confusingly, is found in IO distribution 1.23 and
       later) also implements a "say" method.   Perl6::Say provides its own "say" method to
       IO::Handle if "IO::Handle::say" is not available.

   Usage with Older Perls
       As noted above, some aspects of "Perl6::Say::say()" will not work with versions of Perl
       earlier than 5.8.0.  This is not due to any problem with this module; it is simply that
       Perl did not support printing to an in-memory file ("print \$string, "\n";") prior to that
       point.  (Thanks to a CPAN testers report from David Cantrell for identifying this
       limitation.)

WARNING

       The syntax and semantics of Perl 6 is still being finalized and consequently is at any
       time subject to change. That means the same caveat applies to this module.

DEPENDENCIES

       No dependencies other than on modules included with the Perl core as of version 5.8.0.

       Some of the files in the test suite accompanying this distribution use non-core CPAN
       module IO::Capture::Stdout.  Tests calling IO::Capture::Stdout methods are enclosed in
       "SKIP" blocks and so should pose no obstacle to installation of the distribution on
       systems lacking IO::Capture.  (However, the maintainer strongly recommends IO::Capture for
       developers who write a lot of test code.  So please consider installing it!)

AUTHOR and MAINTAINER

   AUTHOR
       Damian Conway (damian@conway.org).

   MAINTAINER
       Alexandr Ciornii (alexchorny@gmail.com)

ACKNOWLEDGMENTS

       Thanks to Damian Conway for dreaming this up.  Thanks to David A Golden for a close review
       of the documentation.  Thanks to CPAN tester Jost Krieger for reporting an error in my
       SKIP block count in one test file.

BUGS AND IRRITATIONS

       As far as we can determine, Perl 5 doesn't allow us to create a subroutine that truly acts
       like "print". That is, one that can simultaneously be used like so:

           say @data;

       and like so:

           say {$fh} @data;

       Comments, suggestions, and patches welcome.

       Copyright (c) 2004, Damian Conway. All Rights Reserved.  This module is free software. It
       may be used, redistributed and/or modified under the same terms as Perl itself.