/ 
File-URIList-v0.02
River stage zero No dependents
/ File::URIList

NAME

File::URIList - module for reading and writing RFC 2483 URI lists

VERSION

version v0.02

SYNOPSIS

use File::URIList;

This module implements an interface to URI lists as defined by RFC 2483.

All methods in this module die on error unless documented otherwise.

This module inherit from Data::Identifier::Interface::Userdata.

METHODS

new

my File::URIList $list = File::URIList->new($handle [, %opts ] );
# or:
my File::URIList $list = File::URIList->new($filename [, %opts ] );

Creates a new instance of a list object.

The possible access (read or write) depends on the mode $handle was opened as. If a filename (not a ref) is given, the file is opened for reading.

Note: The handle is automatically set to binary mode. See "binmode" in perlfunc for details.

The following options are supported:

blank_lines

Defines how blank lines are handled. One of die (default, recommended; aborts parsing), skip (skips blank lines), undef (passes them as undef), or pass (pass them on to URI. This what RFC 2483 specifies, but often hides errors).

Applies to reading lists only.

extra_spaces

Defines how extra spaces (spaces at begin or end of lines) are handled.

One of die (default, recommended; aborts parsing), trim (removes extra spaces), or pass (pass them on to URI. This what RFC 2483 specifies, but often hides errors).

Applies to reading lists only.

no_scheme

Defines how URIs with no scheme are handled.

One of die (default, recommended; aborts parsing), pass (pass them on to URI. This what RFC 2483 specifies, but often hides errors).

Applies to reading lists only.

slash_as_local

Defines URIs that begin with as slash are handled.

If true the URIs are considerd local filenames (and parsed as such), if false (default) they are parsed as URIs.

Applies to reading lists only.

baseuri

Sets the base URI for all relative URIs in the list. If set all URIs are converted to absolute URIs. Must be an absolute URI or URI string.

Applies to reading lists only.

Note: It is undefined how this interacts with slash_as_local if slash_as_local is set true.

Note: This will disable the check as defined by no_scheme (acting like it was set to pass).

Note: This option is very helpful if one tries to parse M3U files.

write_comment

$list->write_comment($comment0, $comment1, ...);
# or:
$list->write_comment([$comment0, $comment1, ...]);

Writes zero or more comments to the file. Takes plain strings, or any object also supported by "write_list".

If the value is a plain string and contains new lines this method will create a multi-line comment.

write_list

$list->write_list($uri0, $uri1, ...);
# or:
$list->write_list([$uri0, $uri1, ...]);

Writes the given URIs to the list. This method can be called multiple times to add more URIs.

Currently URI, Data::Identifier, Data::Identifier::Cloudlet, Data::URIID::Base (including Data::URIID::Result), and File::URIList objects are supported. Other types might as well be supported. If a URI is a plain string it is automatically converted using "new" in URI.

read_to

$list->read_to(sub { ... } [, %opts ] );

Reads the list, running a given callback for every entry.

The callback is called with $list as first argument, and the URI as second argument.

The following, all optional, options are supported:

as

Tries to convert the resulting entries to the given type. This is implemented using "as" in Data::Identifier. See there for all supported values. At least URI (default) is supported, as well as Data::Identifier (if installed).

read_as_list

my $entries = $list->read_as_list( [ %opts ] );

Reads the list into memory and returns an array ref with the elements of the list.

The following, all optional, options are supported. In addition all options from "read_to" are supported.

list

Ignored for compatibility.

listas

Converts the returned list to the given type (if any). The default (undef) is to return an arrayref. If set to non-undef value "as" in Data::Identifier::Cloudlet is used to convert.

rewind

$list->rewind;

Rewinds the list. This can be used to re-read the list from the start or read a list after it has been written.

Note: This method requires the filehandle (or file) passed to "new" to be seekable. If seeks cannot be performed this method dies.

Note: If the list starts at some offset into the filehandle this method cannot be used.

Note: If you rewind and then write you may corrupt the list as this does not clear already existing data.

clear

$list->clear;

Clears the list. This will delete all entries from the list.

Note: All limitation of "rewind" apply. In addition the filehande (or file) passed to "new" also needs to support changes in size.

AUTHOR

Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2025 by Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)