The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Aion-Surf-0.0.1
River stage zero No dependents
/ Aion::Surf

NAME

Aion::Surf - surfing by internet

VERSION

0.0.1

SYNOPSIS

        use Aion::Surf;
        use common::sense;
        
        # mock
        *LWP::UserAgent::request = sub {
            my ($ua, $request) = @_;
            my $response = HTTP::Response->new(200, "OK");
        
            given ($request->method . " " . $request->uri) {
                $response->content("get")    when $_ eq "GET http://example/ex";
                $response->content("head")   when $_ eq "HEAD http://example/ex";
                $response->content("post")   when $_ eq "POST http://example/ex";
                $response->content("put")    when $_ eq "PUT http://example/ex";
                $response->content("patch")  when $_ eq "PATCH http://example/ex";
                $response->content("delete") when $_ eq "DELETE http://example/ex";
        
                $response->content('{"a":10}')  when $_ eq "PATCH http://example/json";
                default {
                    $response = HTTP::Response->new(404, "Not Found");
                    $response->content("nf");
                }
            }
        
            $response
        };
        
        get "http://example/ex"             # => get
        surf "http://example/ex"            # => get
        
        head "http://example/ex"            # -> 1
        head "http://example/not-found"     # -> ""
        
        surf HEAD => "http://example/ex"    # -> 1
        surf HEAD => "http://example/not-found"  # -> ""
        
        [map { surf $_ => "http://example/ex" } qw/GET HEAD POST PUT PATCH DELETE/] # --> [qw/get 1 post put patch delete/]
        
        patch "http://example/json" # --> {a => 10}
        
        [map patch, qw! http://example/ex http://example/json !]  # --> ["patch", {a => 10}]
        
        get ["http://example/ex", headers => {Accept => "*/*"}]  # => get
        surf "http://example/ex", headers => [Accept => "*/*"]   # => get

DESCRIPTION

Aion::Surf contains a minimal set of functions for surfing the Internet. The purpose of the module is to make surfing as easy as possible, without specifying many additional settings.

SUBROUTINES

to_json ($data)

Translate data to json format.

        my $data = {
            a => 10,
        };
        
        my $result = '{
           "a": 10
        }
        ';
        
        to_json $data # -> $result
        
        local $_ = $data;
        to_json # -> $result

from_json ($string)

Parse string in json format to perl structure.

        from_json '{"a": 10}' # --> {a => 10}
        
        [map from_json, "{}", "2"]  # --> [{}, 2]

to_url_param (;$scalar)

Escape scalar to part of url search.

        to_url_param "a b" # => a+b
        
        [map to_url_param, "a b", "🦁"] # --> [qw/a+b %1F981/]

to_url_params (;$hash_ref)

Generates the search part of the url.

        local $_ = {a => 1, b => [[1,2],3,{x=>10}]};
        to_url_params  # => a&b[][]&b[][]=2&b[]=3&b[][x]=10
1. Keys with undef values not stringify.
2. Empty value is empty.
3. 1 value stringify key only.
4. Keys stringify in alfabet order.
        to_url_params {k => "", n => undef, f => 1}  # => f&k=

parse_url ($url, $onpage, $dir)

Parses and normalizes url.

  • $url — url, or it part for parsing.

  • $onpage — url page with $url. If $url not complete, then extended it. Optional. By default use config ONPAGE = "off://off".

  • $dir (bool): 1 — normalize url path with "/" on end, if it is catalog. 0 — without "/".

        my $res = {
            proto  => "off",
            dom    => "off",
            domain => "off",
            link   => "off://off",
            orig   => "",
            onpage => "off://off",
        };
        
        parse_url ""    # --> $res
        
        $res = {
            proto  => "https",
            dom    => "main.com",
            domain => "www.main.com",
            path   => "/page",
            dir    => "/page/",
            link   => "https://main.com/page",
            orig   => "/page",
            onpage => "https://www.main.com/pager/mix",
        };
        
        parse_url "/page", "https://www.main.com/pager/mix"   # --> $res
        
        $res = {
            proto  => "https",
            user   => "user",
            pass   => "pass",
            dom    => "x.test",
            domain => "www.x.test",
            path   => "/path",
            dir    => "/path/",
            query  => "x=10&y=20",
            hash   => "hash",
            link   => 'https://user:pass@x.test/path?x=10&y=20#hash',
            orig   => 'https://user:pass@www.x.test/path?x=10&y=20#hash',
            onpage => "off://off",
        };
        parse_url 'https://user:pass@www.x.test/path?x=10&y=20#hash'  # --> $res

See also URL::XS.

normalize_url ($url, $onpage, $dir)

Normalizes url.

It use parse_url, and it returns link.

        normalize_url ""   # => off://off
        normalize_url "www.fix.com"  # => off://off/www.fix.com
        normalize_url ":"  # => off://off/:
        normalize_url '@'  # => off://off/@
        normalize_url "/"  # => off://off
        normalize_url "//" # => off://
        normalize_url "?"  # => off://off
        normalize_url "#"  # => off://off
        
        normalize_url "/dir/file", "http://www.load.er/fix/mix"  # => http://load.er/dir/file
        normalize_url "dir/file", "http://www.load.er/fix/mix"  # => http://load.er/fix/mix/dir/file
        normalize_url "?x", "http://load.er/fix/mix?y=6"  # => http://load.er/fix/mix?x

See also URI::URL.

surf ([$method], $url, [$data], %params)

Send request by LWP::UserAgent and adapt response.

@params maybe:

  • query - add query params to $url.

  • json - body request set in json format. Add header Content-Type: application/json; charset=utf-8.

  • form - body request set in url params format. Add header Content-Type: application/x-www-form-urlencoded.

  • headers - add headers. If header is array ref, then add in the order specified. If header is hash ref, then add in the alphabet order.

  • cookies - add cookies. Same as: cookies => {go => "xyz", session => ["abcd", path => "/page"]}.

  • response - returns response (as HTTP::Response) by this reference.

        my $req = "MAYBE_ANY_METHOD https://ya.ru/page?z=30&x=10&y=%1F9E8
        Accept: */*,image/*
        Content-Type: application/x-www-form-urlencoded
        
        x&y=2
        ";
        
        my $req_cookies = 'Set-Cookie3: go=""; path="/"; domain=ya.ru; version=0
        Set-Cookie3: session=%1F9E8; path="/page"; domain=ya.ru; version=0
        ';
        
        # mock
        *LWP::UserAgent::request = sub {
            my ($ua, $request) = @_;
        
            $request->as_string # -> $req
            $ua->cookie_jar->as_string  # -> $req_cookies
        
            my $response = HTTP::Response->new(200, "OK");
            $response->content(3.14);
            $response
        };
        
        my $res = surf MAYBE_ANY_METHOD => "https://ya.ru/page?z=30", [x => 1, y => 2, z => undef],
            headers => [
                'Accept' => '*/*,image/*',
            ],
            query => [x => 10, y => "🧨"],
            response => \my $response,
            cookies => {
                go => "",
                session => ["🧨", path => "/page"],
            },
        ;
        $res           # -> 3.14
        ref $response  # => HTTP::Response

head (;$url)

Check resurce in internet. Returns 1 if exists resurce in internet, otherwice returns "".

get (;$url)

Get content from resurce in internet.

post (;$url, [$headers_href], %params)

Add content resurce in internet.

put (;$url, [$headers_href], %params)

Create or update resurce in internet.

patch (;$url, [$headers_href], %params)

Set attributes on resurce in internet.

del (;$url)

Delete resurce in internet.

chat_message ($chat_id, $message)

Sends a message to a telegram chat.

        # mock
        *LWP::UserAgent::request = sub {
            my ($ua, $request) = @_;
            HTTP::Response->new(200, "OK", undef, to_json {ok => 1});
        };
        
        chat_message "ABCD", "hi!"  # --> {ok => 1}

bot_message (;$message)

Sends a message to a telegram bot.

        bot_message "hi!" # --> {ok => 1}

tech_message (;$message)

Sends a message to a technical telegram channel.

        tech_message "hi!" # --> {ok => 1}

bot_update ()

Receives the latest messages sent to the bot.

        # mock
        *LWP::UserAgent::request = sub {
            my ($ua, $request) = @_;
        
            my $offset = from_json($request->content)->{offset};
            if($offset) {
                return HTTP::Response->new(200, "OK", undef, to_json {
                    ok => 1,
                    result => [],
                });
            }
        
            HTTP::Response->new(200, "OK", undef, to_json {
                ok => 1,
                result => [{
                    message => "hi!",
                    update_id => 0,
                }],
            });
        };
        
        bot_update  # --> ["hi!"]
        
        
        # mock
        *LWP::UserAgent::request = sub {
            HTTP::Response->new(200, "OK", undef, to_json {
                ok => 0,
                description => "nooo!"
            })
        };
        
        eval { bot_update }; $@  # ~> nooo!

SEE ALSO

AUTHOR

Yaroslav O. Kosmina Lmailto:dart@cpan.org

LICENSE

⚖ GPLv3

COPYRIGHT

The Aion::Surf module is copyright © 2023 Yaroslav O. Kosmina. Rusland. All rights reserved.