Request for clarification of $class in B::W::Help::Config

[cxw42]

I am reading more about Beam::Wire in order to understand Statocles config files. I have a few questions about $class in B::W::Help::Config and would appreciate clarification in the documentation.

The "prefixed metadata" section gives an example of "mak[ing] a 'default class' in your config file" using $class: Person. That example calls Beam::Wire::get('person'). However, from the get() docs and this example, it's not clear to me how it works. Would you be willing to expand the example somewhat? For example, the get() docs don't say when get() would return a non-blessed instance. I also do not understand how $class (call the constructor with a hashref of arguments) relates to the "default class" referenced in the docs.

In the Event Handlers (on) section, $class is described as creating an "anonymous object". Does that mean that using $class will always create a hashref? If so, what is the argument of the $class config key used for?

Finally, "Specifying Constructor Args" says that you can pass a hashref of arguments to the constructor by giving class => Foo, args => [{x=>1, y=>2}]. Is $class just shorthand for that? It seems to me it may not be, but I am not sure.

Thanks in advance for any clarification you may be able to provide!

[preaction]

Sorry, yeah, that's a bit confusing because I added $class after the original version had class: and args: as separate things, and not all the documentation got fully-updated it looks like...

For the default class: Beam::Wire only inflates an object if it sees certain indicators that an object is being configured at that point: $class is one indicator, class: and args: is another (the is_meta method does this checking). If Beam::Wire doesn't conclude it's an object, then it must be a hashref (only YAML dictionaries get passed to is_meta) and get() will return that hashref. Then the code can check that it did/didn't get a blessed object and do the right thing. This makes the config file look less weird, because there is no requirement for $class metadata (which requires explaining what that is, how it works, and Beam::Wire itself).

So if I have a "Person" class and a config file with only a HashRef, I can still make sure I get a Person object by either manually checking that the result from get() is blessed, or (more likely) by using coercions from Moose/Type::Tiny (class_type PersonType, { class => 'Person' }; coerce PersonType, from HashRef, via { "Person"->new( %$_ ) }).

# people.yml
# This is not an object to Beam::Wire, but it could be coerced in to one
zoe:
   name: Zoe Washburne
   rank: Commander

my $person = $wire->get( $name );
use Scalar::Util qw( blessed );
$person = Person->new( %$person ) if !blessed $person; # Someone forgot to add $class

But if it's just a data structure, why use Beam::Wire? Because if a more-advanced user adds a $class, they can create a custom Person class of their own to provide custom behavior that can't be added any other way (e.g. can't compose a role with $with).

So, get() returns whatever it finds based on the path you give it. For zoe, above, it would return a hashref. For get( 'zoe/name' ) it will happily return a string: Zoe Washburn. Not everything in the config file has to be an object, and that helps make repeated configurations less messy (don't copy-paste a bunch of usernames/passwords around, use $ref!)

For the event handlers part: That's a bit outdated. It used to be that $class only worked inside of other objects, like this:

# Old-style (ugly)
zoe:
    class: Person
    args:
        name: Zoe Washburne
        spouse:
            $class: Person
            $args:
                name: Hoban Washburne

When I made it so $class worked everywhere, I must've missed that part of the docs. Still, the spouse object in there has no top-level name. It might work to get that object via get( 'zoe/args/spouse' ), but the code couldn't possibly know that the author of the config file added that object in that place in that way (so it can't really try). Like an anonymous hashref can be accessed only via the reference created (my $hr = { foo => "bar" }), so too can the spouse really only be accessed via the outer object (my $spouse = get( 'zoe' )->spouse assuming a spouse attribute on the Person class). $class always means that Beam::Wire will try to call a specific constructor when asked to get() that item.

Finally, for the args: [{ ... }]: $class is a shorthand for a constructor that takes a list of name/value pairs (a hash, not a reference to a hash). The following two objects are equivalent:

oldstyle:
    class: Person
    args:
        name: River Song
newstyle:
    $class: Person
    name: River Song

This works for Moo, Moose, Mojo::Base, and most modern Perl object systems, but some object constructors take specific positional arguments, or references. For this, if Beam::Wire sees an arrayref, it passes the contents of the arrayref directly to the constructor:

# DBI->connect( 'dbi:SQLite:mydata.db' )
oldstyle_dbh:
    class: DBI
    method: connect
    args:
        - 'dbi:SQLite:mydata.db'
newstyle_dbh:
    $class: DBI
    $method: connect
    $args: # $args is required to get this behavior
        - 'dbi:SQLite:mydata.db'

So, the way to get a single hashref to a constructor is to use an arrayref:

# Person->new( { name => 'Zoe Washburne' } );
zoe:
    $class: Person
    $args:
        - name: Zoe Washburne

Unfortunately, it doesn't look like any of my conference talks on Beam::Wire made it to Youtube, though these slides (Dependency Injection with Perl) do a good job of outlining the real problem Beam::Wire is solving (the config file thing being ... not a side-effect really but a convenience feature...)

Does that make more sense now? This is absolutely one of those things for me where I didn't really understand what I was building until I built it, so if I can make it easier to understand please keep asking questions 😄.