/ 
Mooish-AttributeBuilder-0.001
River stage one • 4 direct dependents • 6 total dependents
/ Mooish::AttributeBuilder

NAME

Mooish::AttributeBuilder - build Mooish attribute definitions with less boilerplate

SYNOPSIS

use Moo; # or Moose or Mouse or ...
use Mooish::AttributeBuilder;

# this attribute is required in the constructor
has param 'param_name';
has param 'param_name' => (
	...
);

# this attribute is optional in the constructor
has option 'option_name';
has option 'option_name' => (
	...
);

# this attribute is not available in the constructor
has field 'field_name';
has field 'field_name' => (
	...
);

# this extends parent attribute, much like: has '+name_to_extend'
has extended 'name_to_extend' => (
	...
);

DESCRIPTION

This module implements shortcuts and helpers for has keyword in Moose family of modules.

The shortcuts provided are similar to those in MooseX::Extended or MooX::Keyword::Field, but they don't depend on specific OO system. Instead, those shortcuts are just modifying option lists which are then passed to has. This way you can use the module with any OO system which supports the Moose set of has parameters.

Beta: interface is not yet stable before version 1.000.

EXPORTED FUNCTIONS

All functions are exported by default.

field

has field $field_name => %more_options;

This function produces a property that cannot be passed to the constructor:

has $field_name => (
	is => 'ro',
	init_arg => undef,
	%more_options
);

param

has param $param_name => %more_options;

This function produces a property that is required in the constructor:

has $param_name => (
	is => 'ro',
	required => 1,
	%more_options
);

option

has option $option_name => %more_options;

This function produces a property that is optional in the constructor and has a predicate:

has $option_name => (
	is => 'ro',
	required => 0,
	predicate => "has_${option_name}",
	%more_options
);

extended

has extended $name_to_extend => %more_options;

This function does not introduce any extra hash keys, but adds a plus sign before the name:

has "+${name_to_extend}" => (
	%more_options
);

SHORTCUTS

The %more_options hash can contain some shortcuts that will be expanded by "option", "param", "field" or "extended" functions.

method name shortcuts

The following values:

1
-public
-hidden

... can be passed to the following options, producing standard method names with given prefixes:

reader:    get_
writer:    set_
predicate: has_
clearer:   clear_
builder:   _build_
trigger:   _trigger_

The naming rules are as follows:

  • Properties starting with an underscore produce hidden methods when passed 1 (starting with underscore as well)

    has field '_name' => (
	reader => 1
);

# ... becomes:
has '_name' => (
	...
	reader => '_get_name'
);

  • Properties not starting with an underscore produce public methods when passed 1 (not starting with underscore)

    has field 'name' => (
	writer => 1
);

# ... becomes:
has 'name' => (
	...
	writer => 'set_name'
);

  • Visibility can be forced by passing -public or -hidden instead of 1

    has field '_name' => (
	predicate => -public
);

# ... becomes:
has '_name' => (
	...
	predicate => 'has_name'
);


has field 'name' => (
	predicate => -hidden
);

# ... becomes:
has 'name' => (
	...
	predicate => '_has_name'
);

  • builder and trigger are hidden by default. The only way to have them not start with an underscore (other than passing the name explicitly) is to pass -public.

    These two options also don't change the name based on the leading underscore in property's name. Builders for property and _property will by default both be _build_property.

lazy + default

lazy => sub { return 'default value' }

... will be expanded to:

lazy => 1,
default => sub { return 'default value' }

lazy + builder

lazy => 'builder_name'

... will be expanded to:

lazy => 1,
builder => 'builder_name'

Note: passing 1 will work as described in "method name shortcuts".

isa + coerce

coerce => Types::Standard::Int

... will be expanded to:

isa => Types::Standard::Int,
coerce => 1

As long as it is a blessed reference (object).

builder / default + required

Having a builder or a default will automatically remove required from the option list.

# will no longer be required in the constructor
has param 'optional' => (
	default => undef,
);

init_arg

init_arg can use the same shortcuts as described in "method name shortcuts".

This can be useful to turn _name into name in the constructor with the help of -public:

# no underscore in the constructor
has param '_name' => (
	init_arg => -public
);

trigger

In addition to shortcuts described in "method name shortcuts", trigger can now be passed both as a anon sub (like default) or as a package sub name (like builder).

CAVEATS

All attributes produced are 'ro' by default

Since the module does not depend on specific OO implementation, the only common is => options are ro and rw (as in base Moose). The author considers rw to be a bad idea most of the time. Having one method for reading and writing can lead to bugs that are hard to spot.

Other than that:

writer => -hidden shortcut does more or less what rwp does.

lazy => 1 shortcut does more or less what lazy does.

Partial MooseX::AttributeShortcuts compatibility

The module implements many of the shortcuts from MooseX::AttributeShortcuts, but does not aim to have 100% compatibility. Some details in overlapping functionality may differ.

SEE ALSO

MooseX::Extended
MooseX::AttributeShortcuts

AUTHOR

Bartosz Jarzyna <bbrtj.pro@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2022 by Bartosz Jarzyna

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