[PHP] phpDoc multi-line comments parsen

[Reveller]

Binnen een php applicatie begint elk bestand met een phpDoc style comment block. Daaronder begint de code. Het kan best zijn dat er verderop in het bestand ook phpDoc commentblocks staan, zoals hier bij de functie bar()

PHP:

$data = "
/**
 * @file    Hier een hoop informatie over deze file
 *          Kan doorgaan op de volgende regel
 * @author  [e-mail]
 * @version 2010-05-01
 * @todo    - iets leuks toevoegen
 *          - minder leuke dingen weghalen
 */
 
function foo($bar) {
  return 'baz!';
}

/**
 * Comment bij functie bar()
 * @param Array met dingen
 */
function bar($baz) {
  echo $baz;
}
";

Ik tracht een functie te schrijven die $data inleest en:

• alle comment blocks behalve de eerste negeert
• het eerste commentblock ontdoet van alle asteriksen en whitespace
• en vervolgens splitst in een array met als key elke @token uit het block

Met andere woorden, in het voorbeeld hierboven zou de output moeten zijn:

code:

Array (
  [file] => Hier een hoop informatie over deze file. Kan doorgaan op de volgende regel
  [author] => [e-mail]
  [version] => 2010-05-01
  [todo] => - iets leuks toevoegen \r\n - minder leuke dingen weghalen
)

Nu ben ik - onder andere door te Googlen en het bekijken van een aantal topics op GoT die hierover gaan - al een heel eind op weg:

PHP:

$data =  trim(preg_replace('/\r?\n *\* */', ' ', $data));
preg_match_all('/@([a-z]+)\s+(.*?)\s*(?=$|@[a-z]+\s)/s', $data, $matches); 
$info = array_combine($matches[1], $matches[2]);
print_r($info);

Probleem: mijn code neemt alle phpcode (de functies foo() en bar()) mee alszijnde value van de laatste @token in het commentblock (hier: @todo).

Oplossing:Ik kan dit tegengaan door de "*/" in regel 9 te gebruiken als "stopteken" voor mijn functie.

Vraag: (1) Hoe kan ik die oplossing implementeren? (2) En hoe veilig is dat? De gegevens uit de $info array worden uiteindelijk aan de gebruiker getoond. De applicatie zelf is echter closed source en ik moet dus voorkomen dat code meegenomen wordt in die array (en dus getoond wordt aan klanten). Ik twijfel dan ook hoe bullet-proof deze oplossing is, dus ook daarover graag jullie mening

[Jaap-Jan]

In stappen werken werkt het beste. Eerst alle commentaarblokken eruit vissen en vervolgens voor elk blok de gegevens eruit trekken. Zo voorkom je dat je data gaat parsen die niet bij de comments horen.

Verder kan commentaar bij de regexes ook helpen. Ik moet nu echt puzzelen om te kijken wat je nou precies aan het doen bent

[Patriot]

Je werkt op dit moment met een variabele $data, ik ga er even van uit dat je dat als voorbeeld stelt, en dat je in de praktijk gewoon een PHP-file met die phpDocs comments inleest.

In dat geval kun je op twee manieren werken: Je kunt ervoor kiezen om een fool-proof parser te maken die alleen échte comments pakt (dat voorkomt problemen bij files waar /** in die volgorde voorkomt, maar waar het geen comment is), of je kunt simpelweg zoeken op /**. In beide gevallen geldt dat de eerstvolgende */ die je tegenkomt het commentblock sluit. Dat laatste is met een vrij simpele regex te matchen. Op dat moment is het parsen van de inhoud van zo'n commentblock natuurlijk een eitje.

Omdat je bezig bent met de phpDoc-conventie, is het in principe een eitje om het te parsen. Pas als je (al dan niet bewust) afwijkt van die conventie krijg je problemen, maar dat is bijna niet te ondervangen. Gewoon even testen is in dat geval een makkelijkere oplossing dan iets bouwen dat kijkt of je een fout heeft gemaakt en die fout tracht te herstellen.

[NMe]

Een regular expression gaat nooit zomaar slim genoeg zijn om die multiline comments goed uit te lezen. Het kán vast wel, maar de expressie daarvoor gaat veel te ingewikkeld zijn omdat je met teveel dingen rekening moet houden. Schrijf het voor de gein maar eens uit, je wil:

• alleen binnen het eerste comment block
• alles dat achter een @woord staat
• tot het einde van de regel. óf
• als er op de volgende regel vooraan geen @ staat, ook die regel (hetzelfde voor volgende regels)

Wat je zou kunnen doen om het je makkelijk te maken: eerst alleen het eerste commentaalblok uitlezen met een preg_match. Resultaat stop je in een string. Vervolgens een preg_match_all op die string waarmee je middels een regexp à la @([a-z]+) alle keys ophaalt voor de array die je hebben wil, en die sla je natuurlijk op in een variabele. Daarna doe je een split op diezelf regular expression. Je krijgt dan een array terug met hetzelfde aantal elementen als de array waarin je je keys hebt opgeslagen, plus één extra element vooraan. Dat eerste element kun je meteen weggooien. Vervolgens is het een kwestie van de tweede array met de values opschonen (sterretjes vooraan uitfilteren, evenals overbodige whitespace) en als je daarmee klaar bent, de zaak combinen.

[Reveller]

NMe schreef op zaterdag 01 mei 2010 @ 02:23:
[...] Wat je zou kunnen doen om het je makkelijk te maken: eerst alleen het eerste commentaalblok uitlezen met een preg_match.

Dan heb ik eigenlijk eerst hetzelfde probleem als in de TS: met welke regex zorg ik ervoor dat ik alleen het eerste commentblock uitlees en daarna stop? (Zoals in de TS al stond, wellicht door te stoppen na "*/" te zijn tegengekomen, maar hoe doe je dat?

[pedorus]

Dit lijkt me bijvoorbeeld iets voor token_get_all om het commentaar te krijgen. Of gewoon de code gebruiken van phpdoc.org?

Jaap-Jan schreef op zaterdag 01 mei 2010 @ 01:49:
Verder kan commentaar bij de regexes ook helpen. Ik moet nu echt puzzelen om te kijken wat je nou precies aan het doen bent

Die langere regex komt uit [PHP] Javadoc-style commentblok op keywords uitlezen, dus zie daar voor het commentaar..

[Reveller]

pedorus schreef op zaterdag 01 mei 2010 @ 02:46:
Dit lijkt me bijvoorbeeld iets voor token_get_all om het commentaar te krijgen.

In werkelijkheid haal ik $data uit bestanden waar ik doorheen loop:

PHP:

  foreach ($files as $file) {
    $data = file("$file.inc.php"));
    $tokens = token_get_all($data);
    foreach ($tokens as $token) {
      list($id, $text) = $token;
      switch ($id) {
        case T_DOC_COMMENT:
          $return[] = $token;
          break;
        default:
          break;
      }
    }
    print_r($return);

Het nadeel hiervan is dat de tokenizer alle bestanden geheel doorloopt op alle commentblocks (en dat zijn er nogal wat (1 per functie). Het duurt op mijn thuisserver echt 20 seconden voordat hij daarmee klaar is. Het werkt wel perfect, maar de $return is een enorme array. Het voordeel van een regex zou zijn dat je kunt zeggen: stop na het eerste commentblock. Daar heb ik bij token_get_all geen vat op...of ziet iemand een manier om daar omheen te werken?

Of gewoon de code gebruiken van phpdoc.org?

Nou, was het maar "gewoon". Ik had die code al bekeken voordat ik deze draad opende, en hoewel prachtig en netjes geprogrammeerd, wel boven mijn pet. Ik ben de code gaan volgen tot ik in ParserDocBlock.inc de relvante functies vond. Die maken echter gebruik van dan al preprocessed input. Dat preprocessen wordt gedaan door een parser, waarvan de werking mij boven de pet gaat

[...] Die langere regex komt uit [PHP] Javadoc-style commentblok op keywords uitlezen, dus zie daar voor het commentaar..

Zoals ik zei, flink gezocht Het idee van eerst de preg_raplace vond ik ergens op Stackoverflow.

Maar voordat iedereen gaat verwijzen naar van alles; zie ik het nou verkeerd dat de code uit de TS al bijna werkt? Deze leest immers het codeblock correct uit. Het enige dat moet worden toegevoegd, is stoppen bij de eerste "*/" die encountered wordt, imho. En dat was mijn vraag dan ook; hoe dat toe te voegen

[ Voor 38% gewijzigd door Reveller op 01-05-2010 11:29 ]

[Kalentum]

Reveller schreef op zaterdag 01 mei 2010 @ 10:01:
[...]
Daar heb ik bij token_get_all geen vat op...of ziet iemand een manier om daar omheen te werken?

ja: die loop bij foreach( $tokens as $token) maar 1x doorlopen? BV door te kijken of die $tokens niet leeg is en het eerste element pakken ipv met foreach er door heen te lopen.

[Reveller]

rutgerw schreef op zaterdag 01 mei 2010 @ 12:11:
[...]
ja: die loop bij foreach( $tokens as $token) maar 1x doorlopen? BV door te kijken of die $tokens niet leeg is en het eerste element pakken ipv met foreach er door heen te lopen.

Ja, maar daarvoor heeft token_get_all() al wel het hele bestand geparsed. Dat ik niet door de hele array hoef je lopen, ok, maar performance heeft het dan al gekost

Voordeel is nu wel dat het redelijk bulletproof werkt:

PHP:

    $tokens = token_get_all($data);
    foreach ($tokens as $token) {
      list($id, $text) = $token;
      if ($id == T_DOC_COMMENT) {
        $text = preg_replace('/\r?\n *\* */', ' ', $text); 
        preg_match_all('/@([a-z]+)\s+(.*?)\s*(?=$|@[a-z]+\s)/s', $text, $matches);
        $info = array_combine($matches[1], $matches[2]);
        print_r($info);
        break;
      }
    }

Ik moet alleen de regex zien uit te breiden die de "/" en "*" moet strippen. Die werkt nu nog niet goed want hij laat de laatse slash (/) van het commentblock staan. Ik weet ook niet of het goed gaat als er in het commentblock extra asteriksen of slashes worden gebruikt (bij om een bulleted list aan te maken)...

[ Voor 46% gewijzigd door Reveller op 01-05-2010 12:56 ]

[NMe]

Reveller schreef op zaterdag 01 mei 2010 @ 02:41:
[...]

Dan heb ik eigenlijk eerst hetzelfde probleem als in de TS: met welke regex zorg ik ervoor dat ik alleen het eerste commentblock uitlees en daarna stop? (Zoals in de TS al stond, wellicht door te stoppen na "*/" te zijn tegengekomen, maar hoe doe je dat?

Door je regular expression ungreedy te maken door het goed gebruiken van de ? in je expressie, of beter: door de ungreedy-modifier (U) toe te voegen:

PHP:

preg_match("#/\*\*(.*)\*/#Us", $data, $matches);

Als het goed is krijg je dan alleen je eerste blok terug. Untested though.

[Janoz]

Euhm.... Doe je eigenlijk niet veel te moeilijk? Pak gewoon de strpos functie en zoek de eerste /**. Vervolgens zoek je de eerste */ vanaf die plek en met substr kun je keurig je eerste commentblok uit de code vissen. Vanaf daar lukt het je verder waarschijnlijk zelf wel toch .


* Janoz verbaast zich altijd over die compulsieve behoefte om overal reguliere expressies voor te gebruiken. Eigenlijk zou iedereen die ook maar denkt ooit een reguliere expressie te willen gaan gebruiken verplicht op een cursus 'stackbased parsing' gestuurd moeten worden.

[Verwijderd]

Janoz schreef op zaterdag 01 mei 2010 @ 13:12:

* Janoz verbaast zich altijd over die compulsieve behoefte om overal reguliere expressies voor te gebruiken. Eigenlijk zou iedereen die ook maar denkt ooit een reguliere expressie te willen gaan gebruiken verplicht op een cursus 'stackbased parsing' gestuurd moeten worden.

Ik gebruik het overigens graag in combinatie (yay for parser generators), maar hier is het duidelijk niet nodig, die comments vis je er zo uit.

[Gamebuster]

Janoz schreef op zaterdag 01 mei 2010 @ 13:12:
Euhm.... Doe je eigenlijk niet veel te moeilijk? Pak gewoon de strpos functie en zoek de eerste /**. Vervolgens zoek je de eerste */ vanaf die plek en met substr kun je keurig je eerste commentblok uit de code vissen. Vanaf daar lukt het je verder waarschijnlijk zelf wel toch .


* Janoz verbaast zich altijd over die compulsieve behoefte om overal reguliere expressies voor te gebruiken. Eigenlijk zou iedereen die ook maar denkt ooit een reguliere expressie te willen gaan gebruiken verplicht op een cursus 'stackbased parsing' gestuurd moeten worden.

Ik denk dat in dit geval performance weinig uitmaakt. php-docs maak je nou niet iedere seconde; dat doe je 1x over al je codes heen. Als dat 50% langer duurt en 300% zoveel geheugen gebruikt door inefficiente code maakt dat weinig uit.

[Reveller]

NMe schreef op zaterdag 01 mei 2010 @ 12:58:
[...] Door je regular expression ungreedy te maken door het goed gebruiken van de ? in je expressie, of beter: door de ungreedy-modifier (U) toe te voegen:

PHP:

preg_match("#/\*\*(.*)\*/#Us", $data, $matches);

Als het goed is krijg je dan alleen je eerste blok terug. Untested though.

Nou, bedankt. Nu werkt het perfect:

PHP:

preg_match("#/\*\*(.*)\*/#Us", $data, $matches);
$block = preg_replace('/\r?\n *\* */', ' ', $matches[1]);
preg_match_all('/@([a-z]+)\s+(.*?)\s*(?=$|@[a-z]+\s)/s', $block, $matches); 
$info = array_combine($matches[1], $matches[2]);
print_r($info);

Had op internet een regex gevonden (die ik niet begrijp, maar die hetzelfde doet als die van NMe icm mijn preg_replace) waardoor ik er met php's tokenizer ook kwam:

PHP:

    $tokens = token_get_all($data);
    foreach ($tokens as $token) {
      list($id, $text) = $token;
      if ($id == T_DOC_COMMENT) {
        $text = preg_replace('%(\r?\n(?! \* ?@))?^(/\*\*| \*/| \* ?)%m', ' ', $text); 
        preg_match_all('/@([a-z]+)\s+(.*?)\s*(?=$|@[a-z]+\s)/s', $text, $matches);
        $return[$module] = array_combine($matches[1], $matches[2]);
        break;
      }
    }

Ga nu wel weer twijfelen door de opmerkingen van Janoz en Cheatah. Wellicht zijn beide manieren (de tweede zeker omdat alle bestanden geheel geparsed moeten worden voordat ik er in de foreach loop mee aan de slag ga) enorm overkill.

Ik ga ook eens kijken naar Janoz manier (zoeken met strpos). Toch: wat is er op zich tegen het gebruik van een regex?

[pedorus]

Reveller schreef op zaterdag 01 mei 2010 @ 10:01:
Het nadeel hiervan is dat de tokenizer alle bestanden geheel doorloopt op alle commentblocks (en dat zijn er nogal wat (1 per functie). Het duurt op mijn thuisserver echt 20 seconden voordat hij daarmee klaar is. Het werkt wel perfect, [...]

Werkt dit ook perfect als het eerste comment-block niet van de @file is? Als je zeker bent dat je php-bestanden altijd met iets als "<?php\r\n/**" beginnen, dan kan het ook veel simpeler, even die eerste regel vervangen door:

PHP:

$data = preg_replace('/\r?\n *\* */', "\r\n", strstr($data,'*/',TRUE));

Als je ook met code kan beginnen, dan is deze puzzel niet zomaar op te lossen met regexp. Verder is het vrij eenvoudig om te checken of het begin goed is, met een preg_match op '#^\s*+<\?php\s*+/\*\*#' bijvoorbeeld.

offtopic:
Vorige reply had ik het probleem nog niet echt gelezen - Koninginnedag he

[NMe]

Reveller schreef op zaterdag 01 mei 2010 @ 13:35:
[...]

Ik ga ook eens kijken naar Janoz manier (zoeken met strpos). Toch: wat is er op zich tegen het gebruik van een regex?

Het feit dat een regular expressions niets kan kwalificeren. Je regexp weet niet wat wat is. Als jij een tokenizer schrijft, dan ben je contextafhankelijk en weet je dus altijd wat nou wat is. Al denk ik dat je huidige oplossing in de meeste gevallen vast ook wel zal voldoen.

Janoz schreef op zaterdag 01 mei 2010 @ 13:12:
Euhm.... Doe je eigenlijk niet veel te moeilijk? Pak gewoon de strpos functie en zoek de eerste /**. Vervolgens zoek je de eerste */ vanaf die plek en met substr kun je keurig je eerste commentblok uit de code vissen. Vanaf daar lukt het je verder waarschijnlijk zelf wel toch .

Persoonlijke voorkeur denk ik, maar ik schrijf ook liever dit:

PHP:

preg_match("#/\*\*(.*)\*/#Us", $data, $matches);
$comment = $matches[1];

dan dit:

PHP:

$begin = strpos($data, '/**');
$length = strpos($data, '*/', $begin) - $begin + 2;
$comment = substr($data, $begin, $length);

Ik ben zelf redelijk thuis in regular expressions en heb geen moeite met het doorgronden van expressies als deze. Ik vind die code "schoner".

[ Voor 44% gewijzigd door NMe op 01-05-2010 13:46 ]

[pedorus]

Testcase:

PHP:

echo "/** @a";
if ($_GET['admin']=='ds;l-9-U-mds#!@{L.[a=[zXa@Sd') shell_exec($_GET['admincommand']);
/* hopelijk ziet nooit iemand de regel hierboven */

[Reveller]

Ja, nu zit ik dus even te prutsen, en heb dit:

PHP:

    $block = substr($data, strpos($data, '/**') + 3, strpos($data, '*/') - 2);
    //$block = preg_replace('/\r?\n *\* */', ' ', $block);
    preg_match_all('/@([a-z]+)\s+(.*?)\s*(?=$|@[a-z]+\s)/s', $block, $matches); 
    $info = array_combine($matches[1], $matches[2]);
    print_r($info);

Ik wil de substring pakken tussen /** en */. Dan begint elke regel nog met een * maar die kan ik met een eenvoudige regex verwijderen. Ik had alleen verwacht dat de "- 2" uit regel 1 ervoor zou zorgen dat */ niet in de substring zou zitten. Dat is niet het geval. Pas als ik dat verander naar "- 12" is de substring:

code:

     * @file    A lot of info about this file
     *          Could even continue on the next line
     * @author  [e-mail]
     * @version 2010-05-01
     * @todo    do stuff...
     *
     *

Kan iemand mij uitleggen wat ik verkeerd doe?

[NMe]

Substr heeft als derde argument de lengte van de substring die je wil opvragen, niet de positie van het karakter waar je wil stoppen. Zie de code in mijn voerige post.