Pegjs: Documenter les variables et les méthodes peg$ dans un analyseur généré

Créé le 3 sept. 2017 · 2Commentaires · Source: pegjs/pegjs

Comme mentionné par @felix9 dans #526 , les variables (ainsi que les méthodes) qui sont préfixées par peg$ dans l'analyseur généré ne sont pas exactement bien connues, les développeurs ne les découvrant que lorsqu'ils :

fouiller dans l'analyseur généré
regarder à travers la source de PEG.js
renseignez-vous auprès d'un autre développeur PEG.js (le cas le plus courant je suppose)

Corrigeons cela avec plus de documentation (la joie 😑), ainsi que des identifiants réservés aux documents dans l'espace de noms peg$ (par exemple, peg$c est utilisé par les actions, les jetons, etc.) afin que les développeurs sachent quoi ne pas à écraser, et les pirates savent exactement quoi écraser 🤣

[ ] Variables utilisables
[ ] Méthodes utilisables (aides internes)
[ ] Identifiants réservés non recommandés pour l'écrasement
[ ] Exemples de ce qui pourrait être accompli en utilisant ces

documentation task

Source

futagoza

Commentaire le plus utile

Les variables et fonctions peg$ étaient censées être internes. Ils sont liés aux spécificités de l'implémentation de PEG.js et l'idée était qu'ils peuvent changer à tout moment entre les versions (et ils l'ont fait dans le passé). Ce ne sont certainement pas des API !

Il peut être judicieux de documenter les variables et fonctions peg$ dans le cadre de la documentation des composants internes de PEG.js, mais je déconseille fortement l'idée de les rendre officiellement disponibles pour les auteurs d'analyseurs et/ou les auteurs de plugins. Cela limiterait le développement de PEG.js à l'avenir. Mieux vaut construire l'API dessus.

dmajda le 14 oct. 2017

👍3

Tous les 2 commentaires

dmajda le 14 oct. 2017

👍3

Alors peut-être qu'il devrait y avoir une documentation explicite indiquant que les identifiants "peg$" ne sont pas garantis stables d'une version à l'autre et ne doivent pas être invoqués.