This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
devel/mkapidoc.sh: Add some config symbols
[perl5.git] / 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