Journal Portage de TapTempo en Haskell

Sommaire

• Version.hs
• I18N.hs
• Model.hs
• TapTempo.hs
• Main.hs
• Conclusion

Bonjour à tous,

Suite aux portages de TapTempo en divers langages (Rust, Ada, Javascript, Perl (5.10), Python (2.7), bash), il fallait une version Haskell de TapTempo.

J'ai essayé de respecter scrupuleusement ce qui est décrit dans le journal d'introduction de TapTempo de mfz. Toute différence serait un bug, j'attends vos rapport de bug sur GitHub.

Le répertoire src est composé des fichiers suivants, chacun ayant sa petite particularité Haskell que je détaille dans la suite :

• Version.hs : calcul du numéro de version, réalisé à la compilation par git, depuis le code Haskell
• I18N.hs et messages/ : localisation, en trichant un peu sur la pureté d'Haskell
• Model.hs : modèle de configuration, valeurs par défaut de configuration, avec des entiers au niveau du type
• TapTempo.hs : boucle principale de TapTempo, et son type de paramètre à l'exécution au typage plus que robuste
• Main.hs : lecture de la ligne de commande très robuste et presque automatique.

Version.hs

TapTempo sait afficher son numéro de version avec --version. Je voulais me servir de git describe qui donne un numéro de version en fonction du commit courant et des tags du dépôt. Le fichier version.hs contient une expression évaluable pendant la compilation qui demande à git ce numéro :

versionString = do
  s <- runIO (readProcess "git" ["describe"] "")
  let striped = init s
  [| striped |]

En effet, le compilateur Haskell peut effectuer lors de la compilation n'importe quel code Haskell pour générer du code Haskell… Dans ce cas, on appelle avec readProcess la commande git adéquat. init sert ici à supprimer le retour à la ligne. Au final, $(versionString) nous donnera la version du dépôt.

I18N.hs

Je n'avais JAMAIS auparavant réalisé l'internationalisation d'une application, je découvre donc. La base de donnée de message est lue lors de la compilation grace à cette ligne:

mkMessage "TapTempo" "messages/" ("en")

Voici un morceau du fichier fr.msg :

Hello: Appuyer sur la touche entrée en cadence (q pour quitter).
GoodBye: Au revoir !
Tempo bpm@Float p@Int: Tempo : #{showBpm p bpm}

Par la suite, on pourra utiliser dans le code source message MsgGoodBye pour obtenir la localisation du message correspondant.

Détails intéressants:
- La base de donnée de message peut faire appelle à des fonctions, ici showBpm se charge de mettre en forme les bpm avec la bonne précision, on pourra donc appeler dans le code message (MsgTempo 32.5 3).
- La locale courante est récupérée par la lecture de la variable d'environnement LANG dans la fonction getCurrentLocale. Ce n'est sûrement pas comme ça qu'il faut faire ;)
- getCurrentLocale est une fonction qui réalise des effets de bord (elle lit une variable d'environnement), donc je ne devrais pas pouvoir m'en servir dans une fonction pure comme message. Pour cela j'ai un peu triché en utilisant unsafePerformIO qui permet de faire croire au compilateur qu'une fonction est tout de même pure. Cette triche ici n'est pas grave car il n'y a aucune raison que la variable d'environnement change en cours d'exécution du programme, donc je ne risque pas grand chose.

Model.hs

Le type représentant la configuration est intéressant car il n'est pas possible de crée une configuration invalide (selon les critères proposés dans la version originale de TapTempo) :

data Config = Config
  { precision :: RefinedPrecision
  , resetTime :: RefinedResetTime
  , sampleSize :: RefinedSampleSize
  }
  deriving (Show)

C'est la déclaration d'un type Config contenant trois champs, precision, resetTime et sampleSize aux type suivants :

type MaxPrecision = 5
type RefinedPrecision = Refined (FromTo 0 MaxPrecision) Int
type RefinedResetTime = Refined Positive Int
type RefinedSampleSize = Refined Positive Int

Ici on définit un entier MaxPrecision au niveau du type, et les types raffinés d'entiers RefinedPrecision, RefinedResetTime et RefinedSampleSize qui donnent des garanties à la compilation concernant leur valeur, respectivement entre 0 et MaxPrecision pour le premier, et supérieure à 0 pour les deux derniers. `

On définie aussi plusieurs valeurs disponibles lors de l'exécution pour les valeurs par défauts :

defaultResetTime :: RefinedResetTime
defaultResetTime = $$(refineTH 5)

defaultSampleSize :: RefinedSampleSize
defaultSampleSize = $$(refineTH 5)

defaultPrecision :: RefinedPrecision
defaultPrecision = $$(refineTH 0)

La fonction refineTH est exécutée à la compilation pour vérifier les valeurs. En cas de valeur invalide, une erreur de compilation sera générée :

Model.hs:29:23: error:
    * Value is out of range (minimum: 0, maximum: 5)
    * In the Template Haskell splice $$(refineTH 100)
      In the expression: $$(refineTH 100)
      In an equation for `defaultPrecision':
          defaultPrecision = $$(refineTH 100)
   |
29 | defaultPrecision = $$(refineTH 100)

Pour finir, la valeur maxPrecision est définie à partir du type MaxPrecision. C'est assez verbeux, mais nous auront besoin de cette valeur lors de l'exécution.

maxPrecision :: Int
maxPrecision = fromInteger (natVal (Proxy :: Proxy MaxPrecision))

TapTempo.hs

La boucle principale est dans la fonction 'tapTempo` qui se sert de quelques fonctions utilitaires :

• onReturnPressed qui se charge de lire la ligne de commande jusqu'à exécuter la continuation sur un retour à la ligne ou simplement quitter sur un q.
• computeBPM qui calcul le rythme en se basant sur une liste de mesure de temps.
• clipOldSamples, clipNumberOfSamples, tooOld qui se chargent de la maintenance de la liste d'échantillons

La plupart de ces fonctions sont écrite dans l'optique ne pas pouvoir être appelées d'une manière fausse. Par exemple, tooOld qui vérifie que le delta de temps est supérieure à une valeur en seconde n'accepte que des entiers >= 1 par le biais du type Refined Positive Int.

Tout particulièrement, la séquence d'échantillons de temps Seq TimeSpec est utilisé car elle propose des accès en O(1) à sa tête et sa queue, pratique pour calculer la différence, mais inutile sur un projet comme celui-ci ;). Cependant un autre usage intéressant arrive dans la fonction computeBPM :

computeBPM :: Seq TimeSpec -> Maybe Float
computeBPM s@(first :<| (_ :|> last)) = Just ...
computeBPM _ = Nothing

Cette fonction va tout d'abord réaliser une déconstruction sur la séquence en utilisant les opérateurs d'accès en tête et queue :<| et :|>. Si celle-ci passe, c'est qu'il y a au moins une tête et une queue, on peut donc faire le calcul, sinon on passe dans le cas suivant qui renvoie un échec.

Main.hs

Le fichier sans doute le plus complexe du projet parce que j'ai voulu faire une interface ligne de commande très robuste et ultra documentée. En cas de mauvaise saisie, l'interface répond avec des précisions sur ce qui est attendu. Par example :

$ TapTempo --precision 120
option --precision: Value is out of range (minimum: 0, maximum: 5)

Usage: TapTempo [-p|--precision (0..5)] [-r|--reset-time (INT>0)]
                [-s|--sample-size (INT>0)] [-h|--help] [-v|--version]
  Press the <Enter> key and see your rythm

Pour cela j'ai abusé de deux librairies :

• optparse-applicative chargée de l'analyse de la ligne de commande
• refined, vue avant dans la Config, chargée de s'assurer que les options sont bien dans les bornes

La description de mon parseur de ligne de commande est donc la suivante:

      <$> option (eitherReader (\x -> refine =<< readEither x))
          ( long "precision"
         <> short 'p'
         <> help (message MsgCLIHelpPrecision)
         <> showDefaultWith (\x -> show (unrefine x))
         <> value defaultPrecision
         <> metavar ("(0.." ++ show maxPrecision ++ ")")
          )
      <*> option (eitherReader (\x -> refine =<< readEither x))
          ( long "reset-time"
         <> short 'r'
         <> help (message MsgCLIHelpResetTime)
         <> showDefaultWith (\x -> show (unrefine x))
         <> value defaultResetTime
         <> metavar "(INT>0)" )
      <*> option (eitherReader (\x -> refine =<< readEither x))
          ( long "sample-size"
         <> short 's'
         <> help (message MsgCLIHelpSampleSize)
         <> showDefaultWith (\x -> show (unrefine x))
         <> value defaultSampleSize
         <> metavar "(INT>0)" )

Il y a beaucoup trop de chose, on va s'intéresser seulement à un sous bloc, car en fait il s'agit de la description du parseur des trois options de Config :

option (eitherReader (\x -> refine =<< readEither x))
    ( long "precision"
   <> short 'p'
   <> help (message MsgCLIHelpPrecision)
   <> showDefaultWith (\x -> show (unrefine x))
   <> value (($$(refineTH defaultPrecision))
   <> metavar ("(0.." ++ show maxPrecision ++ ")")
    )

Ici je m'intéresse à l'option, dont le nom long est "precision" et le nom cours est "p". Son message d'aide est donné par help et un appel à la fonction message de localisation. metavar nous donne une petite documentation qui sera affichée dans l'aide sous la forme --precision (0..n) avec "n" ici qui est correctement remplacé par la vraie borne maxPrecision. Le type de destination est un entier raffiné qui n'a pas de méthode d'affichage par défaut, donc on utilise showDefaultWith qui sert à définir la fonction d'affichage, qui se contente de récupérer la valeur comprise dans le type raffiné.

Pour finir, la première ligne contient la fonction utilisée pour parser eitherReader (\x -> refine =<< readEither x). Celle-ci se contente d'utiliser readEither pour lire un entier et passer celui-ci à la fonction refine qui doit produire en entier raffiné, et qui échouera si son argument ne valide pas les critères de l'entier raffiné.

Conclusion

Je me suis bien amusé. En pratique sur un vrai projet je ferais quelque chose de plus simple, principalement au niveau de la localisation et de l'interface ligne de commande. Par exemple, il existe une librairie, optparse-generic qui est capable de générer automatiquement une interface ligne de commande à partir d'un type (ici ce serait Config). C'est toute la complexité du fichier Main.hs qui vient de disparaître, au prix d'un peu moins de souplesse.

Je ne ferais pas la localisation. Par contre, je continuerais à utiliser des types raffinés car cela apporte une sécurité de développements que je trouve agréable.