www.aleph1.co.uk Git - yaffs-website/blob - node_modules/node-sass/src/libsass/docs/api-context.md

   1 Sass Contexts come in two flavors:
   2
   3 - `Sass_File_Context`
   4 - `Sass_Data_Context`
   5
   6 ### Basic Usage
   7
   8 ```C
   9 #include "sass/context.h"
  10 ```
  11
  12 ***Sass_Options***
  13
  14 ```C
  15 // Precision for fractional numbers
  16 int precision;
  17 ```
  18 ```C
  19 // Output style for the generated css code
  20 // A value from above SASS_STYLE_* constants
  21 int output_style;
  22 ```
  23 ```C
  24 // Emit comments in the generated CSS indicating
  25 // the corresponding source line.
  26 bool source_comments;
  27 ```
  28 ```C
  29 // embed sourceMappingUrl as data uri
  30 bool source_map_embed;
  31 ```
  32 ```C
  33 // embed include contents in maps
  34 bool source_map_contents;
  35 ```
  36 ```C
  37 // create file urls for sources
  38 bool source_map_file_urls;
  39 ```
  40 ```C
  41 // Disable sourceMappingUrl in css output
  42 bool omit_source_map_url;
  43 ```
  44 ```C
  45 // Treat source_string as sass (as opposed to scss)
  46 bool is_indented_syntax_src;
  47 ```
  48 ```C
  49 // The input path is used for source map
  50 // generating. It can be used to define
  51 // something with string compilation or to
  52 // overload the input file path. It is
  53 // set to "stdin" for data contexts and
  54 // to the input file on file contexts.
  55 char* input_path;
  56 ```
  57 ```C
  58 // The output path is used for source map
  59 // generating. LibSass will not write to
  60 // this file, it is just used to create
  61 // information in source-maps etc.
  62 char* output_path;
  63 ```
  64 ```C
  65 // String to be used for indentation
  66 const char* indent;
  67 ```
  68 ```C
  69 // String to be used to for line feeds
  70 const char* linefeed;
  71 ```
  72 ```C
  73 // Colon-separated list of paths
  74 // Semicolon-separated on Windows
  75 char* include_path;
  76 char* plugin_path;
  77 ```
  78 ```C
  79 // Additional include paths
  80 // Must be null delimited
  81 char** include_paths;
  82 char** plugin_paths;
  83 ```
  84 ```C
  85 // Path to source map file
  86 // Enables the source map generating
  87 // Used to create sourceMappingUrl
  88 char* source_map_file;
  89 ```
  90 ```C
  91 // Directly inserted in source maps
  92 char* source_map_root;
  93 ```
  94 ```C
  95 // Custom functions that can be called from Sass code
  96 Sass_C_Function_List c_functions;
  97 ```
  98 ```C
  99 // Callback to overload imports
 100 Sass_C_Import_Callback importer;
 101 ```
 102
 103 ***Sass_Context***
 104
 105 ```C
 106 // store context type info
 107 enum Sass_Input_Style type;
 108 ````
 109 ```C
 110 // generated output data
 111 char* output_string;
 112 ```
 113 ```C
 114 // generated source map json
 115 char* source_map_string;
 116 ```
 117 ```C
 118 // error status
 119 int error_status;
 120 char* error_json;
 121 char* error_text;
 122 char* error_message;
 123 // error position
 124 char* error_file;
 125 size_t error_line;
 126 size_t error_column;
 127 ```
 128 ```C
 129 // report imported files
 130 char** included_files;
 131 ```
 132
 133 ***Sass_File_Context***
 134
 135 ```C
 136 // no additional fields required
 137 // input_path is already on options
 138 ```
 139
 140 ***Sass_Data_Context***
 141
 142 ```C
 143 // provided source string
 144 char* source_string;
 145 ```
 146
 147 ### Sass Context API
 148
 149 ```C
 150 // Forward declaration
 151 struct Sass_Compiler;
 152
 153 // Forward declaration
 154 struct Sass_Options;
 155 struct Sass_Context; // : Sass_Options
 156 struct Sass_File_Context; // : Sass_Context
 157 struct Sass_Data_Context; // : Sass_Context
 158
 159 // Create and initialize an option struct
 160 struct Sass_Options* sass_make_options (void);
 161 // Create and initialize a specific context
 162 struct Sass_File_Context* sass_make_file_context (const char* input_path);
 163 struct Sass_Data_Context* sass_make_data_context (char* source_string);
 164
 165 // Call the compilation step for the specific context
 166 int sass_compile_file_context (struct Sass_File_Context* ctx);
 167 int sass_compile_data_context (struct Sass_Data_Context* ctx);
 168
 169 // Create a sass compiler instance for more control
 170 struct Sass_Compiler* sass_make_file_compiler (struct Sass_File_Context* file_ctx);
 171 struct Sass_Compiler* sass_make_data_compiler (struct Sass_Data_Context* data_ctx);
 172
 173 // Execute the different compilation steps individually
 174 // Usefull if you only want to query the included files
 175 int sass_compiler_parse (struct Sass_Compiler* compiler);
 176 int sass_compiler_execute (struct Sass_Compiler* compiler);
 177
 178 // Release all memory allocated with the compiler
 179 // This does _not_ include any contexts or options
 180 void sass_delete_compiler (struct Sass_Compiler* compiler);
 181 void sass_delete_options(struct Sass_Options* options);
 182
 183 // Release all memory allocated and also ourself
 184 void sass_delete_file_context (struct Sass_File_Context* ctx);
 185 void sass_delete_data_context (struct Sass_Data_Context* ctx);
 186
 187 // Getters for Context from specific implementation
 188 struct Sass_Context* sass_file_context_get_context (struct Sass_File_Context* file_ctx);
 189 struct Sass_Context* sass_data_context_get_context (struct Sass_Data_Context* data_ctx);
 190
 191 // Getters for Context_Options from Sass_Context
 192 struct Sass_Options* sass_context_get_options (struct Sass_Context* ctx);
 193 struct Sass_Options* sass_file_context_get_options (struct Sass_File_Context* file_ctx);
 194 struct Sass_Options* sass_data_context_get_options (struct Sass_Data_Context* data_ctx);
 195 void sass_file_context_set_options (struct Sass_File_Context* file_ctx, struct Sass_Options* opt);
 196 void sass_data_context_set_options (struct Sass_Data_Context* data_ctx, struct Sass_Options* opt);
 197
 198 // Getters for Sass_Context values
 199 const char* sass_context_get_output_string (struct Sass_Context* ctx);
 200 int sass_context_get_error_status (struct Sass_Context* ctx);
 201 const char* sass_context_get_error_json (struct Sass_Context* ctx);
 202 const char* sass_context_get_error_text (struct Sass_Context* ctx);
 203 const char* sass_context_get_error_message (struct Sass_Context* ctx);
 204 const char* sass_context_get_error_file (struct Sass_Context* ctx);
 205 size_t sass_context_get_error_line (struct Sass_Context* ctx);
 206 size_t sass_context_get_error_column (struct Sass_Context* ctx);
 207 const char* sass_context_get_source_map_string (struct Sass_Context* ctx);
 208 char** sass_context_get_included_files (struct Sass_Context* ctx);
 209
 210 // Getters for Sass_Compiler options (query import stack)
 211 size_t sass_compiler_get_import_stack_size(struct Sass_Compiler* compiler);
 212 Sass_Import_Entry sass_compiler_get_last_import(struct Sass_Compiler* compiler);
 213 Sass_Import_Entry sass_compiler_get_import_entry(struct Sass_Compiler* compiler, size_t idx);
 214 // Getters for Sass_Compiler options (query function stack)
 215 size_t sass_compiler_get_callee_stack_size(struct Sass_Compiler* compiler);
 216 Sass_Callee_Entry sass_compiler_get_last_callee(struct Sass_Compiler* compiler);
 217 Sass_Callee_Entry sass_compiler_get_callee_entry(struct Sass_Compiler* compiler, size_t idx);
 218
 219 // Take ownership of memory (value on context is set to 0)
 220 char* sass_context_take_error_json (struct Sass_Context* ctx);
 221 char* sass_context_take_error_text (struct Sass_Context* ctx);
 222 char* sass_context_take_error_message (struct Sass_Context* ctx);
 223 char* sass_context_take_error_file (struct Sass_Context* ctx);
 224 char* sass_context_take_output_string (struct Sass_Context* ctx);
 225 char* sass_context_take_source_map_string (struct Sass_Context* ctx);
 226 ```
 227
 228 ### Sass Options API
 229
 230 ```C
 231 // Getters for Context_Option values
 232 int sass_option_get_precision (struct Sass_Options* options);
 233 enum Sass_Output_Style sass_option_get_output_style (struct Sass_Options* options);
 234 bool sass_option_get_source_comments (struct Sass_Options* options);
 235 bool sass_option_get_source_map_embed (struct Sass_Options* options);
 236 bool sass_option_get_source_map_contents (struct Sass_Options* options);
 237 bool sass_option_get_source_map_file_urls (struct Sass_Options* options);
 238 bool sass_option_get_omit_source_map_url (struct Sass_Options* options);
 239 bool sass_option_get_is_indented_syntax_src (struct Sass_Options* options);
 240 const char* sass_option_get_indent (struct Sass_Options* options);
 241 const char* sass_option_get_linefeed (struct Sass_Options* options);
 242 const char* sass_option_get_input_path (struct Sass_Options* options);
 243 const char* sass_option_get_output_path (struct Sass_Options* options);
 244 const char* sass_option_get_source_map_file (struct Sass_Options* options);
 245 const char* sass_option_get_source_map_root (struct Sass_Options* options);
 246 Sass_C_Function_List sass_option_get_c_functions (struct Sass_Options* options);
 247 Sass_C_Import_Callback sass_option_get_importer (struct Sass_Options* options);
 248
 249 // Getters for Context_Option include path array
 250 size_t sass_option_get_include_path_size(struct Sass_Options* options);
 251 const char* sass_option_get_include_path(struct Sass_Options* options, size_t i);
 252 // Plugin paths to load dynamic libraries work the same
 253 size_t sass_option_get_plugin_path_size(struct Sass_Options* options);
 254 const char* sass_option_get_plugin_path(struct Sass_Options* options, size_t i);
 255
 256 // Setters for Context_Option values
 257 void sass_option_set_precision (struct Sass_Options* options, int precision);
 258 void sass_option_set_output_style (struct Sass_Options* options, enum Sass_Output_Style output_style);
 259 void sass_option_set_source_comments (struct Sass_Options* options, bool source_comments);
 260 void sass_option_set_source_map_embed (struct Sass_Options* options, bool source_map_embed);
 261 void sass_option_set_source_map_contents (struct Sass_Options* options, bool source_map_contents);
 262 void sass_option_set_source_map_file_urls (struct Sass_Options* options, bool source_map_file_urls);
 263 void sass_option_set_omit_source_map_url (struct Sass_Options* options, bool omit_source_map_url);
 264 void sass_option_set_is_indented_syntax_src (struct Sass_Options* options, bool is_indented_syntax_src);
 265 void sass_option_set_indent (struct Sass_Options* options, const char* indent);
 266 void sass_option_set_linefeed (struct Sass_Options* options, const char* linefeed);
 267 void sass_option_set_input_path (struct Sass_Options* options, const char* input_path);
 268 void sass_option_set_output_path (struct Sass_Options* options, const char* output_path);
 269 void sass_option_set_plugin_path (struct Sass_Options* options, const char* plugin_path);
 270 void sass_option_set_include_path (struct Sass_Options* options, const char* include_path);
 271 void sass_option_set_source_map_file (struct Sass_Options* options, const char* source_map_file);
 272 void sass_option_set_source_map_root (struct Sass_Options* options, const char* source_map_root);
 273 void sass_option_set_c_functions (struct Sass_Options* options, Sass_C_Function_List c_functions);
 274 void sass_option_set_importer (struct Sass_Options* options, Sass_C_Import_Callback importer);
 275
 276 // Push function for paths (no manipulation support for now)
 277 void sass_option_push_plugin_path (struct Sass_Options* options, const char* path);
 278 void sass_option_push_include_path (struct Sass_Options* options, const char* path);
 279
 280 // Resolve a file via the given include paths in the sass option struct
 281 // find_file looks for the exact file name while find_include does a regular sass include
 282 char* sass_find_file (const char* path, struct Sass_Options* opt);
 283 char* sass_find_include (const char* path, struct Sass_Options* opt);
 284
 285 // Resolve a file relative to last import or include paths in the sass option struct
 286 // find_file looks for the exact file name while find_include does a regular sass include
 287 char* sass_compiler_find_file (const char* path, struct Sass_Compiler* compiler);
 288 char* sass_compiler_find_include (const char* path, struct Sass_Compiler* compiler);
 289 ```
 290
 291 ### More links
 292
 293 - [Sass Context Example](api-context-example.md)
 294 - [Sass Context Internal](api-context-internal.md)
 295