manpage-scan.pl 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289
  1. #!/usr/bin/env perl
  2. #***************************************************************************
  3. # _ _ ____ _
  4. # Project ___| | | | _ \| |
  5. # / __| | | | |_) | |
  6. # | (__| |_| | _ <| |___
  7. # \___|\___/|_| \_\_____|
  8. #
  9. # Copyright (C) 2016, 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
  10. #
  11. # This software is licensed as described in the file COPYING, which
  12. # you should have received as part of this distribution. The terms
  13. # are also available at https://curl.haxx.se/docs/copyright.html.
  14. #
  15. # You may opt to use, copy, modify, merge, publish, distribute and/or sell
  16. # copies of the Software, and permit persons to whom the Software is
  17. # furnished to do so, under the terms of the COPYING file.
  18. #
  19. # This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  20. # KIND, either express or implied.
  21. #
  22. ###########################################################################
  23. #
  24. # Scan symbols-in-version (which is verified to be correct by test 1119), then
  25. # verify that each option mention in there that should have its own man page
  26. # actually does.
  27. #
  28. # In addition, make sure that every current option to curl_easy_setopt,
  29. # curl_easy_getinfo and curl_multi_setopt are also mentioned in their
  30. # corresponding main (index) man page.
  31. #
  32. # src/tool_getparam.c lists all options curl can parse
  33. # docs/curl.1 documents all command line options
  34. # src/tool_help.c outputs all options with curl -h
  35. # - make sure they're all in sync
  36. #
  37. # Output all deviances to stderr.
  38. use strict;
  39. use warnings;
  40. # we may get the dir roots pointed out
  41. my $root=$ARGV[0] || ".";
  42. my $buildroot=$ARGV[1] || ".";
  43. my $syms = "$root/docs/libcurl/symbols-in-versions";
  44. my $curlh = "$root/include/curl/curl.h";
  45. my $errors=0;
  46. # the prepopulated alias list is the CURLINFO_* defines that are used for the
  47. # debug function callback and the fact that they use the same prefix as the
  48. # curl_easy_getinfo options was a mistake.
  49. my %alias = (
  50. 'CURLINFO_DATA_IN' => 'none',
  51. 'CURLINFO_DATA_OUT' => 'none',
  52. 'CURLINFO_END' => 'none',
  53. 'CURLINFO_HEADER_IN' => 'none',
  54. 'CURLINFO_HEADER_OUT' => 'none',
  55. 'CURLINFO_LASTONE' => 'none',
  56. 'CURLINFO_NONE' => 'none',
  57. 'CURLINFO_SSL_DATA_IN' => 'none',
  58. 'CURLINFO_SSL_DATA_OUT' => 'none',
  59. 'CURLINFO_TEXT' => 'none'
  60. );
  61. sub scanmanpage {
  62. my ($file, @words) = @_;
  63. open(M, "<$file");
  64. my @m = <M>;
  65. close(M);
  66. foreach my $m (@words) {
  67. my @g = grep(/^\.IP $m/, @m);
  68. if(!$g[0]) {
  69. print STDERR "Missing mention of $m in $file\n";
  70. $errors++;
  71. }
  72. }
  73. }
  74. # check for define alises
  75. open(R, "<$curlh") ||
  76. die "no curl.h";
  77. while(<R>) {
  78. if(/^\#define (CURL(OPT|INFO|MOPT)_\w+) (.*)/) {
  79. $alias{$1}=$3;
  80. }
  81. }
  82. close(R);
  83. my @curlopt;
  84. my @curlinfo;
  85. my @curlmopt;
  86. open(R, "<$syms") ||
  87. die "no input file";
  88. while(<R>) {
  89. chomp;
  90. my $l= $_;
  91. if($l =~ /(CURL(OPT|INFO|MOPT)_\w+) *([0-9.]*) *([0-9.-]*) *([0-9.]*)/) {
  92. my ($opt, $type, $add, $dep, $rem) = ($1, $2, $3, $4, $5);
  93. if($alias{$opt}) {
  94. #print "$opt => $alias{$opt}\n";
  95. }
  96. elsif($rem) {
  97. # $opt was removed in $rem
  98. # so don't check for that
  99. }
  100. else {
  101. if($type eq "OPT") {
  102. push @curlopt, $opt,
  103. }
  104. elsif($type eq "INFO") {
  105. push @curlinfo, $opt,
  106. }
  107. elsif($type eq "MOPT") {
  108. push @curlmopt, $opt,
  109. }
  110. if(! -f "$root/docs/libcurl/opts/$opt.3") {
  111. print STDERR "Missing $opt.3\n";
  112. $errors++;
  113. }
  114. }
  115. }
  116. }
  117. close(R);
  118. scanmanpage("$root/docs/libcurl/curl_easy_setopt.3", @curlopt);
  119. scanmanpage("$root/docs/libcurl/curl_easy_getinfo.3", @curlinfo);
  120. scanmanpage("$root/docs/libcurl/curl_multi_setopt.3", @curlmopt);
  121. # using this hash array, we can whitelist specific options
  122. my %opts = (
  123. # pretend these --no options exists in tool_getparam.c
  124. '--no-alpn' => 1,
  125. '--no-npn' => 1,
  126. '-N, --no-buffer' => 1,
  127. '--no-sessionid' => 1,
  128. '--no-keepalive' => 1,
  129. # pretend these options without -no exist in curl.1 and tool_help.c
  130. '--alpn' => 6,
  131. '--npn' => 6,
  132. '--eprt' => 6,
  133. '--epsv' => 6,
  134. '--keepalive' => 6,
  135. '-N, --buffer' => 6,
  136. '--sessionid' => 6,
  137. # deprecated options do not need to be in tool_help.c nor curl.1
  138. '--krb4' => 6,
  139. '--ftp-ssl' => 6,
  140. '--ftp-ssl-reqd' => 6,
  141. # for tests and debug only, can remain hidden
  142. '--test-event' => 6,
  143. '--wdebug' => 6,
  144. );
  145. #########################################################################
  146. # parse the curl code that parses the command line arguments!
  147. open(R, "<$root/src/tool_getparam.c") ||
  148. die "no input file";
  149. my $list;
  150. my @getparam; # store all parsed parameters
  151. while(<R>) {
  152. chomp;
  153. my $l= $_;
  154. if(/struct LongShort aliases/) {
  155. $list=1;
  156. }
  157. elsif($list) {
  158. if( /^ \{([^,]*), *([^ ]*)/) {
  159. my ($s, $l)=($1, $2);
  160. my $sh;
  161. my $lo;
  162. my $title;
  163. if($l =~ /\"(.*)\"/) {
  164. # long option
  165. $lo = $1;
  166. $title="--$lo";
  167. }
  168. if($s =~ /\"(.)\"/) {
  169. # a short option
  170. $sh = $1;
  171. $title="-$sh, $title";
  172. }
  173. push @getparam, $title;
  174. $opts{$title} |= 1;
  175. }
  176. }
  177. }
  178. close(R);
  179. #########################################################################
  180. # parse the curl.1 man page, extract all documented command line options
  181. # The man page may or may not be rebuilt, so check both possible locations
  182. open(R, "<$buildroot/docs/curl.1") || open(R, "<$root/docs/curl.1") ||
  183. die "no input file";
  184. my @manpage; # store all parsed parameters
  185. while(<R>) {
  186. chomp;
  187. my $l= $_;
  188. if(/^\.IP \"(-[^\"]*)\"/) {
  189. my $str = $1;
  190. my $combo;
  191. if($str =~ /^-(.), --([a-z0-9.-]*)/) {
  192. # figure out the -short, --long combo
  193. $combo = "-$1, --$2";
  194. }
  195. elsif($str =~ /^--([a-z0-9.-]*)/) {
  196. # figure out the --long name
  197. $combo = "--$1";
  198. }
  199. if($combo) {
  200. push @manpage, $combo;
  201. $opts{$combo} |= 2;
  202. }
  203. }
  204. }
  205. close(R);
  206. #########################################################################
  207. # parse the curl code that outputs the curl -h list
  208. open(R, "<$root/src/tool_help.c") ||
  209. die "no input file";
  210. my @toolhelp; # store all parsed parameters
  211. while(<R>) {
  212. chomp;
  213. my $l= $_;
  214. if(/^ \{\" *(.*)/) {
  215. my $str=$1;
  216. my $combo;
  217. if($str =~ /^-(.), --([a-z0-9.-]*)/) {
  218. # figure out the -short, --long combo
  219. $combo = "-$1, --$2";
  220. }
  221. elsif($str =~ /^--([a-z0-9.-]*)/) {
  222. # figure out the --long name
  223. $combo = "--$1";
  224. }
  225. if($combo) {
  226. push @toolhelp, $combo;
  227. $opts{$combo} |= 4;
  228. }
  229. }
  230. }
  231. close(R);
  232. #
  233. # Now we have three arrays with options to cross-reference.
  234. foreach my $o (keys %opts) {
  235. my $where = $opts{$o};
  236. if($where != 7) {
  237. # this is not in all three places
  238. $errors++;
  239. my $exists;
  240. my $missing;
  241. if($where & 1) {
  242. $exists=" tool_getparam.c";
  243. }
  244. else {
  245. $missing=" tool_getparam.c";
  246. }
  247. if($where & 2) {
  248. $exists.= " curl.1";
  249. }
  250. else {
  251. $missing.= " curl.1";
  252. }
  253. if($where & 4) {
  254. $exists .= " tool_help.c";
  255. }
  256. else {
  257. $missing .= " tool_help.c";
  258. }
  259. print STDERR "$o is not in$missing (but in$exists)\n";
  260. }
  261. }
  262. exit $errors;