openmusic / common lisprepmus.ircam.fr/_media/bresson/enseignement/stage... · le langage common...

Notions de programmation objet et création de bibliothèques dans OpenMusic

Jean Bresson - IRCAM 10-11-12/04/12010

1

OpenMusic / Common Lisp :

Notions de programmation par objets en

Common Lisp et dans OM

Création d'une librairie externe

Jean Bresson – Stage OpenMusic – 12/04/2010



2

Rappels: Définition de fonctions en Common Lisp Déclarer une fonction en Common Lisp :

(defun ma-fonction (arg1 arg2 arg3) … [ séquence d'opérations] … resultat)

Exemple :

(defun ma-fonction (a b c) (let ((x (+ a 5))) (* x (/ b c)))

Remarques :

- a, b, c sont appelés arguments. Ce sont des variables qui prendront une valeur lorsque la fonction est appelée.

- let : déclare une variable local (ici "x") dans le corps de la fonction

- La dernière expression correspond au résultat rendu par la fonction, ici : (* x (/ b c))

Appel de la fonction : En Lisp : (ma-fonction 1 2 3) [evaluation] => 4

Dans OM :

Les arguments de la fonction sont les valeurs des boites connectées à ses entrées, et le résultat et la valeur obtenue par sa sortie.

Toutes les fonctions Lisp (les "primitives" comme append, first, +, -, etc. et les fonctions définies comme ci-dessus) peuvent être appelées dans un patch OM, soit par l'intermédiaire des menus "Fonctions" (si elles y sont), soit en tapant CMD+clic et leur nom.



3

I. Notions de programmation par objet en Common Lisp et dans OpenMusic Le langage Common Lisp comprend une composante importante dédiée à la programmation orientée objet, que l'on appelle CLOS (Common Lisp Object System).

1. Classes Une CLASSE est une entité définissant un type d'objet, principalement par ses différents attributs (appelés slots). Par exemple, l'objet "note" en musique peut être représenté par une classe du même nom, ayant pour attributs (slots) : une hauteur, une intensité, une durée.. En Lisp/CLOS, on définit une classe de la manière suivante1 :

(defclass note ( ) ((hauteur :accessor hauteur :initarg :hauteur :initform 60) (intensite :accessor intensite :initarg :intensite :initform 0.5) (duree :accessor duree :initarg :duree :initform 1.0)) Décryptage :

(defclass nom-de-la-classe (superclasses) ((slot1 ...) (slot2 ...)

...)) La ou les "superclasses" sont d'autres classes dont la classe définie peut hériter certaines propriétés. Pour chaque slot, il faut spécifier au moins :

:accessor = le nom de la fonction qui permettra de lire ou modifier la valeur de cet attribut (généralement le même que le nom du slot) :initarg = l'indicateur qui permettra d'initialiser ce slot avec une valeur lors de la création d'un objet (généralement aussi le même que le nom du slot). :initform = la valeur par défaut de cet attribut.

Dans OM, taper 'e' sur un objet permet d'accéder à la définition de sa classe:

Remarque : Ici la classe note a deux superclasses : on dit que note est une sous-classe de simple-score-element et de tonal-object. 1 Remarque : on a pris soin d'éviter les accents dans les noms donnés aux objets et attributs; c'est valable aussi pour les fonctions et autres parties du code en général.

(defclass* note (simple-score-element tonal-object) ((midic :initform 6000 :accessor midic :initarg :midic :type number :documentation "pitch (midicents)") (vel :initform 80 :accessor vel :initarg :vel :type number :documentation "velocity (0-127)") (dur :initform 1000 :accessor dur :initarg :dur :type number :documentation "duration (ms)") (chan :initform 1 :accessor chan :initarg :chan :type integer :documentation "MIDI channel (1-16)") (port :initform *outmidiport* :accessor port) (tie :initform nil :accessor tie) (symb-info :initform nil :accessor symb-info)) (:icon 137) (:documentation "A simple NOTE defined with ..."))



4

2. Utilisation des classes : Instanciation On parle d'instanciation lorsque qu'on crée un objet à partir d'une classe donnée. Dans OM, c'est ce qui se passe dès qu'une boîte de classe (ou "factory") est évaluée.

Dans OM, on "attrape" les instances par la sortie self des boîtes. Les autres entrées/sorties correspondent aux slots de la classe note, accessible par leur "clé" :initarg (ici: midic, vel, dur, chan). Une classe est unique mais elle peut donc générer une multitude d'instances : une nouvelle instance est créée à chaque évaluation de la boîte (le numéro affiché comme résultat – ou dans le listener OM – indique une adresse mémoire, sans importance pour le moment). En Lisp/CLOS, on instancie une classe grâce à la fonction MAKE-INSTANCE :

(make-instance 'note) => #<note 25931ED3> Pour donner des valeurs aux slots, on utilise les "initargs" :

(make-instance 'note :midic 6700 :dur 3000) => #<note 20104147> Dans nos fonctions, nous utiliserons des variables (avec LET, SETF, etc.) pour garder les instances créées, par exemple :

(setf une-note (make-instance 'note :midic 6700 :dur 3000)) On peut ensuite accéder aux valeurs des attributs des instances grâce aux accesseurs :

(midic une-note) => 6700

(setf (midic une-note) 8000) (midic une-note) => 8000

Remarque: Si on travaille dans un autre package, ne pas oublier les om:: devant les symboles OM

(setf une-note (make-instance 'om::note)) (setf (om::midic une-note) 8000) Etc.



5

3. Méthodes Une méthode est une fonction particulière dont les arguments sont typés (c'est-à-dire, ils sont d'un type, ou d'une classe particulière). En CLOS, les methodes sont regroupées par "fonctions génériques" (generic functions) : une generic function contient un certain nombre de méthodes correspondant à un comportement variable en fonction du type des arguments. Par exemple, on pourra imaginer qu'une fonction générique "transposition" se comporte différemment selon le type d'objet qui lui est passé en argument (ou, de façon équivalente si on travaille dans OM, qui est connecté à la boite). Ici (sans donner le détail du corps des fonctions) trois méthodes sont définies pour les types note, voice, et sound :

(defmethod transposition ((objet om::note) intervalle) ; crée une nouvelle note transposée

(make-instance 'om::note :midic (+ (om::midic objet) intervalle)))

(defmethod transposition ((objet om::voice) intervalle) ; crée une nouvelle voice transposée

(make-instance 'om::voice ……))

(defmethod transposition ((objet om::sound) intervalle) ; crée un nouveau 'sound' transposé ……)

La première méthode définie (defmethod transposition…) définit implicitement une fonction générique à laquelle sont rattachées les définitions suivantes. Toutes les méthodes doivent donc avoir la même "signature", ou configuration de leurs arguments (nombre, ordre, etc.) Seuls les types des arguments (et le contenu de la fonction) changent d'une méthode à l'autre.



6

4. OMClasses – OMMethods Pour qu'une classe ou une méthode définie en Lisp soit utilisable dans OM, il faut qu'elle soit déclarée comme une "OMClass" ou une "OMMethod". Elles pourront alors êtres complétées avec une icône, et éventuellement des textes de documentation et/ou des menus pour les différents arguments (c'est-à-dire des propriétés propres au caractère visuel de OM). Des syntaxes spécifiques doivent être utilisées pour cela defclass! et defmethod!: (om::defclass! my-class (superclasses) (slots) (:icon XXX) (:documentation "…")) => #<omclass my-class> (om::defmethod! my-method ((arg1 type1) (arg2 type2) …) :initvals '(defval1 defval2 …) :indoc '("doc1" "doc2" …) :icon XXX :doc "……" […] ) => #<ommethod my-class> Les icônes, par convention, sont désignées par un nombre correspondant à un fichier se trouvant dans le dossier resources/icon/ de OM (ou d'une librairie – cf. partie III).

- Un nombre seul – par ex. 400 – correspond à une icône OM - Un nombre dans une liste – par ex. '(400) – correspond à une icône de librairie.

Des détails sur la syntaxe et l'utilisation de defmethod! sont donnés dans la partie III.2. Remarque 1 : il est aussi possible d'utiliser les méthodes et fonctions "standard" dans les patches OM. Celles-ci sont identifiées par l'icône "LISP". Remarque 2 : dans les définitions de méthodes, les types sont optionnels. On peut donc dans un premier temps déclarer une méthode exactement comme une fonction en remplaçant defun par defmethod (ou om::defmethod!).



7

II. Les bibliothèques (ou libraries) dans OM Dans OM, les libraries sont des bibliothèques de fonctions spécialisées pour des applications ou domaines particuliers. Un certain nombre se trouvent dans la distribution OpenMusic, d'autres peuvent être chargées dynamiquement par l'utilisateur. 1. Généralités On accède aux bibliothèques par le menu Windows/Library/ (ou CMD+ 'P').

Chaque bibliothèque contient du code Lisp qui est évalué au moment ou la librairie est chargée dans OM. Les fonctions et classes qu'elle contient deviennent alors accessibles depuis les patches OM.

Une fois la librairie chargée, son contenu est affiché sur la partie droite de la fenêtre. Un carré vert dans le coin supérieur gauche de l'icône indique que la librairie est chargée.

Pour charger une librairie : - Clic droit / CTRL+clic + "Load Library" - Ou : double cliquer sur la partie inférieure de l'icône.



8

2. Bibliothèques externes Des bibliothèques supplémentaires peuvent être chargées dans OM. Il est recommandé de créer un dossier dédié à ces bibliothèques, par exemple /Users/…/OM-Libraries/ Aller ensuite dans les préférences OM, onglet "Libraries", pour donner l'emplacement de ce dossier.

Remarque : ce même onglet dans les préférences permet de sélectionner des librairies à charger automatiquement au démarrage du workspace. Quelques librairies supplémentaires ont été mises à disposition par leurs créateurs sur le site OpenMusic: http://recherche.ircam.fr/equipes/repmus/OpenMusic/, onglet "Externals". 3. Dépendances Généralement, OM est capable de savoir si un patch utilise des fonctions définies dans une bibliothèque (voir partie III). Dans ce cas, il sera proposé (si cette bibliothèque n'est pas chargée) :

- De charger la bibliothèque si elle est visible - D'ouvrir le patch sans la bibliothèque si elle est introuvable.

Si la bibliothèque n'est pas chargée, les boîtes se référant à ses fonctions ou ses classes seront remplacées par des "dead boxes", inutilisables dans les calculs.

Il est recommandé de charger la librairie puis recharger le patch (par exemple avec "Last Saved") afin de rétablir les boîtes originales. Remarque : il peut arriver également qu'une bibliothèque fasse appel à une autre bibliothèque et nécessite donc également son chargement.



9

III. Création d'une bibliothèque externe pour OM Une bibliothèque externe est un simple dossier contenant essentiellement du code Lisp (c'est à dire des fichiers "texte" dont l'extension est ".lisp"), et éventuellement quelques ressources additionnelles (par exemple des images pour les icônes). Ce dossier devra se situer dans le dossier des "external user libraries" spécifié dans les préférences (cf. II.2). Le nom du dossier avant le premier espace est celui de la bibliothèque. On peut donc par exemple ajouter un numéro de version ensuite, ex. "OM-Test-Lib 1.0" 1. Organisation / Structure de la bibliothèque Généralement, la bibliothèque est organisée de la manière suivante :

- un dossier "sources" contenant le code des fonctions de la librairies - un dossier "resources" contenant les icônes et autres ressources (images, fichiers

audio, MIDI, etc.) dans des sous-dossiers. - Un fichier de chargement portant le même nom que celui de la bibliothèque (sans

le numero de version) et l'extension ".lisp" (par exemple "OM-Test-Lib.lisp")

Par convention, l'ensemble du code est généralement enregistré sous forme de fichiers ".lisp" dans le dossier "sources" de la bibliothèque. Il sera chargé par des instructions spécifiques à l'intérieur du fichier de chargement de la bibliothèque (voir section suivante).

Les icônes utilisées dans la bibliothèque doivent se trouver dans un dossier "resources/icon" Ce sont des images (dans un format supporté par OM: TIF, JPG, BMP…) ayant comme nom un numéro unique (ex. 400.jpg)



10

2. Sources : le code Lisp Le code peut contenir à la fois du Common Lisp "standard" et du code "spécifique OM" (OMClasses, OMMethods – voir partie I.4.) Les OMClasses/OMMethods offrent un certain nombre d'avantages :

- Possibilité de spécifier o une icône pour les boites correspondantes o une documentation détaillée o des valeurs par défaut pour les arguments des fonctions o des menus pour les entrées

- La fonction ou la classe est attachée à la bibliothèque, qui sera automatiquement

invoquée lors du chargement ultérieur des patches (voir section II.3. – Dépendances)

Par ailleurs, on devra obligatoirement utiliser des OMClasses (donc om::defclass! à la place de defclass) lorsque l'on veut que la classe en question soit accessible sous forme de boite "factory" dans les patches OM. Remarque : Si une autre librairie est nécessaire pour le chargement ou l'execution du code de notre librairie, il est possible de le spécifier avec require-library Ex.

(om::require-library "esquisse")

Rappel : Pour avoir accès aux ressources et fonctions de OpenMusic, il faut :

- soit "placer" son code dans le package "OM".1 On écrira alors en haut de notre code : (in-package :om)

- soit penser à utiliser l'indication de package om:: devant tous les symboles et

fonctions OM.



11

3. Créer des fonctions pour OM: OMMethods Syntaxe Générale Voici un exemple de methode définie dans OM pour transposer une note, utilisant les différentes options de defmethod! (om::defmethod! ma-transposition (n itvl) :icon '(400) :initvals '(nil 5) :indoc '("une note" "intervalle de transposition (demi-tons)") :doc "Transpose une note 'n' de 'itvl' demi-tons"

(make-instance 'om::note :midic (+ (om::midic n) (* itvl 100)) ; OM note pitches in midicents :dur (om::dur n) :vel (om::vel n) ; dur, vel stay the same )) Dans cet exemple, la fonction "ma-transposition" est définie dans la bibliothèque (donc accessible dans OM ou depuis d'autres fonctions Lisp) :icon => L'icône correspondante est le fichier "400" se trouvant dans le dossier OM-Test-Lib 1.0/resources/icon/ :initvals => Les valeurs par défaut des 2 arguments :indoc => Les aides des différents inputs (tooltips, online reference, etc.) :doc => Documentation générale de la fonction (tooltips, reference, etc.)

Menus defmethod! permet de générer des menus en entrée des boites avec l'option :menuins Par exemple, pour notre intervalle : (om::defmethod! ma-transposition (n itvl) :icon '(400) :initvals '(nil 5) :indoc '("une note" "intervalle de transposition (demi-tons)") :doc "Transpose une note 'n' de 'itvl' demi-tons" :menuins '((1 (("seconde" 2)

("tierce mineure" 3) ("tierce majeure" 4) ("quarte" 5) ("quinte" 7))))

(make-instance 'om::note

:midic (+ (om::midic n) (* itvl 100)) :dur (om::dur n) :vel (om::vel n)

)) Ici :menuins nous indique que l'argument 1 (en commençant à 0, donc le deuxième) doit avoir un menu. La liste des (option , valeur) pour cet argument est donnée ensuite.



12

Spécialisation Pour spécialiser cette méthode, il est possible de spécifier le type attendu pour l'argument "n". Par exemple, avec une note, nous aurons :

(om::defmethod! ma-transposition ((n om::note) itvl) … ) On peut ensuite, de la même façon, définir des méthodes pour d'autres types d'objets :

(om::defmethod! ma-transposition ((n om::chord) itvl) (make-instance 'om::chord

:lmidic (om+ (om::lmidic n) (* itvl 100)) :ldur (om::ldur n) :lvel (om::lvel n)

)) Remarque : les attributs (:icon, :indoc, :initvals, etc.) s'appliquent à la fonction générique, et non pas à une méthode particulière. Ils sont donc définis avec la première méthode uniquement (inutile de les répéter ensuite). Sorties Multiples Pour qu'une boite ait plusieurs sorties, il faut :

1) Donner le nombre de sorties avec l'option :numouts 2) Renvoyer le résultat de la fonction / méthode avec la fonction VALUES :

(om::defmethod! transposition-2 (n itvl) :icon '(400) :initvals '(nil 5) :indoc '("une note" "intervalle de transposition (demi-tons)") :doc "Renvoie 1) une note transposée 2) la valeur du pitch midi" :numouts 2

(let ((new-pitch (+ (om::midic n) (* itvl 100)))

(new-note (make-instance 'om::note :dur (om::dur n) :vel (om::vel n)))) (setf (om::midic new-note) new-pitch) (values new-note (/ new-pitch 100)) ))



13

4. Fichier de chargement Le fichier de chargement se trouve dans le dossier principal de la bibliothèque et porte le même nom. C'est lui qui est évalué lorsque la librairie est chargée depuis OM. Sa principale mission est donc de charger le reste du code Lisp de la librairie. Quelques nouvelles fonctions Lisp à connaître : LOAD : charge un fichier lisp ou compilé

ex. (load "/Users/mondossier/monfichier.lisp")

COMPILE-FILE : compile un fichier Lisp et génère un fichier compilé (.xfasl, .nfasl, selon la plateforme)

Une fonction supplémentaire définie dans OM : COMPILE&LOAD : compile le fichier Lisp si possible (et si nécessaire) et charge le fichier C'est celle qu'on va utiliser généralement. Remarque : OM seul ne permet pas de compiler les fichiers Lisp mais seulement de les charger. compile&load sera donc équivalent à load. Pour désigner les fichiers à charger, on pourra utiliser la fonction OM-RELATIVE-PATH, qui permet de spécifier un fichier à partir de l'emplacement de notre fichier de chargement :

(om::om-relative-path (liste-de-dossiers) nom-du-fichier) Ex. (om::om-relative-path '("sources") "fichier1") => Pour charger les fichiers : (om::compile&load (om::om-relative-path '("sources") "fichier1") (om::compile&load (om::om-relative-path '("sources") "fichier2") Avec beaucoup de fichiers, on peut créer une itération :

(setf *mes-fichiers* '("fichier1" "fichier2" …))

(loop for file in *mes-fichiers* do (om::compile&load (om::om-relative-path '("sources") file)))



14

5. Génération du Package

Dans OM, les classes et fonctions sont rangées dans des packages . Les packages sont eux-mêmes divisés en "sous-packages". Les bibliothèques sont des sous-packages spéciaux (reconaissable par leur icône de couleur jaune) se trouvant dans le package "libraries". On utilisera généralement le fichier de chargement d'une bibliothèque pour mettre en place le "package" correspondant, c'est à dire décider des fonctions qui apparaîtront dans les menus OM et dans la fenêtre "Library". Remarque : Toutes les autres fonctions définies dans la bibliothèque "existent" quand même (et sont chargées avec la bibliothèque) et peuvent donc être aussi appelées depuis OM (en tapant leur nom dans le patch). Deux possibilités pour metre en place le package: 1) "A la main" On peut retrouver le package (initalement vide) de la librairie avec la fonction exist-lib-p. Si la bibliothèque existe (c'est à dire si elle a été repérée dans le dossier des librairies), on obtient le package (omlib) correspondant.

(om::exist-lib-p "OM-Test-Lib") => #<omlib 20CBEC0F> On peut alors "remplir" le package à l'aide des fonctions omng-make-new-package, addpackage2pack, addgenfun2pack, addclass2pack, addlispfun2pack. Ex. (setf *mylib* (om::exist-lib-p "OM-Test-Lib"))

(defvar *myNewPackage* (omng-make-new-package "SousPack1")) (addpackage2pack *myNewPackage* *mylib*) (addgenfun2pack '(transposition ...) *myNewPackage*) 2) "automatiquement" La fonction fill-library permet de constituer automatiquement le package au moment du chargement de la bibliothèque: (om::fill-library '( ("SousPack1" (liste-de-sous-packages) (classes) (fonctions) (class-alias)) ("SousPAck2" (liste-de-sous-packages) (classes) (fonctions) (class-alias)) [etc.] )) Ex.

(om::fill-library '( ("my-lib-package" nil nil (ma-transposition transposition-2) nil)

)) (Ici: un seul sous-package contenant deux fonctions.)



15

6. Documentation Les méthodes et classes enregistrées dans le package peuvent être exportées vers une "référence en ligne". Pour cela : 1) Documenter les méthodes et classes (avec les options :doc, :indoc ...) – cf. III.3. 2) Evaluer la ligne suivante (remplacer "OM-Test-Lib" par le nom de la librairie)

(om::gen-lib-reference (om::lib-exist-p "OM-Test-Lib")) Un dossier "reference" sera normalement créé dans la librairie, contenant les pages HTML de la référence en ligne. Celles-ci apparaissent lorsqu'on tape 'd' sur les boites OM correspondantes. Remarque : Si cette ligne est dans le fichier de chargement, la référence sera re-générée à chaque chargement de la librairie (ça n'est pas forcément nécessaire). Elle peut donc être commentée (précédée d'un ";") et évaluée "manuellement" avant de distribuer la librairie. 7. Tutorial patches Il est possible de fournir avec une librairie un ensemble de patches d'exemples/tutoriels. Pour cela, il suffit de mettre ceux-ci dans un dossier "examples" ajouté dans le dossier de la bibliothèque. Les patches d'exemples peuvent eux-mêmes être organisés en sous-dossiers. Il est conseillé de les exporter directement depuis un dossier créé dans OM.

Les tutorial patches pourront ensuite être importés dans OM via le menu

Help/Import Tutorial Patches/Libraries/OM-TestLib

openmusic / common lisprepmus.ircam.fr/_media/bresson/enseignement/stage... · le langage common...

Documents