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]"
  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 isperlroot $PERLROOT; then
  59   cat >$OUTPUT <<EOF
  60 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  61 :
  62 :  !!!! Do NOT edit this file directly! -- Edit devel/mkapidoc.sh instead. !!!!
  63 :
  64 :  This file was automatically generated from the API documentation scattered
  65 :  all over the Perl source code. To learn more about how all this works,
  66 :  please read the F<HACKERS> file that came with this distribution.
  67 :
  68 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  69
  70 :
  71 : This file lists all API functions/macros that are documented in the Perl
  72 : source code, but are not contained in F<embed.fnc>.
  73 :
  74
  75 : This line needs to be in this file for things to work, even though it's been
  76 : removed from later embed.fnc versions
  77 ApTod   |int    |my_sprintf     |NN char *buffer|NN const char *pat|...
  78
  79 EOF
  80     grep -hr '^=for apidoc' $PERLROOT | sed -e 's/=for apidoc //'           \
  81   | grep '|'                                                                \
  82   | sort                                                                    \
  83   | uniq                                                                    \
  84   | sort -f -t'|' -k3                                                       \
  85   | perl -e 'use warnings;
  86              use strict;
  87              my $f=pop;
  88              my %h;
  89
  90              # Populate %h with the embed.fnc entry names
  91              open(F,$f) || die "$f:$!";
  92              while (<F>) {                      # In embed.fnc,
  93                 next unless /^[A-Za-z]+\t/;     # skip lines that arent defns
  94                 (  split /\s*\|\s*/ ) [2] =~ /(\w+)/;
  95                 $h{$1}++;   # Note in %h that $1 is in $EMBED
  96             }
  97             while (<>) {
  98                 s/\|/d|/ unless /^[^|]*d/; # Many of the entries omit the "d"
  99                                            # flag to indicate they are
 100                                            # documented, but  we wouldnt have
 101                                            # found this unless it was
 102                                            # documented in the source
 103                 s/[ \t]+$//;
 104                 (  split /\s*\|\s*/  ) [2] =~ /(\w+)/;
 105                 $h{$1} || print
 106             }'  $EMBED >> $OUTPUT
 107 else
 108   echo "$0: First parameter must be a directory containing embed.fnc and perl.h"
 109   usage
 110 fi