App-Raider
2 results

 view release on metacpan or  search on metacpan

.claude/skills/perl-moose/SKILL.md  view on Meta::CPAN 

};

after 'save' => sub {
    my ($self, @args) = @_;
    $self->log("saved");                         # side effects; cannot change return value
};

around 'calculate' => sub {
    my ($orig, $self, $x) = @_;
    return 0 if $x < 0;
    return $self->$orig($x) * 2;                # CAN change return value
};
```

**Execution order:** `before` (LIFO), then `around` (LIFO, wrapping), then original, then `after` (FIFO).

**Rules:** `before`/`after` cannot alter return value; `around` can. Always capture and forward `@_` correctly in `around`. Multiple modifiers from multiple roles stack in composition order.

---

## Pattern 11 – `augment` / `inner` (Inverted Inheritance)

```perl
package Report;
use Moose;
use namespace::autoclean;
sub render {
    my $self = shift;
    "<html>" . inner() . "</html>";    # inner() calls augment from child
}
__PACKAGE__->meta->make_immutable;

package PDFReport;
use Moose;
use namespace::autoclean;
extends 'Report';
augment 'render' => sub {
    my $self = shift;
    "<pdf>" . inner() . "</pdf>";     # chain further down if needed
};
__PACKAGE__->meta->make_immutable;
```

Use when the parent defines the *frame* and children fill in the *content*. Rare — only when the parent controls the wrapper structure.

---

## Pattern 12 – Constructor Lifecycle

```perl
around BUILDARGS => sub {
    my ($orig, $class, @args) = @_;
    # normalize: allow single string arg
    return $class->$orig(id => $args[0]) if @args == 1 && !ref $args[0];
    $class->$orig(@args);
};

sub BUILD {
    my ($self, $args) = @_;     # called AFTER all attributes are set
    die "SSN required for US" if $self->country eq 'USA' && !$self->ssn;
    # don't call SUPER::BUILD — Moose handles the chain (parent→child order)
}
```

**Rules:**
- Never define `sub new` — use `BUILDARGS`/`BUILD` instead.
- `BUILDARGS`: class method, runs before construction, returns hashref.
- `BUILD`: object method, runs after construction. Moose calls all `BUILD` in the hierarchy automatically.
- Never call `SUPER::BUILD` manually.
- For cleanup: use `DEMOLISH` (child→parent order), never override `DESTROY`.

---

## Pattern 13 – `make_immutable` + `namespace::autoclean`

```perl
package MyClass;
use Moose;
use namespace::autoclean;          # remove imported keywords after compile

has name => (is => 'ro', required => 1);

__PACKAGE__->meta->make_immutable; # ALWAYS — massive perf gain on object creation
```

**Rules:**
- `namespace::autoclean` goes at the top (after `use Moose`), `make_immutable` at the bottom.
- After `make_immutable`: no more dynamic `add_attribute`, `add_role` etc.
- `namespace::autoclean` removes `has`, `with`, `extends` etc. from the symbol table — they won't accidentally become methods.

---

## Pattern 14 – Type Constraints

```perl
use Moose::Util::TypeConstraints;

subtype 'PositiveInt',
    as 'Int',
    where { $_ > 0 },
    message { "$_ is not a positive integer" };

coerce 'PositiveInt',
    from 'Str',
    via { int($_) };

# Or use Type::Tiny (recommended — works with both Moo and Moose):
use Types::Standard qw(Str Int ArrayRef InstanceOf);
has name => (is => 'ro', isa => Str);
has items => (is => 'ro', isa => ArrayRef[Str], default => sub { [] });
```

Prefer `Type::Tiny` / `Types::Standard` — portable between Moo and Moose, better error messages.

---

## Decision Guide

| Situation | Use |
|---|---|
| Shared attributes/methods, stable "is-a" | `extends` |
| Optional/horizontal feature | `Moose::Role` + `with` |
| Enforce interface contract | `requires` |
| Same role, different config | `MooseX::Role::Parameterized` |
| Delegate method set to sub-object | `handles` (list/hash/role form) |
| Array/Hash/Counter operations | `traits => ['Array']` + `handles` |
| Logging/validation/caching wrapper | `before`/`around`/`after` |
| Parent defines frame, child fills content | `augment`/`inner` |
| Normalize constructor args | `around BUILDARGS` |
| Post-construction validation/setup | `BUILD` |
| Catch constructor typos | `MooseX::StrictConstructor` |
| Named types with coercion | `Type::Tiny` / `Moose::Util::TypeConstraints` |
| Multiple roles define same method | Resolve in class or `-alias`/`-excludes` |
| Metaclass extensions | `traits` on attributes or class |
| Per-instance behavior change | `Moose::Util::apply_all_roles` |

---

## Common Pitfalls

- `default => []` → **shared state bug**. Always `default => sub { [] }`.
- `extends 'A'; extends 'B'` → replaces, does NOT add. Use `extends 'A', 'B'`.
- Separate `with 'RoleA'; with 'RoleB'` → skips conflict detection. Use one `with`.
- `with` before `has` → `requires` check may fail spuriously. Define `has` first.
- `coerce` on built-in type names → global side effects across the whole program.
- Never define `sub new` — breaks Moose constructor optimization.
- Never call `SUPER::BUILD` manually — Moose handles the chain.
- Never override `DESTROY` — use `DEMOLISH`.
- Forgetting `make_immutable` → significant performance penalty on every `new`.
- `around` without forwarding `@_` correctly → subtle argument loss.

---

## MooseX Extensions (Cheatsheet)

| Module | Purpose |
|---|---|
| `MooseX::StrictConstructor` | Dies on unknown constructor args |
| `MooseX::Role::Parameterized` | Parameterized roles |
| `MooseX::ClassAttribute` | Class-level (shared) attributes |
| `MooseX::Types` | Named type libraries |
| `MooseX::Singleton` | Singleton pattern (`->instance`) |
| `MooseX::Getopt` | Auto CLI options from attributes |
| `MooseX::Storage` | Serialization/deserialization |



( run in 1.381 second using v1.01-cache-2.11-cpan-800906f7e73 )