NAME

Net::API::CPAN::List - Meta CPAN API List

SYNOPSIS

    use Net::API::CPAN::List;
    my $list = Net::API::CPAN::List->new(
        items => $array_ref,
    ) || die( Net::API::CPAN::List->error, "\n" );
    # or
    my $list = Net::API::CPAN::List->new;
    $list->load_data( $hash_ref ) || die( $list->error );

VERSION

    v0.1.1

DESCRIPTION

This class is used to retrieve and manipulate list of data such as the ones resulting from a search query.

It inherits from Net::API::CPAN::Generic

CONSTRUCTOR

new

Provided with an hash or an hash reference of parameters and this will instantiate a new list object.

The valid parmeters that can be used are as below and can also be accessed with their corresponding method:

api

An Net::API::CPAN object.
items

An array reference of data.

METHODS

api_uri

Sets or gets the MetaCPAN API base URI, which defaults to https://fastapi.metacpan.org

This returns an URI object.

api_version

Sets or gets the MetaCPAN API version, which defaults to 1. This is used to form the base of the endpoints, such as /v1/author/search

It returns a scalar object

container

Sets or gets a string representing the property containing the array of all the data.

If this is not set, then "load_data" will try to guess it.

data

    $list->data( $hash_ref ) || die( $list->error );
    my $array_ref = $list->data;

This is a convenient shortcut that calls load_data when data is provided, and returns the call to items either way.

filter

Sets or gets the filter object. It returns undef in scalar context if none is set, but it instantiates automatically a new instance in object context.

    my $filter = $list->filter; # undef
    my $from = $list->filter->from; # ok, it works, but still undef

get

    # implicit
    my $obj = $list->get;
    # explicit
    my $obj = $list->get(0);
    # or
    my $obj = $list->get(2);

This returns the data object at the current offset, or at the provided offset if one was provided.

If no data object exists at the offset, this will return undef in scalar context, or an empty list in list context, and it will return a null object in object context to prevent a perl error of some methods called with an undefined value. The null object virtual method call will return undef eventually.

For example, let's assume a list of only 1 element. Calling get with offset 3 exceeds the size of the data pool, and would return an undef value, but since it is called in object context, it returns a null object instead.

    my $undef = $list->get(3)->author;

has_more

Read-only. This will return true if there are more data to be fetched from the MetaCPAN API, or false otherwise.

http_request

Sets or gets an HTTP::Promise::Request object.

http_response

Sets or gets an HTTP::Promise::Response object.

items

Provided with an array reference and an hash or hash reference of options and this sets the provided array as the active pool of data.

The data contained can be either an array reference of hash reference, or an array reference of objects. If the data provided are an array reference of hash reference, they will be turned into their corresponding object, based on the value of each hash _type property, such as _type => "author"

It always return an array object, whether any data were provided or not.

load

Using the filter object accessible with "filter", this will issue a new HTTP POST query to the MetaCPAN API endpoint to retrieve the JSON data.

It will then populate the data, notably to items, timed_out, total, took and return the current object for chaining.

It also sets the HTTP request object and the HTTP response object that can be retrieved with "http_request" and "http_response" respectively.

If an error occurred, it will set an error object, and return undef in scalar context or an empty list in list context.

There is no need to access load directly. This would be called automatically when more data is requested and if there is indeed more data.

load_data

Provided with an hash reference of data, and this will load it into the current object, and return the current object for chaining. Upon error, this will set an error object and return undef in scalar context, or an empty list in list context.

length

Read-only. This returns the size of the data pool as a number object.

A 10-elements data pool would return 10. The value returned is directly related to the sie of the arra reference data pool, so if you use the methods "pop", "unshift", "shift", "unshift", it will affect the value returned here.

offset

Read-only. Returns the offset position of the current item across the entire data set.

For example, if you are currently checking the 3rd element of the 2 data page, the offset value would be 12, because offset starts at 0

This returns a number object

page

Integer. Sets or gets an integer representing the current page of data being used.

Returns a number object

page_type

Sets or gets a scalar object representing the type of paging used to access next and previous pages. Possible values are from and page, and this defaults to from

When it is set to from, load will use a data offset starting from 0. For example, on a data set broken into pages of 20 elements each, moving to the 2 pages would set the from value to 20.

If page_type is set to page, the page number starting from 1 will be used.

pageable

Boolean. Sets or gets a boolean value representing whether more data can be loaded beyond the current set, or if the current set the only set of available data.

Returns a boolean object

For example, autocomplete returns a set of 10 elements, but is not pageable.

page_size

Integer. This indicates the size of each result page. Contrary to size, which is a preference that can be set to indicate how many result per page one wants, page_size is set upon loading data with load_data and reflects the actul page size.

If the page contains only a small amount of results, such as 3, then page_size will be 3, but if the overall total exceeds that of the page size, page_size will show how many result per page is provided.

This information is then used for new requests to load more data by next and prev

Thus it is more an internal method.

pop

    my $obj = $list->pop;

This removes the last entry from the data pool, thus altering it, and returns it.

If the value to be returned is undefined, it will return undef in scalar context and an empty list in list context, and it will return a null object in object context to prevent a perl error of some methods called with an undefined value. The null object virtual method call will return undef eventually.

For example, let's assume the list is empty. Calling pop would return an undef value, but since it is called in object context, it returns a null object instead.

    my $undef = $list->pop->author;

You might want to use $list->get(-1) instead to avoid modifying the array reference of data.

pos

Read-ony. Returns the current position in the array reference of data pool. This would be a positive integer, or undef if no data was accessed yet.

postprocess

Sets or gets the caller (anonymous subroutine) that is is called by "load_data" with the hash reference of data received from the MetaCPAN API, for possible post processing.

This method, not the callback, returns the current object for chaining, or upon error, sets an error and returns undef in scalar context or an empty list in list context.

preprocess

Sets or gets the caller (anonymous subroutine) that is is called by "load_data" with the hash reference of data received from the MetaCPAN API, for possible pre processing.

This method, not the callback, returns the current object for chaining, or upon error, sets an error and returns undef in scalar context or an empty list in list context.

    my $obj = $list->next;

This returns the previous data object in the data pool, or if none exists, undef in scalar context and an empty list in list context, and it will return a null object in object context to prevent a perl error of some methods called with an undefined value. The null object virtual method call will return undef eventually.

For example, let's assume the list is empty. Calling prev would return an undef value, but since it is called in object context, it returns a null object instead.

    my $undef = $list->prev->author;

push

    $list->push( $object );

Provided with a proper object value, and this will add it to the end of the data pool and returns the current list object for chaining purposes.

A valid value must be an object of the same type as the ones used in this data pool.

Upon error, this will set an error object and returns undef in scalar context and an empty list in list context.

request

Sets or gets the original HTTP request object that was used for this list object.

shift

    my $obj = $list->shift;

This removes the first entry from the data pool, thus altering it, and returns it.

For example, let's assume the list is empty. Calling shift would return an undef value, but since it is called in object context, it returns a null object instead.

    my $undef = $list->shift->author;

size

Sets or gets the size of each page. Normally, this is figured out automatically by load_data, but sometimes, when large chunk of data are returning at once, and you want to break it down, setting the size makes it possible.

This returns a number object

size_prop

Sets or gets the property name in the data containing the size of the data set. Typically this is size and this is the default value.

This returns a scalar object

timed_out

Sets or gets the boolean value returned from the last API call to MetaCPAN and representing whether the query has timed out.

took

Sets or gets a number returned from the last API call to MetaCPAN. If set, this will return a number object, otherwise undef

total

Sets or gets the overall size of the data available from MetaCPAN API, possibly across multiple API calls.

For example, a query might result in data of 120 elements found, and each page with 10 elements. total would then be 120.

It returns a number object.

See also "length", which returns the current size of the data at hands stored in items

type

Sets or gets the underlying object type of the data pool. This can be author, changes, cover, distribution, favorite, file, mirror, module, package, permission, rating, release, but is not enforced, so whatever value you set is your responsibility.

unshift

    $list->unshift( $object );

Provided with a proper object value, and this will add it at the beginning of the data pool and returns the current list object for chaining purposes.