txt: ## dist_zef-masukomi-XDG-GuaranteedResources.md
  # NAME
  
  XDG::GuaranteedResources - Guarantees that a resource is present in the expected XDG Base Directory directory
  
  # SYNOPSIS
  
  First, you need to implement a class that can get resources from within your package. I suggest you copy this, and change the class name. Alas, this is not something that another package like this one can provide.
  
  ```
  use XDG::GuaranteedResources::AbstractResourcer;
  
  unit class My::Resourcer does XDG::GuaranteedResources::AbstractResourcer;
  
  # for XDG::GuaranteedResources::AbstractResourcer
  method fetch-resource(::?CLASS:U:){%?RESOURCES;}
  
  ```
  
  Once you've got that, you can just pass it in as the 2nd param to either of the provided methods, or assign it to a variable and pass that in.
  
  ```
  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/my_app/app_config.toml", My::Resourcer);
  
  # assigning your resourcer to a variable is fine.
  my $resourcer = My::Resourcer;
  # if you have multiple to guarantee you pass a list to the plural form.
  guarantee-resources(<config/my_app/app_config.toml data/my_app/cool_database.db>, $resourcer);
  
  ```
  
  # DESCRIPTION
  
  Many tools expect a config file, sqlite database, or similar to be present. We store these in the resources listed in `META6.json`, and need to test if they exist and copy them over from `resources` if not.
  
  `XDG::GuaranteedResources` handles this common operation.
  
  For example:
  
  Let's assume your script uses a pre-prepared sqlite db that you store under resources. Store it under `resources/data/my_app/my_database.db`, then when your script boots up you can call `guarantee-resource("data/my_app/my_database.db");`. If that file already exists under `%*ENV<XDG_CONFIG_HOME>/my_app/my_database.db` nothing will happen. If it isn't found there, a fresh copy will be placed there from the one you referenced in `resources`.
  
  Note that `my_app` should be the directory name your apps files should be stored under. For example, a config file for [clu](https://github.com/masukomi/clu) would be stored under `~/.config/clu/` after install. So, you would store it under `resources/config/clu/` in your package.
  
  Resources that should be copied to `XDG_CONFIG_HOME` should be stored under `resources/config/my_app`
  
  Resources that should be copied to `XDG_DATA_HOME` should be stored under `resources/data/my_app`
  
  Subdirectories are fine. E.g. `resources/data/my_app/subdir/my_db.db`
  
  ⚠ Currently only works on Unix (Linux, BSD, macOS, etc.) systems.
  
  # AUTHOR
  
  Kay Rhodes a.k.a masukomi ([masukom@masukomi.org](mailto:masukom@masukomi.org))
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2022
  
  This library is free software; you can redistribute it and/or modify it under the MIT License.
  
  ### multi sub guarantee-resource
  
  ```
  multi sub guarantee-resource(
      Str $resource_path,
      $resourcer
  ) returns Str
  
  ```
  
  Guarantees a resource is present & provides the path it can be found at.
  
  ### sub guarantee-resources
  
  ```
  sub guarantee-resources(
      @resource_paths,
      $resourcer
  ) returns Array
  
  ```
  
  Guarantees a list of resources are present. Returns the paths they can be found at.
  