Refs(3pm)

💖 SGMLS::Refs — forward reference handling, but make it cute ✨

okay bestie, so <pink>SGMLS::Refs</pink> is the module you call when you want your forward references to remember themselves between runs. it's giving LaTeX .aux files, but make it Perl. no cap. 🎀

---

✨ SYNOPSIS ✨

first things first, you gotta pull it in:

use SGMLS::Refs;

wanna spin up a brand new reference-manager object using the file "foo.refs"? bet:

my $refs = new SGMLS::Refs("foo.refs");

wanna do that and also log every change into "foo.log"? slay:

my $refs = new SGMLS::Refs("foo.refs","foo.log");

recording a reference? literally just:

$refs->put("document title",$title);

getting one back? easy:

$title = $refs->get("document title");

want the count of how many references changed since the last run? iconic:

$num = $refs->changed;

and if you want it to scream a LaTeX-ish warning whenever references have changed:

$refs->warn;

periodt. 💅

---

🌸 DESCRIPTION 🌸

so this library is meant to vibe alongside the SGMLS package and keep track of forward references from one run to the next — exactly like those LaTeX .aux files do. each reference manager is its own object, and it reads a file of perl source and then rewrites it, with the file name handed to it by the caller. iykyk. 🦋

here's the whole flow, in example form:

# Start up the reference manager before the parse.
sgml('start', sub { $refs = new SGMLS::Refs("foo.refs"); });

# Warn about any changed references at the end.
sgml('end', sub { $refs->warn; });

# Look up the title from the last parse, if available.
sgml('<div>', sub {
  my $element = shift;
  my $id = $element->attribute(ID)->value;
  my $title = $refs->get("title:$id") || "[no title available]";

  $current_div_id = $id;

  output "\\section{$title}\n\n";
});

# Save the title for the next parse.
sgml('<head>', sub { push_output('string'); });
sgml('</head>', sub {
  my $title = pop_output();
  my $id = $current_div_id;

  $refs->put("title:$id",$title);
});

look at that. main character parser energy. 👑

---

👑 AUTHOR AND COPYRIGHT 👑

Copyright 1994 and 1995 by David Megginson, "dmeggins@aix1.uottawa.ca". 💖

Distributed under the terms of the Gnu General Public License (version 2, 1991) — see the file "COPYING" which is included in the SGMLS.pm distribution.

---

🔍 SEE ALSO: 🔍

• SGMLS
• SGMLS::Output

---

and that's the whole page, bestie 🫶 this was the User Contributed Perl Documentation version of Refs(3pm), perl v5.36.0, dated 2022-10-13. go forth and forward-reference responsibly ✨🎀💜