Ubuntu Manpage: LiveJournal - A Perl implementation of the LiveJournal protocol

Provided by: liblivejournal-perl_1.3-7_all

NAME

       LiveJournal - A Perl implementation of the LiveJournal protocol

SYNOPSIS

        use LiveJournal;

        my %info = (
               user => 'foo',
               password => 'bar',
        );

        my $lj = LiveJournal->new(\%info);

        my $response = $lj->login();

        print "Logged in successfully\n" if ($response->{success} eq "OK");

        ...

        my $friend = LiveJournal::Friend->new();

        my $response = $friend->check();

        ...

        my $journal = LiveJournal::Journal->new();

        my $response = $journal->syncitems();

DESCRIPTION

       This module is implements the LiveJournal protocol.  See
       http://www.livejournal.com/developer/protocol.bml for details.  Data is requested from the server through
       mode lines.  Many methods return a hash reference containing key/value pairs returned by the server.
       Descriptions of possible responses can be found at http://www.livejournal.com/developer/modelist.bml

CONSTRUCTOR

       new (INFO)
           This  is the constructor for a new LiveJournal object.  "INFO" is a hash containing at least username
           and password (plaintext) or hpassword (MD5 hash) key/value pairs.  You may also include  a  URL,  for
           which the default is http://www.livejournal.com/cgi-bin/log.cgi.  To use a proxy, add a proxy key and
           value.

       LiveJournal::livejournal->new([ FILES ])
           If  you  want  to  use a file in the livejournalrc format to store your data, you can use this method
           instead.  "FILES" is an array reference to the file(s) you want to load.  If you don't  specify  any,
           it  will use the first one found of ~/.livejournalrc, ~/.livejournal.rc, or /etc/livejournalrc.  This
           will return an object in the LiveJournal class.

BASE CLASS METHODS

       login ([ INFO ])
           Log in to the LiveJournal server.  Returns a hash reference.  The server returns whether the password
           is good or not, the user's name, an optional message to be displayed to the user, and the list of the
           user's friend groups.  "INFO" is an optional hash reference containing the  optional  keys  getmoods,
           getmenus, and getpickws.

           getmoods  should  exist and be the number of the highest mood ID you have cached/stored on the user's
           computer. For example, if you logged in last time with and got mood IDs 1, 2, 4, and 5, then send "5"
           as the value of "getmoods". The server will return every new mood that has an internal MoodID greater
           than 5. If you've never downloaded moods before, send "0".

           getmenus should exist if you want to get a list/tree of web jump menus to show in your client.

           getpickws should exist if you want to receive that list of picture keywords.

       user ()
           Returns the username

       password ()
           Returns the password or hpassword, whichever is set.

       version ([VERSION])
           Returns the version string.  You may alter the version string by passing a "VERSION".

       access ([ INFO ])
           Sets/returns the journals that the  user  has  the  ability  to  post  to.   This  method  is  called
           automatically by "parse_login()".  It returns a list reference containing each journal.

       friend_group ([ INFO ])
           Sets/returns  the  friend group information.  This method is called automatically by "parse_login()".
           It returns a hash of hashes containing name and sortorder key/value pairs.  We use a hash instead  of
           an  array  here  because the group numbers start from 1 and it seemed more appropriate than having an
           undef 0 element or requiring adding 1 all the time.

       friend_group_max ([ MAX ])
           Sets/returns  the  maximum  friend_group  number.    This   method   is   called   automatically   by
           "parse_login()".

       menu ([ INFO ])
           Sets/returns   the   menu  text  and  URL  information.   This  method  is  called  automatically  by
           "parse_login()".  You can use the list of lists of hashes it returns as data for menus.

       mood ([ INFO ])
           Sets/returns the mood information.  This method is called automatically by "parse_login()".   Returns
           a list of hashes containing the keys id and name for each mood.

       mood_count ([ COUNT ])
           Sets/returns the number of moods.  This method is called automatically by "parse_login()".

       name ([ NAME ])
           Sets/returns  the  name  of  the  the  logged  in  user.   This  method  is  called  automatically by
           "parse_login()".

       pic_keyword ([ KEYWORDS ])
           Sets/returns the picture keywords.  This method is called automatically by "parse_login()".   Returns
           a reference to a list of the keywords.

       escape (STRING)
           Use this method to escape strings.  "STRING" is any string.  All non-alphanumeric characters and non-
           whitespace are converted to their %hex values.  Spaces are converted to +s.

FRIEND METHODS

       check ()
           Poll  the server to see if the friends list has been updated. This request is extremely quick, and is
           the preferred way for users to see when their friends list is updated.  Returns a hash reference.

       get ([ [ FRIENDOF ] [, GROUPS ] ])
           Takes two optional arguments.  If "FRIENDOF" is set to 1, you will also get back the  info  from  the
           "friendof"  mode.   If  "GROUPS"  is set to 1, you will get the info from the "getfriendgroups" mode.
           This method returns a hash reference which should be passed to parse() to be more useful.  YOU SHOULD
           ALWAYS USE THIS METHOD BEFORE VIEWING AND AFTER MODIFYING YOUR FRIENDS LIST TO AVOID INCONSISTENCIES.

       parse (FRIENDS)
           Takes one argument: the hash reference returned from get().   Returns  a  hash  of  lists  of  hashes
           containing the info (user, name, fg, bg, etc) for each friend such as:

           'friend' =>
               [
                  {
                   'fg'        => '#000000',
                   'bg'        => '#FFFFFF',
                   'groupmask' => '3',
                   'user'      => 'SomeUser',
                   'name'      => 'Some X. Name'
                  }
               ]

           You should call parse() anytime you call get() to keep your friend count up to date.

       edit (FRIENDS)
           This method is used to add and edit friends to your friends list.  It takes a hash of hash references
           structure  which  has the username as the first level of keys.  The second level contains optional fg
           and bg colors in #RRGGBB format.

           'newfriend' =>
              {
               'fg' => '#000000',
               'bg' => '#FFFFFF',
              }

           newfriend is the name of the new user.  number should be the sum of "numfriends() +  n"  where  n  is
           incremented for each friend you are adding.

       add (FRIEND, [ FG [, BG ] ])
           Use  this  method  to  add a user from your friends list.  "FRIEND" is a username.  "FG" and "BG" are
           foreground and background values in #RRGGBB format.

       remove (USERS)
           Use this method to remove users from your friends  list.   Pass  it  an  array  reference  containing
           usernames.  Returns a hash reference.

       friendof ()
           This method returns a hash reference of the users that list you as a friend.  This hash reference can
           be passed to parse().

       lastupdate ([ LAST ])
           Returns or sets the last time check was used.  check() sets this value so you don't have to.

       numfriends ([ NUMBER ])
           This method sets and returns the number of friends you have.  It is automatically called from parse()
           so you shouldn't have to worry about setting it manually.

       friends ()
           Sets  and  returns  your friends list.  This method is called by "parse()" automatically to propagate
           the hash.

       getgroups ()
           This method returns a hash reference containing information about your friend groups

       editgroups (INFO)
           Use this method to create or edit a friend group.  You can modify the name, sort  order,  and  public
           attributes  of  the  group  by passing a hashref containing the keys called name, sort, or public and
           respective new values.  You can also add a friend to a group or groups by passing their username as a
           key and the new groupmask as a value.

       deletegroups (NUMBERS)
           This method deletes a friend group.  Pass it an array reference containing the numbers of the  groups
           to delete.

       friends_by_group ()
           Returns a hash of list references containing users and the groups they are members of.

       add_friend_to_group (USER, GROUP)
           Use this method to add a friend to a user group.  "USER" is the username of the person and "GROUP" is
           the group number.

       remove_friend_from_group (USER, GROUP)
           Use  this  method  to  remove  a  friend from a user group.  "USER" is the username of the person and
           "GROUP" is the group number.

JOURNAL METHODS

get (INFO)
Use this method to download parts of a user's journal. "INFO" is a hash reference containing at
least a key called selecttype and a value of either syncitems, day, lastn, or one.

syncitems will use the "lastcync()" method by default, otherwise pass it a date in the yyyy-mm-dd
hh::mm::ss format.

If you use day, you may provide year, month, and day keys to specify which day. Default is today.

The lastn value requires a howmany key which says how many of the most recent items to download.
Maximum is 50. Default is 20.

If you want a particular entry, you should use the one value and a complimentary itemid key
containing the id of the item you want to grab.

For further detail, see http://www.livejournal.com/developer/modeinfo.bml?getevents

post (INFO)
This method is used to post a journal entry. "INFO" is a hash reference containing at least an event
key with a value of the post content. The date keys are created for you.

For further detail, see http://www.livejournal.com/developer/modeinfo.bml?postevent

edit (INFO)
Used to edit user's past journal entry. "INFO" is a a hash reference containing at least the itemid
and event being submitted. Other optional values are documented at
http://www.livejournal.com/developer/modeinfo.bml?editevent

remove (ITEMID)
Used to delete a past journal entry. "ITEMID" is a scalar containing the unique item id to delete.

syncitems ()
Returns a hash reference containing items (journal entries, to-do items, comments) that have been
created or updated on LiveJournal since you last downloaded them.

lastsync ([ LAST ])
Returns or sets the last time syncitems() was used. syncitems() sets this value so you don't have
to.

getdaycounts ()
This mode retrieves the number of journal entries per day. Useful for populating calendar widgets in
GUI clients.

AUTHOR

       Frank Sheiness <archon@forbidden.dough.net> http://feeding.frenzy.com/~rainking/

CREDITS

       •   Brad 'bradfitz' Fitz <bradfitz@livejournal.com> for unconfusing me

       •   Joe  'pinman'  Wreschnig <piman@sacredchao.net> for his idea providing ventures into Perl-LiveJournal
           land

URL

       •   http://forbidden.dough.net/~archon/lj/