Langage de programmation - C++ - LibSass

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» :



#include <stdio.h>

#include "sass/context.h"

 
int main() {

  puts(libsass_version());

  return 0;

}

que vous pouvez compilez avec une commande comme ceci :

gcc -Wall version.c -lsass -o version && ./version

Autres exemples en C

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 :



struct Sass_Options;

struct Sass_Context : Sass_Options;

struct Sass_File_context : Sass_Context;

struct Sass_Data_context : Sass_Context;

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 :



// pour allouer le tampon à remplir

void* sass_alloc_memory(size_t size);

// pour allouer un tampon à partir d'une chaîne existante

char* sass_copy_c_string(const char* str);

// pour libérer la mémoire saturée une fois terminé

void sass_free_memory(void* ptr);

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

Structures internes

Dernière mise à jour : Mardi, le 8 octobre 2024

Section courante

A propos

Section administrative du site