1Sass functions are used to define new custom functions callable by Sass code. They are also used to overload debug or error statements. You can also define a fallback function, which is called for every unknown function found in the Sass code. Functions get passed zero or more `Sass_Values` (a `Sass_List` value) and they must also return a `Sass_Value`. Return a `Sass_Error` if you want to signal an error.
2
3## Special signatures
4
5- `*` - Fallback implementation
6- `@warn` - Overload warn statements
7- `@error` - Overload error statements
8- `@debug` - Overload debug statements
9
10Note: The fallback implementation will be given the name of the called function as the first argument, before all the original function arguments. These features are pretty new and should be considered experimental.
11
12### Basic Usage
13
14```C
15#include "sass/functions.h"
16```
17
18## Sass Function API
19
20```C
21// Forward declaration
22struct Sass_Compiler;
23struct Sass_Function;
24
25// Typedef helpers for custom functions lists
26typedef struct Sass_Function (*Sass_Function_Entry);
27typedef struct Sass_Function* (*Sass_Function_List);
28// Typedef defining function signature and return type
29typedef union Sass_Value* (*Sass_Function_Fn)
30  (const union Sass_Value*, Sass_Function_Entry cb, struct Sass_Compiler* compiler);
31
32// Creators for sass function list and function descriptors
33Sass_Function_List sass_make_function_list (size_t length);
34Sass_Function_Entry sass_make_function (const char* signature, Sass_Function_Fn cb, void* cookie);
35// In case you need to free them yourself
36void sass_delete_function (Sass_Function_Entry entry);
37void sass_delete_function_list (Sass_Function_List list);
38
39// Setters and getters for callbacks on function lists
40Sass_Function_Entry sass_function_get_list_entry(Sass_Function_List list, size_t pos);
41void sass_function_set_list_entry(Sass_Function_List list, size_t pos, Sass_Function_Entry cb);
42
43// Setters to insert an entry into the import list (you may also use [] access directly)
44// Since we are dealing with pointers they should have a guaranteed and fixed size
45void sass_import_set_list_entry (Sass_Import_List list, size_t idx, Sass_Import_Entry entry);
46Sass_Import_Entry sass_import_get_list_entry (Sass_Import_List list, size_t idx);
47
48// Getters for custom function descriptors
49const char* sass_function_get_signature (Sass_Function_Entry cb);
50Sass_Function_Fn sass_function_get_function (Sass_Function_Entry cb);
51void* sass_function_get_cookie (Sass_Function_Entry cb);
52
53// Getters for callee entry
54const char* sass_callee_get_name (Sass_Callee_Entry);
55const char* sass_callee_get_path (Sass_Callee_Entry);
56size_t sass_callee_get_line (Sass_Callee_Entry);
57size_t sass_callee_get_column (Sass_Callee_Entry);
58enum Sass_Callee_Type sass_callee_get_type (Sass_Callee_Entry);
59Sass_Env_Frame sass_callee_get_env (Sass_Callee_Entry);
60
61// Getters and Setters for environments (lexical, local and global)
62union Sass_Value* sass_env_get_lexical (Sass_Env_Frame, const char*);
63void sass_env_set_lexical (Sass_Env_Frame, const char*, union Sass_Value*);
64union Sass_Value* sass_env_get_local (Sass_Env_Frame, const char*);
65void sass_env_set_local (Sass_Env_Frame, const char*, union Sass_Value*);
66union Sass_Value* sass_env_get_global (Sass_Env_Frame, const char*);
67void sass_env_set_global (Sass_Env_Frame, const char*, union Sass_Value*);
68```
69
70### More links
71
72- [Sass Function Example](api-function-example.md)
73- [Sass Function Internal](api-function-internal.md)
74
75