doc/tta_api/api_includes/Texinfo-Reader.texi

@node Texinfo@asis{::}Reader
@chapter Texinfo::Reader

@node Texinfo@asis{::}Reader NAME
@section Texinfo::Reader NAME

Texinfo::Reader - Texinfo tree reader

@node Texinfo@asis{::}Reader SYNOPSIS
@section Texinfo::Reader SYNOPSIS

@verbatim
  use Texinfo::Parser;
  use Texinfo::Reader;

  my $parser = Texinfo::Parser::parser();
  my $document = $parser->parse_texi_file("somefile.texi");

  my $start_element = $document->tree();

  my $reader = Texinfo::Reader::new($start_element);

  while (1) {
    my $next = $reader->read();
    last if (!defined($next));

    my $category = $next->{'category'};

    my $element = $next->{'element'};

    if ($category == Texinfo::Reader->TXI_READ_TEXT) {
      my $text = $element->{'text'};
      ....
    } elsif ($category == Texinfo::Reader->TXI_READ_ELEMENT_START) {
      my $cmdname = $element->{'cmdname'};
      ...
    ....
    }
  }
@end verbatim

@node Texinfo@asis{::}Reader NOTES
@section Texinfo::Reader NOTES

The Texinfo Perl module main purpose is to be used in @code{texi2any} to convert
Texinfo to other formats.  There is no promise of API stability.

Note that this module is not used in @code{texi2any}.

Note that this module could be removed at any time.

@node Texinfo@asis{::}Reader DESCRIPTION
@section Texinfo::Reader DESCRIPTION

@code{Texinfo::Reader} offers an interface to a Texinfo tree obtained from
parsing Texinfo code.  This interface is based on a stream of tokens associated
to tree elements.  This interface is conceptually similar to the interface of
@url{https://metacpan.org/pod/XML::LibXML::Reader, XML::LibXML::Reader} or @url{https://metacpan.org/pod/Pod::Simple::PullParser, Pod::Simple::PullParser}.

The Reader acts as a cursor going forward on the Texinfo tree and stopping
at each element on the way, providing with a new token.  The user's code keeps
control of the progress and simply calls the @code{read()} function repeatedly to
progress to the next token in the Texinfo document order.  The other
function provides means for skipping sub-trees.

@node Texinfo@asis{::}Reader METHODS
@section Texinfo::Reader METHODS

@table @asis
@item $reader = Texinfo::Reader::new ($element)
@anchor{Texinfo@asis{::}Reader $reader = Texinfo@asis{::}Reader@asis{::}new ($element)}
@cindex @code{Texinfo::Reader::new}

Initialize a reader starting at the @emph{$element} Texinfo tree element.

@item $token = $reader->read()
@anchor{Texinfo@asis{::}Reader $token = $reader->read()}
@cindex @code{read}

Returns the next token or undef at the end of the tree.

A token is an hash reference with string keys:

@table @asis
@item element
@anchor{Texinfo@asis{::}Reader element}

The current tree element.

@item category
@anchor{Texinfo@asis{::}Reader category}

Information on the tree element and on the position read.  The possible token
category values are declared as constants and are accessed through
the @code{Texinfo::Reader} package, like
@code{Texinfo::Reader->TXI_READ_ELEMENT_START}.

The token category can take the following @code{Texinfo::Reader} constant values:

@table @asis
@item TXI_READ_ELEMENT_START
@anchor{Texinfo@asis{::}Reader TXI_READ_ELEMENT_START}

Start of the tree element, before getting the element contents.

@item TXI_READ_ELEMENT_END
@anchor{Texinfo@asis{::}Reader TXI_READ_ELEMENT_END}

End of the tree element after having read the contents (after a closing
brace, an @@end, at the end of a container).

@item TXI_READ_TEXT
@anchor{Texinfo@asis{::}Reader TXI_READ_TEXT}

Text element.

@item TXI_READ_IGNORABLE_TEXT
@anchor{Texinfo@asis{::}Reader TXI_READ_IGNORABLE_TEXT}

Text element supposed to be ignored, such as spaces appearing after
an opening brace or around a comma delimiting arguments.

@item TXI_READ_EMPTY
@anchor{Texinfo@asis{::}Reader TXI_READ_EMPTY}

A tree element which is not a text tree element and does not hold content.  For
Texinfo @@-commands without braces nor line argument such as @code{@@@@} and for empty
arguments.  For example the @code{brace_container} argument container of @code{@@TeX@{@}}
is empty.  Also for invalid constructs such as brace @@-commands without braces.

@end table

@end table

The Texinfo tree element is described in @ref{Texinfo@asis{::}Parser TEXINFO TREE}.

@item $token = $reader->skip_children($element)
@anchor{Texinfo@asis{::}Reader $token = $reader->skip_children($element)}
@cindex @code{skip_children}

Skip the remaining of the contents currently being processed.
Return a token with the @emph{TXI_READ_ELEMENT_END} category, or undef at the end
of the tree.

If the @emph{$element} optional argument is specified, a fatal error is emitted if
it does not match with the parent element of the skipped contents.

@item $elements = reader_collect_commands_list($element, $command_names)
@anchor{Texinfo@asis{::}Reader $elements = reader_collect_commands_list($element@comma{} $command_names)}

Collect all the tree elements corresponding to @@-command names in the
@emph{$command_names} array reference, starting at @emph{$element}.  The
return value is an array reference of the collected elements, in the order of
their appearence in the Texinfo tree.

@end table

@node Texinfo@asis{::}Reader SEE ALSO
@section Texinfo::Reader SEE ALSO

@ref{Texinfo@asis{::}Parser NAME,, Texinfo::Parser}. @ref{Texinfo@asis{::}Document NAME,, Texinfo::Document}.

@node Texinfo@asis{::}Reader AUTHOR
@section Texinfo::Reader AUTHOR

Patrice Dumas.

@node Texinfo@asis{::}Reader COPYRIGHT AND LICENSE
@section Texinfo::Reader COPYRIGHT AND LICENSE

Copyright 2025- Free Software Foundation, Inc.  See the source file for
all copyright years.

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at
your option) any later version.