head

code

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

README

URI::Template - implementation of RFC 6570


=begin code

use URI::Template;

my $template = URI::Template.new(template => 'http://foo.com{/foo,bar}');

say $template.process(foo => 'baz', bar => 'quux'); # http://foo.com/baz/quux

=end code


This provides an implementation of
L<RFC6570|https://tools.ietf.org/html/rfc6570> which allows for the
definition of a URI through variable expansion. Please refer to the
specification for full details of the template expansion.


A URI template comprises a string representing a full or partial URI
containing on or more template expressions.  A template expression
is delimited by curly braces ('{', '}',) and may contain one or more
variable names to be expanded separated by commas.  The variables may
be qualified by either an integer maximum length (separated from the
variable name by a ':',) or by a '*' that indicates that aggregate
values should be 'exploded', (how this explosion manifests in detail
depends on the expression 'operator' and is described in the specification.)


The expression can be modified with an optional 'operator' which should be
supplied immediately after the opening '{', the operator may modify the
way in which the values of the variables are encoded, the way that multiple
variables are joined in the same expression and the way in which aggregate
variable values are expanded.


The operators and their general meaning are thus:


=begin code

      +   Reserved character strings;

      #   Fragment identifiers prefixed by "#";

      .   Name labels or extensions prefixed by ".";

      /   Path segments prefixed by "/";

      ;   Path parameter name or name=value pairs prefixed by ";";

      ?   Query component beginning with "?" and consisting of
          name=value pairs separated by "&"; and,

      &   Continuation of query-style &name=value pairs within
          a literal query component.

=end code


method new(Str :$template) returns URI::Template


The constructor of the class.  The C<$template> must be a valid URI template if
it is provided.  If it is not provided to the constructor then it must be provided
by setting the attribute accessor before C<process> is called.


Expand the template with the values of the template variables specified as named
arguments.  If no C<template> has been provided then a C<X::NoTemplate> exception
will be thrown.  If the provided template is unable to be parsed then a
C<X::InvalidTemplate> exception will be thrown.


A read/write public accessor for the template.  If this parameter is not set by
the accessor it must be set using C<template> before C<process> is called.


Because of the way the template is parsed it will only be done once for any
given C<URI::Template> object, so setting this after C<process> has been called
for the first time will have no effect.  If you need a different template it is
recommended to use a different object.



class URI::Template:ver<0.0.8>:auth<github:jonathanstowe>:api<1.0> {

    has Str $.template is rw;

    # this holds the parsed parts
    has @.parts;


    #| Simply a marker to indicate whether encoding need happen
    my role PreEncoded {
    }

    #| Mark that we don't need the name expansion
    my role PreExploded {
    }

    class Variable {
        has Str $.name;
        has Int $.max-length;
        has Bool $.explode;

        method get-value(Str $operator, %vars --> Str ) {
            my Str $value;

            if %vars{$!name}:exists {
                $value = self.expand-value($operator, %vars{$!name});

            }

            $value;
        }

        multi method expand-value(Str $operator, Any:U $) {
            Str;
        }

        multi method expand-value(Str $operator, Numeric:D $value) {
            self.expand-value($operator, $value.Str);
        }
        multi method expand-value(Str $operator, Str $value) {
            my Str $exp-value;


            if $!max-length {
                $exp-value = $value.substr(0, $!max-length);
            }
            else {
                $exp-value = $value;
            }
            $exp-value;
        }

        multi method expand-value(Str $operator, @value) {

            if @value.elems {
                my $joiner = self!get-joiner($operator);
                my &exp = self!get-exploder($operator);
                my Str $exp-value = @value.map(&uri-encode-component).map(&exp).join($joiner);

                $exp-value does PreEncoded;
                if self!was-exploded($operator) {
                    $exp-value does PreExploded;
                }

                return $exp-value;
            }
            else {
                Nil;
            }
        }

        method !was-exploded(Str $operator --> Bool ) {
            my Bool $ret = False;
            if $operator.defined {
                if self.explode {
                    if $operator ~~ any(<& ? ;>) {
                        $ret = True;
                    }
                }
            }
            $ret;
        }

        #! return a closure to handle the array explosion
        method !get-exploder(Str $operator --> Callable ) {

            my &exp =  sub ( $val ) {
                my $exp-val = $val;
                if $operator.defined {
                    if self.explode {
                        if $operator ~~ any(<& ? ;>) {
                            $exp-val = self.name ~ "=" ~ $exp-val;
                            $exp-val does PreExploded;
                        }
                    }
                }
                $exp-val;
            }
            &exp;
        }

        multi method expand-value(Str $operator, %value) {

            if ?%value.keys {
                my Str $res;
                my $joiner = self!get-joiner($operator);
                my &enc = self!get-hash-encoder($operator);
                if self.explode {
                    $res = %value.kv.map({.Str}).map(&enc).map( -> $k, $v { "$k=$v"}).join($joiner);
                    $res does PreExploded;
                }
                else {
                    $res = %value.kv.map({.Str}).map(&enc).join($joiner);
                }

                $res does PreEncoded;

                $res;
            }
            else {
                Nil;
            }

        }

        #| lookup for the joiners
        my %joiners = (
                        '+'  =>     ",",
                        '#'  =>     ",",
                        '.'  =>     ".",
                        '/'  =>     "/",
                        ';'  =>     ";",
                        '?'  =>     "&",
                        '&'  =>     "&" ,
        );

        #| Get the appropriate character to join elements
        method !get-joiner(Str $operator --> Str ) {
            my $joiner = self.explode ?? $operator.defined ?? %joiners{$operator} !! ',' !! ',';
            $joiner;
        }

        my &enc = sub ($m) {
            $m.Str.encode.list.map({.fmt('%%%02X')}).join('')
        }

        my sub uri-encode (Str:D $text) {
            return $text.subst(/<[\x00..\x10ffff]-[a..zA..Z0..9_.~\!\+\-\#\$\&\+,\/\:;\=\?@]>/, &enc, :g);
        }

        my sub uri-encode-component (Str:D $text) {
            return $text.subst(/<[\x00..\x10ffff]-[a..zA..Z0..9_.~\-]>/, &enc, :g);
        }

        #| Returns the appropriate encoding sub for the operator
        method !get-encoder(Str $operator --> Callable ) {
            my &encoder = do if $operator.defined {
                given $operator {
                    when /<[\+\#\;\.]>/ {
                        &uri-encode;
                    }
                    default {
                        &uri-encode-component;
                    }
                }
            }
            else {
                &uri-encode-component;
            }
            &encoder;
        }

        #| Returns the appropriate encoding sub for the operator
        #| this is special for the hash case for the time being
        method !get-hash-encoder(Str $operator --> Callable ) {
            my &encoder = do if $operator.defined {
                given $operator {
                    when /<[\+\#]>/ {
                        &uri-encode;
                    }
                    default {
                        &uri-encode-component;
                    }
                }
            }
            else {
                &uri-encode-component;
            }
            &encoder;
        }

        #| encode the string if it it needed
        method !encode-expanded(Str $operator, Str $value --> Str ) {
            my $res = do if $value ~~ PreEncoded {
                $value;
            }
            else {
                self!get-encoder($operator).($value);
            }

            $res;
        }

        multi method process(Str $operator, %vars) {
            my $res;

            my $val = self.get-value($operator, %vars);
            if $val {
                if $val !~~ PreExploded {
                    my $eq = $operator.defined && $operator eq ';' ?? '=' !! '';
                    $res = (self!get-primer($operator) // '') ~ $eq;
                }
                $res ~= self!encode-expanded($operator, $val);
            }
            elsif $val.defined {
               $res = self!get-primer($operator);
            }
            else {
                $res = Nil;
            }
            $res;
        }

        method !get-primer(Str $operator --> Str ) {
            my Str $primer = do given $operator {
                when '&' {
                    $!name ~ '=';
                }
                when '?' {
                    $!name ~ '=';
                }
                when ';' {
                    $!name;
                }
                default {
                    Str;
                }
            }
            $primer;
        }

    }

    sub get-joiner(Str $operator) {
        my $joiner = do given $operator {
            when '/' {
                '/';
            }
            when '&' {
                '&';
            }
            when '?' {
                '&';
            }
            when '.' {
                '.';
            }
            when ';' {
                ';';
            }
            default {
                ',';
            }
        }

        $joiner;

    }

    class Expression {
        has $.operator;
        has Variable @.variables;

        method process(%vars --> Str ) {
            my Str $str;

            my @processed-bits = ();

            for self.variables -> $variable {
               @processed-bits.push($variable.process($!operator, %vars));
            }

            my $joiner = get-joiner($!operator);

            my &filter = self!get-part-filter;

            my $show-op = self!show-operator(@processed-bits);

            $str = @processed-bits.grep(&filter).map({ $_ // ''}).join($joiner);

            if $!operator.defined && $!operator ne '+' && $str.defined {
                $str = ($show-op ?? $!operator !! '') ~ $str;
            }

            $str;
        }

        method !show-operator(@bits) {
            my &pc = self!get-part-filter;
            return ?@bits.grep(&pc);
        }

        # This is a bit hacky but adjusting to match the spec
        method !get-part-filter() {
            sub ( $value ) {
                my Bool $rc;
                if $!operator.defined && $!operator eq '#' {
                    $rc = $value ~~ Str;
                }
                else {
                    $rc = $value ~~ Str;
                }
                $rc;
            }
        }

    }

    has Grammar $.grammar = our grammar Grammar {
        rule TOP {
            <bits>* [ <expression>+ ]* %% <bits>+
        }

        token bits { <-[{]>+ }

        regex expression {
            '{' <operator>? <variable>+ % ',' '}'
        }

        regex operator {
            <reserved>          ||
            <fragment>          ||
            <label-dot>         ||
            <path-slash>        ||
            <path-semicolon>    ||
            <form-ampersand>    ||
            <form-continuation>


        }

        token reserved {
            '+'
        }
        token fragment {
            '#'
        }

        token label-dot {
            '.'
        }

        token path-slash {
            '/'
        }

        token path-semicolon {
            ';'
        }

        token form-ampersand {
            '?'
        }

        token form-continuation {
            '&'
        }

        regex variable {
            <variable-name><var-modifier>?
        }
        regex variable-name {
             <-[\s,\:\*\}]>+
        }

        rule var-modifier {
            <explode> || <prefix>
        }

        token explode {
            '*'
        }
        token prefix {
            ':' <max-length>
        }
        token max-length {
            \d+
        }
    }

    our class Actions {

        has @.PARTS = ();
        has Match $!last-bit;

        method TOP($/) {
            $/.make(@!PARTS);
        }

        method bits($/) {
            # This shouldn't be necessary but I can't work out why
            # the last bit is duplicated
            if !$!last-bit.defined || $/.from  != $!last-bit.from {
                @!PARTS.push($/.Str);
            }
            $!last-bit = $/;
        }

        method expression($/) {
            my $operator =  $/<operator>.defined ?? $/<operator>.Str !! Str;
            my @variables = $/<variable>.list.map({ $_.made });
            @!PARTS.push(Expression.new(:$operator, :@variables));
        }

        method variable($/) {

            my Str $name = $/<variable-name>.Str;
            my Int $max-length;
            my Bool $explode = False;

            my $vm = $/<var-modifier>;

            if $vm.defined {
                $max-length = $vm<prefix><max-length>.defined ?? $vm<prefix><max-length>.Int !! Int;
                $explode = $vm<explode>.defined;
            }
            $/.make(Variable.new(:$name, :$max-length, :$explode));
        }

    }

    #| thrown when no template
    class X::NoTemplate is Exception {
        has $.message = "Template is not defined";
    }

    #| thrown when template can't be parsed
    class X::InvalidTemplate is Exception {
        has $.message = "Invalid or un-parseable template";
    }

    #| accessor for the parsed parts of the template
    #| forces it to be made if it hasn't been already
    method parts() {
        if not @!parts.elems {

            if $!template.defined {


                my $actions = Actions.new;

                my $match = URI::Template::Grammar.parse($!template, :$actions);

                if $match {
                    @!parts = $match.made;
                }
                else {
                    X::InvalidTemplate.new.throw;
                }
            }
            else {
                X::NoTemplate.new.throw;
            }
        }
        @!parts;
    }

    method process(*%vars --> Str ) {
        my Str $string;

        for self.parts -> $part {
            given $part {
                when Str {
                    $string ~= $part
                }
                when Expression {
                    $string ~= $part.process(%vars);
                }
                default {
                    die "Unexpected object of type { $part.WHAT.name } found in parsed template";

                }
            }
        }

        $string;
    }


}
# vim: expandtab shiftwidth=4 ft=raku


Template

unit package URI::Query::FromHash:auth<zef:raku-land>:ver<0.0.1>;

my regex reserved { < [ ; / * ' ! ? : @ & = + , $ \[ \] ( ) % \\                        ]> }
my regex    other { <-[ ; / * ' ! ? : @ & = + , $ \[ \] ( ) % \\ _ . ~ A..Z a..z 0..9 - ]> }

my %escapes = BEGIN (^256).map: {
    .&chr ~~ /<[ . ~ A..Z a..z 0..9 - ]>/
        ?? Empty !! .&chr => .fmt: '%%%02X';
}

my sub escape ( $_, &class = &reserved --> Str ) {
    return '' unless .defined;
    .Str.subst( :g, /<&class>/, { .encode».&{ %escapes{$_} // .fmt: '%%%02X' }.join } )
        .trans: ' ' => '+';
}

proto hash2query ( |c --> Str ) is export {*}

multi hash2query ( Any:U $ --> '' ) { }

multi hash2query ( Any:D $input --> Str ) {
    CATCH { return '' when X::Hash::Store::OddNumber }
    my Hash() $hash = $input;

    return '' unless $hash.elems;

    my $query = join '&', $hash.pairs.sort(*.key).map: -> ( :$key, :$value ) {
        $value.List.map: { $key.&escape ~ '=' ~ .&escape }
    }

    escape $query, &other;
}



URI::Query::FromHash - Construct a query string from a hash


=begin code :lang<raku>
use URI::Query::FromHash;

say hash2query {
   foo  => 'bar',
   baz  => < qux quux >,
   utf8 => '🦋',
}
# OUTPUT:
# baz=qux&baz=quux&foo=bar&utf8=%F0%9F%A6%8B
=end code


URI::Query::FromHash aims to be a fast, light query string constructor.


Inspired by L<the Perl module of the same name|https://metacpan.org/pod/URI::Query::FromHash>
and Ruby on Rails' L<to_query|http://api.rubyonrails.org/classes/Hash.html#method-i-to_query>
hash method.


=begin code :lang<raku>
sub hash2query ( Hash() $hash --> Str )
=end code


Accepts anything that can be coerced to a Hash of query parameters and
returns a Str suitable to be used as the query parameters of a URI. Values
will be coerced to List and iterated over, with every element being coerced
to Str before processing. Every one of these elements will then be
URL-encoded and will appear in the generated string once preceded by the
corresponding URL-encoded key and an equal sign (C<=>).


Pairs in the input Hash will be processed alphabetically by key.


When this function encounters input it cannot handle, it returns the empty
string, meaning it should always be safe to use.


This library is free software; you can redistribute it and/or modify it
under the Artistic License 2.0.


FromHash

The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


README

NAME

SYNOPSIS

DESCRIPTION

SUBROUTINES

hash2query

COPYRIGHT AND LICENSE

URI::Query::FromHash v0.0.1

Authors

License

Dependencies

Test Dependencies

Provides

Documentation