NAME

Zef::Configuration - Manipulate Zef configurations

SYNOPSIS

use Zef::Configuration;

my $zc = Zef::Configuration.new;         # factory settings

my $zc = Zef::Configuration.new(:user);  # user settings

my $zc = Zef::Configuration.new($io);    # from a config file path

Or use the command-line interface:

$ zef-configure

$ zef-configure enable something

$ zef-configure disable something

$ zef-configure reset

DESCRIPTION

Zef::Configuration is a class that allows you to manipulate the configuration of Zef programmatically. Perhaps more importantly, it provides a command-line script zef-configure that allows you to perform simple actions to Zef's config-files.

COMMAND-LINE INTERFACE

General named arguments

config-path

$ zef-configure --config-path=~/.zef/config.json

The config-path named argument can be used to indicate the location of the configuration to read from / write to.

dry-run

$ zef-configure enable rea --dry-run

The dry-run named argument can be used to inhibit writing any changes to the configuration file.

Possible actions

The zef-configure script that is installed with this module, allows for the following actions. Please note that sub-commands (such as "enable") can be shortened as long as they are not ambiguous..

Getting an overview

$ zef-configure

Calling zef-configure without any parameters (except maybe the config-path parameter) will show an overview of all the settings in the configuration. The names shown can be used to indicate what part of the configuration you want changed.

Enabling a setting

$ zef-configure enable rea

If a setting is disabled, then you can enable it with the enable directive, followed by the name of the setting you want enabled.

Disabling a setting

$ zef-configure disable cpan

If a setting is enabled, then you can disable it with the disable directive, followed by the name of the setting you want disabled.

Reset to factory settings

$ zef-configure reset

To completely reset a configuration to the "factory" settings, you can use the reset directive.

$ zef-configure reset --config-path=~/.zef/config.json

You can also use this function in combination with config-=path to create a configuration file with the "factory" settings.

GENERAL NOTES

All of the attributes of the classes provided by this distribution, are either an Array (and thus mutable), or a an attribute with the is rw trait applied to it. This is generally ok, since it is expected that this module will mostly only be used by a relatively short-lived CLI.

Note that if you change an object that is based on one of the default objects, you will be changing the default as well. This may or may not be what you want. If it is not, then you should probably first create a clone of the object, or use the clone method with named arguments to create a clone with changed values.

METHODS ON ALL CLASSES

All of these classes provided by this distribution provide these methods (apart from the standard methods provided by Raku).

new

Apart from the normal way of creating objects with named arguments, one can also specify a hash as returned with data to create an object.

data

Return a Raku data-structure for the object. This is usually a Map, but can also be a List.

json

Return a pretty JSON string with sorted keys for the object. Takes named parameters :!pretty and :!sorted-keys should you not want the JSON string to be pretty, or have sorted keys.

status

Return a string describing the status of the object.

METHODS ON MOST CLASSES

With the exception of the Zef::Configuration, Zef::Configuration::License and Zef::Configuration::RepositoryGroup classes, the following attributes / methods are always provided.

short-name

A name identifying the object. Must be specified in the creation of the object.

module

The name of the Raku module to be used by this object. Must be specified in the creation of the object unless there is a default available for the given object.

enabled

A boolean indicating whether the object is enabled. Defaults to True.

comment

Any comments applicable to this object. Defaults to the Str type object.

Zef::Configuration

The Zef::Configuration class contains all information about a configuration of Zef. A Zef::Configuration object can be made in 6 different ways:

CREATION

my $zc = Zef::Configuration.new;         # "factory settings"

my $zc = Zef::Configuration.new(:user);  # from the user's Zef config

my $zc = Zef::Configuration.new($io);    # from a file as an IO object

my $zc = Zef::Configuration.new($json);  # a string containing JSON

my $zc = Zef::Configuration.new(%hash);  # a hash, as decoded from JSON

my $zc = Zef::Configuration.new:         # named arguments to set attributes
  ConfigurationVersion => 2,
  RootDir              => 'foo/bar',
  ...
;

ATTRIBUTES / METHODS

It contains the following attributes / methods:

ConfigurationVersion

The version of the configuration. Defaults to 1.

RootDir

The directory in which Zef keeps all of its information. Defaults to $*HOME/.zef.

StoreDir

The directory in which Zef keeps all of the information that has been downloaded. Defaults to RootDir ~ "/store".

TempDir

The directory in which Zef stores temporary files. Defaults to RootDir ~ "/tmp".

License

A Zef::Configuration::License object. Defaults to Zef::Configuration.default-licenses<default>.

Repository

An array of Zef::Configuration::RepositoryGroup objects in the order in which they will be checked when searching for distributions. Defaults to Zef::Configuration.default-repository-groups in the order: primary, secondary, tertiary, last.

Fetch

An array of Zef::Configuration::Fetch objects. Defaults to Zef::Configuration.default-fetch.

Extract

An array of Zef::Configuration::Extract objects. Defaults to Zef::Configuration.default-extract.

Build

An array of Zef::Configuration::Build objects. Defaults to Zef::Configuration.default-build.

Test

An array of Zef::Configuration::Test objects. Defaults to Zef::Configuration.default-test.

Report

An array of Zef::Configuration::Report objects. Defaults to Zef::Configuration.default-report.

Install

An array of Zef::Configuration::Install objects. Defaults to Zef::Configuration.default-install.

DefaultCUR

An array of strings indicating which CompUnitRepository(s) to be used when installing a module. Defaults to Zef::Configuration.default-defaultCUR.

ADDITIONAL CLASS METHODS

is-configuration-writeable

Class method that takes an IO::Path of a configuration file (e.g. as returned by user-configuration) and returns whether that file is safe to write to (files part of the installation should not be written to).

new-user-configuration

Class method that returns an IO::Path with location at which a new configuration file can be stored, to be visible with future default incantations of Zef. Returns Nil if no such location could be found.

user-configuration

Class method that returns an IO::Path object of the configuration file that Zef is using by default.

ADDITIONAL INSTANCE METHODS

default-...

Instance methods for getting the default state of a given aspect of the Zef::Configuration object.

• default-license

• default-repository

• default-repositorygroup

• default-fetch

• default-extract

• default-build

• default-test

• default-report

• default-install

• default-defaultCUR

Each of these can either called without any arguments: in that case a Map will be returned with each of the applicable objects, associated with a tag. Or it can be called with one of the valid tags, in which case the associated object will be returned.

object-from-tag

Instance method that allows selection of an object by its tag (usually the short-name) in one of the attributes of the Zef::Configuration object.

Tags can be specified just by themselves if they are not ambiguous, else the group name should be prefixed with a hyphen inbetween (e.g. license-default).

If an ambiguous tag is given, then a List of Pairs will be returned in which the key is a group name, and the value is the associated object.

If only one object was found, then that will be returned. If no objects were found, then Nil will be returned.

Zef::Configuration::License

Contains which licenses are blacklisted and which ones are whitelisted. Defaults to no blacklisted licenses, and "*" in the whitelist, indicating that any license will be acceptable. Does not contain any other information.

Zef::Configuration::Repository

Contains the information about a repository in which distributions are located. It provided these additional attributes / methods:

name

The full name of the repository. Defaults to the short-name.

module

The Raku module to be used for handling the Zef::Configuration::Repository defaults to Zef::Repository::Ecosystems.

auto-update

The number of hours that should pass until a local copy of the distribution information about a repository should be considered stale. Defaults to 1.

uses-path

A boolean indicating whether the path field in the distribution should be used to obtain a distribution. Defaults to False, unless the repository's short-name equals zef.

mirrors

An array of URLs that should be used to fetch the information about all the distributions in the repository. Must be specified with the URL of at least one mirror if auto-update has been (implicitely) set to a non-zero value.

Zef::Configuration::RepositoryGroup

Contains a list of Zef::Configuration::Repository objects in the order in which a search should be done for modules. Does not contain any other information.

Zef::Configuration::Fetch

Information on how to fetch a distribution from a Zef::Configuration::Repository.

Zef::Configuration::Extract

Information on how to extract information from a fetched distribution.

Zef::Configuration::Build

Information on how to build modules from a fetched distribution.

Zef::Configuration::Test

Information on how to perform tesing on a fetched distribution.

Zef::Configuration::Report

Information about how a report of a distribution test should be reported.

Zef::Configuration::Install

Information about how a distribution should be installed.

AUTHOR

Elizabeth Mattijsen liz@raku.rocks

Source can be located at: https://github.com/lizmat/Zef-Configuration . Comments and Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a small sponsorship would mean a great deal to me!

COPYRIGHT AND LICENSE

Copyright 2022, 2023, 2024 Elizabeth Mattijsen

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