.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SGMLS::Output 3"
.TH SGMLS::Output 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SGMLS::Output \- Stack\-based Output Procedures
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use SGMLS::Output;
.Ve
.PP
To print a string to the current output destination:
.PP
.Vb 1
\&  output($data);
.Ve
.PP
To push a new output level to the filehandle DATA:
.PP
.Vb 1
\&  push_output(\*(Aqhandle\*(Aq,DATA);
.Ve
.PP
To push a new output level to the file "foo.data" (which will be
opened and closed automatically):
.PP
.Vb 1
\&  push_output(\*(Aqfile\*(Aq,\*(Aqfoo.data\*(Aq);
.Ve
.PP
To push a new output level to a pipe to the shell command "sort":
.PP
.Vb 1
\&  push_output(\*(Aqpipe\*(Aq,\*(Aqsort\*(Aq);
.Ve
.PP
To push a new output level \fIappending\fR to the file "foo.data":
.PP
.Vb 1
\&  push_output(\*(Aqappend\*(Aq,\*(Aqfoo.data\*(Aq);
.Ve
.PP
To push a new output level to an empty string:
.PP
.Vb 1
\&  push_output(\*(Aqstring\*(Aq);
.Ve
.PP
To push a new output level appending to the string "David is ":
.PP
.Vb 1
\&  push_output(\*(Aqstring\*(Aq,"David is ");
.Ve
.PP
To push a new output level to The Great Beyond:
.PP
.Vb 1
\&  push_output(\*(Aqnul\*(Aq);
.Ve
.PP
To revert to the previous output level:
.PP
.Vb 1
\&  pop_output();
.Ve
.PP
To revert to the previous output level, returning the contents of an
output string:
.PP
.Vb 1
\&  $data = pop_output();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This library allows redirectable, stack-based output to files, pipes,
handles, strings, or nul.  It is especially useful for packages like
SGMLS, since handlers for individual \fBSGML\fR elements can
temporarily change and restore the default output destination.  It is
also particularly useful for capturing the contents of an element (and
its sub-elements) in a string.
.PP
Example:
.PP
.Vb 2
\&  sgmls(\*(Aq<title>\*(Aq, sub{ push_output(\*(Aqstring\*(Aq); });
\&  sgmls(\*(Aq</title>\*(Aq, sub{ $title = pop_output(); });
.Ve
.PP
In between, anything sent to \fBoutput\fR (such as CDATA) will be
accumulated in the string returned from \fBpop_output()\fR.
.PP
Example:
.PP
.Vb 2
\&  sgmls(\*(Aq<tei.header>\*(Aq, sub { push_output(\*(Aqnul\*(Aq); });
\&  sgmls(\*(Aq</tei.header>\*(Aq, sub { pop_output(); });
.Ve
.PP
All output will be ignored until the header has finished.
.SH "AUTHOR AND COPYRIGHT"
.IX Header "AUTHOR AND COPYRIGHT"
Copyright 1994 and 1995 by David Megginson,
\&\f(CW\*(C`dmeggins@aix1.uottawa.ca\*(C'\fR.  Distributed under the terms of the Gnu
General Public License (version 2, 1991) \-\- see the file \f(CW\*(C`COPYING\*(C'\fR
which is included in the \fBSGMLS.pm\fR distribution.
.SH "SEE ALSO:"
.IX Header "SEE ALSO:"
SGMLS.