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

   1 `Sass_Values` are used to pass values and their types between the implementer
   2 and LibSass. Sass knows various different value types (including nested arrays
   3 and hash-maps). If you implement a binding to another programming language, you
   4 have to find a way to [marshal] [1] (convert) `Sass_Values` between the target
   5 language and C. `Sass_Values` are currently only used by custom functions, but
   6 it should also be possible to use them without a compiler context.
   7
   8 [1]: https://en.wikipedia.org/wiki/Marshalling_%28computer_science%29
   9
  10 ### Basic Usage
  11
  12 ```C
  13 #include "sass/values.h"
  14 ```
  15
  16 ```C
  17 // Type for Sass values
  18 enum Sass_Tag {
  19   SASS_BOOLEAN,
  20   SASS_NUMBER,
  21   SASS_COLOR,
  22   SASS_STRING,
  23   SASS_LIST,
  24   SASS_MAP,
  25   SASS_NULL,
  26   SASS_ERROR,
  27   SASS_WARNING
  28 };
  29
  30 // Tags for denoting Sass list separators
  31 enum Sass_Separator {
  32   SASS_COMMA,
  33   SASS_SPACE,
  34   // only used internally to represent a hash map before evaluation
  35   // otherwise we would be too early to check for duplicate keys
  36   SASS_HASH
  37 };
  38
  39 // Value Operators
  40 enum Sass_OP {
  41   AND, OR,                   // logical connectives
  42   EQ, NEQ, GT, GTE, LT, LTE, // arithmetic relations
  43   ADD, SUB, MUL, DIV, MOD,   // arithmetic functions
  44   NUM_OPS                    // so we know how big to make the op table
  45 };
  46 ```
  47
  48 ### Sass Value API
  49
  50 ```C
  51 // Forward declaration
  52 union Sass_Value;
  53
  54 // Creator functions for all value types
  55 union Sass_Value* sass_make_null    (void);
  56 union Sass_Value* sass_make_boolean (bool val);
  57 union Sass_Value* sass_make_string  (const char* val);
  58 union Sass_Value* sass_make_qstring (const char* val);
  59 union Sass_Value* sass_make_number  (double val, const char* unit);
  60 union Sass_Value* sass_make_color   (double r, double g, double b, double a);
  61 union Sass_Value* sass_make_list    (size_t len, enum Sass_Separator sep, bool is_bracketed);
  62 union Sass_Value* sass_make_map     (size_t len);
  63 union Sass_Value* sass_make_error   (const char* msg);
  64 union Sass_Value* sass_make_warning (const char* msg);
  65
  66 // Generic destructor function for all types
  67 // Will release memory of all associated Sass_Values
  68 // Means we will delete recursively for lists and maps
  69 void sass_delete_value (union Sass_Value* val);
  70
  71 // Make a deep cloned copy of the given sass value
  72 union Sass_Value* sass_clone_value (const union Sass_Value* val);
  73
  74 // Stringify a Sass_Values and also return the result as a Sass_Value (of type STRING)
  75 union Sass_Value* sass_value_stringify (const union Sass_Value* a, bool compressed, int precision);
  76
  77 // Execute an operation for two Sass_Values and return the result as a Sass_Value too
  78 union Sass_Value* sass_value_op (enum Sass_OP op, const union Sass_Value* a, const union Sass_Value* b);
  79
  80 // Return the sass tag for a generic sass value
  81 // Check is needed before accessing specific values!
  82 enum Sass_Tag sass_value_get_tag (const union Sass_Value* v);
  83
  84 // Check value to be of a specific type
  85 // Can also be used before accessing properties!
  86 bool sass_value_is_null (const union Sass_Value* v);
  87 bool sass_value_is_number (const union Sass_Value* v);
  88 bool sass_value_is_string (const union Sass_Value* v);
  89 bool sass_value_is_boolean (const union Sass_Value* v);
  90 bool sass_value_is_color (const union Sass_Value* v);
  91 bool sass_value_is_list (const union Sass_Value* v);
  92 bool sass_value_is_map (const union Sass_Value* v);
  93 bool sass_value_is_error (const union Sass_Value* v);
  94 bool sass_value_is_warning (const union Sass_Value* v);
  95
  96 // Getters and setters for Sass_Number
  97 double sass_number_get_value (const union Sass_Value* v);
  98 void sass_number_set_value (union Sass_Value* v, double value);
  99 const char* sass_number_get_unit (const union Sass_Value* v);
 100 void sass_number_set_unit (union Sass_Value* v, char* unit);
 101
 102 // Getters and setters for Sass_String
 103 const char* sass_string_get_value (const union Sass_Value* v);
 104 void sass_string_set_value (union Sass_Value* v, char* value);
 105 bool sass_string_is_quoted(const union Sass_Value* v);
 106 void sass_string_set_quoted(union Sass_Value* v, bool quoted);
 107
 108 // Getters and setters for Sass_Boolean
 109 bool sass_boolean_get_value (const union Sass_Value* v);
 110 void sass_boolean_set_value (union Sass_Value* v, bool value);
 111
 112 // Getters and setters for Sass_Color
 113 double sass_color_get_r (const union Sass_Value* v);
 114 void sass_color_set_r (union Sass_Value* v, double r);
 115 double sass_color_get_g (const union Sass_Value* v);
 116 void sass_color_set_g (union Sass_Value* v, double g);
 117 double sass_color_get_b (const union Sass_Value* v);
 118 void sass_color_set_b (union Sass_Value* v, double b);
 119 double sass_color_get_a (const union Sass_Value* v);
 120 void sass_color_set_a (union Sass_Value* v, double a);
 121
 122 // Getter for the number of items in list
 123 size_t sass_list_get_length (const union Sass_Value* v);
 124 // Getters and setters for Sass_List
 125 enum Sass_Separator sass_list_get_separator (const union Sass_Value* v);
 126 void sass_list_set_separator (union Sass_Value* v, enum Sass_Separator value);
 127 bool sass_list_get_is_bracketed (const union Sass_Value* v);
 128 void sass_list_set_is_bracketed (union Sass_Value* v, bool value);
 129 // Getters and setters for Sass_List values
 130 union Sass_Value* sass_list_get_value (const union Sass_Value* v, size_t i);
 131 void sass_list_set_value (union Sass_Value* v, size_t i, union Sass_Value* value);
 132
 133 // Getter for the number of items in map
 134 size_t sass_map_get_length (const union Sass_Value* v);
 135 // Getters and setters for Sass_Map keys and values
 136 union Sass_Value* sass_map_get_key (const union Sass_Value* v, size_t i);
 137 void sass_map_set_key (union Sass_Value* v, size_t i, union Sass_Value*);
 138 union Sass_Value* sass_map_get_value (const union Sass_Value* v, size_t i);
 139 void sass_map_set_value (union Sass_Value* v, size_t i, union Sass_Value*);
 140
 141 // Getters and setters for Sass_Error
 142 char* sass_error_get_message (const union Sass_Value* v);
 143 void sass_error_set_message (union Sass_Value* v, char* msg);
 144
 145 // Getters and setters for Sass_Warning
 146 char* sass_warning_get_message (const union Sass_Value* v);
 147 void sass_warning_set_message (union Sass_Value* v, char* msg);
 148 ```
 149
 150 ### More links
 151
 152 - [Sass Value Example](api-value-example.md)
 153 - [Sass Value Internal](api-value-internal.md)
 154