Taxi(3)

📦
version 0.96 · 4 versions
, in epel 9

🚕 Taxi(3) — the manual page, but make it make sense

okay so bestie, this is the manual page for Data::Taxi, and it's part of the User Contributed Perl Documentation (which is the fancy way of saying "a real one in the Perl community wrote this, not the core team"). Buckle up, we're learning about taint-aware XML-ish data serialization 💅

✨ NAME ✨

Data::Taxi — Taint-aware, XML-ish data serialization 🎀

PLEASE NOTE: Data::Taxi is no longer being developed or supported. Not me delivering the bad news first thing 😭 but yeah. It's done. It's retired. It's living its best retired life.

🌸 SYNOPSIS 🌸

use Data::Taxi ':all';
my ($ob, $str);

$ob = MyClass->new();
$str = freeze($ob);
$ob = thaw($str);

that's the whole vibe honestly. freeze it, thaw it, periodt 🧊➡️💧

🛠️ INSTALLATION 🛠️

The classic, iconic, no-notes installation routine — literally the usual:

perl Makefile.PL
make
make test
make install

and if you're feeling extra lowkey about it? You can also just copy Taxi.pm straight into the Data/ directory of one of your library trees. that's it. that's the whole install. so easy it's giving "why is everything else so hard" 💀

💖 DESCRIPTION 💖

Taxi (short for Taint-Aware XML-Ish, ikyk) is a data serializer with several handy features, and honestly? the features ate:

Taint aware Taxi does not force you to trust the data you are serializing. None of the input data is executed. ever. so you can stop clutching your pearls 🫶

Human readable Taxi produces a human-readable string that simplifies checking the output of your objects. literally you can just look at it with your eyeballs 👀

XML-ish While the author doesn't (currently) promise full XML compliance, Taxi produces a block of XML-ish data that could probably be read in by other XML parsers. "probably" is doing a lot of heavy lifting there but we respect the honesty ⭐

📦 EXPORT 📦

None by default. You get freeze and thaw with ':all':

use Data::Taxi ':all';

that's the whole shortcut. you're welcome 🎀

🚀 Subroutines 🚀

❄️ freeze($ob, %opts) ❄️

freeze serializes a single scalar, hash reference, array reference, or scalar reference into an XML string. and like, freeze can recurse any number of levels of a nested tree and preserve multiple references to the same object. she's versatile, she's thorough, she's iconic 👑

Let's look at an example, because the example is honestly the moment:

        my ($tree, $format, $members, $bool, $mysca);

        # anonymous hash
        $format = {
                'app'=>'trini',
                'ver'=>'0.9',
                'ver'=>'this & that',
        };

        # anonymous array
        $members = ['Starflower', 'Mary', 'Paul', 'Hallie', 'Ryan'];

        # blessed object
        $bool = Math::BooleanEval->new('whatever');

        # scalar reference (to an anonymous hash, no less)
        $mysca = {'name'=>'miko', 'email'=>'miko@idocs.com', };

        # the whole thing
        $tree = {
                'dataformat' => $format,
                'otherdataformat' => $format,
                'bool' => $bool,
                'members' => $members,
                'myscaref' => \$mysca,
        };

        $frozen = freeze($tree);

(and yes, $format has 'ver' listed twice — that's in the original, we do not fix, we do not touch, we simply observe 🙈)

freeze accepts one object as input. The code above results in the following XML-ish string:

   <taxi ver="1.00">
      <hashref id="0">
         <hashref name="otherdataformat" id="1">
            <scalar name="ver" value="this &#38;amp; that"/>
            <scalar name="app" value="trini"/>
         </hashref>
         <scalarref name="myscaref" id="2">
            <hashref id="3">
               <scalar name="email" value="miko@idocs.com"/>
               <scalar name="name" value="miko"/>
            </hashref>
         </scalarref>
         <hashref name="bool" id="4" class="Math::BooleanEval">
            <hashref name="blanks" id="5">
            </hashref>
            <scalar name="pos" value="0"/>
            <arrayref name="arr" id="6">
               <scalar value="whatever"/>
            </arrayref>
            <scalar name="expr" value="whatever"/>
         </hashref>
         <hashref name="dataformat" id="1" redundant="1"/>
         <arrayref name="members" id="7">
            <scalar value="Starflower"/>
            <scalar value="Mary"/>
            <scalar value="Paul"/>
            <scalar value="Hallie"/>
            <scalar value="Ryan"/>
         </arrayref>
      </hashref>
   </taxi>

notice how otherdataformat and dataformat both point at id="1" and the second one is flagged redundant="1"? that's the shared-reference magic bestie, she remembers 🔥

🌊 thaw 🌊

thaw accepts one argument — the serialized data string — and returns a single value, the reconstituted data, rebuilding the entire data structure including blessed references. it's giving resurrection, it's giving revival, it's giving "she's back and better" 💖

   $tree = thaw($frozen);

🧐 IS TAXI DATA XML? 🧐

Although Taxi's data format is XML-ish, it's not fully compliant to XML in all regards. For now, Taxi only promises that it can input its own output. that's the deal, that's the contract, take it or leave it 🤝

The reason the author didn't go for full XML compliance is that he wanted to keep Taxi as light as possible while achieving its main goal in life: pure-perl serialization. XML compliance is not part of that goal. periodt 💅

If you want to help make Taxi fully XML compliant w/o making it bloated, that's cool — drop him an email and you can work together 🫶

📝 TODO 📝

Tied scalars don't work. The code started getting spaghettish trying to implement them, so he decided to use the Asimov method and stop thinking about it for a while 🍝😭

Tied hashes and arrays should work fine. should. should. we love a confident "should" 🌈

⚖️ TERMS AND CONDITIONS ⚖️

Copyright (c) 2002 by Miko O'Sullivan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This software comes with NO WARRANTY of any kind. like, none. zero. not a crumb. 🚫

👑 AUTHOR 👑

Miko O'Sullivan miko@idocs.com — the main character who built this whole thing 💜

🗓️ VERSION 🗓️

  • Version 0.90 — June 15, 2002 — initial public release 🎉
  • Version 0.91 — July 10, 2002 — minor improvment to documentation (their spelling, not mine, we keep it fr fr) ✍️
  • Version 0.94 — April 26, 2003 — Fixed problem handling undefined scalars. 🐛
  • Version 0.95 — Oct 31, 2008 — Adding notice of last release. spooky timing 🎃
  • Version 0.96 — Nov 14, 2010 — Fixing bug: (and then... nothing. the sentence just ends. we may never know what the bug was 💀)

💀 POD ERRORS 💀

Hey! The above document had some coding errors, which are explained below:

Around line 684:

=end CPAN without matching =begin.  (Stack: [empty])

ngl that's iconic. the documentation has a documentation error and the manual page just... reports it. self-aware king 👑

🌸 okay bestie, that's the whole page! this was perl v5.32.1, dated 2021-07-22, and that's the Taxi(3) manual page signing off — go freeze something and thaw it back out, you've got this 🫶💖✨

📦 where this page comes from