J’utilise régulièrement ruby-taglib. Malheureusement, certains bugs empêchent son utilisation avec ruby 1.9. Après avoir tenté, avec plus ou moins de succès, de corriger ces bugs, j’ai décidé de réécrire cette bibliothèque. La version originale est basée sur ruby/DL, bibliothèque que je n’ai jamais utilisée. Je profite de cette réécriture pour proposer une série d’articles sur la manière d’adapter une bibliothèque C.

Préparation

Je développe pour l’instant sous ubuntu 10.04 (je terminerai sûrement ces articles sous la version 10.10). J’ai installé taglib, ruby et rdoc soit les paquets debian suivant : libtagc0, libtagc0-dev, ruby, ruby-dev, rdoc.

Hiérarchie

La commande tree présente l’arborescence de mon répertoire de travail.

Le fichier extconf.rb, écrit en ruby, permettra de préparer les sources en vue de compiler la bibliothèque. Le fichier lib/taglib2.rb, lui aussi écrit en ruby, est le fichier lu par l’interpréteur ruby lors de l’appel à require « taglib2″ qui chargera notre future bibliothèque.Le fichier taglib2.c, écrit en C, contiendra les méthodes qui permettent d’interfacer taglib.

Ruby

Dans un premier temps, j’utiliserai seulement le langage ruby. J’écris donc les premières lignes de code dans le fichier lib/taglib2.rb.

Une constante nommée VERSION est définie comme un tableau contenant 3 entiers. D’ores et déjà, je peux tester mon code grâce à irb, un interpréteur ruby en ligne de commande. La bibliothèque n’étant pas encore installée, j’utilise un chemin relatif pour y accéder.

Interface ruby/C

Exceptions

Nous nous intéressons enfin au fichier taglib2.c. Nous définissons, tout d’abord, les différents types d’exceptions qui peuvent être levés par la bibliothèque.

Les fichiers nécessaires au développement de la bibliothèque sont tout d’abord inclus puis nous déclarons des variables de type VALUE. Ce type est utilisé pour toute variable représentant un objet du langage ruby. Les noms de variables représentant des exceptions sont généralement préfixés par la lettre e. Pour les modules, la lettre m est utilisée, pour les classes, la lettre c.
Il s’agit d’une convention et non d’une règle. Finalement, on retrouve la fonction Init_taglib2 qui (re)définit le module TagLib ainsi que 4 classes descendant de la classe ruby Exception représentée en C par la variable rb_eException.

Le code suivant, écrit en ruby, est équivalent à la définition donnée en C de l’exception TagLib::BadPath

Compilation

Afin de compiler notre bibliothèque, nous devons créer un fichier Makefile. La bibliothèque mkmf nous facilite le travail.

Dans le fichier extconf.rb, la présence des fichiers « header » de ruby et de taglib sont vérifiées ligne 3 et 4. La ligne 6 permet de créer le fichier Makefile du projet taglib2. Lors du chargement d’une interface ruby/C, la fontion appelée est de la forme Init_NomDuProjet,c’est pourquoi l’unique fonction du fichier taglib2.c s’appelle Init_taglib2. Il s’agit de l’équivalent de la fonction main d’un programme C traditionnel.

Après avoir créer le fichier Makefile, compilons.

Un bibliothèque dynamique taglib2.so vient de faire son apparition. Ruby permet de charger directement ce type de bibliothèque. Nous ajoutons donc l’instruction (require « taglib2.so ») de chargement dans le fichier lib/taglib2.rb.

Test

Nous testons notre code sous irb.

J’ajoute tout d’abord le répertoire courant et le répertoire lib dans les chemins vérifiés lors du chargement d’un fichier afin que les appels à require « taglib2″ et à require « taglib2.so » n’échouent pas. Cette astuce ne sera plus nécessaire une fois la bibliothèque installée. On vérifie que les constantes définies dans les fichiers sources lib/taglib2.rb et taglib2.c sont accessibles.

Conclusion

Lors de ce premier billet, j’ai mis en place les différents éléments (bibliothèques, fichiers) qui seront nécessaires à l’interface ruby de taglib. Nous avons, déjà, réussi à obtenir un code fonctionnel. Il nous reste à porter les fonctions proposées par taglib afin de pourvoir accéder, en ruby, aux tags de fichiers musicaux.
À la prochaine.

Je ne suis pas un spécialiste du langage C, si vous avez des suggestions à faire sur mon code
commentez ce billet.

Addendum

Je rajoute la liste des billets faisant suite à celui-ci :

• billet 2,
• billet 3,
• billet 4,
• billet 5.

Je vais présenter ici quelques fonctions utiles. Pour des questions de faciliter, j’ai créé deux nouvelles méthodes pour le module TagLib bien qu’elles n’aient rien avoir avec taglib.

Utiliser un bloc

La méthode TagLib.block ne prend aucun paramètre, mais un bloc doit lui être fourni. Elle exécute ce bloc en lui passant comme argument l’objet TagLib et retourne le bloc sous la forme d’un Proc.

Voici la fonction implémentant ce comportement.

rb_yield permet d’appeler le bloc passé à la méthode alors que rb_block_proc permet de le manipuler sous la forme d’un Proc.

Utiliser des paramètres optionnels

Je propose d’écrire l’équivalent de code écrit en ruby.

Le dernier argument lors de la déclaration de la méthode TagLib.n vaut -1 ce qui indique que la méthode ne possède pas un nombre d’arguments fixees. La fonction rb_scan_args permet de récupérer de manière propre les paramètres passés à la méthode. Le troisième argument de cette fonction est une chaîne de caractère représentant deux chiffres. Le premier indique le nombre de paramètres obligatoires, le second indique le nombre de paramètres optionnels.

TagLib.n peut donc être appelée avec un paramètre ou sans. Si aucun argument n’a été passé (tab=nil), tab est initialisé en créant un tableau contenant deux objets String. On vérifie ensuite que tab appartient à la classe Array ou s’en rapproche (duck typing). rb_funcall permet d’appeler une méthode (deuxième argument) d’un objet (premier argument) avec un certain nombre (troisième argument) de paramètres (arguments suivant). rb_intern permet d’obtenir la méthode à partir d’une chaîne de caractères.
La fonction n1 est ensuite appelé pour chacun des éléments du tableau grâce à rb_iterate. LA méthode retourne, finalement, le premier élément de tab, la macro RARRAY permettant d’accéder à la structure interne d’un objet de la classe Array, le champ ptr permettant d’accéder aux éléments.

Liens utiles

Quelques liens qui m’ont aidé à écrire des extensions pour ruby en C :
le fichier README.EXt fourni avec ruby,
ruby-doc.
En ce qui concerne taglib :
l’exemple dans les sources de taglib,
le fichier bindings/c/tag_c.h.

Sources

Le code, présenté dans ces billets, implémentant le module, TagLib est téléchargeable ici.

Conclusion

Cette série d’articles est finie. J’espère qu’ils vous seront utiles.

Documentation

Commenter

Pour documenter les méthodes de la classe TagLib::File, il suffit de commenter les différentes fonctions les implémentant.

La méthode title permet d’obtenir le titre d’une piste. On l’indique en commentaire juste avant la fonction file_get_title.

Par défaut, les paramètres d’une méthode sont nommés p1, p2, …. Pour la méthode title=, on utilise l’instruction call-seq: pour afficher le texte title=title (au lieu de title=(p1)).

La méthode initialize ne devrait jamais être appelée directement depuis un code ruby. On utilise l’instruction :nodoc: pour indiquer que la méthode ne doit pas apparaitre dans la documentation.

J’indique que je ne désire pas commenter le module TagLib en plaçant un commentaire vide afin d’éviter que rdoc utilise un commentaire non-désiré.

Dans le fichier lib/raglib2.rb, j’ajoute la directive :main: afin que la page initiale de la documentation pointe sur la classe TagLib::File.

Bizarrement, cette directive ne semble pas fonctionner si elle est placée dans le fichier taglib2.c.

Produire la documentation

Le fichier doc/index.html est créé.

Conclusion

Rendez-vous pour le dernier billet où j’introduirai quelques concepts que je n’ai pas utilisé dans le module TagLib.

Jouer avec les tags

Accéder au tag

La structure tgFileData contient un champ tag qui permettra d’accéder au tag du fichier. Il a été initialisé avec la valeur NULL. La fonction file_tag retourne la valeur de ce champ après l’avoir complété au besoin.

La macro Data_Get_Struct permet d’accéder à la structure tgFileData de notre objet. Si le champ tag n’est pas rempli, on récupère sa valeur grâce à la fonction taglib_file_tag de la bibliothèque taglib. Une exception est levée dans le cas où cette dernière fonction faillirait. La valeur du champ est finalement retournée.

Obtenir le titre d’une piste audio

Afin d’obtenir le titre contenu dans un tag, une méthode title est ajoutée à la classe TagLib::File, dans la fonction Init_taglib2.

La fonction file_get_title implémente la méthode TagLib::File#title

La valeur du titre est obtenu grâce à la fonction taglib_tag_title qui prend la valeur du champ tag de la structure interne tgFileData. La fonction rb_str_new2 transforme cette valeur obtenue sous la forme d’un pointeur sur chaîne de caractères en un objet ruby de la classe String. La mémoire allouée par taglib pour cette opération est libérée avant de retourner l’objet.

Modifier le titre d’une piste audio

La méthode TagLib::File#title=, prenant un argument, est ajoutée.

La fonctionfile_set_title utilise la bibliothèque taglib pour modifier le tag. Une nouvelle fois, la macro StringValuePtr est utilisée pour convertir une variable du type VALUE vers le type char *. Une fonction implémentant une méthode accessible depuis ruby doit obligatoirement retournée une valeur du type VALUE. J’ai choisi ici de retourner la chaîne de caractère passée en argument.

Il me semble que traditionnellement les méthodes du type variable= retourne l’argument alors que les méthodes du type set_variable retourne l’objet. La troisième possibilité étant de retourner nil.

Sauvegarder les modifications

Après avoir modifié le titre à l’aide de la méthode vue au précédent paragraphe, il faut écrire cette modification dans le fichier audio.

La méthode TagLib::File#save permet cette écriture. La méthode retourne true si l’opération est réussie ou false.

La fonction taglib_file_save réalise l’écriture après avoir accédé au champ file de la structure interne de notre objet ruby.

Tester le code

Voici le contenu du fichier taglib2.c

Après avoir recompilé, nous pouvons tester les méthodes ajoutées dans cet article.

Conclusion

Nous avons vu comment accéder au titre d’une piste audio. Accéder aux autres propriétés (auteur, album, etc) n’est pas plus difficile. Je ne développerai pas cet aspect. Les sources du code complet seront cependant mis à votre disposition lors du dernier article. Le prochain article devrait parler de l’aspect documentation.

Addendum

Afin que notre bibliothèque soit correctement liée à taglib lors de la compilation, il faut ajouter la ligne have_library(‘tag_c’) || exit(1) au fichier extconf.rb, juste avant d’invoquer la création du Makefile.

Créer un objet appartenant à la classe TagLib::File

Ajouter une classe File

Après avoir déclaré une nouvelle variable de type VALUE (cFile), je définis une nouvelle classe nommée File appartenant au module TagLib. Elle hérite de la classe Objet (classe mère de toutes les classes en ruby).

Après avoir recompilé notre bibliothèque, je peux créer un objet de type TagLib::File, cette classe ayant héritée de la méthode Objet.new.

Redéfinir la méthode new

Dans la fonction Init_taglib2, je redéfinis la méthode de classe new (et non une méthode d’instance). C’est pourquoi j’utilise rb_define_singleton_method et non rb_define_method. Cette fonction prend quatre arguments : l’object pour lequel la méthode va ếtre (re)défini, le nom de la méthode, la fonction écrite en C à appeler, le nombre d’aguments passés à la fonction.

Voici la fonction file_new qui redéfinit TagLib::File.new.

La méthode new est appelée avec un seul argument qui est une chaîne de caractère ruby représentant un chemin vers un fichier audio. Cependant, la function file_new possède un argument supplémentaire : le premier qui représente l’objet auquel s’applique la méthode.
La fonction taglib_file_new permet de créer une structure qui représente un fichier audio pour la bibliothèque taglib. Elle requière, comme argument, un pointeur sur une chaîne de caractère C obtenu grâce à la macro StringValuePtr.
La variable data est une structure qui représentera un objet de type TagLib::File au niveau du langage C. Elle est composée de trois champs représentant le fichier audio (file), le tag associé au fichier (tag) et les propriétés audio du fichier (audio). Après avoir alloué la mémoire nécéssaire (grâce à la macro ALLOC) et initialiser ses différents champs, cette structure est transformée en object ruby grâce à l’aide de la macro Data_Wrap_Struct. Cet object rbData appartient à la classe TagLib::File (représenté par la variable cFile). Lorsque l’objet est détruit, la fonction free_tgFileData est appelée.
Enfin, l’objet est initialisé (rb_obj_call_init).

Écrire la méthode initialize

La méthode new appelle la méthode initialize qui, comme son nom l’indique, s’occupe d’initialiser l’objet, en particulier ses variables d’instance.
Cette dernière méthode est déclarée dans la fonction Init_taglib2.

Ici, la méthode initialize se borne à valoriser la variable d’instance @path.

Libérer la mémoire

Lorsque le ramasse-miettes de ruby détruit un object de type TagLib::File, il utilise la fonction indiquée lors de l’appel à la macro Data_Wrap_Struct, pour libérer la mémoire allouée à cet objet.

Code

Voici l’ensemble du code :

Tester le code

Après une recompilation, on vérifie que la méthode TagLib::File.new est correctement appelée depuis l’interpréteur irb.

Conclusion

Lors de ce deuxième billet, nous avons interfacé une structure C avec un objet ruby, représentant un fichier audio. Dans le prochain billet, nous écrirons les méthodes qui permettent d’accéder au tag de ce fichier.

Les fonctionnalités présentées dans cet article sont implémentées par la classe StatusIcon. Cette classe est documentée, en anglais, sur le hiki du projet ruby-gnome2. Un code fonctionnel, récapitulant les notions abordées, est donné en fin d’article.

Afficher une icône

Nous allons tout d’abord afficher une icône dans la zone de notification.

Après avoir lancé le code ci-dessus dans une console, il est nécessaire d’utiliser Ctrl+C pour récupérer la main.

Analysons le code. Nous chargeons tout d’abord la bibliothèque ruby/Gtk2 (ligne 1), puis un objet icône est créé (ligne 4). L’image utilisée pour afficher l’icône est définie à la ligne suivante. Ici, une image commune est utilisée. Nous aurions pu utiliser une image personnelle grâce à la méthode pixbuf=() (si.pixbuf=Gdk::Pixbuf.new('/chemin/vers/image.svg')). La méthode tooltip=() permet d’indiquer le texte à afficher lorsque la souris survole l’icône.

Intéragir avec l’icône

Nous allons maintenant voir comment implémenter l’intéraction entre la souris et l’icône.

Intéractions avec le bouton gauche de la souris

si.signal_connect('activate'){|icon| icon.blinking=!(icon.blinking?)}

La méthode signal_connect permet de guetter l’émission d’un signal. Le signal activate est émis lors d’un clic gauche sur l’icône. Le bloc appelé ({|icon| icon.blinking=!(icon.blinking?)}) modifie l’état de l’icône qui clignotera ou pas suivant le nombre de clics.

Ajouter un menu

Il est possible d’ajouter un menu qui apparait lors d’un clic droit sur l’icône.

Nous construisons un menu auquel nous ajoutons deux éléments (info et quit). Le menu est affiché par la méthode popup lorsque le signal popup-menu, indiquant un clic droit, est émis. L’élément quit permet de quitter la boucle principale proprement. Un clic sur l’élément info affiche en console trois informations. La méthode embedded? permet de vérifier la présence d’une zone de notification. Certains bureaux n’utilisent pas de zone de notification. Notre icône n’est alors pas visible par l’utilisateur.

Intéractions avec la molette de la souris

Si votre bibliothèque gtk est récente, vous pouvez surveiller les mouvements de la molette au niveau de l’icône.

Surveillons le signal scroll-event. L’objet event retourné appartient à la classe Gdk::EventScroll. La méthode direction de cet objet permet d’obtenir le sens dans lequel la molette tourne.

Il est aussi possible de contrôler quels modificateurs (control, shift, alt, meta…) sont actifs lors de l’intéraction. Remplacez le code précédent par le suivant.

event.state est masque représentant l’état de l’ensemble des modificateurs, par exemple du clavier. Dans le cas présent, nous nous intéressons seulement aux modificateurs control et shift. À cet usage, nous filtrons les modificateurs complets avec un masque des modificateurs que nous voulons gérer. Puis nous comparons le résultat aux différents cas possibles.

Récapitulatif

Le code suivant est un exemple complet reprenant les notions vues dans cet article. N’hésitez pas à réagir à cet article en laissant un commentaire.