[Catalyst] doc patches and minor revelations

[Tomas Doran]

On 29 May 2009, at 19:43, Jarom Smith wrote:
>
> Pretend I'm a complete ignoramus... (that shouldn't be too hard,  
> LOL) If I were to want to submit a "doc patch", how would I go  
> about doing it and what exactly would I be submitting?
>

Right, so there are two things we want:

1) Documenting the answer to your question
2) Making that answer easy to find.

So lets go back in time a little:

On 27 May 2009, at 17:59, Jarom Smith wrote:
> In a Catalyst context, where do I put these kinds of "helper" DB  
> methods and how do I access them? (both from within a Catalyst app,  
> as well as from the command-line like in a Cron job or  
> whatever...)  Some actual specific examples would be great.  I'm  
> sure there is a way, and I'm guessing it involves the model somehow  
> (possibly by creating a new model class?) but I haven't been able  
> to figure it out yet.  I tried adding methods to the classes  
> created by Catalyst/DBIC in the Schema/Result directory, but  
> gradually it dawned on me that methods placed here are only dealing  
> with a single entity of that type.  To go back to Java-speak, it  
> seems like the stuff in Schema/Result are DTO methods; what I'm  
> trying to figure out is how/where to put the DAO methods.

So I guess the most obvious place for this doc would be in Catalyst- 
Model-DBIC-Schema - or at least, the documentation there should point  
you in the right direction!

Are there any other significant places you looked for documentation  
where it should also be mentioned? (You know - you just searched!)

And I guess that some of this is already documented in  
DBIx::Class::Schema::Loader.. So go read the documentation around  
there, and make a call about what should be added to the  
documentation there (if anything), what should be added in  
Catalyst::Model::DBIC::Schema, and any other places you think you  
should link it from..

Then check the relevant projects out of subversion:

http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Model-DBIC- 
Schema/
http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class-Schema-Loader/
http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/

Are the things I guess you may want to be patching.

Add some POD as you think is relevant (and use pod2text and/or  
pod2html to check it looks ok), make sure the tests still pass (as  
they'll test the pod structure for you), then when you're happy, svn  
diff and attach the diff to an email..

Someone will then review and apply, or send you some comments back.  
If you do this more than a couple of times, someone will hand you a  
commit bit so you can just commit directly.

Note the patch to DBIx-Class-Schema-Loader (if you think one is  
appropriate) is best sent to the dbic list.

> One revelation I had recently which I don't think has been  
> mentioned anywhere (at least not that I recall) is that when using  
> DBIC and Catalyst, *everything* is treated as a scalar.  (is this a  
> true statement?)  So in other words,
>
> my $people = $c->model('AddressDB::People')
>
> instead of
>
> my @people = $c->model('AddressDB::People')

Erm, I think you're a bit confused.

When you ask for: my $people = $c->model('AddressDB::People'), then  
you get an instance of a ResultSet (i.e. a blessed scalar). This  
doesn't hit the DB with a query.

To give you a list back, there have to be things in the list - ergo  
you need to go to the db.

my @people = $c->model('AddressDB::People')->all will do this for  
you, but beware, this will suck your entire table into RAM...

> This hit me while reading p. 41 of the book.  I'm not even totally  
> sure it's correct but things seem to work better when I adopt this  
> view-point, so it probably is correct.  It kind of makes sense,  
> because the Catalyst stash stores things using scalars (strings) as  
> keys, so if you just think of everything as a scalar (which could  
> be a ref to an array or hash) then things become slightly less  
> confusing.  At least, that's my current understanding.  I am still  
> very much muddling my way through all this stuff.

Erm, it's up to the specific method invoked what it wants to return.

Some methods implicitly behave differently when called in list or  
scalar context, some don't.

That's just perl.

Cheers
t0m

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.scsys.co.uk/pipermail/catalyst/attachments/20090530/e868df56/attachment.htm