Palm::StdAppInfo(3pm)

💖 Palm::StdAppInfo(3pm) — bestie edition 💖

okay so. you're out here in Perl land, dealing with Palm::StdAppInfo, from the Palm distro. this is a perl manpage, and honestly? it's giving "niche but iconic". let's get into it 🦋

---

✨ NAME ✨

Palm::StdAppInfo — handle standard AppInfo blocks in Palm OS PDBs. that's the whole vibe. no cap. 💅

🌸 VERSION 🌸

This doc describes version 1.400 of Palm::StdAppInfo, released March 14, 2015, as part of Palm version 1.400. she's been around a minute but she still slays. 👑

🎀 SYNOPSIS 🎀

So usually, bestie, you're gonna do this:

package MyPDBHandler;
use Palm::StdAppInfo();             # Note the parentheses

@ISA = qw( Palm::StdAppInfo );

use constant APPINFO_PADDING = 1;

sub ParseAppInfoBlock {
    my $self = shift;
    my $data = shift;
    my $appinfo = {};

    &Palm::StdAppInfo::parse_StdAppInfo($appinfo, $data);

    $app_specific_data = $appinfo->{other};
}

sub PackAppInfoBlock {
    my $self = shift;
    my $retval;

    $self->{appinfo}{other} = <pack application-specific data>;
    $retval = &Palm::StdAppInfo::pack_StdAppInfo($self->{appinfo});
    return $retval;
}

📌 heads up bestie: notice that use Palm::StdAppInfo(); — the parentheses are the whole point. that comment is literally in the source, # Note the parentheses. do not skip them. 🙈

Or if you're using her as a standalone PDB helper class, it's just:

use Palm::StdAppInfo;

🌈 DESCRIPTION 🌈

okay so picture this: a LOT of Palm apps use the same common format to keep track of categories. that's the entire reason Palm::StdAppInfo exists — she deals with that shared format so you don't have to:

$pdb = new Palm::PDB;
$pdb->Load("myfile.pdb");

@categories  = @{ $pdb->{appinfo}{categories} };
$lastUniqueID =   $pdb->{appinfo}{lastUniqueID};
$other        =   $pdb->{appinfo}{other};

and here's the breakdown of what those are, one by one:

@categories is an array of references-to-hash. literally a lil list of hashrefs, each one a category, and the way she's structured is:

• $cat = $categories[0]; — yes, that's how you grab one, the manual just says it like that.
• $cat->{name} — the name of the category, a string of at most 16 characters. sixteen! keep it cute and keep it short. ✂️
• $cat->{id} — the category ID, an integer in the range 0-255. every category has a unique ID, that's the rule. and by convention:
  • 0 is reserved for the "Unfiled" category.
  • IDs assigned by the Palm are in the range 1-127.
  • IDs assigned by the desktop are in the range 128-255.
• $cat->{renamed} — a boolean. this one is true iff the category has been renamed since the last sync. so if it's true, something got renamed, periodt.

$lastUniqueID is (and I quote, this is literally in the source) "(I think) the last category ID that was assigned." the author is out here being honest about their level of certainty and honestly? relatable. 😭

$other is any data that follows the category list in the AppInfo block. so here's the tea: if you're writing a helper class for a PDB that includes a category list, you should parse this field to get any data that follows the category list. you should also make sure that this field is initialized before you call &Palm::StdAppInfo::pack_AppInfo. don't skip that step. that's the whole assignment. 📝

💜 APPINFO_PADDING 💜

so normally, the AppInfo block includes a byte of padding at the end, and the reason is just to bring its length to an even number. aesthetics, basically. ✨

BUT. some databases use this byte for data instead. sneaky. 🕵️

so if your database uses that padding byte for data, then your &ParseAppInfoBlock method (peep the "SYNOPSIS" section above) should call &parse_StdAppInfo with a true $nopadding argument.

and if, for whatever reason, you wish to inherit &StdAppInfo::ParseAppInfoBlock, then you add:

use constant APPINFO_PADDING => 0;

to your handler package, which tells it that the padding byte is really data. okay?? 🫶

🔥 FUNCTIONS 🔥

⭐ seed_StdAppInfo

&Palm::StdAppInfo::seed_StdAppInfo(\%appinfo);

Creates the standard fields in an existing AppInfo hash. usually you use this to make sure that a newly-created AppInfo block contains an initialized category array:

my $appinfo = {};

&Palm::StdAppInfo::seed_StdAppInfo($appinfo);

💀 Note: this is not a method. it's just a function. don't come for her with arrow syntax, she's not that kind of girl.

⭐ newStdAppInfo

$appinfo = Palm::StdAppInfo->newStdAppInfo;

Like "seed_StdAppInfo", but she creates an AppInfo hash and returns a reference to it. two-for-one. iconic. 💅

⭐ new

$pdb = new Palm::StdAppInfo;

Creates a new PDB, initialized with nothing but a standard AppInfo block.

ngl, there are very few reasons to use this, and even fewer good ones. 😭 so if you're writing a helper class to parse some PDB format that contains a category list, then you should make that helper class a subclass of "Palm::StdAppInfo". that's the move. that's what the cool kids do.

⭐ parse_StdAppInfo

$len = &Palm::StdAppInfo::parse_StdAppInfo(\%appinfo, $data, $nopadding);

This function (and yes, again — this is not a method) is intended to be called from within a PDB helper class's "ParseAppInfoBlock" method.

"parse_StdAppInfo()" parses a standard AppInfo block from the raw data $data and fills in the fields in %appinfo. it returns the number of bytes parsed. 💫

$nopadding is optional, and defaults to false. normally, the AppInfo block includes a padding byte at the end. but if $nopadding is true, then &parse_StdAppInfo assumes that the padding byte is application data, and includes it in $appinfo{'other'}, so that the caller can parse it. handing off the responsibility, love that for her. 🎀

⭐ ParseAppInfoBlock

$pdb = new Palm::StdAppInfo;
$pdb->ParseAppInfoBlock($data);

If your application's AppInfo block contains standard category support and nothing else, you may choose to just inherit this method instead of writing your own "ParseAppInfoBlock" method. otherwise? see the example in "SYNOPSIS". 💖

⭐ pack_StdAppInfo

$data = &Palm::StdAppInfo::pack_StdAppInfo(\%appinfo);

This function (you guessed it — this is not a method) is intended to be called from within a PDB helper class's "PackAppInfoBlock" method.

"pack_StdAppInfo" takes an AppInfo hash and packs it as a string of raw data that can be written to a PDB. packing her up and sending her off. 📦✨

⚠️ Note: if you're using this inside a helper class's "PackAppInfoBlock" method, you should make sure that $appinfo{other} is properly initialized before you call &Palm::StdAppInfo::pack_StdAppInfo. do not skip this. i'm serious. 🙏

$nopadding is optional, and defaults to false. normally, the AppInfo block includes a byte of padding at the end. if $nopadding is true, then &pack_StdAppInfo doesn't include this byte of padding, so that the application can use it. your byte, your choice. 🫶

⭐ PackAppInfoBlock

$pdb = new Palm::StdAppInfo;
$data = $pdb->PackAppInfoBlock();

If your application's AppInfo block contains standard category support and nothing else, you may choose to just inherit this method instead of writing your own "PackAppInfoBlock" method. otherwise, see the example in "SYNOPSIS". same energy as before, fr fr. 🌸

⭐ addCategory

$pdb->addCategory($name [, $id [, $renamed]]);

Adds a category to $pdb. 🎉

• $name — specifies the new category's name.
• $id — optional, specifies the new category's numeric ID; if omitted or undefined, &addCategory will pick one for you. she's got you. 💅
• $renamed — optional, a boolean value indicating whether the new category should be marked as having been modified. this defaults to true, and here's why: since, conceptually, &addCategory doesn't really add a category — it finds one whose name happens to be empty, and renames it. plot twist. 😭

Returns a true value if successful, false otherwise. and in case of failure, &addCategory sets $Palm::StdAppInfo::error to an error message. so go check that variable, bestie. 🔍

⭐ deleteCategory

$pdb->deleteCategory($name);

Deletes the category with name $name. Actually, though — it doesn't delete the category. it just changes its name to the empty string, and marks the category as renamed. it's giving "i'm not leaving, i'm just going quiet". 🙈 iconic honestly.

⭐ renameCategory

$pdb->renameCategory($oldname, $newname);

Renames the category named $oldname to $newname. glow-up arc. 🦋

If successful, returns a true value. if there is no category named $oldname, returns a false value and sets $Palm::StdAppInfo::error to an error message.

---

🌟 SEE ALSO 🌟

• Palm::PDB — her main character counterpart. 💖

🧚 CONFIGURATION AND ENVIRONMENT 🧚

Palm::StdAppInfo requires no configuration files or environment variables. low maintenance queen. zero drama. periodt. 👑

🌸 INCOMPATIBILITIES 🌸

None reported. no beef, no conflict, nothing. peaceful. ✨

💀 BUGS AND LIMITATIONS 💀

No bugs have been reported. she's clean, bestie. 🫶

🎀 AUTHORS 🎀

• Andrew Arensburger "<arensb AT ooblick.com>"
• Currently maintained by Christopher J. Madsen "<perl AT cjmweb.net>"

Please report any bugs or feature requests to "<bug-Palm AT rt.cpan.org>" or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=Palm.

You can follow or contribute to p5-Palm's development at https://github.com/madsen/p5-Palm. go be a contributor, bestie, iykyk. 💜

👑 COPYRIGHT AND LICENSE 👑

This software is copyright (c) 2003 by Andrew Arensburger & Alessandro Zummo.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay. 💅

🔥 DISCLAIMER OF WARRANTY 🔥

okay bestie, here comes the all-caps part, and it is not a drill. read it. this is the real deal, no jokes, because it actually means something:

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

tl;dr bestie: no warranty, at all, and the risk is yours. that's the deal. 🫠

---

and that's the whole page!! ✨ mwah 💖

this was documented for perl v5.34.0, dated 2022-06-16, and yes, it's the Palm::StdAppInfo(3pm) page. thanks for reading, bestie, go parse some PDBs responsibly. 🦋💅🎀