1# Developer Documentation
2
3Custom functions are internally represented by `struct Sass_C_Function_Descriptor`.
4
5## Sass_C_Function_Descriptor
6
7```C
8struct Sass_C_Function_Descriptor {
9  const char*      signature;
10  Sass_C_Function  function;
11  void*            cookie;
12};
13```
14
15- `signature`: The function declaration, like `foo($bar, $baz:1)`
16- `function`:  Reference to the C function callback
17- `cookie`:    any pointer you want to attach
18
19### signature
20
21The signature defines how the function can be invoked. It also declares which arguments are required and which are optional.  Required arguments will be enforced by LibSass and a Sass error is thrown in the event a call as missing an argument. Optional arguments only need to be present when you want to overwrite the default value.
22
23    foo($bar, $baz: 2)
24
25In this example, `$bar` is required and will error if not passed. `$baz` is optional and the default value of it is 2. A call like `foo(10)` is therefore equal to `foo(10, 2)`, while `foo()` will produce an error.
26
27### function
28
29The callback function needs to be of the following form:
30
31```C
32union Sass_Value* call_sass_function(
33    const union Sass_Value* s_args,
34    void*                   cookie
35) {
36  return sass_clone_value(s_args);
37}
38```
39
40### cookie
41
42The cookie can hold any pointer you want. In the `perl-libsass` implementation it holds the structure with the reference of the actual registered callback into the perl interpreter. Before that call `perl-libsass` will convert all `Sass_Values` to corresponding perl data types (so they can be used natively inside the perl interpreter). The callback can also return a `Sass_Value`. In `perl-libsass` the actual function returns a perl value, which has to be converted before `libsass` can work with it again!
43
44## Sass_Values
45
46```C
47// allocate memory (copies passed strings)
48union Sass_Value* sass_make_null    (void);
49union Sass_Value* sass_make_boolean (bool val);
50union Sass_Value* sass_make_string  (const char* val);
51union Sass_Value* sass_make_qstring (const char* val);
52union Sass_Value* sass_make_number  (double val, const char* unit);
53union Sass_Value* sass_make_color   (double r, double g, double b, double a);
54union Sass_Value* sass_make_list    (size_t len, enum Sass_Separator sep, bool is_bracketed);
55union Sass_Value* sass_make_map     (size_t len);
56union Sass_Value* sass_make_error   (const char* msg);
57union Sass_Value* sass_make_warning (const char* msg);
58
59// Make a deep cloned copy of the given sass value
60union Sass_Value* sass_clone_value (const union Sass_Value* val);
61
62// deallocate memory (incl. all copied memory)
63void sass_delete_value (const union Sass_Value* val);
64```
65
66## Example main.c
67
68```C
69#include <stdio.h>
70#include <stdint.h>
71#include "sass/context.h"
72
73union Sass_Value* call_fn_foo(const union Sass_Value* s_args, void* cookie)
74{
75  // we actually abuse the void* to store an "int"
76  return sass_make_number((size_t)cookie, "px");
77}
78
79int main( int argc, const char* argv[] )
80{
81
82  // get the input file from first argument or use default
83  const char* input = argc > 1 ? argv[1] : "styles.scss";
84
85  // create the file context and get all related structs
86  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
87  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
88  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
89
90  // allocate a custom function caller
91  Sass_C_Function_Callback fn_foo =
92    sass_make_function("foo()", call_fn_foo, (void*)42);
93
94  // create list of all custom functions
95  Sass_C_Function_List fn_list = sass_make_function_list(1);
96  sass_function_set_list_entry(fn_list, 0, fn_foo);
97  sass_option_set_c_functions(ctx_opt, fn_list);
98
99  // context is set up, call the compile step now
100  int status = sass_compile_file_context(file_ctx);
101
102  // print the result or the error to the stdout
103  if (status == 0) puts(sass_context_get_output_string(ctx));
104  else puts(sass_context_get_error_message(ctx));
105
106  // release allocated memory
107  sass_delete_file_context(file_ctx);
108
109  // exit status
110  return status;
111
112}
113```
114
115## Compile main.c
116
117```bash
118gcc -c main.c -o main.o
119gcc -o sample main.o -lsass
120echo "foo { margin: foo(); }" > foo.scss
121./sample foo.scss => "foo { margin: 42px }"
122```
123