Utilisation de l'API
LibSass ne serait pas très utile sans interface. Ce tutoriel d'interface décrivent les différentes fonctions et structures de données disponibles pour les implémenteurs. Elles sont réparties en quatre composantes principaux, chacun possédant ses propres fichiers sources (ainsi que des fonctionnalités communes).
| Composante | Description |
|---|---|
| Contexte Sass | Déclencher et gérer la compilation Sass principale |
| Valeur Sass | Échanger des valeurs et leur format avec LibSass |
| Fonction Sass | Invoquée par LibSass pour les instructions de fonction |
| Importateur Sass | Invoquée par LibSass pour les instructions @import |
Utilisation de base
Vous devez d'abord inclure le fichier d'entête ! Tous les autres entêtes seront alors automatiquement chargés :
- #include "sass/context.h"
Exemple de base en C
Voici un exemple du programme «version.c» :
que vous pouvez compilez avec une commande comme ceci :
| gcc -Wall version.c -lsass -o version && ./version |
Autres exemples en C
- Exemple de code pour le contexte Sass
- Exemple de code pour la valeur Sass
- Exemple de code pour la fonction Sass
- Exemple de code pour l'importateur Sass
Compiler votre code
Le plus important est votre fichier Sass (ou chaîne de code Sass). Avec celui-ci, vous allez lancer un compilateur LibSass. Voici un pseudo-code décrivant le processus. Le compilateur propose deux modes : saisie directe sous forme de chaîne avec Sass_Data_Context, ou lecture du fichier par LibSass via Sass_File_Context.
En règle générale, si l'API utilise const char*, elle effectue une copie. En revanche, si l'API utilise char*, elle prend en charge la mémoire. Veillez donc à transmettre la mémoire allouée via sass_copy_c_string ou sass_alloc_memory.
Création d'un compilateur de fichiers
- context = sass_make_file_context("file.scss");
- options = sass_file_context_get_options(context);
- sass_option_set_precision(options, 1);
- sass_option_set_source_comments(options, true);
-
- sass_file_context_set_options(context, options);
-
- compiler = sass_make_file_compiler(sass_context);
- sass_compiler_parse(compiler);
- sass_compiler_execute(compiler);
-
- output = sass_context_get_output_string(context);
- // Récupérer les erreurs lors de la compilation
- error_status = sass_context_get_error_status(context);
- json_error = sass_context_get_error_json(context);
- // Libérer la mémoire dédiée au compilateur C
- sass_delete_compiler(compiler);
Construire un compilateur de données
- // LibSass prend en charge la propriété de la mémoire, assurez-vous d'allouer un tampon via `sass_alloc_memory` ou `sass_copy_c_string`.
- buffer = sass_copy_c_string("div { a { color: blue; } }");
-
- context = sass_make_data_context(buffer);
- options = sass_data_context_get_options(context);
- sass_option_set_precision(options, 1);
- sass_option_set_source_comments(options, true);
-
- sass_data_context_set_options(context, options);
-
- compiler = sass_make_data_compiler(context);
- sass_compiler_parse(compiler);
- sass_compiler_execute(compiler);
-
- output = sass_context_get_output_string(context);
- // div a { color: blue; }
- // Récupérer les erreurs lors de la compilation
- error_status = sass_context_get_error_status(context);
- json_error = sass_context_get_error_json(context);
- // Libérer la mémoire dédiée au compilateur C
- sass_delete_compiler(compiler);
Contexte interne de Sass
Tout est entreposé dans des structures :
Cela reflète parfaitement l'utilisation de ces structures par libsass.
- Sass_Options contient tout ce que vous renseignez avant la compilation. Il héberge également les options input_path et output_path, utilisées pour générer/calculer les liens relatifs dans les sources-maps. L'option input_path est partagée avec Sass_File_Context.
- Sass_Context contient toutes les données renvoyées par la compilation.
- Sass_File_Context est une implémentation spécifique ne nécessitant aucun champ supplémentaire.
- Sass_Data_Context est une implémentation spécifique ajoutant le champ input_source.
Les structures peuvent être converties en structures descendantes pour accéder au contexte ou aux options !
Gestion de la mémoire et cycles de vie
Nous conservons la mémoire tant que l'objet de contexte principal n'est pas détruit (sass_delete_context). LibSass crée des copies de la plupart des entrées/options en plus du code Sass principal. Vous devez allouer et remplir ce tampon avant de le transmettre à LibSass. Vous pouvez également prendre le contrôle de la gestion mémoire de LibSass pour certaines valeurs de retour (par exemple, sass_context_take_output_string). Assurez-vous de la libérer via sass_free_memory :
Fonctions API diverses
- // Une fonction d'assistance de chaîne pratique
- char* sass_string_unquote (const char* str);
- char* sass_string_quote (const char* str, const char quote_mark);
-
- // Obtenir la version compilée de libsass
- const char* libsass_version(void);
-
- // Version du langage Sass implémentée
- // Version 3.4 codée en dur pour le moment
- const char* libsass_language_version(void);
Pièges courants
input_path
L'option input_path fait partie de Sass_Options, mais constitue également l'option principale de Sass_File_Context. Elle permet également de générer des liens de fichiers relatifs dans les sources maps. Il est donc très utile de transmettre cette information si vous disposez d'un Sass_Data_Context et connaissez le chemin d'origine.
output_path
Veuillez noter que libsass n'écrit pas le fichier de sortie lui-même. Cette option sert simplement à lui fournir les informations nécessaires pour générer des liens dans les tables de sources. Le fichier doit être écrit sur le disque par la liaison/implémentation. Si le chemin de sortie est omis, libsass tente d'en extrapoler un à partir du chemin d'entrée en remplaçant (ou en ajoutant) le fichier se terminant par .css.
Codes d'erreur
Le code d'erreur est une valeur entière indiquant le type d'erreur survenue dans le processus LibSass. Voici la liste des codes d'erreur, accompagnée d'une brève description :
| Valeur | Description |
|---|---|
| 1 | Erreurs normales telles que les erreurs d'analyse ou d'évaluation |
| 2 | Erreur d'allocation incorrecte (erreur de mémoire) |
| 3 | Exception C++ «non traduite» (lancer std::exception) |
| 4 | Exceptions de chaîne de caractères héritées (lancer const char* ou sass::string) |
| 5 | Autre exception inconnue |
Bien que pour l'utilisateur de l'API, les codes d'erreur n'offrent pas beaucoup de valeur, si ce n'est pour indiquer si une erreur s'est produite lors de la compilation, ils facilitent le débogage des chemins de code internes de LibSass.
Compatibilité ABI ascendante
Ils ont utilisez une API fonctionnelle pour renforcer la fiabilité et la compatibilité future des liens dynamiques. L'API n'étant pas encore totalement stable, il ne garantisse pas encore la compatibilité ABI ascendante.
Plugiciels (expérimental)
LibSass peut charger des plugiciels depuis des répertoires. Il suffit de définir plugin_path dans les options contextuelles pour charger tous les plugiciels depuis ces répertoires. Pour implémenter des plugiciels, veuillez consulter les exemples d'implémentation suivants :
- https://github.com/mgreter/libsass-glob
- https://github.com/mgreter/libsass-math
- https://github.com/mgreter/libsass-digest