Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IO::YAML(3)	      User Contributed Perl Documentation	   IO::YAML(3)

NAME
       IO::YAML	- read and write YAML streams incrementally

SYNOPSIS
	   use IO::YAML;

	   $io = IO::YAML->new($path_or_filehandle);
	   $io = IO::YAML->new(
	       'path'	   => '/path/to/a/file',
	       'auto_load' => $bool,
	   );
	   $io = IO::YAML->new(
	       'handle'	=> $fh,
	       'mode'	=> '>',	 # or 'w'; '<' or 'r'; '>>' or 'a'
	   );

	   $io = IO::YAML->new;
	   $io->open($path, '>')  or die $!;  #	Open a stream for writing
	   $io->open($path, '>>') or die $!;  #	Open a stream for appending

	   # Automatically add "...\n" at end of each document written
	   $io->auto_terminate(1);

	   print $io $mystring;
	   print $io @myvalues;
	   print $io \@myarray;
	   print $io \%myhash;
	   print $io $myobj;

	   $io = IO::YAML->new;
	   $io->open($path, '<')  or die $!;  #	Open a stream for reading
	   while (<$io>) {
	       $data = YAML::Load($_);
	   }

	   $io = IO::YAML->new;
	   $io->open($path) or die $!;	# Default mode is reading
	   $io->auto_load(1);
	   while (not $io->eof)	{
	       $data = <$io>;
	   }

	   $io = IO::YAML->new($path_or_handle);
	   $io->auto_load(1);
	   my @values =	<$io>;	# Roughly equivalent to	YAML::LoadFile(...)

DESCRIPTION
       IO::YAML	may be used to read and	write YAML streams one "document"
       (i.e., one value) at a time.

       A YAML stream is	a file consisting of a sequence	of YAML	documents,
       each of which may (optionally) be terminated by a line consisting
       solely of three periods ("...").

       The first line of each document must begin with the three-byte sequence
       "---".

       Here's a	simple YAML file consisting of three documents;	their values
       are the string 'foo', an	empty array, and a hash	with three elements:

	   --- #YAML:1.0 foo
	   --- #YAML:1.0 []
	   --- #YAML:1.0
	   title: Testing 1, 2,	3
	   author: nkuitse
	   date: 2004-03-05
	   ^D

       (Here, "^D" indicates the end of	the file.)

       In this next example, the stream	consists of a single YAML document
       whose value is "undef":

	   --- ~
	   ^D

       As this example shows, the first	line in	each document need not contain
       the full	YAML 1.0 header.

   Reading from	a YAML stream
       To read from a YAML stream, you may use the angle-brackets operator
       (e.g., <$fh>) or	the equivalent methods "getline" or "read".  Rather
       than reading a single line, this	will read an entire YAML document.

	   while(defined(my $yaml = <$io>)) {
	       my $value = YAML::Load($yaml);
	       ...
	   }

       The "YAML::Load"	step may be omitted by setting the IO::YAML object's
       "auto_load" property to a true value:

	   $io->auto_load(1);
	   while(defined(my $value = <$io>)) {
	       ...
	   }

       However,	this example is	complicated by the fact	that the value of a
       YAML document may be undef; the loop as written will terminate when the
       end of the stream is reached or when an undef value is read.

       To avoid	this problem while still taking	advantage of the "auto_load"
       property, use "$io->eof"	to test	for the	end of the stream:

	   $io->auto_load(1);
	   while(not $io->eof) {
	       my $value = <$io>;
	       ...
	   }

       IO::YAML	properly recognizes the	document terminator ("...").  Some
       versions	of YAML	do not recognize it, however; in order to prevent
       problems	when reading YAML streams with auto-loading off, IO::YAML
       strips the document terminator line if it is present.

   Writing to a	YAML stream
       To print	to a YAML stream, call "print" just as you would with a
       regular file handle; the	value(s) you're	printing will be converted to
       YAML format before being	written:

	   $io = IO::YAML->new;
	   $io->open('>file') or die "Couldn't open 'file'";
	   print $io $anything;

       You can `print' anything	that YAML is capable of	serializing; an
       exception will be raised	if you attempt to print	something that can't
       be serialized (e.g., a reference	to a subroutine).

       The complication	with undef values that affects the reading of a	YAML
       stream is not an	issue when writing to a	YAML stream.

   Terminating YAML documents
       Documents in a YAML stream may be terminated by a line consisting
       solely of the string "...".  You	can use	the "terminate"	method to add
       an explicit document terminator to a YAML stream	that you have open for
       writing (or appending):

	   $io = IO::YAML->new($file_or_handle,	'>');

	   foreach my $value (@data_values) {
	       print $io $value;
	       $io->terminate;
	   }

       It's generally safer to have YAML documents terminated automatically:

	   # 1.	Set auto_terminate to a	true value
	   #	a) When	creating the object
	   $io = IO::YAML->new(
	       'handle'	=> $fh,
	       'mode' => '>>',
	       'auto_terminate'	=> 1,
	   );
	   # or	b) At any point	thereafter
	   $io = IO::YAML->new(...);
	   $io->auto_terminate(1);

	   # 2.	Documents are now auto-terminated
	   foreach my $value (@data_values) {
	       print $io $value;
	       # $io->terminate	called implicitly
	   }

       Note that it's not the YAML stream that's terminated; it's the YAML
       document	that was previously written.

   Low-level access
       Sometimes it is helpful to be able to access a YAML stream at a lower
       level.  For example, you	may wish to read and write a file consisting
       of a YAML document (here, serving as a header of	sorts) followed	by
       arbitrary text.	The "handle" method may	be used	to obtain the
       underlying file handle so that it can be	used for this low-level
       access:

	   # Read header + body
	   $io->auto_load(1);
	   $header = <$io>;
	   $fh = $io->handle;
	   while (<$fh>) {
	       # Process each line after the YAML document
	   }

	   # Write header + body
	   $io->auto_terminate(1);
	   print $io $header;
	   $fh = $io->handle;
	   for (@other_stuff_to_write) {
	       print $fh $_;
	   }

METHODS
       new
	       $io = IO::YAML->new;

	       # Concise forms
	       $io = IO::YAML->new("$file");	 # Default is read-only
	       $io = IO::YAML->new("<$file");	 # Read-only made explicit
	       $io = IO::YAML->new(">$file");	 # Read-write (empty header & body)
	       $io = IO::YAML->new($file, '<');	 # Or '>', '+<', 'r', etc.
	       $io = IO::YAML->new(\*STDIN);
	       $io = IO::YAML->new(\*STDOUT, '>');
	       $io = IO::YAML->new($anything_that_isa_GLOB);

	       # Full-fledged forms
	       $io = IO::YAML->new(
		   'path' => $file,	   # File will be opened read-only
		   'auto_load' => 1,	   # Default is	0
	       );
	       $io = IO::YAML->new(
		   'path' => $file,	   # File will be opened or created
		   'mode' => '>',	   # Default is	'<'; '>>' is also allowed
	       );

	   Instantiate an IO::YAML object.  An exception is thrown if anything
	   goes	wrong.

	   If a	path is	specified, the file at that path will be opened.
	   Otherwise, you'll have to open it yourself using the	"open()"
	   method.

	   If a	path has been specified	and the	file doesn't already exist, it
	   will	be created -- but only if you've specified a mode that permits
	   writing; if you haven't, an exception will be thrown.

	   The following arguments may be specified in the constructor:

	   path
	       Path to a file to create	(if it doesn't already exist) and
	       open.

	   mode
	       Read/write/append mode for the new file.	 This must be
	       specified in one	of the following forms:

	       <
	       >
	       >>
	       r
	       w
	       a   Modes that allow for	both reading and writing are not
		   allowed, since YAML documents are variable in size.

	       NOTE: Numeric modes are not yet implemented.

	   auto_load
	       Indicates whether YAML document values should be	auto-loaded
	       after being read	(see above).  The default is not to auto-load
	       values.

	   auto_terminate
	       Indicates whether YAML documents	should be auto-terminated when
	       they are	written	(see above).  The default is not to auto-
	       terminate documents.

       open
	       $io = IO::YAML->new;
	       $io->open("<$file") or die $!;
	       $io->open($file,	$mode) or die $!;

	   Open	a file with the	specified name and mode.  You must use this
	   method if the instance was created without a	"path" element (and
	   one has not been assigned using the "path()"	method).

	   Upon	failure, sets $! to a meaningful message and returns a false
	   value.

	   The possible	modes are as described for new.

	   The "open()"	method may be called repeatedly	on the same instance,
	   without having to close it.

       close
	       $io->close or die $!;

	   Close the filehandle.

       print
	       $io->print($data) or die	$!;

       getline
       getlines
       seek
	       $io->seek($pos, $whence);

	   Set the IO::YAML file handle's position in bytes within the YAML
	   stream.  This will fail unless it moves the position	to the
	   beginning of	a YAML document	or the end of the whole	file handle.

       tell
	       $pos = $io->tell;

	   Return the the IO::YAML file	handle's position in bytes.

       truncate
	       $io->truncate(0);
	       $io->truncate($io->tell);

	   Truncates the IO::YAML file to the specified	length.	 As
	   illustrated here, this must be either 0 or equal to the
	   filehandle's	current	position.

       eof
	       if ($io->eof) { ... }

	   Return 1 if the IO::YAML filehandle is at the end of	the YAML
	   stream.

BUGS
       Autoflush might not be working.

       Seeking to the first position beyond the	end of the YAML	stream should
       be possible but doesn't currently work.

TO DO
       Normalize modes passed in the constructor.

       Implement numeric modes.

       Add tests for seek and tell methods.

       Enable seeking to the first byte	beyond the end of the YAML stream.

       Figure out how to allow read-write access and truncate().

SEE ALSO
       YAML

AUTHOR
       Paul Hoffman (nkuitse AT	cpan DOT org)

COPYRIGHT
       Copyright 2004-2007, 2009 Paul M. Hoffman.

       This is free software, and is made available under the same terms as
       Perl itself.

perl v5.32.0			  2020-08-10			   IO::YAML(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | BUGS | TO DO | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::YAML&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help