Blame docs/api-value.md

Packit Service 7770af
`Sass_Values` are used to pass values and their types between the implementer
Packit Service 7770af
and LibSass. Sass knows various different value types (including nested arrays
Packit Service 7770af
and hash-maps). If you implement a binding to another programming language, you
Packit Service 7770af
have to find a way to [marshal] [1] (convert) `Sass_Values` between the target
Packit Service 7770af
language and C. `Sass_Values` are currently only used by custom functions, but
Packit Service 7770af
it should also be possible to use them without a compiler context.
Packit Service 7770af
Packit Service 7770af
[1]: https://en.wikipedia.org/wiki/Marshalling_%28computer_science%29
Packit Service 7770af
Packit Service 7770af
### Basic Usage
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
#include "sass/values.h"
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
// Type for Sass values
Packit Service 7770af
enum Sass_Tag {
Packit Service 7770af
  SASS_BOOLEAN,
Packit Service 7770af
  SASS_NUMBER,
Packit Service 7770af
  SASS_COLOR,
Packit Service 7770af
  SASS_STRING,
Packit Service 7770af
  SASS_LIST,
Packit Service 7770af
  SASS_MAP,
Packit Service 7770af
  SASS_NULL,
Packit Service 7770af
  SASS_ERROR,
Packit Service 7770af
  SASS_WARNING
Packit Service 7770af
};
Packit Service 7770af
Packit Service 7770af
// Tags for denoting Sass list separators
Packit Service 7770af
enum Sass_Separator {
Packit Service 7770af
  SASS_COMMA,
Packit Service 7770af
  SASS_SPACE,
Packit Service 7770af
  // only used internally to represent a hash map before evaluation
Packit Service 7770af
  // otherwise we would be too early to check for duplicate keys
Packit Service 7770af
  SASS_HASH
Packit Service 7770af
};
Packit Service 7770af
Packit Service 7770af
// Value Operators
Packit Service 7770af
enum Sass_OP {
Packit Service 7770af
  AND, OR,                   // logical connectives
Packit Service 7770af
  EQ, NEQ, GT, GTE, LT, LTE, // arithmetic relations
Packit Service 7770af
  ADD, SUB, MUL, DIV, MOD,   // arithmetic functions
Packit Service 7770af
  NUM_OPS                    // so we know how big to make the op table
Packit Service 7770af
};
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
### Sass Value API
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
// Forward declaration
Packit Service 7770af
union Sass_Value;
Packit Service 7770af
Packit Service 7770af
// Creator functions for all value types
Packit Service 7770af
union Sass_Value* sass_make_null    (void);
Packit Service 7770af
union Sass_Value* sass_make_boolean (bool val);
Packit Service 7770af
union Sass_Value* sass_make_string  (const char* val);
Packit Service 7770af
union Sass_Value* sass_make_qstring (const char* val);
Packit Service 7770af
union Sass_Value* sass_make_number  (double val, const char* unit);
Packit Service 7770af
union Sass_Value* sass_make_color   (double r, double g, double b, double a);
Packit Service 7770af
union Sass_Value* sass_make_list    (size_t len, enum Sass_Separator sep);
Packit Service 7770af
union Sass_Value* sass_make_map     (size_t len);
Packit Service 7770af
union Sass_Value* sass_make_error   (const char* msg);
Packit Service 7770af
union Sass_Value* sass_make_warning (const char* msg);
Packit Service 7770af
Packit Service 7770af
// Generic destructor function for all types
Packit Service 7770af
// Will release memory of all associated Sass_Values
Packit Service 7770af
// Means we will delete recursively for lists and maps
Packit Service 7770af
void sass_delete_value (union Sass_Value* val);
Packit Service 7770af
Packit Service 7770af
// Make a deep cloned copy of the given sass value
Packit Service 7770af
union Sass_Value* sass_clone_value (const union Sass_Value* val);
Packit Service 7770af
Packit Service 7770af
// Stringify a Sass_Values and also return the result as a Sass_Value (of type STRING)
Packit Service 7770af
union Sass_Value* sass_value_stringify (const union Sass_Value* a, bool compressed, int precision);
Packit Service 7770af
Packit Service 7770af
// Execute an operation for two Sass_Values and return the result as a Sass_Value too
Packit Service 7770af
union Sass_Value* sass_value_op (enum Sass_OP op, const union Sass_Value* a, const union Sass_Value* b);
Packit Service 7770af
Packit Service 7770af
// Return the sass tag for a generic sass value
Packit Service 7770af
// Check is needed before accessing specific values!
Packit Service 7770af
enum Sass_Tag sass_value_get_tag (const union Sass_Value* v);
Packit Service 7770af
Packit Service 7770af
// Check value to be of a specific type
Packit Service 7770af
// Can also be used before accessing properties!
Packit Service 7770af
bool sass_value_is_null (const union Sass_Value* v);
Packit Service 7770af
bool sass_value_is_number (const union Sass_Value* v);
Packit Service 7770af
bool sass_value_is_string (const union Sass_Value* v);
Packit Service 7770af
bool sass_value_is_boolean (const union Sass_Value* v);
Packit Service 7770af
bool sass_value_is_color (const union Sass_Value* v);
Packit Service 7770af
bool sass_value_is_list (const union Sass_Value* v);
Packit Service 7770af
bool sass_value_is_map (const union Sass_Value* v);
Packit Service 7770af
bool sass_value_is_error (const union Sass_Value* v);
Packit Service 7770af
bool sass_value_is_warning (const union Sass_Value* v);
Packit Service 7770af
Packit Service 7770af
// Getters and setters for Sass_Number
Packit Service 7770af
double sass_number_get_value (const union Sass_Value* v);
Packit Service 7770af
void sass_number_set_value (union Sass_Value* v, double value);
Packit Service 7770af
const char* sass_number_get_unit (const union Sass_Value* v);
Packit Service 7770af
void sass_number_set_unit (union Sass_Value* v, char* unit);
Packit Service 7770af
Packit Service 7770af
// Getters and setters for Sass_String
Packit Service 7770af
const char* sass_string_get_value (const union Sass_Value* v);
Packit Service 7770af
void sass_string_set_value (union Sass_Value* v, char* value);
Packit Service 7770af
bool sass_string_is_quoted(const union Sass_Value* v);
Packit Service 7770af
void sass_string_set_quoted(union Sass_Value* v, bool quoted);
Packit Service 7770af
Packit Service 7770af
// Getters and setters for Sass_Boolean
Packit Service 7770af
bool sass_boolean_get_value (const union Sass_Value* v);
Packit Service 7770af
void sass_boolean_set_value (union Sass_Value* v, bool value);
Packit Service 7770af
Packit Service 7770af
// Getters and setters for Sass_Color
Packit Service 7770af
double sass_color_get_r (const union Sass_Value* v);
Packit Service 7770af
void sass_color_set_r (union Sass_Value* v, double r);
Packit Service 7770af
double sass_color_get_g (const union Sass_Value* v);
Packit Service 7770af
void sass_color_set_g (union Sass_Value* v, double g);
Packit Service 7770af
double sass_color_get_b (const union Sass_Value* v);
Packit Service 7770af
void sass_color_set_b (union Sass_Value* v, double b);
Packit Service 7770af
double sass_color_get_a (const union Sass_Value* v);
Packit Service 7770af
void sass_color_set_a (union Sass_Value* v, double a);
Packit Service 7770af
Packit Service 7770af
// Getter for the number of items in list
Packit Service 7770af
size_t sass_list_get_length (const union Sass_Value* v);
Packit Service 7770af
// Getters and setters for Sass_List
Packit Service 7770af
enum Sass_Separator sass_list_get_separator (const union Sass_Value* v);
Packit Service 7770af
void sass_list_set_separator (union Sass_Value* v, enum Sass_Separator value);
Packit Service 7770af
// Getters and setters for Sass_List values
Packit Service 7770af
union Sass_Value* sass_list_get_value (const union Sass_Value* v, size_t i);
Packit Service 7770af
void sass_list_set_value (union Sass_Value* v, size_t i, union Sass_Value* value);
Packit Service 7770af
Packit Service 7770af
// Getter for the number of items in map
Packit Service 7770af
size_t sass_map_get_length (const union Sass_Value* v);
Packit Service 7770af
// Getters and setters for Sass_Map keys and values
Packit Service 7770af
union Sass_Value* sass_map_get_key (const union Sass_Value* v, size_t i);
Packit Service 7770af
void sass_map_set_key (union Sass_Value* v, size_t i, union Sass_Value*);
Packit Service 7770af
union Sass_Value* sass_map_get_value (const union Sass_Value* v, size_t i);
Packit Service 7770af
void sass_map_set_value (union Sass_Value* v, size_t i, union Sass_Value*);
Packit Service 7770af
Packit Service 7770af
// Getters and setters for Sass_Error
Packit Service 7770af
char* sass_error_get_message (const union Sass_Value* v);
Packit Service 7770af
void sass_error_set_message (union Sass_Value* v, char* msg);
Packit Service 7770af
Packit Service 7770af
// Getters and setters for Sass_Warning
Packit Service 7770af
char* sass_warning_get_message (const union Sass_Value* v);
Packit Service 7770af
void sass_warning_set_message (union Sass_Value* v, char* msg);
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
### More links
Packit Service 7770af
Packit Service 7770af
- [Sass Value Example](api-value-example.md)
Packit Service 7770af
- [Sass Value Internal](api-value-internal.md)
Packit Service 7770af