NAME
    IO::Barf - Barfing content to output file.

SYNOPSIS
     use IO::Barf qw(barf);

     barf($file_or_handler, 'CONTENT');

SUBROUTINES
  "barf"
     barf($file_or_handler, 'CONTENT');

    Barf content to file or handler.

    Returns undef.

ERRORS
     barf():
             Cannot open file '%s'.
             Cannot close file '%s'.
             Unsupported reference '%s'.

EXAMPLE1
     use strict;
     use warnings;

     use File::Temp;
     use IO::Barf;

     # Content.
     my $content = "foo\nbar\n";

     # Temporary file.
     my $temp_file = File::Temp->new->filename;

     # Barf out.
     barf($temp_file, $content);

     # Print tempory file.
     system "cat $temp_file";

     # Unlink temporary file.
     unlink $temp_file;

     # Output:
     # foo
     # bar

EXAMPLE2
     use strict;
     use warnings;

     use IO::Barf;

     # Content.
     my $content = "foo\nbar\n";

     # Barf out.
     barf(\*STDOUT, $content);

     # Output:
     # foo
     # bar

EXAMPLE3
     use strict;
     use warnings;

     use Benchmark qw(cmpthese);
     use IO::All;
     use IO::Any;
     use IO::Barf;
     use File::Raw qw(spew);
     use File::Slurp qw(write_file);
     use File::Temp;
     use Path::Tiny;

     # Temporary files.
     my $temp1 = File::Temp->new->filename;
     my $temp2 = File::Temp->new->filename;
     my $temp3 = File::Temp->new->filename;
     my $temp4 = File::Temp->new->filename;
     my $temp5 = File::Temp->new->filename;
     my $temp6 = File::Temp->new->filename;

     # Some data.
     my $data = 'x' x 1000;

     # Benchmark (10s).
     cmpthese(-10, {
             'File::Raw' => sub {
                     file_spew($temp1, $data);
                     unlink $temp1;
             },
             'File::Slurp' => sub {
                     write_file($temp2, $data);
                     unlink $temp2;
             },
             'IO::All' => sub {
                     $data > io($temp3);
                     unlink $temp3;
             },
             'IO::Any' => sub {
                     IO::Any->spew($temp4, $data);
                     unlink $temp4;
             },
             'IO::Barf' => sub {
                     barf($temp5, $data);
                     unlink $temp5;
             },
             'Path::Tiny' => sub {
                     path($temp6)->spew($data);
                     unlink $temp6;
             },
     });

     # Output like this:
     # X270, Intel(R) Core(TM) i5-6300U CPU @ 2.40GHz
     #                Rate Path::Tiny   IO::All  IO::Any File::Slurp IO::Barf File::Raw
     # Path::Tiny   5707/s         --      -27%     -36%        -71%     -75%      -84%
     # IO::All      7814/s        37%        --     -12%        -60%     -66%      -79%
     # IO::Any      8899/s        56%       14%       --        -54%     -61%      -76%
     # File::Slurp 19521/s       242%      150%     119%          --     -14%      -47%
     # IO::Barf    22735/s       298%      191%     155%         16%       --      -38%
     # File::Raw   36606/s       541%      368%     311%         88%      61%        --

EXAMPLE4
     use strict;
     use warnings;

     use Benchmark qw(cmpthese);
     use File::Temp;

     # Temporary files.
     my $temp1 = File::Temp->new->filename;
     my $temp2 = File::Temp->new->filename;
     my $temp3 = File::Temp->new->filename;
     my $temp4 = File::Temp->new->filename;
     my $temp5 = File::Temp->new->filename;

     # Some data.
     my $data = 'x' x 1000;

     # Benchmark (10s).
     cmpthese(-10, {
             'File::Raw' => sub {
                     require File::Raw;
                     File::Raw->import('spew') if ! defined &file_spew;
                     file_spew($temp1, $data);
                     unlink $temp1;
             },
             'File::Slurp' => sub {
                     require File::Slurp;
                     File::Slurp::write_file($temp2, $data);
                     unlink $temp2;
             },
             'IO::Any' => sub {
                     require IO::Any;
                     IO::Any->spew($temp3, $data);
                     unlink $temp3;
             },
             'IO::Barf' => sub {
                     require IO::Barf;
                     IO::Barf::barf($temp4, $data);
                     unlink $temp5;
             },
             'Path::Tiny' => sub {
                     require Path::Tiny;
                     Path::Tiny::path($temp5)->spew($data);
                     unlink $temp5;
             },
     });

     # Output like this:
     # X270, Intel(R) Core(TM) i5-6300U CPU @ 2.40GHz
     #                Rate  Path::Tiny     IO::Any    IO::Barf File::Slurp   File::Raw
     # Path::Tiny   5755/s          --        -37%        -66%        -70%        -84%
     # IO::Any      9204/s         60%          --        -46%        -52%        -74%
     # IO::Barf    16907/s        194%         84%          --        -12%        -53%
     # File::Slurp 19162/s        233%        108%         13%          --        -47%
     # File::Raw   35860/s        523%        290%        112%         87%          --

DEPENDENCIES
    Error::Pure, Exporter, Readonly, Scalar::Util.

SEE ALSO
    File::Raw
        Fast IO operations using direct system calls

    File::Slurp
        Simple and Efficient Reading/Writing/Modifying of Complete Files

    IO::Any
        open anything

    Perl6::Slurp
        Implements the Perl 6 'slurp' built-in

REPOSITORY
    <https://github.com/michal-josef-spacek/IO-Barf>

AUTHOR
    Michal Josef Špaček <mailto:skim@cpan.org>

    <http://skim.cz>

LICENSE AND COPYRIGHT
    © 2009-2026 Michal Josef Špaček

    BSD 2-Clause License

VERSION
    0.12