Module:Wikidata/Chemin/Documentation

Ceci est la page de documentation de Module:Wikidata/Chemin [modifier] [purger].

Cette sous-page contient les instructions et les catégories de son module d'origine et elle n'est pas destinée à être visualisée directement.

Cette page est en cours de réécriture ou de restructuration importante (indiquez la date de pose grâce au paramètre date).

Un utilisateur prévoit de modifier cet article pendant plusieurs jours. Vous êtes invité(e) à en discuter en page de discussion et à participer à son amélioration de préférence en concertation pour des modifications de fond.

Le module Wikidata/Chemin est une implémentation un peu adaptée des PropertyPath de Q54871 (« SPARQL ») en Lua poun Wikidata et les clients Wikibase.

Il existe cependant quelques différences entre les chemins de propriétés sparql et cette implémentation:

la syntaxe est étendue pour gérer les qualificatifs des déclarations (opérateur >)
contrairement au cas de l’implémentation sparql, il est nécessaire de fournir un point de départ pour le calcul des valeurs possibles au bout du chemin
il est possible d’utiliser les identifiants Wikidata des propriétés sans préfixe d’uri, et il est également possible d’utiliser les intitulés des propriétés dans la langue principale du wiki (par exemple il est possible d’utiliser père pour la propriété P22 (« père »)
l’opérateur ^ ne peut pas fonctionner en lua avec l’API mw.wikibase actuelle (mai 2019)

Chemins

Exemple introductif

Un chemin pour trouver les petits-enfants "enfant/enfant" sera notre premier chemin. Nous allons l’utiliser en paramètre d’un modèle de démonstration capable d’utiliser des chemins, à partir d’un élément choisi, prenons l’élément du Dieu Grec Zeus (Q34201 (« Zeus ») : {{Liste valeur chemin wikidata|Q34201|enfant/enfant}}

Le modèle liste en premier résultat (au moment de l’écriture de ces lignes) Q572133 (« Antéros »). La raison de sa présence est l’existence d’une déclaration Wikidata

Q34201 (« Zeus »)

P22 (« père ») : Q40901 (« Arès »)

puis sur Q40901 (« Arès ») d’une déclaration

Q40901 (« Arès »)

P22 (« père ») : Q572133 (« Antéros ») .

En réalité Zeus à de nombreux autres petits enfants qui ne sont par montrés parce que le modèle se limite par défaut à un certain nombre de résultats.

De manière similaire, si nous voulons lister les mères des enfants de Zeus nous pouvons utiliser le chemin enfant/P25 grâce à la propriété P25 (« mère ») :

Ces exemples n’utilisent qu’un seul connecteur, / qui permet d’exprimer une séquence de déclarations. Il en existe d’autre que nous allons décrire brièvement dans la section suivante, qui peuvent se combiner pour créer des chemins plus complexes.

Opérateurs

Dans ce qui suit, un chemin d’entités sera une séquence d’éléments et de propriétés. Un chemin d’entités sera potentiellement terminé par une valeur Wikidata comme une date ou une quantité. Voici un exemple de chemin d’entités Q1001 (« Mahatma Gandhi ») → P31 (« nature de l’élément ») → Q5 (« être humain ») → P279 (« sous-classe de ») → Q215627 (« personne ») ou Q34201 (« Zeus ») → P40 (« enfant ») → Q40901 (« Arès ») → P40 (« enfant ») → Q572133 (« Antéros »). Il est possible de créer des chemins à partir des déclarations Wikidata en partant d’un élément est en suivant les propriétés principales et valeurs principales des différentes déclaration, mais également en suivant les propriétés des qualificatifs et leurs valeurs. Dans ce dernier cas, un chemin peut ressembler à ceci Q991 (« Fiodor Dostoïevski ») → P19 (« lieu de naissance ») → Q656 (« Saint-Pétersbourg ») → P1448 (« nom officiel ») → P580 (« date de début »)

Nous allons maintenant décrire la manière de faire correspondre les « chemins de propriétés » (qu’on appellera également « motif de chemin »), qu’on peut voir comme des motifs, à l’instar des expressions rationnelles à des chemins d’entités. Pour cela nous allons introduire l’opération de « dévorage », entre un chemin de propriété et un chemin d’entités. On dira qu’une propriété peut « dévorer » un chemin d’entité C si la première propriété du chemin est P. Le résultat de l’opération sera le chemin auquel on aura ôté les deux premiers éléments. Par exemple si

P peut dévorer C pour donner le résultat suivant Q656 (« Saint-Pétersbourg ») → P1448 (« nom officiel ») → P580 (« date de début »). Aucune autre propriété ne peut dévorer ce chemin. Nous allons l’étendre dans la suite à des chemins plus complexes que ceux composés avec une unique propriété. L’opération de « dévorage » est utilisée pour construire l’opération de « correspondance » entre un chemin de propriété et un chemin d’entité. Elle peut trouver tous les chemins d’entités qu’on peut construire en partant d’un élément et en suivant les différentes propriétés. Un chemin de propriété correspond à un chemin d’entité si le chemin de propriété peut dévorer entièrement le chemin, à l'exception de son dernier élément.

Par exemple : le chemin Mexique → limitrophe de → USA → limitrophe de → Canada correspond au motif limitrophe de/limitrophe de mais ne correspond pas à limitrophe de ni à limitrophe de/limitrophe de/limitrophe de. Le premier ne correspond pas parce que certaines parties du chemin ne sont pas dévorées, et le dernier parce que le dernier limitrophe de n’a rien à dévorer.

Ce module implémente l’opération d’énumérer les chemins d’entités qui correspondent (peuvent être totalement dévorés) par un motif de chemins. Les différents motifs ont définis dans la suite à l’aide d’opérateurs, pour lesquels on étendra l’opération de dévorage.

Un chemin est construit à partir de chemins élémentaires (des propriétés) et d’opérateurs qui combinent des chemins.

chemin élémentaire: Un chemin élémentaire est soit un identifiant de propriété, comme P31, soit un intitulé de propriété en français comme nature. Un chemin élémentaire dévore un chemin d’entité comme expliqué ci-dessus.
/: l’opérateur de séquençage. Voir l’exemple introductif. Si P1 est un chemin et P2 est un chemin alors P1/P2 est également un chemin P1/P2 dévorera un chemin d’entités CE si P1 dévore CE dans un premier temps, puis si P2 dévore le résultat de ce premier dévorage dans un deuxième temps.
|: L’opérateur d’alternative. Si P1 est un chemin et P2 est un chemin alors P1|P2 est également un chemin. P1|P2 dévorera un chemin CI si soit P1 dévore IP, soit P2 dévore CI. Le résultat est le résultat de l’opération de dévorage de l’alternative qui correspond.
?: Un opérateur qui rend le chemin qui précède optionnel. Il « dévorera » quelque chose quoi qu’il arrive. Par exemple le motif limitrophe de? en partant de l’élément « Mexico » correspondra au chemin d’entité Mexique (dans ce cas le résultat de l’opération laisse le chemin inchangé) mais également le chemin Mexique → limitrophe de → USA (dans ce cas le résultat du dévorage est USA .
*: Un opérateur (qui correspond à l’étoile de Kleene) qui comme le précédent dévore quelque chose quoi qu’il arrive. Si P est un motif, alors P* est aussi un motif. Il peut manger des chemins de taille arbitraire (en théorie, il existe une limite dans l’implémentation) en répétant le dévorage autant de fois que possible l’opération de dévorage de P. Par exemple le code (père|mère)* va correspondre aux chemins d’entités qui mène d’une personne vers tous ses ancêtres (en incluant elle-même). Elle trouvera le père et la mère de quelqu’un, puis les parents de ces parents, les parents des grands parents et ainsi de suite.
+: P+ est équivalent à P/P*. Similaire à l’opérateur * sauf que le chemin sous jascent P doit pouvoir dévorer au moins une fois.
>: This operator is related to qualifier snaks matching. For example the path union of>of will eat the qualifier "of" snaks of the statements "union of" of an item. The values from which the next operator of the path will start is the value of the snak.; It also can be used either at the very beginning of the path, if the starting point of the path is a statement and not an item.
!: This operator is a way to define property that will not be eaten. It is followed by either a single property or a list of properties separated by a | put into parenthesis. for example !(instance of|subclass of) will eat any (one-propertied) path like Donald Duck → Father → Picsou, but neither Ghandi → instance of → human nor human → subclass of → animal. It can also be used with the > operator to exclude a set of qualifiers for matching.
{number} and {min, max}: This operator is used to specify that a path can match several times, but with a bound. P{4} is equivalent to P/P/P/P, that is P must eat exactly four times something, and P{4,6} must match between 4 and six times. It's equivalent to P/P/P/P/P?/P?

Results

This module manipulates and generate a datastructure called "ResultNode" that represent nodes on a matching path (a path that is totally eaten by a path pattern).

The path is designed such as the result is a linked list of Nodes. Those nodes represents a path (say <human> → <P31> → <Q5> → <P279> → <Q42> ) in backward order. Actually each node can be interpreted as either a snak or a statement (like the <P279> → <Q42>) in the usual lua Wikidata data model (it's actually a snak or a statement which is adjoined a few functions and attributes. So a result node can be used as a snak or a statement in the functions of Module:Wikidata.

The previous snak or statement can be retrieved thanks trough the "parent" field of the node.

Interface

Main functions
iterate

path (string), start_item (string, entity object) -> iterator (on result node)

function that takes a path and a start item and returns an iterable object, usable in lua for loops that iterates over the set of paths matching the pattern, each represented by a ResultNode (see above)

Utilisation

Fonctions exportables :

fonction(frame) – description (courte description de fonction(frame) et autres informations pertinentes).
fonction2() – description2 (courte description de fonction2() et autres informations pertinentes).

Autres fonctions :

fonction() – description2 (courte description de fonction() et autres informations pertinentes).

Modules externes et autres éléments dont ce module a besoin pour fonctionner :

mw.title – description (courte description expliquant la dépendance de ce module externe).

Exemples

Pour des exemples, voir la page de test permettant de tester diverses modifications apportées.

Projet Scribunto