NAME
    Net::Jifty - interface to online Jifty applications

VERSION
    Version 0.06 released 17 Mar 07

SYNOPSIS
        use Net::Jifty;
        my $j = Net::Jifty->new(
            site        => 'http://mushroom.mu/',
            cookie_name => 'MUSHROOM_KINGDOM_SID',
            email       => 'god@mushroom.mu',
            password    => 'melange',
        );

        # the story begins
        $j->create(Hero => name => 'Mario', job => 'Plumber');

        # find the hero whose job is Plumber and change his name to Luigi
        # and color to green
        $j->update(Hero => job => 'Plumber',
            name  => 'Luigi',
            color => 'Green',
        );

        # win!
        $j->delete(Enemy => name => 'Bowser');

DESCRIPTION
    Jifty is a full-stack web framework. It provides an optional REST
    interface for applications. Using this module, you can interact with
    that REST interface to write client-side utilities.

    You can use this module directly, but you'll be better off subclassing
    it, such as what we've done for Net::Hiveminder.

    This module also provides a number of convenient methods for writing
    short scripts. For example, passing "use_config => 1" to "new" will look
    at the config file for the username and password (or SID) of the user.
    If neither is available, it will prompt the user for them.

  BUILD
    Each Net::Jifty object will do the following upon creation:

    Read config
        ..but only if you "use_config" is set to true.

    Log in
        ..unless a sid is available, in which case we're already logged in.

  login
    This assumes your site is using Jifty::Plugin::Authentication::Password.
    If that's not the case, override this in your subclass.

    This is called automatically when each Net::Jifty object is constructed
    (unless a session ID is passed in).

  call ACTION, ARGS
    This uses the Jifty "web services" API to perform "ACTION". This is
    *not* the REST interface, though it resembles it to some degree.

    This module currently only uses this to log in.

  form_url_encoded_args ARGS
    This will take a hash containing arguments and convert those arguments
    into URL encoded form. I.e., (x => 1, y => 2, z => 3) becomes:

      x=1&y=2&z=3

    These are then ready to be appened to the URL on a GET or placed into
    the content of a PUT.

  method METHOD, URL[, ARGS]
    This will perform a GET, POST, PUT, DELETE, etc using the internal
    LWP::UserAgent object.

    "URL" may be a string or an array reference (which will have its parts
    properly escaped and joined with "/"). "URL" already has
    "http://your.site/=/" prepended to it, and ".yml" appended to it, so you
    only need to pass something like "model/YourApp.Model.Foo/name", or
    "[qw/model YourApp.Model.Foo name]".

    This will return the data structure returned by the Jifty application,
    or throw an error.

  post URL, ARGS
    This will post "ARGS" to "URL". See the documentation for "method" about
    the format of "URL".

  get URL, ARGS
    This will get the specified "URL" with "ARGS" as query parameters. See
    the documentation for "method" about the format of "URL".

  act ACTION, ARGS
    Perform "ACTION", using "ARGS". This does use the REST interface.

  create MODEL, FIELDS
    Create a new object of type "MODEL" with the "FIELDS" set.

  delete MODEL, KEY => VALUE
    Find some "MODEL" where "KEY" is "VALUE" and delete it.

  update MODEL, KEY => VALUE, FIELDS
    Find some "MODEL" where "KEY" is "VALUE" and set "FIELDS" on it.

  read MODEL, KEY => VALUE
    Find some "MODEL" where "KEY" is "VALUE" and return it.

  search MODEL, FIELDS[, OUTCOLUMN]
    Searches for all objects of type "MODEL" that satisfy "FIELDS". The
    optional "OUTCOLUMN" defines the output column, in case you don't want
    the entire records.

  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.

    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.

  get_sid
    Retrieves the sid from the LWP::UserAgent object.

  join_url FRAGMENTS
    Encodes "FRAGMENTS" and joins them with "/".

  escape STRINGS
    Returns "STRINGS", properly URI-escaped.

  load_date DATE
    Loads "DATE" (which must be of the form "YYYY-MM-DD") into a DateTime
    object.

  email_eq EMAIL, EMAIL
    Compares the two email addresses. Returns true if they're equal, false
    if they're not.

  is_me EMAIL
    Returns true if "EMAIL" looks like it is the same as the current user's.

  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 peculiarities.

    *   It will "warn" if the permissions are too liberal on the config
        file, and fix them.

    *   It will prompt the user for an email and password if necessary.
        Given the email and password, it will attempt to log in using them.
        If that fails, then it will try again.

    *   Upon successful login, it will write a new config consisting of the
        options already in the config plus session ID, email, and password.

  config_permissions
    This will warn about (and fix) config files being readable by group or
    others.

  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).

  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.

  prompt_login_info
    This will ask the user for her email and password. It may do so
    repeatedly until login is successful.

  filter_config [DIRECTORY] -> HASH
    Looks at the (given or) current directory, and all parent directories,
    for files named "$self->filter_file". Each file is YAML. The contents of
    the files will be merged (such that child settings override parent
    settings), and the merged hash will be returned.

    What this is used for is up to the application or subclasses. Net::Jifty
    doesn't look at this at all, but it may in the future (such as for email
    and password).

  email_of ID
    Retrieve user "ID"'s email address.

SEE ALSO
    Jifty, Net::Hiveminder

AUTHOR
    Shawn M Moore, "<sartak at bestpractical.com>"

CONTRIBUTORS
    Andrew Sterling Hanenkamp, "<hanenkamp@gmail.com>"

BUGS
    Please report any bugs or feature requests to "bug-net-jifty at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Jifty>.

COPYRIGHT & LICENSE
    Copyright 2007 Best Practical Solutions.

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

