22 Feb 2010

Script bash pour générer le fichier de toutes les fonctions PHP

Category: Linux,PHP,Script Shell

Le script

Voici un petit script bash (nommons le all-php-func.sh) qui permet de générer la liste de toutes les fonctions PHP avec leurs argument.
Le principe est de « parser » le répertoire contenant tous les fichiers de description de la documentation officielle de PHP à coup de awk et de sed.
Le code mériterait d'être amélioré mais, pour ce qu'on lui demande de faire, il est reste convenable.

#!/bin/bash

#!/bin/bash

# Copyright (c) 2010, Philippe Ivaldi <www.piprime.fr>
# Version: $Id: all-php-func.sh,v 0.0 2010/02/22 10:36:08 Exp $

# This program is free software ; you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation ; either version 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY ; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.

# You should have received a copy of the GNU Lesser General Public License
# along with this program ; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

# COMMENTARY:

# This program generates the list of all php functions from the documentation of php.
# The functions are presented with its arguments.
# Using the -v option, a brief description is added in the line after.

# Output without -v option :
# 8<------8<------8<------8<------8<------8<------8<------8<------
# abs(mixed number)
# acos(float arg)
# acosh(float arg)
# addcslashes(string str, string charlist)
# etc…
# 8<------8<------8<------8<------8<------8<------8<------8<------

# Output with -v option :
# 8<------8<------8<------8<------8<------8<------8<------8<------
# abs(mixed number)
#    Absolute value --returns number--
# acos(float arg)
#    Arc cosine --returns float--
# acosh(float arg)
#    Inverse hyperbolic cosine --returns float--
# addcslashes(string str, string charlist)
#    Quote string with slashes in a C style --returns string--
# etc…
# 8<------8<------8<------8<------8<------8<------8<------8<------

# THANKS:

# BUGS:

# CODE:

DIR="/usr/share/doc/php-doc/html/"


VERBOSE=false
case $1 in
    -v)
        VERBOSE=true
        ;;
esac

function extract_function () {
    FUNC=$(cat "$1" | \
        awk -v FS="^Z" '/<div class="methodsynopsis \
dc-description">/,/<\/div>/{print}')

    if [ "X$FUNC" == "X" ]; then # cas des alias et autres
        FUNC=$(cat "$1" | \
            awk -v FS='<span class="refname">' -v RS='^Z' '{print $2}' | \
            awk -v FS='</span>' -v RS='^Z' '{print $1}')
        # On ajoute un type phantom car un type est attendu pour la suite…
        FUNC="? ${FUNC}"
    fi

    echo $FUNC | \
        tr '\n' ' ' | \
        awk 'BEGIN {ORS = "@-@"; RS = "<[^<>]*>"}{print}'  | \
        sed 's/@-@//g;s/\$//g' > /tmp/php-f

    SIGN=$(cat /tmp/php-f | awk '{for(k=2; k <= NF; k++) print $k}' | \
        tr '\n' ' ' | sed 's/ ( /(/g;s/ )/)/g;s/ ,/,/g')
    $VERBOSE && {
        TYP=$(cat /tmp/php-f | awk '{print $1}')

        DESC=$(cat $1 | \
            awk -v FS='<span class="dc-title">' -v RS='^Z' '{print $2}' | \
            awk -v FS='</span>' -v RS='^Z' '{print $1}' | \
            tr '\n' ' ' | \
            awk 'BEGIN {ORS = "@-@"; RS = "<[^<>]*>"}{print}'  | \
            sed -re "s/@-@//g;s/^ *//g;s/ *$//g;s/  +/ /g;s/&#039;/'/g;s/\\$//g")
    }

    echo "$SIGN"
    $VERBOSE && echo "   ${DESC} --returns $TYP--"
}


for fic in `find "$DIR" -name "function.*.html" | sort`; do
    extract_function "$fic"
done

Les fichiers

Si vous n'avez pas la chance d'être sous Gnu/Linux, vous pouvez quand même récupérer les fichiers tels qu'il sont à l'heure où j'écris ces lignes (je mettrais à jour sur demande).
all-php-func.sh > all-php-func.txt donne le fichier all-php-func.txt de toutes les fonctions php sans les descriptions.
all-php-func.sh -v > all-php-func-desc.txt donne le fichier all-php-func-desc.txt de toutes les fonctions php avec les descriptions.
sed 's/(.*)//g' all-php-func.txt > all-php-func-basic.txt donne le fichier all-php-func-basic.txt de toutes les fonctions php sans les arguments et sans les descriptions.

Mais à quoi cela peut-il bien servir ?

Voici quelques exemples d'utilisations.

  • On peut se servir du fichier all-php-func-basic.txt pour implémenter l'auto complètement (plus souvent connu sous l'anglicisme d'auto complétion) dans son éditeur favori. Par exemple, sous Emacs, il suffit de rajouter la ligne suivante :
    (setq php-completion-file "/ousque/vous/l/avez/mis/all-php-func-basic.txt")
  • En conjonction avec le script define-snippets.py de Andrew Gwozdziewycz on peut générer tous les snippet PHP pour yasnippet
  • En conjonction avec org-mode on peut obtenir une brève description de toutes les fonctions php en une seule page avec une présentation html sympathique.

Et vous, comment utilisez-vous ces fichiers ?