README.pod6

=begin pod

[![Build Status](https://github.com/Kaiepi/ra-Kind/actions/workflows/test.yaml/badge.svg)](https://github.com/Kaiepi/ra-Kind/actions/workflows/test.yaml)

=head1 NAME

Kind - Typechecking based on kinds

=head1 SYNOPSIS

=begin code :lang<raku>
use Kind;

my constant Class = Kind[Metamodel::ClassHOW];

proto sub is-class(Mu --> Bool:D)  {*}
multi sub is-class(Class --> True) { }
multi sub is-class(Mu --> False)   { }

say Str.&is-class;  # OUTPUT: True
say Blob.&is-class; # OUTPUT: False
=end code

=head1 DESCRIPTION

C<Kind> is an uninstantiable parametric type that can be used to typecheck
values based off their kind. A parameterization produces a type object that can
process the HOW of a type in a typecheck context with C<ACCEPTS> when
available, otherwise falling back to the bare typecheck.

C<Kind> is documented. You can view the documentation for it and its methods at
any time using C<WHY>.

=head1 METAMETHODS

=head2 method parameterize

=for code :lang<raku>
method ^parameterize(|args) is raw

Produces a parameterization by delegating to C<^kind> with C<args>.

=head2 method kind

=for code :lang<raku>
method ^kind(Mu $obj is raw, Mu \K, Mu:U \T = Mu) is raw

Produces a cached subset with a refinement (C<where>) built from C<K> and a
refinement (C<of>) from C<T> if present. This backs C<^parameterize> so as to
allow for a different parameterizer in a subtype. This is more or less a
wrapper for C<Metamodel::Primitives.parameterize_type>.

Some useful values with which to produce a type are:

=item a metaclass or metarole

=for code :lang<raku>
# Smartmatches any class.
Kind[Metamodel::ClassHOW]

=item a junction of metaclasses or metaroles

=for code :lang<raku>
# Smartmatches any type that supports naming, versioning, and documenting.
Kind[Metamodel::Naming & Metamodel::Versioning & Metamodel::Documenting]

=item a block

=for code :lang<raku>
# Smartmatches any parametric type.
Kind[{ use nqp; nqp::hllbool(nqp::can($_, 'parameterize')) }]

=item a metaobject

=begin code :lang<raku>
# This class' metamethods constrain their metaobject to itself or its subtypes.
class Configurable {
    my constant K := Kind[$?CLASS.HOW.WHAT, $?CLASS];

    my constant %configuration := hash;

    method ^configure(K $obj, %config --> Map:D) {
        %configuration{$obj.WHAT.WHICH} := %config.Map
    }

    method ^configuration(K $obj --> Map:D) {
        %configuration{$obj.WHAT.WHICH} // Map.new
    }
}
=end code

For more examples of parameterizations of C<Kind>, refer to
C<t/01-typecheck.t>.

=head1 SYMBOLS

=head2 &set_parameterizer

=for code :lang<raku>
our sub set_parameterizer(Mu $obj is raw, &parameterizer = &parameterize --> Nil)

Applies the parameterizer of C<Kind> to a metaobject, providing it with a
parameterization cache. A subtype needs to apply this at C<BEGIN>-time in order
to parameterize with the default metamethods, for instance:

=for code :lang<raku>
class Kind::Instantiable is Kind {
    BEGIN Kind::set_parameterizer($?CLASS);
}

A C<&parameterizer> may be provided, in which case that will be set instead.
This should carry a compatible signature with C<&parameterize>.

For more examples of how to subclass C<Kind>, refer to C<t/02-meta.t>.

=head2 &parameterize

=for code :lang<raku>
our sub parameterize(Mu $root is raw, Any $args) is raw

Given the C<$root> metaobject of the parameterization and its C<$args>,
produces a type object minus the caching. C<$args> is assumed to carry C<K> at
position C<0> and C<T>, if present, at position C<1>.

=head1 AUTHOR

Ben Davies (Kaiepi)

=head1 COPYRIGHT AND LICENSE

Copyright 2022 Ben Davies

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

=end pod