head

Image

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

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

XDG::BaseDirectory - locate shared data and configuration


=begin code

    use XDG::BaseDirectory;
    my $bd = XDG::BaseDirectory.new

    for $bd.load-config-paths('mydomain.org', 'MyProg', 'Options') -> $d {
        say $d;
    }

    # Directories can be made available as terms as well
    use XDG::BaseDirectory :terms;
    say config-home;

=end code


The freedesktop.org Base Directory specification provides a way for
applications to locate shared data and configuration:


http://standards.freedesktop.org/basedir-spec/


This module can be used to load and save from and to these directories.


The interface is loosely based on that of the C<pyxdg> module, however all
methods that return a string path in that module return an L<IO::Path> here.



class XDG::BaseDirectory:ver<0.0.11>:auth<github:jonathanstowe>:api<1.0> {



This reflects the base path where local data should be stored.  Can be
over-ridden by the environment variable C<XDG_DATA_HOME>.



    has IO::Path $.data-home;

    method data-home( --> IO::Path ) {
        $!data-home //= %*ENV<XDG_DATA_HOME>.defined ?? %*ENV<XDG_DATA_HOME>.IO !! $*HOME.add($*SPEC.catfile('.local', 'share'));

    }



This returns a list of the locations where data can be read from, it can
be over-ridden by the colon separated environment variable C<XDG_DATA_DIRS>
but will always prefer C<data-home>.



    has IO::Path @.data-dirs;

    method data-dirs() {
        if ! @!data-dirs.elems {
            @!data-dirs = ($.data-home, (%*ENV<XDG_DATA_DIRS> || '/usr/local/share:/usr/share').split(':').map({ $_.IO })).flat;
        }
        @!data-dirs;
    }



Reflects the location where application should be saved to to.  Can
be over-ridden by the enviroment variable C<XDG_CONFIG_HOME>.



    has IO::Path $.config-home;

    method config-home( --> IO::Path ) {
        $!config-home //= %*ENV<XDG_CONFIG_HOME>.defined ?? %*ENV<XDG_CONFIG_HOME>.IO !! $*HOME.add('.config');
    }



returns a list of directorys from which configuration can be read, it will
always prefer C<config-home> but the defaults can be over-ridden by the
environment variable C<XDG_CONFIG_DIRS> which can be a list separated by
colons.



    has IO::Path @.config-dirs;

    method config-dirs() {
        if ! @!config-dirs.elems {
            @!config-dirs = ($.config-home, (%*ENV<XDG_CONFIG_DIRS> || '/etc/xdg' ).split(':').map({ $_.IO })).flat;
        }
        @!config-dirs;
    }



Returns the path where application cache data should be saved. This can be
over-ridden by the environment variable C<XDG_CACHE_HOME>.



    has IO::Path $.cache-home;

    method cache-home( --> IO::Path ) {
        $!cache-home //= (%*ENV<XDG_CACHE_HOME> || $*HOME.add('.cache')).IO;
    }



Returns the directory where user specific, run-time files (and other
filesystem objects such as sockets and named pipes,) should be placed.
The directory will not persist between logins and reboots of the
system. For this to work correctly the system should be managing the
directory and set the environment variable C<XDG_RUNTIME_DIR>, however
if this is not the case the behaviour will be emulated in a less secure
fashion and a warning will be emitted.



    has IO::Path $.runtime-dir;

    method runtime-dir( --> IO::Path ) {
        $!runtime-dir //= do {
            if %*ENV<XDG_RUNTIME_DIR>:exists {
                %*ENV<XDG_RUNTIME_DIR>.IO
            }
            else {
                warn "XDG_RUNTIME_DIR not set -falling back to insecure method";
                my $dir = $*SPEC.tmpdir.add($*USER.Int);
                $dir.mkdir;
                $dir.chmod(0o700);
                $dir;
            }
        }
    }



Ensure C< <config-home>/<resource>/> exists, and return its path.
'resource' should normally be the name of your application. Use this
when SAVING configuration settings. Use the C<config-dirs> variable
for loading.



    method save-config-path(*@resource where @resource.elems > 0  --> IO::Path ) {
        self!home-path($.config-home, @resource);
    }



Ensure C< <data-home>/<resource>/> exists, and return its path.
'resource' is the name of some shared resource. Use this when updating
a shared (between programs) database. Use the C<data-dirs> variable
for loading.



    method save-data-path(*@resource where @resource.elems > 0 --> IO::Path ) {
        self!home-path($.data-home, @resource);
    }

    # given an IO::Path and a resource description, will return an IO::Path of the
    # appropriate sub-directory which will be created if necessary
    method !home-path(IO::Path $home-path, *@resource where @resource.elems > 0 ) {
        my Str $resource = self!resource-path(@resource);

        my IO::Path $path = $home-path.add($resource);

        if ! $path.d {
            $path.mkdir(0o700);
        }
        $path.cleanup;
    }



Returns an iterator which gives each directory named 'resource' in the
configuration search path. Information provided by earlier directories should
take precedence over later ones (ie, the user's config dir comes first).



    method load-config-paths(*@resource ) {
        self!load-resource-paths(@.config-dirs, @resource);
    }



load-first-config(Str *@resource) returns L<IO::Path>


Returns the first result from load-config-paths, or None if there is
nothing to load.



    method load-first-config(*@resource) {
        self.load-config-paths(@resource)[0];
    }



Returns an iterator which gives each directory named 'resource' in the
shared data search path. Information provided by earlier directories should
take precedence over later ones.



    method load-data-paths(*@resource where @resource.elems > 0 ) {
        self!load-resource-paths(@.data-dirs, @resource);
    }

    # given an array of IO::Path objects and a resource description
    # return those resulting resource paths that actually exist
    method !load-resource-paths(@dirs, *@resource where @resource.elems > 0 ) {
        my Str $resource = self!resource-path(@resource);
        gather {
            for @dirs -> $config-dir {
                my $path = $config-dir.add($resource);

                if $path.d {
                    take $path;
                }
            }
        }
    }

    class X::InvalidResource is Exception {
        has Str $.message = "invalid resource description";
    }
    # return a somewhat sanitized path part that can be appended to
    # some config path based on the supplied resource description parts
    method !resource-path(*@resource where @resource.elems > 0) {

        if any(@resource) ~~ $*SPEC.updir {
            X::InvalidResource.new.throw;
        }
        my Str $resource = $*SPEC.catfile(@resource);

        if $resource.IO.is-absolute {
            X::InvalidResource.new(message => "absolute path $resource is not allowed").throw;
        }

        $resource;
    }
}



When XDG::BaseDirectory is C<use>d with the C<:terms> tag, the following
properties of a generic XDG::BaseDirectory object are exported as eponymous
terms:


item

=begin code

    use XDG::BaseDirectory :terms;

    say "Put config files into " ~ config-home ~ ", please.";

=end code


You can over-ride the default C<XDG::BaseDirectory> object used
in these C<terms> by assigning to the dynanic variabled C<$*XDG>:


=begin code

   use XDG::BaseDirectory :terms;

   my $*XDG = XDG::BaseDirectory.new( config-home => "foo".IO );

   ....

   say config-home; # -> "foo";

=end code



my  $XDG;

my sub xdg-basedirectory( --> XDG::BaseDirectory ) {
    $XDG //= ( $*XDG // XDG::BaseDirectory.new );
}

sub term:<data-home>   is export(:terms) { xdg-basedirectory.data-home   }
sub term:<data-dirs>   is export(:terms) { xdg-basedirectory.data-dirs   }
sub term:<config-home> is export(:terms) { xdg-basedirectory.config-home }
sub term:<config-dirs> is export(:terms) { xdg-basedirectory.config-dirs }
sub term:<cache-home>  is export(:terms) { xdg-basedirectory.cache-home  }
sub term:<runtime-dir> is export(:terms) { xdg-basedirectory.runtime-dir }

# vim: expandtab shiftwidth=4 ft=raku


BaseDirectory

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

XDG::BaseDirectory

image i_github_com_jonathanstowe_xdg_basedirectory_workflows_ci_badge_svg not found

Synopsis

Description

Installation

Support

Licence

XDG::BaseDirectory v0.0.13

Authors

License

Dependencies

Test Dependencies

Provides

Documentation