Blame docs/api-function.md

Packit Service 7770af
Sass 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.
Packit Service 7770af
Packit Service 7770af
## Special signatures
Packit Service 7770af
Packit Service 7770af
- `*` - Fallback implementation
Packit Service 7770af
- `@warn` - Overload warn statements
Packit Service 7770af
- `@error` - Overload error statements
Packit Service 7770af
- `@debug` - Overload debug statements
Packit Service 7770af
Packit Service 7770af
Note: 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.
Packit Service 7770af
Packit Service 7770af
### Basic Usage
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
#include "sass/functions.h"
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
## Sass Function API
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
// Forward declaration
Packit Service 7770af
struct Sass_Compiler;
Packit Service 7770af
struct Sass_Function;
Packit Service 7770af
Packit Service 7770af
// Typedef helpers for custom functions lists
Packit Service 7770af
typedef struct Sass_Function (*Sass_Function_Entry);
Packit Service 7770af
typedef struct Sass_Function* (*Sass_Function_List);
Packit Service 7770af
// Typedef defining function signature and return type
Packit Service 7770af
typedef union Sass_Value* (*Sass_Function_Fn)
Packit Service 7770af
  (const union Sass_Value*, Sass_Function_Entry cb, struct Sass_Compiler* compiler);
Packit Service 7770af
Packit Service 7770af
// Creators for sass function list and function descriptors
Packit Service 7770af
Sass_Function_List sass_make_function_list (size_t length);
Packit Service 7770af
Sass_Function_Entry sass_make_function (const char* signature, Sass_Function_Fn cb, void* cookie);
Packit Service 7770af
// In case you need to free them yourself
Packit Service 7770af
void sass_delete_function (Sass_Function_Entry entry);
Packit Service 7770af
void sass_delete_function_list (Sass_Function_List list);
Packit Service 7770af
Packit Service 7770af
// Setters and getters for callbacks on function lists
Packit Service 7770af
Sass_Function_Entry sass_function_get_list_entry(Sass_Function_List list, size_t pos);
Packit Service 7770af
void sass_function_set_list_entry(Sass_Function_List list, size_t pos, Sass_Function_Entry cb);
Packit Service 7770af
Packit Service 7770af
// Setters to insert an entry into the import list (you may also use [] access directly)
Packit Service 7770af
// Since we are dealing with pointers they should have a guaranteed and fixed size
Packit Service 7770af
void sass_import_set_list_entry (Sass_Import_List list, size_t idx, Sass_Import_Entry entry);
Packit Service 7770af
Sass_Import_Entry sass_import_get_list_entry (Sass_Import_List list, size_t idx);
Packit Service 7770af
Packit Service 7770af
// Getters for custom function descriptors
Packit Service 7770af
const char* sass_function_get_signature (Sass_Function_Entry cb);
Packit Service 7770af
Sass_Function_Fn sass_function_get_function (Sass_Function_Entry cb);
Packit Service 7770af
void* sass_function_get_cookie (Sass_Function_Entry cb);
Packit Service 7770af
Packit Service 7770af
// Getters for callee entry
Packit Service 7770af
const char* sass_callee_get_name (Sass_Callee_Entry);
Packit Service 7770af
const char* sass_callee_get_path (Sass_Callee_Entry);
Packit Service 7770af
size_t sass_callee_get_line (Sass_Callee_Entry);
Packit Service 7770af
size_t sass_callee_get_column (Sass_Callee_Entry);
Packit Service 7770af
enum Sass_Callee_Type sass_callee_get_type (Sass_Callee_Entry);
Packit Service 7770af
Sass_Env_Frame sass_callee_get_env (Sass_Callee_Entry);
Packit Service 7770af
Packit Service 7770af
// Getters and Setters for environments (lexical, local and global)
Packit Service 7770af
union Sass_Value* sass_env_get_lexical (Sass_Env_Frame, const char*);
Packit Service 7770af
void sass_env_set_lexical (Sass_Env_Frame, const char*, union Sass_Value*);
Packit Service 7770af
union Sass_Value* sass_env_get_local (Sass_Env_Frame, const char*);
Packit Service 7770af
void sass_env_set_local (Sass_Env_Frame, const char*, union Sass_Value*);
Packit Service 7770af
union Sass_Value* sass_env_get_global (Sass_Env_Frame, const char*);
Packit Service 7770af
void sass_env_set_global (Sass_Env_Frame, const char*, union Sass_Value*);
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
### More links
Packit Service 7770af
Packit Service 7770af
- [Sass Function Example](api-function-example.md)
Packit Service 7770af
- [Sass Function Internal](api-function-internal.md)
Packit Service 7770af