LiveJournal(3pm)

📦
version 1.3 · 2 versions
  • 1.3 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 1.3 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ LiveJournal 💖

okay bestie, gather round, because this is the LiveJournal(3pm) page from the User Contributed Perl Documentation, and it's literally the whole LiveJournal protocol wrapped up in Perl like a little gift 🎀. It's a lot, so buckle up.

🌸 NAME 🌸

LiveJournal — a Perl implementation of the LiveJournal protocol. That's it, that's the whole vibe. 💅

🦋 SYNOPSIS 🦋

here's the lil taste test, no cap:

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();

see? iconic. we build an object, we log in, we go bother the friends list and the journal. ✨

💜 DESCRIPTION 💜

So this module implements the LiveJournal protocol. (yes the original says "is implements", we're leaving that exactly as the universe intended, it's giving ✨charm✨). The full protocol deets live at http://www.livejournal.com/developer/protocol.bml.

The way it works is mode lines — you ask the server for data through them. And here's the thing: a whole bunch of these methods hand you back a hash reference stuffed with the key/value pairs the server sent back. If you wanna know what responses are even possible, go peek at http://www.livejournal.com/developer/modelist.bml. iykyk. 🫶

👑 CONSTRUCTOR 👑

new (INFO)

okay so this is THE constructor, the main character, the one that makes you a fresh new LiveJournal object. 🌟

INFO is a hash and it needs at least:

  • a username and password (plaintext), or
  • an hpassword (that's the MD5 hash version) key/value pair

You can also toss in a URL if you want — and if you don't, the default is http://www.livejournal.com/cgi-bin/log.cgi. And if you're rolling with a proxy? just add a proxy key and its value. easy. 🍓

LiveJournal::livejournal->new([ FILES ])

ooh okay this one is for my organized girlies 💖. If you want to keep your data in a file using the livejournalrc format, use this method instead.

FILES is an array reference to the file(s) you wanna load. Don't specify any? It'll go hunting and use the first one it finds out of:

  • ~/.livejournalrc
  • ~/.livejournal.rc
  • /etc/livejournalrc

and what you get back is an object in the LiveJournal class. slay. 🌈

✨ BASE CLASS METHODS ✨

login ([ INFO ])

bestie, this is the log-in. 🚪✨ You're logging into the LiveJournal server and it hands you back a hash reference.

What does the server tell you? It tells you whether the password is good or not, the user's name, an optional message to show to the user, and the list of the user's friend groups. that's a full little care package.

INFO here is an optional hash reference that can hold these optional keys:

  • getmoods
  • getmenus
  • getpickws

now let me break those down because they're kinda specific:

getmoods — this one should exist, and it should be the number of the highest mood ID you've cached/stored on the user's computer. Example so you get it: if you logged in last time and got mood IDs 1, 2, 4, and 5, then you send "5" as the value of getmoods. The server will then return every new mood with an internal MoodID greater than 5. And if you've literally never downloaded moods before? send "0". simple as. 🧚

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. that's it. short king. 👑

password ()

returns the password or the hpassword — whichever one is set. 😌

version ([VERSION])

returns the version string. And if you want to change it up? just pass a VERSION in and you can alter it. 🌟

access ([ INFO ])

sets/returns the journals that the user actually has the ability to post to. This one gets called automatically by parse_login(). What comes back is a list reference with every journal in it. 📓

friend_group ([ INFO ])

sets/returns the friend group info. Also called automatically by parse_login(). You get back a hash of hashes with name and sortorder key/value pairs inside.

and okay, why a hash and not an array, you ask? because group numbers start from 1, and it just felt more right than having an undef element sitting at index 0 or making you add 1 to everything forever. we don't do that here. 💅

friend_group_max ([ MAX ])

sets/returns the maximum friend_group number. Called automatically by parse_login(). 🫶

sets/returns the menu text and URL info. Called automatically by parse_login(). The thing it gives you back is a list of lists of hashes — and you can literally use that as data for your menus. 🌈

mood ([ INFO ])

sets/returns the mood info. Called automatically by parse_login(). Returns a list of hashes with the keys id and name for each mood. 😭💖

mood_count ([ COUNT ])

sets/returns the number of moods. Called automatically by parse_login(). ⭐

name ([ NAME ])

sets/returns the name of the the logged in user. (yes, "the the", we're keeping it, it's canon now 💀). Called automatically by parse_login(). 🌸

pic_keyword ([ KEYWORDS ])

sets/returns the picture keywords. Called automatically by parse_login(). Returns a reference to a list of the keywords. 🎀

escape (STRING)

use this one to escape your strings, bestie. STRING is any string. What it does:

  • all non-alphanumeric characters and non-whitespace get converted to their %hex values
  • spaces get converted to +s

that's the whole deal. 🦋

💅 FRIEND METHODS 💅

check ()

polls the server to see if the friends list has been updated. 👀 and here's the tea: this request is EXTREMELY quick, so it's the preferred way for users to see when their friends list updates. Returns a hash reference. ⚡

get ([ [ FRIENDOF ] [, GROUPS ] ])

takes two optional arguments:

  • if FRIENDOF is set to 1, you'll also get back the info from the friendof mode
  • if GROUPS is set to 1, you'll get the info from the getfriendgroups mode

This method returns a hash reference — and that reference should be passed to parse() to actually be useful. 🫶

YOU SHOULD ALWAYS USE THIS METHOD BEFORE VIEWING AND AFTER MODIFYING YOUR FRIENDS LIST TO AVOID INCONSISTENCIES. — that's in all caps in the original and it's in all caps here because it matters, bestie. no skipping. 😭

parse (FRIENDS)

takes one argument: the hash reference that came back from get(). Returns a hash of lists of hashes holding the info (user, name, fg, bg, etc) for each friend, like this:

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

You should call parse() anytime you call get() — that's how you keep your friend count up to date. 🔄

edit (FRIENDS)

this is the method for adding and editing friends on your friends list. It takes a hash of hash references structure where the username is the first level of keys, and the second level holds optional fg and bg colors in #RRGGBB format. like:

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

newfriend is the name of the new user. And the number should be the sum of numfriends() + n, where n gets incremented for each friend you're adding. math but make it friends. 🧮💖

add (FRIEND, [ FG [, BG ] ])

use this to add a user to your friends list. FRIEND is a username. FG and BG are foreground and background values in #RRGGBB format. ➕✨

remove (USERS)

use this to remove users from your friends list. Pass it an array reference containing usernames. Returns a hash reference. bye bestie 👋💀

friendof ()

returns a hash reference of the users that list you as a friend. And yup, this hash reference can be passed straight to parse(). 🫂

lastupdate ([ LAST ])

returns or sets the last time check was used. and good news: check() sets this value for you, so you literally don't have to. 😌

numfriends ([ NUMBER ])

sets and returns the number of friends you have. It gets called automatically from parse(), so you shouldn't have to worry about setting it manually. let the machine work. 🤖

friends ()

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

getgroups ()

returns a hash reference with info about your friend groups. 🎀

editgroups (INFO)

use this to create or edit a friend group. You can modify the group's name, sort, or public attributes by passing a hashref containing those keys (name, sort, or public) with their 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)

deletes a friend group. Pass it an array reference containing the numbers of the groups to delete. gone. poof. 💨

friends_by_group ()

returns a hash of list references containing users and the groups they're members of. 🫶

add_friend_to_group (USER, GROUP)

use this 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 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 to download parts of a user's journal. INFO is a hash reference containing at least a key called selecttype, and its value is one of:

  • syncitems
  • day
  • lastn
  • one

here's how each one goes down:

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

day — if you use this one, you may provide year, month, and day keys to specify which day. Default is today. 📅

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

one — if you want a particular entry, use the one value plus a complimentary itemid key containing the id of the item you wanna grab. 🎯

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

post (INFO)

this is how you post a journal entry. ✍️ INFO is a hash reference containing at least an event key whose value is the post content. and don't stress about dates — the date keys are created for you. 💖

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

edit (INFO)

used to edit a user's past journal entry. INFO is 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. and syncitems() sets this value for you, so you don't have to. 😌

getdaycounts ()

this mode retrieves the number of journal entries per day. super useful for populating calendar widgets in GUI clients. 🗓️💅

💖 AUTHOR 💖

This whole masterpiece was written by Frank Sheiness <archon@forbidden.dough.net> — and if you wanna slide into his digital home, it's at http://feeding.frenzy.com/~rainking/ 🫶

🌈 CREDITS 🌈

No one does it alone bestie, and our girl Frank is no exception. Shoutout to the icons who helped make this happen:

  • Brad 'bradfitz' Fitz <bradfitz@livejournal.com> — literally credited with "unconfusing me" 💀 which, honestly? A gift. A service. An act of love.
  • Joe 'pinman' Wreschnig <piman@sacredchao.net> — the mastermind whose idea opened up the whole "ventures into Perl-LiveJournal land" arc 🧚✨ like he lowkey started the lore.

🦋 URL 🦋

🎀 SEE ALSO 🎀

Go read these too, bestie, don't be shy:

⭐ and that's the whole page, no cap — every option, every method, every flag accounted for. nothing skipped, nothing invented, periodt.

okay bestie this was LiveJournal(3pm) from perl v5.36.0, dated 2022-11-19 — that's the source, the version, and the date, all in one cute lil bow 🎀

now go journal something iconic. mwah. 💖

📦 where this page comes from