C'est quoi Gram ?

Gram est un DSL (Domain-Specific Language) déclaratif open-source pour les recettes de cuisine, pensé pour les développeurs.

La plupart des formats de recettes ne sont que des blocs de texte statiques. Gram propose une approche différente : il prend vos instructions rédigées en texte brut et les compile en données structurées, calculées et relationnelles.

La philosophie

Cuisiner, c’est un peu comme exécuter un algorithme : on prend des ingrédients en entrée et on obtient un plat en sortie. Mais c’est avant tout une passion. Gram est né de ce constat : passionné de cuisine, je cherchais un outil capable d’allier la rigueur du code à la créativité culinaire.

J’ai toujours aimé l’idée d’écrire des recettes en texte brut (plain text), en m’inspirant de projets pionniers comme l’excellent Cooklang (idéal pour des recettes maison simples et rapides). Mais dès que les choses se compliquent — comme en pâtisserie, avec ses multiples préparations, le « pourcentage du boulanger » ou des plannings complexes — s’appuyer uniquement sur le langage naturel montre vite ses limites.

Structurellement, Gram s’inspire beaucoup du célèbre site Cooking for Engineers et de ses recettes présentées sous forme de tableaux. Puisque Gram compile les recettes en un arbre JSON déterministe, cela ouvre la voie au développement de rendus visuels avancés (diagrammes de Gantt, flux tabulaires, etc.).

J’ai créé Gram comme une alternative pour ces scénarios plus exigeants. Il introduit une logique relationnelle, une précision physique et une composition modulaire dans la rédaction de vos recettes :

• Variables relationnelles : Si vous préparez une pâte à l’étape 1, vous pouvez l’utiliser comme ingrédient à l’étape 5. Fini les duplications.
• Précision physique & Calculs : Gram comprend la différence entre « le zeste d’un citron » et « le jus de 2 citrons », s’assurant que votre liste de courses agrège précisément « Acheter 2 citrons » au lieu de 3. Il calcule aussi les masses réelles et les ratios relatifs (70% @&farine).
• Contrats de données stricts : Grâce à des tags explicites (@, ~, ^, #), Gram garantit que l’analyseur syntaxique ne confondra jamais les températures, les temps, les ingrédients et le matériel.
• Modularité et Réutilisation (@use) : Découpez vos composants réutilisables (pâtes, bouillons, sauces) dans leurs propres fichiers .gram. Gram intègre leurs étapes, adapte automatiquement leurs proportions aux quantités requises et fusionne leurs ingrédients sur la liste de courses globale.

L’approche par écosystème

Gram n’est pas juste une syntaxe ; c’est un écosystème complet pour construire des applications culinaires. Que vous conceviez une application de recettes, un planificateur de repas ou un tableau de bord pour la cuisine, vous n’avez plus besoin d’analyser du texte brut à la main. Le Moteur Gram transforme votre texte en un arbre syntaxique abstrait (AST) riche, y injecte des propriétés physiques (comme la normalisation des masses ou le calcul nutritionnel), et génère une structure JSON sur laquelle vous pouvez bâtir en toute confiance.

Pensé pour les développeurs

L’écosystème Gram met à votre disposition tout le nécessaire pour concevoir vos recettes comme de véritables logiciels :

Analyse syntaxique & Compilation

@gram-lang/kitchen : Simule la chronologie de la recette, agrège les listes d’ingrédients et gère l’ajustement dynamique des quantités.

Analyseur sémantique

@gram-lang/analyzer : Gère la normalisation des masses, le calcul des rendements, l’estimation nutritionnelle et l’agrégation avancée des courses via votre base de données locale.

Serveur de langage (LSP)

@gram-lang/language-server : Apporte un véritable support d’édition pour vos recettes (autocomplétion, diagnostics en temps réel, infobulles).

Interface CLI

@gram-lang/cli : Permet de compiler, d’ajuster les proportions, de comparer les révisions (diff) et de gérer votre base d’ingrédients depuis le terminal.

Moteur de rendu

@gram-lang/renderer : Génère instantanément du HTML sémantique ou du Markdown à partir du JSON compilé.

À quoi ça ressemble ?

Gram reste très lisible, mais introduit discrètement des structures de données puissantes. Voici un aperçu avec la recette classique des cannelés bordelais :

canneles.gram

canneles.gram

---
title: 'Cannelés'
portions: 10
---

## Appareil ~{-1d} ->&batter

[Mélanger] Dans un #cul-de-poule{}, combiner la @farine{300 g}, le @sucre{500 g}, et le @sel{3 g}. ->&ingrédients secs{}

[Chauffer] Dans une #grande casserole{}, amener le @lait{1 l}, le @beurre{100 g}, et la @gousse de vanille{1}(fendue et grattée) à ^{85°C}. ->&lait chaud{}

[Mélanger] Verser le &lait chaud{} sur les &ingrédients secs{} en une seule fois. Fouetter vigoureusement.

[Incorporer] Ajouter les @jaunes d'œufs{6}<@œufs{6} et le @rhum{100 ml}.

[Repos] Couvrir de #film alimentaire{} au contact et réfrigérer pendant au moins ~_réfrigérateur{24 h}.

Aperçu de la Sortie

Aperçu de la Sortie

{
  "title": "Cannelés",
  "meta": { "portions": "10" },
  "metrics": {
    "totalTime": 1465,
    "totalMass": 2132,
    "nutrition": {
      "total": {
        "calories": 4927,
        "protein": 80.2,
        "carbs": 781.6
        // ...
      }
    }
  },
  "shopping_list": [
    {
      "id": "farine",
      "qty": 300,
      "unit": "g",
      "normalizedMass": 300,
      "conversionMethod": "physical"
    },
    // ...
    {
      "type": "composite",
      "id": "œufs",
      "qty": 6,
      "usage": [ { "id": "jaunes d'œufs", "qty": 6, "normalizedMass": 102 } ]
    }
  ],
  "sections": [
    {
      "title": "Appareil",
      "retro_planning": { "raw": "-1d", "sign": -1, "value": 1, "unit": "d", "minutes": -1440 },
      "intermediate_preparation": "batter",
      "steps": [
        {
          "type": "step",
          "action": "Mélanger",
          "content": [
            "Dans un ",
            { "id": "cul-de-poule", "_usageId": "36", "fixed": false },
            ", combiner la ",
            { "id": "farine", "qty": 300, "unit": "g", "normalizedMass": 300 },
            // ... (suite de l'AST)
          ],
          "timings": { "start": 0, "end": 2, "activeDuration": 2 }
        }
        // ... (autres étapes)
      ]
    }
    // ... (autres sections)
  ]
}

Remarquez l’étape [Incorporer] qui utilise <@œufs{6} : cette syntaxe d’ingrédient composite indique à Gram que vous n’utilisez que les jaunes, tout en précisant que la liste de courses devra comptabiliser des œufs entiers. Le tag de section ~{-1d} met en place un rétro-planning basé sur l’heure finale de cuisson, et ->&lait chaud{} déclare une variable intermédiaire prête à être réutilisée plus loin.

Prêt à vous lancer ?Consultez le guide « Premiers pas » pour installer Gram et écrire votre première recette.