NAME

HTTP::Promise::Body::Form::Data - A multipart/form-data Representation Class

SYNOPSIS

    use HTTP::Promise::Body::Form;
    my $form = HTTP::Promise::Body::Form::Data->new;
    my $form = HTTP::Promise::Body::Form::Data->new({
        fullname => 'Jigoro Kano',
        location => HTTP::Promise::Body::Form::Data->new_field(
            name => 'location',
            value => 'Tokyo',
        ),
        picture => HTTP::Promise::Body::Form::Data->new_field(
            name => 'picture',
            file => '/some/where/file.txt',
        ),
    });
    my $form = HTTP::Promise::Body::Form::Data->new( $hash_ref );
    my $form = HTTP::Promise::Body::Form::Data->new( q{e%3Dmc2} );
    die( HTTP::Promise::Body::Form->error, "\n" ) if( !defined( $form ) );

VERSION

    v0.1.0

DESCRIPTION

This class represents a form-data content as key-value pairs and is designed to make construction and manipulation of multipart/form-data easier. It inherits from HTTP::Promise::Body::Form

For x-www-form-urlencoded, use HTTP::Promise::Body::Form instead.

Each key represents a form-data field and its value can either be a simple string or a HTTP::Promise::Body::Form::Field object.

multipart/form-data is the only valid Content-Type for sending multiple data. rfc7578 in section 4.3 states: "[RFC2388] suggested that multiple files for a single form field be transmitted using a nested "multipart/mixed" part. This usage is deprecated."

See also this Stackoverflow discussion and this one too

CONSTRUCTOR

new

This takes an optional data, and some options and returns a new HTTP::Promise::Body::Form object.

Acceptable data are:

An hash reference

An url encoded string

If a string is provided, it will be automatically decoded into an hash of name-value pairs. When a name is found more than once, its values are added as an array reference.

    my $form = HTTP::Promise::Body->new( 'name=John+Doe&foo=bar&foo=baz&foo=' );

Would result in a HTTP::Promise::Body::Form object containing:

    name => 'John Doe', foo => ['bar', 'baz', '']

METHODS

HTTP::Promise::Body::Form inherits all the methods from Module::Generic::Hash, and adds or override the following ones.

as_string

Provided with an hash or hash reference of options and this returns a scalar object of the form-data properly formatted as multipart elements.

Be mindful of the size of the parts and that this is not cached, so each time this is called, it creates the parts.

Supported options are:

• boundary

  A string used as a part delimiter. Note, however, that even if you provide this value, it will not replace the boundary value of a HTTP::Promise::Body::Form::Field Content-Disposition field if it is set.

  If this is not provided, a new one will be automatically generated using "create_str" in Data::UUID

• eol

  The end-of-line terminator. This defaults to \015\012

• fields

  An array reference of form field names. This is used to set the order of appearance.

  If not provided, it will default to alphabetic order.

as_urlencoded

This returns a new HTTP::Promise::Body::Form object based on the current data, or upon error, sets an error and returns undef.

make_parts

This takes an hash or hash reference of options and creates entity part objects and returns them as an array object

Supported options are:

• boundary

  A string used as a part delimiter. Note, however, that even if you provide this value, it will not replace the boundary value of a HTTP::Promise::Body::Form::Field Content-Disposition field if it is set.

  If this is not provided, a new one will be automatically generated using "create_str" in Data::UUID

make_parts

Provided with an hash or hash reference of options and this returns an array object of parts

Note that at this point, the body is not encoded and the Content-Length is not added. You can use "encode_body" in HTTP::Promise::Entity on each part to encode a form part value.

Supported options are:

• fields

  An array reference of form field names. This is used to set the order of appearance.

  If not provided, it will default to alphabetic order.

new_field

This takes an hash or hash reference of options and returns the new HTTP::Promise::Body::Form::Data object, or upon error, sets an error and returns undef.

Supported options are:

• headers

  This is optional. Either as HTTP::Promise::Headers object or as an array reference.

• name

  Field name

• value

  Field value as a string, scalar reference or a file object

open

This transform all the form-data elements into a proper multipart/form-data using "as_string" and returns a new Module::Generic::Scalar::IO object.

It then opens the scalar passing "open" in Module::Generic::Scalar whatever arguments were provided and returns an Module::Generic::Scalar::IO object.

order

Sets or gets an array object of form fields in the desired order of appearance when stringified.

print

Provided with a valid filehandle, and this print the form-data representation of the form fields and their values, to the given filehandle, or upon error, sets an error and returns undef

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

HTTP::Promise, HTTP::Promise::Request, HTTP::Promise::Response, HTTP::Promise::Message, HTTP::Promise::Entity, HTTP::Promise::Headers, HTTP::Promise::Body, HTTP::Promise::Body::Form, HTTP::Promise::Body::Form::Data, HTTP::Promise::Body::Form::Field, HTTP::Promise::Status, HTTP::Promise::MIME, HTTP::Promise::Parser, HTTP::Promise::IO, HTTP::Promise::Stream, HTTP::Promise::Exception

Module::Generic::Scalar

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm HTTP::Promise

perl -MCPAN -e shell
install HTTP::Promise