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

use XML;

our proto canonical(|) is export {*}

my multi sub canonical(Str $xml, :$subset, :$exclusive, :@namespaces) {
    canonical(from-xml($xml).root, :$subset, :$exclusive, :@namespaces)
}

my multi sub canonical(XML::Document $xml, :$subset, :$exclusive, :@namespaces) {
    canonical($xml.root, :$subset, :$exclusive, :@namespaces)
}

my multi sub canonical(XML::Text $xml, *%) {
    my $text = $xml.text;

    # normalize line endings
    $text ~~ s:g/\n/\n/;

    # un-escape everything
    $text ~~ s:g/\&(\S+?)\;/{
        my $e = $0.Str.lc;

        if    $e eq 'amp'          { '&' }
        elsif $e eq 'apos'         { "'" }
        elsif $e eq 'lt'           { '<' }
        elsif $e eq 'gt'           { '>' }
        elsif $e eq 'quot'         { '"' }
        elsif $e ~~ /^<[0..9]>+$/  { chr($e) }
        elsif $e ~~ /^x<[0..9]>+$/ { chr(:16($e.substr(1))) }

        else { die "Unknown XML entity: "~$e }
    }/;

    escape-amp-lt-gt $text
}

my multi sub canonical(XML::CDATA $xml, *%) {
    escape-amp-lt-gt $xml.data
}

multi sub canonical(
  XML::Element $xml is copy,
           :$subset is copy,
           :$exclusive,
           :$namespaces,
           :%exc-rendered-ns is copy
) {
    my @namespaces = @$namespaces;
    %exc-rendered-ns{'#default'} = '' unless %exc-rendered-ns;

    my %extra-attribs;
    if $subset {
        my @parts = $subset.split(/\//).grep({$_});
        die "Invalid subset" if @parts[0] ne $xml.name;
        @parts.shift;
        while @parts {
            for $xml.attribs.kv -> $k, $v {
                if $k ~~ /^xmlns(.*)?/ {
                    my $part = $0.Str;
                    $part ~~ s/\:// if $part;
                    if !$exclusive || @namespaces.grep({ $part ?? $_ eq $part !! $_ eq '#default' }) {
                        %extra-attribs{$k} = $v;
                        %exc-rendered-ns{$k} = $v;
                    }
                }
            }
            my $tmp = $xml.elements(:TAG(@parts[0]), :SINGLE);
            die "Invalid subset" unless $tmp;
            $xml := $tmp;
            @parts.shift;
        }
    }

    my $element = '<' ~ $xml.name;
    my @keys = $xml.attribs.keys;

    @keys = @keys.grep: { needed-attribute $xml, $_ }

    if $exclusive {
        # special namespace rules, so strip out all xmlns attributes
        # (inclusivenamespaces rule handled with extra-attribs below)
        @keys .= grep({ !( $_ ~~ /^xmlns/ ) });

        my %used_ns;
        for @keys {
            my @s = .split(/\:/);
            if @s.elems > 1 {
                %used_ns{@s[0]}++;
            }
        }
        my @s = $xml.name.split(/\:/);
        if @s.elems > 1 {
            %used_ns{@s[0]}++;
        }
        else {
            %used_ns{'#default'}++;
        }

        for %used_ns.keys {
            if !(%exc-rendered-ns{$_}:exists)
              || %exc-rendered-ns{$_} ne ($_ eq '#default'
                   ?? $xml.nsURI('')
                   !! $xml.nsURI($_)
            ) {
                if $_ eq '#default' {
                    %extra-attribs{'xmlns'} = $xml.nsURI('');
                    %exc-rendered-ns{'#default'} = $xml.nsURI('');
                }
                else {
                    %extra-attribs{'xmlns:' ~ $_} = $xml.nsURI($_);
                    %exc-rendered-ns{$_} = $xml.nsURI($_);
                }
            }
        }
    }

    @keys.append(%extra-attribs.keys);

    @keys = @keys.sort: -> $a, $b { compare-attributes $xml, $a, $b }

    for @keys -> $k {
        my $v = %extra-attribs{$k};
        $v //= $xml.attribs{$k};

        # escape " < > &
        $v = $v
          .subst('&', '&amp;')
          .subst('"', '&quot;')
          .subst('<', '&lt;')
          .subst('>', '&gt;');

        $element ~= " $k=\"$v\"";
    }
    $element ~= '>';

    for $xml.nodes {
        $element ~= canonical($_, :$exclusive, :@namespaces, :%exc-rendered-ns);
    }

    $element ~= '</' ~ $xml.name ~ '>';

    $element
}

my sub needed-attribute($xml, $key) {
    return True unless $key ~~ /^xmlns/;

    if $xml.parent ~~ XML::Document {
        $xml.attribs{$key}.Bool
    }
    else {
        my $value := $xml.attribs{$key};
        my @keyparts = $key.split(/\:/);
        @keyparts[1] ||= '';

        $xml.parent.nsURI(@keyparts[1]) ne $value
    }
}

my sub compare-attributes($xml, $a, $b) {
    # namespaces go first
    if is-xmlns($a) && !is-xmlns($b) {
        Less
    }
    elsif is-xmlns($b) && !is-xmlns($a) {
        More
    }
    # namespaces ordered simply
    elsif is-xmlns($a) && is-xmlns($b) {
        $a cmp $b
    }
    # attributes ordered by namespace, then name
    # if no namespace, treat the namespace as "" (empty string)
    else {
        my @aparts = $a.split(/\:/);
        if @aparts[1] {
            @aparts[0] = $xml.nsURI(@aparts[0]);
        }
        else {
            @aparts[1] = @aparts[0];
            @aparts[0] = '';
        }

        my @bparts = $b.split(/\:/);
        if @bparts[1] {
            @bparts[0] = $xml.nsURI(@bparts[0]);
        }
        else {
            @bparts[1] = @bparts[0];
            @bparts[0] = '';
        }

        @aparts[0] cmp @bparts[0] || @aparts[1] cmp @bparts[1]
    }
}

sub is-xmlns($a) {
    $a eq 'xmlns' || $a.starts-with('xmlns:')
}

# escape < > &
my sub escape-amp-lt-gt(Str:D $text) {
    $text
      .subst('&','&amp;')
      .subst('<','&lt;')
      .subst('>','&gt;')
}



XML::Canonical - Provide a canonical version of XML


=begin code :lang<raku>

use XML::Canonical;

my $xml-string = canonical($xml);
my $xml-string = canonical($xml, :subset('/a/b/c'));

=end code


XML::Canonical is a module that exports a single subroutine C<canonical>
that transforms any given C<XML> to a canonical version.


Source can be located at: https://github.com/raku-community-modules/XML-Canonical .
Comments and Pull Requests are welcome.


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


Canonical

XDG::GuaranteedResources - Guarantees that a resource is present in the expected XDG Base Directory directory


=begin code :lang<raku>

use XDG::GuaranteedResources;
# pass it the relative path to a file under your resources directory
# path must be listed in the resources array of your META6.json
guarantee-resource("config/app_config.toml");

=end code


Many tools expect a config file, sqlite database, or similar to be present. We store these in the resources listed in C<META6.json>, and need to test if they exist and copy them over from C<resources> if not.


C<XDG::GuaranteedResources> handles this common operation.


Resources that should be copied to C<XDG_CONFIG_HOME>
should be stored under C<resources/config>


Resources that should be copied to C<XDG_DATA_HOME>
should be stored under C<resources/data>


Subdirectories are fine. E.g. C<resources/data/subdir/my_db.db>


⚠ Currently only works on Unix (Linux, BSD, macOS, etc.) systems.


Kay Rhodes a.k.a masukomi (masukom@masukomi.org)


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




unit module XDG::GuaranteedResources:ver<1.0.0>:auth<masukomi (masukomi@masukomi.org)>;

use XDG::BaseDirectory :terms;
use XDG::GuaranteedResources::Resourcer;


my sub guarantee-dir(Str $dir){
	mkdir($dir.Str) unless $dir.IO.e;
	CATCH {
		when X::IO::Mkdir { die "Unable to create directory $dir" ; }
	}
}

my sub xdg-home-for-dir_array(@directory_array){
	given @directory_array.first {
		when $_ eq 'config' {
			config-home
		}
		when $_ eq 'data' {
			data-home
		}
		default {
			die("resources must be stored under config or data subdirectory");
		}
	}
}

my sub path-to-directory-array(IO::Path $path, @directory_array = [] ) {
	my $parent = $path.parent;
	# TODO: UNIX limitation. Need good way to determine path separator
	return @directory_array if $parent.Str eq '/' or $parent.Str eq '.';
	@directory_array.unshift($parent.basename);
	path-to-directory-array($parent, @directory_array);
}

my sub resource-to-xdg-dir(@directory_array) returns Str {
	# experting directory_array to be something like
	# ["config", "foo.txt"]
	# ["convig", "subdir", "foo.txt"]
	my $home_dir = xdg-home-for-dir_array(@directory_array);
	# TODO: UNIX limitation. Need good way to determine path separator
	my $joined_subpath = @directory_array.elems == 2
						  ?? @directory_array[1]
						  !! @directory_array[1..∞].join("/");
	IO::Spec::Unix.catpath($, $home_dir.Str, $joined_subpath)
}


my sub copy-resource(Str $resource, Str $destination) {
	copy(XDG::GuaranteedResources::Resourcer.gimme{$resource}, $destination);
}

#| checks if the resource is present and copies it over if not.
our sub guarantee-resource(Str $resource_path) is export returns Str {
	my $io_path = $resource_path.IO;
	my @dir_array = path-to-directory-array($io_path);
	my $xdg_dir = resource-to-xdg-dir(@dir_array);
	guarantee-dir($xdg_dir);
	my $xdg_path = IO::Spec::Unix.catpath($, $xdg_dir, $io_path.basename);
	unless $xdg_path.IO.e {
		copy-resource($resource_path, $xdg_path);
	}
	return $xdg_path;

	CATCH {
		when X::IO::Copy  { die "Unable to copy resource to $xdg_path"; }
	}

}


GuaranteedResources

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

AUTHOR

COPYRIGHT AND LICENSE

sub guarantee-resource

XDG::GuaranteedResources v1.0.0

Authors

License

Dependencies

Test Dependencies

Provides

Documentation