dist/Devel-PPPort/devel/mkapidoc.sh

   1 #!/bin/bash
   2 ################################################################################
   3 #
   4 #  mkapidoc.sh -- generate apidoc.fnc from scanning the Perl source
   5 #
   6 # Should be called from the base directory for Devel::PPPort.
   7 # If that happens to be in the /dist directory of a perl build structure, and
   8 # you're doing the standard thing, no parameters are required.  Otherwise
   9 # (again with the standard things, it can be called with one parameter:
  10 #       sh devel/mkapidoc.sh /path/to/the/embed.fnc/you/want
  11 #
  12 ################################################################################
  13 #
  14 #  Version 3.x, Copyright (C) 2004-2013, Marcus Holland-Moritz.
  15 #  Version 2.x, Copyright (C) 2001, Paul Marquess.
  16 #  Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
  17 #
  18 #  This program is free software; you can redistribute it and/or
  19 #  modify it under the same terms as Perl itself.
  20 #
  21 ################################################################################
  22
  23 function isperlroot
  24 {
  25   [ -f "$1/embed.fnc" ] && [ -f "$1/perl.h" ]
  26 }
  27
  28 function usage
  29 {
  30   echo "USAGE: $0 [perlroot] [output-file] [input embed.fnc] [input config_h.SH]"
  31   exit 0
  32 }
  33
  34 if [ -z "$1" ]; then
  35   if isperlroot "../../.."; then
  36     PERLROOT=../../..
  37   fi
  38 else
  39   PERLROOT=$1
  40 fi
  41
  42 if [ -z "$2" ]; then
  43   if [ -f "parts/apidoc.fnc" ]; then
  44     OUTPUT="parts/apidoc.fnc"
  45   else
  46     usage
  47   fi
  48 else
  49   OUTPUT=$2
  50 fi
  51
  52 if [ -z "$3" ]; then
  53   EMBED="$PERLROOT/embed.fnc"
  54 else
  55   EMBED=$3
  56 fi
  57
  58 if [ -z "$4" ]; then
  59   CONFIG="$PERLROOT/config_h.SH"
  60 else
  61   CONFIG=$4
  62 fi
  63
  64 if isperlroot $PERLROOT; then
  65   cat >$OUTPUT <<EOF
  66 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  67 :
  68 :  !!!! Do NOT edit this file directly! -- Edit devel/mkapidoc.sh instead. !!!!
  69 :
  70 :  This file was automatically generated from the API documentation scattered
  71 :  all over the Perl source code. To learn more about how all this works,
  72 :  please read the F<HACKERS> file that came with this distribution.
  73 :
  74 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  75
  76 :
  77 : This file lists all API functions/macros that are documented in the Perl
  78 : source code, but are not contained in F<embed.fnc>.
  79 :
  80
  81 : This line needs to be in this file for things to work, even though it's been
  82 : removed from later embed.fnc versions
  83 ApTod   |int    |my_sprintf     |NN char *buffer|NN const char *pat|...
  84
  85 EOF
  86     grep -hr '^=for apidoc' $PERLROOT | sed -e 's/=for apidoc //'           \
  87   | grep '|'                                                                \
  88   | sort                                                                    \
  89   | uniq                                                                    \
  90   | sort -f -t'|' -k3                                                       \
  91   | perl -e 'use warnings;
  92              use strict;
  93              my $c=pop;
  94              my $f=pop;
  95              my %h;
  96
  97              # Populate %h with the embed.fnc entry names
  98              open(F,$f) || die "$f:$!";
  99              while (<F>) {                      # In embed.fnc,
 100                 next unless /^[A-Za-z]+\t/;     # skip lines that arent defns
 101                 (  split /\s*\|\s*/ ) [2] =~ /(\w+)/;
 102                 $h{$1}++;   # Note in %h that $1 is in $EMBED
 103             }
 104             close F;
 105
 106             # STDIN consists of the =for apidoc lines.  Those in embed.fnc
 107             # already give us their prototypes, so skip.  Otherwise massage the
 108             # input somewhat and save them
 109             my @entries;
 110             while (<>) {
 111                 s/\|/d|/ unless /^[^|]*d/; # Many of the entries omit the "d"
 112                                            # flag to indicate they are
 113                                            # documented, but  we wouldnt have
 114                                            # found this unless it was
 115                                            # documented in the source
 116                 s/[ \t]+$//;
 117                 (  split /\s*\|\s*/  ) [2] =~ /(\w+)/;
 118                 push @entries, $_ unless $h{$1}
 119             }
 120
 121             # The entries in config_h.SH are also (documented) macros that are
 122             # accessible to XS code, and ppport.h backports some of them.  We
 123             # use only the unconditionally compiled parameterless ones (as
 124             # that"s all that"s backported so far, and we don"t have to know
 125             # the types of the parameters.
 126             open(C, "<", $c) or die "$c: $!";
 127             my $if_depth = 0;   # We don"t use the ones within #if statements
 128                                 # The #ifndef that guards the whole file is not
 129                                 # noticed by the code below
 130             while (<C>) {
 131                 $if_depth ++ if / ^ \# [[:blank:]]* (ifdef | if\ defined ) /x;
 132                 $if_depth -- if $if_depth > 0 && / ^ \# [[:blank:]]* endif /x;
 133                 next unless $if_depth <= 0;
 134
 135                 # We are only interested in #defines with no parameters
 136                 next unless /^ \# [[:blank:]]* define [[:blank:]]+
 137                                  ( [A-Za-z][A-Za-z0-9]* )
 138                                  [[:blank:]]
 139                             /x;
 140                 next if $h{$1}; # Ignore duplicates
 141                 push @entries, "Amnd||$1\n";
 142                 $h{$1}++;
 143             }
 144             close C;
 145
 146             require "./parts/inc/inctools";
 147             print sort sort_api_lines @entries;
 148            '  $EMBED $CONFIG >> $OUTPUT
 149 else
 150   echo "$0: First parameter must be a directory containing embed.fnc and perl.h"
 151   usage
 152 fi