Howto sort inline POD entries of a Perl package documentation for IMenu or a final documentation

52 views Asked by At

I'm developing with Emacs 27 in the cperl-mode + PDE.

I'm consolidating my Perl packages and try to add inline documentation entries above the method/ sub headers. I use the inline POD schema, because I've both, fast navigation and the description of the code in place via the Imenu-Tree.

Usually the methods/ sub's are not alphabetically ordered in the source code. So the entries occuring in the Imenu-Tree in the order of their definition, they appear in the order the source code is evolved. Now I want to have an alphabetical order of the matter to find/navigate to methods/ subs faster. I know how to produce such a list on the shell ordered or linked to the source code line (grep -n), but have no idea how to adopt this in direction POD-Tools or Emacs + Imenu + PDE to embed the results.

Question:

Is there a POD specific tool or a Imenu plugin or setting to sort the matter alphabetically like at the command line?

$ grep '=head2 METHOD' AppTK.pm | sort
=head2 METHOD checkDiskSize($path, $formatted) -> ($error, $size, $used, $avail)
=head2 METHOD checkHelpUsage($runDict, $tool, $minArgs, $exit) -> BOOL
=head2 METHOD checkRuntimeSettings ( $self, $cmdDict ) ->  ( $output, $exitFun, $cmdFun )
=head2 METHOD getRuntime ($self) -> $runDict
=head2 METHOD getRuntimeValue ( $self, $key ) -> $value|undef
=head2 METHOD getRuntimeValues($self) -> ( $tool, $output, $response, $command, $exitFun, $param )
=head2 METHOD initApplication ( $self, $version, $date, $author, $contact ) -> BOOL
=head2 METHOD initRuntime ( $self, $magic, $tool, $ioType, $param ) -> BOOL
=head2 METHOD ioAddResult ( $self, $dict, $key, $value ) -> dict
=head2 METHOD ioCreateResult ( $self, $name, $type, $data = [] ) -> $dict
=head2 METHOD listPlainToStr ( $self, $list, $sort = 0, $sep=' ', $quote="'") -> Str
=head2 METHOD outEncodeResult ( $self, $indent, $dict )
=head2 METHOD outEofMagic($self) -> BOOL
=head2 METHOD outIoDsLine($self, $ascii = 1) -> 1
=head2 METHOD outIoHeader($self) -> 1
=head2 METHOD outIoHsLine($self, $ascii = 1) -> 1
=head2 METHOD outIoResult($self, $resList, $type, $handle = undef, $fname = undef ) -> 1
=head2 METHOD outIoVersion ( $self, $program, $exit ) -> BOOL
=head2 METHOD outResultDataRecord ( $self, $strIndent, $type, $ident, $values ) -> ($error, $text)
=head2 METHOD outRunEof ( $self, $what = '' ) -> 1
=head2 METHOD outRunHeader ( $self, $what) -> 1
=head2 METHOD outRunMessage ( $self, $what, $aspect, $with = '', $pfxLen = 12 ) -> 1
=head2 METHOD outRunStreamRate( $self, $show,...) -> $lastTime
=head2 METHOD outRunWarning ( $self, $what, $aspect, $with = '', $pfxLen = 12 ) -> 1
=head2 METHOD parseCommandline ( $self, @ ) -> BOOL
=head2 METHOD setRuntimeInteractive ( $self, $cmdDict, $command ) -> BOOL
=head2 METHOD setRuntime ( $self, $cmdDict, $command ) -> BOOL
=head2 METHOD strQuotePlain($self, $item, $quote ="'") -> Str

Facsimile of POD code

...

# ==================================================================

=pod

=head2 METHOD ioCreateResult ( $self, $name, $type, $data = [] ) -> $dict

Create a new dictionary to write resulting datasets produced tool by
the tool.

=over 4

=item INPUT

      $name -- name of the result set,
      $type -- DATA.RECORD|DATA.TABLE,
      $data -- an optional array reference for
               existing data
               DEFAULT: []

=item RETURNS

      A reference to a dictionary with a well defined structure.

=item TODO

      Consider a OO implementation here to be more interaction safe.

=back

=cut

sub ioCreateResult ( $self, $name, $type, $data = [] ) {
    my $res = {
        NAME => $name,
        TYPE => $type,
        DATA => $data,
    };
    return $res;
}

# ==================================================================

=pod

=head2 METHOD ioAddResult ( $self, $dict, $key, $value ) -> dict

Add a key value pair to the existing result set. Internal a
array reference with the structure [ $key, $value ] is used, so
multiple keys with the same names can occur.

=over 4

=item INPUT

      $dict  -- A dictionary created with
                ioCreateResult(...)
      $key   -- Key of the entry
      $value -- of the entry

=item RETURNS

      $dict -- the resulting dictionary

=item EXAMPLE

      my $out = $tk->ioCreateResult('DEFAULT','DATA.RECORD');
         $tk->ioAddResult($out, 'DISK.PATH',    $path);
         $tk->ioAddResult($out, 'COUNT.FILES',  $fcnt);

=back

=cut

sub ioAddResult ( $self, $dict, $key, $value ) {
    my $list = $dict->{DATA};
    push( @$list, [ $key, $value ] );
    return $dict;
}

...

0

There are 0 answers