[Jifty-commit] r5991 - Net-Jifty/trunk/lib/Net
Jifty commits
jifty-commit at lists.jifty.org
Mon Nov 17 06:39:19 EST 2008
Author: ruz
Date: Mon Nov 17 06:39:16 2008
New Revision: 5991
Modified:
Net-Jifty/trunk/lib/Net/Jifty.pm
Log:
* rework documentation
Modified: Net-Jifty/trunk/lib/Net/Jifty.pm
==============================================================================
--- Net-Jifty/trunk/lib/Net/Jifty.pm (original)
+++ Net-Jifty/trunk/lib/Net/Jifty.pm Mon Nov 17 06:39:16 2008
@@ -680,7 +680,78 @@
the config file for the username and password (or SID) of the user. If neither
is available, it will prompt the user for them.
-=head2 BUILD
+=head1 METHODS
+
+=head2 CRUD - create, read, update and delete.
+
+=head3 create MODEL, FIELDS
+
+Create a new object of type C<MODEL> with the C<FIELDS> set.
+
+=head3 read MODEL, KEY => VALUE
+
+Find some C<MODEL> where C<KEY> is C<VALUE> and return it.
+
+=head3 update MODEL, KEY => VALUE, FIELDS
+
+Find some C<MODEL> where C<KEY> is C<VALUE> and set C<FIELDS> on it.
+
+=head3 delete MODEL, KEY => VALUE
+
+Find some C<MODEL> where C<KEY> is C<VALUE> and delete it.
+
+=head2 Other actions
+
+=head3 search MODEL, FIELDS[, OUTCOLUMN]
+
+Searches for all objects of type C<MODEL> that satisfy C<FIELDS>. The optional
+C<OUTCOLUMN> defines the output column, in case you don't want the entire
+records.
+
+=head3 act ACTION, ARGS
+
+Perform any C<ACTION>, using C<ARGS>. This does use the REST interface.
+
+=head2 Arguments of actions
+
+Arguments are treated as arrays with (name, value) pairs so you can do the following:
+
+ $jifty->create('Model', x => 1, x => 2, x => 3 );
+
+Some actions may require file uploads then you can use hash reference as value with
+content, filename and content_type fields. filename and content_type are optional.
+content_type by default is 'application/octeat-stream'.
+
+=head3 validate_action_args action => args
+
+Validates the given action, to check to make sure that all mandatory arguments
+are given and that no unknown arguments are given.
+
+Arguments are checked CRUD and act methods if 'strict_arguments' is set to true.
+
+You may give action as a string, which will be interpreted as the action name;
+or as an array reference for CRUD - the first element will be the action
+(create, update, or delete) and the second element will be the model name.
+
+This will throw an error or if validation succeeds, will return 1.
+
+=head2 Specifications of actions and models
+
+=head3 get_action_spec NAME
+
+Returns the action spec (which arguments it takes, and metadata about them).
+The first request for a particular action will ask the server for the spec.
+Subsequent requests will return it from the cache.
+
+=head3 get_model_spec NAME
+
+Returns the model spec (which columns it has). The first request for a
+particular model will ask the server for the spec. Subsequent requests will
+return it from the cache.
+
+=head2 Subclassing
+
+=head3 BUILD
Each L<Net::Jifty> object will do the following upon creation:
@@ -696,32 +767,41 @@
=back
-=head2 login
+=head3 login
+
+This method is called automatically when each L<Net::Jifty> object is
+constructed (unless a session ID is passed in).
This assumes your site is using L<Jifty::Plugin::Authentication::Password>.
If that's not the case, override this in your subclass.
-This is called automatically when each L<Net::Jifty> object is constructed
-(unless a session ID is passed in).
+=head3 prompt_login_info
-=head2 call ACTION, ARGS
+This will ask the user for her email and password. It may do so repeatedly
+until login is successful.
+
+=head3 call ACTION, ARGS
This uses the Jifty "web services" API to perform C<ACTION>. This is I<not> the
REST interface, though it resembles it to some degree.
This module currently only uses this to log in.
-=head2 form_url_encoded_args ARGS
+=head2 Requests helpers
-This will take a hash containing arguments and convert those arguments into URL encoded form. I.e., (x => 1, y => 2, z => 3) becomes:
+=head3 post URL, ARGS
- x=1&y=2&z=3
+This will post C<ARGS> to C<URL>. See the documentation for C<method> about
+the format of C<URL>.
-These are then ready to be appened to the URL on a GET or placed into the content of a PUT.
+=head3 get URL, ARGS
-=head2 method METHOD, URL[, ARGS]
+This will get the specified C<URL> with C<ARGS> as query parameters. See the
+documentation for C<method> about the format of C<URL>.
+
+=head3 method METHOD, URL[, ARGS]
-This will perform a GET, POST, PUT, DELETE, etc using the internal
+This will perform a C<METHOD> (GET, POST, PUT, DELETE, etc) using the internal
L<LWP::UserAgent> object.
C<URL> may be a string or an array reference (which will have its parts
@@ -733,92 +813,70 @@
This will return the data structure returned by the Jifty application, or throw
an error.
-=head2 post URL, ARGS
-
-This will post C<ARGS> to C<URL>. See the documentation for C<method> about
-the format of C<URL>.
-
-=head2 get URL, ARGS
-
-This will get the specified C<URL> with C<ARGS> as query parameters. See the
-documentation for C<method> about the format of C<URL>.
-
-=head2 act ACTION, ARGS
-
-Perform C<ACTION>, using C<ARGS>. This does use the REST interface.
-
-=head2 create MODEL, FIELDS
-
-Create a new object of type C<MODEL> with the C<FIELDS> set.
-
-=head2 delete MODEL, KEY => VALUE
-
-Find some C<MODEL> where C<KEY> is C<VALUE> and delete it.
+=head3 form_url_encoded_args ARGS
-=head2 update MODEL, KEY => VALUE, FIELDS
+This will take an array containing (name, value) argument pairs and
+convert those arguments into URL encoded form. I.e., (x => 1, y => 2, z => 3) becomes:
-Find some C<MODEL> where C<KEY> is C<VALUE> and set C<FIELDS> on it.
+ x=1&y=2&z=3
-=head2 read MODEL, KEY => VALUE
+These are then ready to be appened to the URL on a GET or placed into
+the content of a PUT. However this method can not handle file uploads
+as they must be sent using 'multipart/form-date'.
-Find some C<MODEL> where C<KEY> is C<VALUE> and return it.
+See also L</"form_form_data_args ARGS"|"form_form_data_args"> and
+L</"Arguments of actions">.
-=head2 search MODEL, FIELDS[, OUTCOLUMN]
+=head3 form_form_data_args ARGS
-Searches for all objects of type C<MODEL> that satisfy C<FIELDS>. The optional
-C<OUTCOLUMN> defines the output column, in case you don't want the entire
-records.
+This will take an array containing (name, value) argument pairs and
+convert those arguments into L<HTTP::Message> objects ready for adding
+to a 'mulitpart/form-data' L<HTTP::Request> as parts with something like:
-=head2 validate_action_args action => args
+ my $req = HTTP::Request->new( POST => $uri );
+ $req->header('Content-type' => 'multipart/form-data');
+ $req->add_part( $_ ) foreach $self->form_form_data_args( @args );
-Validates the given action, to check to make sure that all mandatory arguments
-are given and that no unknown arguments are given.
+This method can handle file uploads, read more in L</"Arguments of actions">.
-You may give action as a string, which will be interpreted as the action name;
-or as an array reference for CRUD - the first element will be the action
-(create, update, or delete) and the second element will be the model name.
+See also L</"form_form_data_args ARGS"|"form_form_data_args"> and
+L</"Arguments of actions">.
-This will throw an error or if validation succeeds, will return 1.
+=head3 join_url FRAGMENTS
-=head2 get_action_spec action_name
+Encodes C<FRAGMENTS> and joins them with C</>.
-Returns the action spec (which arguments it takes, and metadata about them).
-The first request for a particular action will ask the server for the spec.
-Subsequent requests will return it from the cache.
+=head3 escape STRINGS
-=head2 get_model_spec model_name
+Returns C<STRINGS>, properly URI-escaped.
-Returns the model spec (which columns it has). The first request for a
-particular model will ask the server for the spec. Subsequent requests will
-return it from the cache.
+=head2 Various helpers
-=head2 get_sid
+=head3 email_eq EMAIL, EMAIL
-Retrieves the sid from the L<LWP::UserAgent> object.
+Compares the two email addresses. Returns true if they're equal, false if
+they're not.
-=head2 join_url FRAGMENTS
+=head3 is_me EMAIL
-Encodes C<FRAGMENTS> and joins them with C</>.
+Returns true if C<EMAIL> looks like it is the same as the current user's.
-=head2 escape STRINGS
+=head3 email_of ID
-Returns C<STRINGS>, properly URI-escaped.
+Retrieve user C<ID>'s email address.
-=head2 load_date DATE
+=head3 load_date DATE
Loads C<DATE> (which must be of the form C<YYYY-MM-DD>) into a L<DateTime>
object.
-=head2 email_eq EMAIL, EMAIL
+=head3 get_sid
-Compares the two email addresses. Returns true if they're equal, false if
-they're not.
-
-=head2 is_me EMAIL
+Retrieves the sid from the L<LWP::UserAgent> object.
-Returns true if C<EMAIL> looks like it is the same as the current user's.
+=head2 Working with config
-=head2 load_config
+=head3 load_config
This will return a hash reference of the user's preferences. Because this
method is designed for use in small standalone scripts, it has a few
@@ -844,27 +902,22 @@
=back
-=head2 config_permissions
+=head3 config_permissions
This will warn about (and fix) config files being readable by group or others.
-=head2 read_config_file
+=head3 read_config_file
This transforms the config file into a hashref. It also does any postprocessing
needed, such as transforming localhost to 127.0.0.1 (due to an obscure bug,
probably in HTTP::Cookies).
-=head2 write_config_file
+=head3 write_config_file
This will write the config to disk. This is usually only done when a sid is
discovered, but may happen any time.
-=head2 prompt_login_info
-
-This will ask the user for her email and password. It may do so repeatedly
-until login is successful.
-
-=head2 filter_config [DIRECTORY] -> HASH
+=head3 filter_config [DIRECTORY] -> HASH
Looks at the (given or) current directory, and all parent directories, for
files named C<< $self->filter_file >>. Each file is YAML. The contents of the
@@ -875,10 +928,6 @@
doesn't look at this at all, but it may in the future (such as for email and
password).
-=head2 email_of ID
-
-Retrieve user C<ID>'s email address.
-
=head1 SEE ALSO
L<Jifty>, L<Net::Hiveminder>
@@ -889,7 +938,8 @@
=head1 CONTRIBUTORS
-Andrew Sterling Hanenkamp, C<< <hanenkamp at gmail.com> >>
+Andrew Sterling Hanenkamp, C<< <hanenkamp at gmail.com> >>,
+Ruslan Zakirov E<lt>ruz at bestpractical.comE<gt>
=head1 BUGS
More information about the Jifty-commit
mailing list