/ 
Mite-0.005004
River stage zero No dependents
/ Mite::Manual::Syntax

NAME

Mite::Manual::Syntax - Moose-like syntax supported by Mite

MANUAL

Mite is a subset of Moose. These docs will only describe what Moose features are implemented or where they differ. For everything else, please read Moose and Moose::Manual.

import

To start a class:

use Your::Project::Mite;

To start a role:

use Your::Project::Mite -role;

By default, classes get has, extends, with, before, after, and around functions imported into them.

By default, roles get has, requires, with, before, after, and around functions imported into them.

You can list additional functions you want to import:

use Your::Project::Mite -role, qw( true false );

You can suppress importing default functions:

use Your::Project::Mite -role, qw( !before !after !around );

The -all flag imports everything possible.

has $name => %spec

Like has in Moose, this declares an attribute. Not all Moose options are supported.

is Enum["ro","rw","bare","rwp","lazy"]

Supported values for is include "ro", "rw", and "bare" like Moose, but also "rwp" and "lazy" like Moo. These are all just shortcuts for defining other options.

The default is is => 'bare'.

reader Maybe[Str]

The name of the attribute reader method to generate. If set to "1", will generate a reader called "get_foo" if your attribute is called "foo" and "_get__foo" if your attribute is called "_foo".

If your attribute is defined as is => "ro", is => "rwp", or is => "lazy" then reader defaults to $name.

If your reader contains "%s" this will be replaced by the name of the attribute. This allows:

# readers called "fetch_foo" and "fetch_bar"
has [ 'foo', 'bar' ] => (
    required => true,
    reader   => 'fetch_%s',
);
writer Maybe[Str]

The name of the attribute writer method to generate. If set to "1", will generate a writer called "set_foo" if your attribute is called "foo" and "_set__foo" if your attribute is called "_foo".

If your attribute is defined as is => "rwp", then writer defaults to "_set_$name".

If your writer contains "%s" this will be replaced by the name of the attribute.

accessor Maybe[Str]

The name of the dual-purpose attribute reader/writer method to generate. If set to "1", will generate a reader called "foo" if your attribute is called "foo" and "_foo" if your attribute is called "_foo".

If your attribute is defined as is => "rw", then accessor defaults to $name.

If your accessor contains "%s" this will be replaced by the name of the attribute.

clearer Maybe[Str]

The name of the attribute clearer method to generate. If set to "1", will generate a clearer called "clear_foo" if your attribute is called "foo" and "_clear__foo" if your attribute is called "_foo".

If your clearer contains "%s" this will be replaced by the name of the attribute.

predicate Maybe[Str]

The name of the attribute predicate method to generate. If set to "1", will generate a predicate called "has_foo" if your attribute is called "foo" and "_has__foo" if your attribute is called "_foo".

If your predicate contains "%s" this will be replaced by the name of the attribute.

handles HashRef|ArrayRef

Delegated methods. Currying and native traits are not supported.

If your handles hashref keys contain "%s", they will be replaced by the name of the attribute.

# $this->user_agent_get is a shortcut for $this->user_agent->get
#
has user_agent => (
    required => true,
    isa      => 'Object',
    handles  => {
        '%s_get'  => 'get',
        '%s_post' => 'post',
    },
);
init_arg Maybe[Str]

The parameter expected to be passed to the constructor to initialize this attribute. May be undef if the attribute should not be intitialized in the constructor.

Defaults to the attribute's name.

If your init_arg contains "%s" this will be replaced by the name of the attribute.

required Bool

Indicates whether the attribute is required in the parameter. If the attribute has a non-lazy default, this is ignored.

weak_ref Bool

Indicates that the attribute should weaken its reference to the attribute value.

isa Str|TypeTiny

A string type name from Types::Standard, Types::Common::String, or Types::Common::Numeric, or a blessed Type::Tiny object. If using a blessed object, you'll be introducing a dependency for your project on whatever type constraint library you're using, so prefer string type contraint names.

Any string supported by Type::Utils dwim_type is supported, so things like "Int | Enum['small', 'medium', 'large']" should work!

If you need custom types, you can add something like this to your .mite/config:

types: Your::Project::Types

The module Your::Project::Types would be a type library constructed with Type::Library. It should just contain type constraints and coercions which can be inlined, and none of your classes should load it directly (just rely on Mite to load it). This way you can use custom types in your project and your project will not have a dependency on Type::Library.

does Str|TypeTiny

Same as isa, but if the type name is unrecognized, assumes it was a role name instead of assuming it was a class name.

coerce Bool

Indicates that the attribute should attempt to coerce values to fit the type constraint.

trigger CodeRef|Maybe[Str]

If set to a string, is the name of a method to call whenever a new attribute value is set. This is not called when an attribute is defaulted. If set to "1", will assume a trigger called "_trigger_foo" if your attribute is called "foo" and "_trigger__foo" if your attribute is called "_foo".

If set to a coderef, acts like it was set to "1" but installs the coderef into your class with that name.

If your trigger method name contains "%s" this will be replaced by the name of the attribute.

default Undef|Str|CodeRef|ScalarRef

A default value for the attribute, or a coderef called as a method to generate that default value.

Unlike Moose, you can alternatively include an inline string of Perl code as a ScalarRef:

has list => (
    is => 'ro',
    isa => 'ArrayRef',
    default => \ '[]',
);

This has performance benefits over using a coderef as it avoids the overhead of a sub call.

builder Str|CodeRef

If set to a string, is the name of a method to call to build the default attribute value. If set to "1", will assume a builder called "_build_foo" if your attribute is called "foo" and "_build__foo" if your attribute is called "_foo".

If you used is => "lazy", this will default to "1".

If set to a coderef, acts like it was set to "1" but installs the coderef into your class with that name.

If your builder method name contains "%s" this will be replaced by the name of the attribute.

lazy Bool

Indicates that the default should be set lazily. Defaults to false unless you used is => "lazy".

alias Str|ArrayRef[Str]

A list of aliases for the attibutes. If the attribute has an init_arg (including a default one), this provides alternative initialization arguments. If the attribute is => "rw", then these aliases are aliases for the accessor; otherwise they are aliases for the reader.

The strings can contain "%s" which will be replaced by the attribute name, allowing this to work:

has [ 'foo', 'bar' ] => (
    is => 'ro',
    alias => 'get_%s',
);

If you try to create aliases but don't have a reader or accessor, then as a last resort the alias will be an alias for the writer.

# foo can be set using `set_foo` or `whatever`
#
has foo => (
    is => 'bare',
    writer => 1,
    alias => 'whatever',
);

Aliases are not natively supported by Moose, but this feature is analagous to MooseX::Aliases.

documentation Any

This option is ignored, but you can set it to a documentation string for your attribute.

has name => (
    is => 'rwp',
    isa => 'Str',
    documentation => 'First name and surname',
);

Multiple attributes can be defined using an arrayref.

# Defines get_foo, get_bar, set_foo, and set_bar.
#
has [ 'foo', 'bar' ] => (
    isa => 'Str',
    reader => 1,
    writer => 1,
);

Like in Moose, you can use a plus sign to modify an attribute definition from a role or parent class:

has '+foo' => (
    default => sub { 'new default' },
);

When modifying an attribute, you cannot use is.

extends @parents

Works as in Moose.

You cannot use extends from within roles.

Options hashrefs, including the -version option are not implemented.

requires @methods

Works as in Moose.

You cannot use requires from within classes.

with @roles

Works as in Moose.

Roles must be Mite roles created in your own project, or Role::Tiny roles. Mite does not support using roles from other projects, or using role implementations other than Mite and Role::Tiny.

Options hashrefs, including the -version option are not implemented.

strict

Mite will turn strict on for you.

warnings

Mite will turn warnings on for you.

BUILDARGS

Works as in Moose.

FOREIGNBUILDARGS

Works as in Moo and MooseX::NonMoose.

BUILD / BUILDALL.

Works as in Moose.

DEMOLISH

Works as in Moose.

On Perl older than 5.14, the $in_global_destruction argument will be undefined unless Devel::GlobalDestruction is installed, so add that to your project's dependencies if you are relying on it and need to support older versions of Perl.

Strict Constructor

Mite provides a similar feature to MooseX::StrictConstructor, so your constructor will die if you pass it unknown attributes.

Chainable Writers

Mite provides a similar feature to MooseX::Attribute::Chained, so writer methods, clearer methods, and accessor methods used as writers all return $self, so they can be chained:

$object->clear_foo->set_bar( 42 )->set_baz( 99 );

Method Modifiers

Basic versions of the before, around, and after method modifiers are provided, but these may run in a different order from Moose if you use several modifiers on the same method.

Booleans

Although they're not imported by default, you can import true and false keywords. They can made attribute definitions a little prettier:

use Your::Project::Mite qw( true false );
# OR:
use Your::Project::Mite qw( -bool );

has foo => (
    is => 'rw',
    required => true,
);

Constants for "is"

You can export constants called ro, rw, rwp, bare, and lazy. Again, these can make attribute definitions prettier:

use Your::Project::Mite qw( ro rw );
# OR:
use Your::Project::Mite qw( -is );

has foo => ( is => rw, required => true );

param and field keywords

The param and field keywords are available, like MooseX::Extended.

use Your::Project::Mite qw( param field !has );

param foo => ( isa => 'Str' );

carp, croak, and confess

These functions can be exported to your class:

use Your::Project::Mite qw( croak );

sub my_method {
    croak 'Not implemented yet';
}

The functions provided are superpowered versions of the ones from Carp. If called with multiple arguments, the first is treated as a format string for sprintf and the remainder are passed through Data::Dumper if they are references.

sub my_method {
    my $self = shift;
    croak '%s does not implement this method', ref( $self );
}

blessed

blessed from Scalar::Util can also be imported.

use Your::Project::Mite qw( blessed );

Clean Classes

Mite will automatically import namespace::autoclean into your classes if it is installed on the end user's system. If it's not available, your classes will quietly be left with imported keywords cluttering up their namespace.

To force namespace::autoclean, then just use it manually:

use Your::Project::Mite;
use namespace::autoclean;

To force it to not be used:

use Your::Project::Mite qw( -unclean );

BUGS

Please report any bugs to https://github.com/tobyink/p5-mite/issues.

AUTHOR

Michael G Schwern <mschwern@cpan.org>.

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2011-2014 by Michael G Schwern.

This software is copyright (c) 2022 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.