Refining C-API and more streamlining

Author: mgreter

Makefile.conf

@@ -7,14 +7,14 @@
 INCFILES = \
 	sass.h \
 	sass/base.h \
-	sass/compiler.h \
-	sass/context.h \
 	sass/enums.h \
 	sass/error.h \
-	sass/function.h \
 	sass/fwdecl.h \
 	sass/import.h \
-	sass/lists.h \
+	sass/importer.h \
+	sass/function.h \
+	sass/compiler.h \
+	sass/variable.h \
 	sass/traces.h \
 	sass/values.h \
 	sass/version.h
@@ -42,13 +42,13 @@ HPPFILES = \
 	charcode.hpp \
 	color_maps.hpp \
 	constants.hpp \
-	context.hpp \
 	cssize.hpp \
 	dart_helpers.hpp \
 	debugger.hpp \
 	emitter.hpp \
 	environment.hpp \
 	exceptions.hpp \
+	settings.hpp \
 	memory.hpp \
 	memory/config.hpp \
 	memory/allocator.hpp \
@@ -74,7 +74,6 @@ HPPFILES = \
 	interpolation.hpp \
 	logger.hpp \
 	json.hpp \
-	kwd_arg_macros.hpp \
 	randomize.hpp \
 	mapping.hpp \
 	ordered_map.hpp \
@@ -97,12 +96,13 @@ HPPFILES = \
 	offset.hpp \
 	remove_placeholders.hpp \
 	capi_sass.hpp \
-	capi_base.hpp \
-	capi_list.hpp \
 	capi_error.hpp \
-	capi_context.hpp \
+	capi_traces.hpp \
+	capi_import.hpp \
+	capi_importer.hpp \
 	capi_compiler.hpp \
-	capi_functions.hpp \
+	capi_variable.hpp \
+	capi_function.hpp \
 	capi_values.hpp \
 	scanner_string.hpp \
 	source_map.hpp \
@@ -112,7 +112,7 @@ HPPFILES = \
 	preloader.hpp \
 	units.hpp \
 	unicode.hpp \
-	util_string.hpp \
+	hashing.hpp \
 	visitor_css.hpp \
 	visitor_expression.hpp \
 	visitor_selector.hpp \
@@ -122,7 +122,9 @@ HPPFILES = \
 	callstack.hpp \
 	environment_cnt.hpp \
 	environment_key.hpp \
-	environment_stack.hpp
+	environment_stack.hpp \
+	b64/cencode.hpp \
+	b64/encode.hpp
 
 SOURCES = \
 	ast.cpp \
@@ -139,7 +141,6 @@ SOURCES = \
 	ast_sel_weave.cpp \
 	ast_selectors.cpp \
 	modules.cpp \
-	context.cpp \
 	constants.cpp \
 	compiler.cpp \
 	fn_meta.cpp \
@@ -153,7 +154,6 @@ SOURCES = \
 	environment.cpp \
 	ast_fwd_decl.cpp \
 	file.cpp \
-	util_string.cpp \
 	string_utils.cpp \
 	logger.cpp \
 	strings.cpp \
@@ -188,13 +188,14 @@ SOURCES = \
 	scanner_string.cpp \
 	remove_placeholders.cpp \
 	capi_sass.cpp \
-	capi_base.cpp \
-	capi_lists.cpp \
 	capi_error.cpp \
-	capi_values.cpp \
-	capi_context.cpp \
+	capi_traces.cpp \
+	capi_import.cpp \
+	capi_importer.cpp \
 	capi_compiler.cpp \
-	capi_functions.cpp \
+	capi_variable.cpp \
+	capi_function.cpp \
+	capi_values.cpp \
 	character.cpp \
 	environment_stack.cpp \
 	source_map.cpp \

include/sass.h

@@ -1,30 +1,21 @@
 #ifndef SASS_H
 #define SASS_H
 
-// #define DEBUG 1
-
 // Note: we can't forward declare with inheritance
 // https://stackoverflow.com/a/10145303/1550314
 
 // include API headers
 #include <sass/base.h>
+#include <sass/enums.h>
 #include <sass/fwdecl.h>
 #include <sass/version.h>
-#include <sass/lists.h>
-#include <sass/values.h>
 #include <sass/error.h>
-#include <sass/import.h>
 #include <sass/traces.h>
-#include <sass/functions.h>
-#include <sass/context.h>
+#include <sass/values.h>
+#include <sass/import.h>
+#include <sass/importer.h>
+#include <sass/function.h>
 #include <sass/compiler.h>
-
-typedef struct SassImport* Sass_Import_Entry;
-typedef struct SassImporter* Sass_Importer_Entry;
-typedef struct SassFunction* Sass_Function_Entry;
-
-typedef struct SassImportList* Sass_Import_List;
-typedef struct SassImporterList* Sass_Importer_List;
-typedef struct SassFunctionList* Sass_Function_List;
+#include <sass/variable.h>
 
 #endif

include/sass/base.h

@@ -1,5 +1,8 @@
-#ifndef SASS_C_BASE_H
-#define SASS_C_BASE_H
+/*****************************************************************************/
+/* Part of LibSass, released under the MIT license (See LICENSE.txt).        */
+/*****************************************************************************/
+#ifndef SASS_BASE_H
+#define SASS_BASE_H
 
 #ifdef _MSC_VER
   #pragma warning(disable : 4503)
@@ -42,7 +45,7 @@
 
 #ifdef _WIN32
 
-  /* You should define ADD_EXPORTS *only* when building the DLL. */
+/* You should define ADD_EXPORTS *only* when building the DLL. */
   #ifdef ADD_EXPORTS
     #define ADDAPI __declspec(dllexport)
     #define ADDCALL __cdecl
@@ -87,16 +90,6 @@ extern "C" {
   ADDAPI void ADDCALL sass_free_memory(void* ptr);
   ADDAPI void ADDCALL sass_free_c_string(char* ptr);
 
-  // Resolve a file via the given include paths in the sass option struct
-  // find_file looks for the exact file name while find_include does a regular sass include
-  // ADDAPI char* ADDCALL sass_find_file (const char* path, struct SassOptionsCpp* opt);
-  // ADDAPI char* ADDCALL sass_find_include (const char* path, struct SassOptionsCpp* opt);
-
-  // Resolve a file relative to last import or include paths in the sass option struct
-  // find_file looks for the exact file name while find_include does a regular sass include
-  // ADDAPI char* ADDCALL sass_compiler_find_file(const char* path, struct SassCompiler* compiler);
-  // ADDAPI char* ADDCALL sass_compiler_find_include(const char* path, struct SassCompiler* compiler);
-
   // Return implemented sass language version
   ADDAPI const char* ADDCALL libsass_version(void);
 

include/sass/compiler.h

@@ -1,91 +1,168 @@
+/*****************************************************************************/
+/* Part of LibSass, released under the MIT license (See LICENSE.txt).        */
+/*****************************************************************************/
 #ifndef SASS_C_COMPILER_H
 #define SASS_C_COMPILER_H
 
 #include <sass/base.h>
+#include <sass/function.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-  // Create a new compiler from the libsass context and the given entry point
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
+
+  // Create a new LibSass compiler context
   ADDAPI struct SassCompiler* ADDCALL sass_make_compiler();
 
-  // Release all memory allocated with the structures
+  // Release all memory allocated with the compiler
   ADDAPI void ADDCALL sass_delete_compiler(struct SassCompiler* compiler);
 
-  // Parse the entry point and potentially all imports within
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
+
+  // Parse the entry point and potentially all imports within.
   ADDAPI void ADDCALL sass_compiler_parse(struct SassCompiler* compiler);
 
-  // Evaluate the parsed entry point and store resulting ast-tree
+  // Evaluate the parsed entry point and store resulting ast-tree.
   ADDAPI void ADDCALL sass_compiler_compile(struct SassCompiler* compiler);
 
-  // Render the evaluated ast-tree to get the final output string
+  // Render the evaluated ast-tree to get the final output string.
   ADDAPI void ADDCALL sass_compiler_render(struct SassCompiler* compiler);
 
-  // Push function for paths (no manipulation support for now)
-  ADDAPI void ADDCALL sass_compiler_load_plugins(struct SassCompiler* compiler, const char* paths);
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
+
+  // Add additional include paths where LibSass will look for includes.
+  // Note: the passed in `paths` can be path separated (`;` on windows, `:` otherwise).
   ADDAPI void ADDCALL sass_compiler_add_include_paths(struct SassCompiler* compiler, const char* paths);
+
+  // Load dynamic loadable plugins from `paths`. Plugins are only supported on certain OSs and
+  // are still in experimental state. This will look for `*.dll`, `*.so` or `*.dynlib` files.
+  // It then tries to load the found libraries and does a few checks to see if the library
+  // is actually a LibSass plugin. We then call its init hook if the library is compatible.
+  // Note: the passed in `paths` can be path separated (`;` on windows, `:` otherwise).
+  ADDAPI void ADDCALL sass_compiler_load_plugins(struct SassCompiler* compiler, const char* paths);
+
+  // Add a custom header importer that will always be executed before any other 
+  // compilations takes place. Useful to prepend a shared copyright header or to
+  // provide global variables or functions. This feature is still in experimental state.
+  // Note: With the adaption of Sass Modules this might be completely replaced in the future.
   ADDAPI void ADDCALL sass_compiler_add_custom_header(struct SassCompiler* compiler, struct SassImporter* header);
+
+  // Add a custom importer that will be executed when a sass `@import` rule is found.
+  // This is useful to e.g. rewrite import locations or to load content from remote.
+  // For more please check https://github.com/sass/libsass/blob/master/docs/api-importer.md
+  // Note: The importer will not be called for regular css `@import url()` rules.
   ADDAPI void ADDCALL sass_compiler_add_custom_importer(struct SassCompiler* compiler, struct SassImporter* importer);
+
+  // Add a custom function that will be executed when the corresponding function call is
+  // requested from any sass code. This is useful to provide custom functions in your code.
+  // For more please check https://github.com/sass/libsass/blob/master/docs/api-function.md
   ADDAPI void ADDCALL sass_compiler_add_custom_function(struct SassCompiler* compiler, struct SassFunction* function);
 
-  // Setters for output and console logging styles
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
+
+  // Setter for output style (see `enum SassOutputStyle` for possible options).
   ADDAPI void ADDCALL sass_compiler_set_output_style(struct SassCompiler* compiler, enum SassOutputStyle output_style);
+
+  // Setter for logging style (see `enum SassLoggerStyle` for possible options).
   ADDAPI void ADDCALL sass_compiler_set_logger_style(struct SassCompiler* compiler, enum SassLoggerStyle log_style);
 
-  // Getters for compiler option values
+  // Getter for compiler precision (how floating point numbers are truncated).
   ADDAPI int ADDCALL sass_compiler_get_precision(struct SassCompiler* compiler);
-  ADDAPI const char* ADDCALL sass_compiler_get_output_path(struct SassCompiler* compiler);
-  ADDAPI struct SassImport* ADDCALL sass_compiler_get_entry_point(struct SassCompiler* compiler);
 
-  // Setters for compiler option values
+  // Setter for compiler precision (how floating point numbers are truncated).
   ADDAPI void ADDCALL sass_compiler_set_precision(struct SassCompiler* compiler, int precision);
-  ADDAPI void ADDCALL sass_compiler_set_output_path(struct SassCompiler* compiler, const char* output_path);
+
+  // Getter for compiler entry point (which file or data to parse first).
+  ADDAPI struct SassImport* ADDCALL sass_compiler_get_entry_point(struct SassCompiler* compiler);
+
+  // Setter for compiler entry point (which file or data to parse first).
   ADDAPI void ADDCALL sass_compiler_set_entry_point(struct SassCompiler* compiler, struct SassImport* import);
 
-  // Getter for sass compiler results
+  // Getter for compiler output path (where to store the result)
+  // Note: LibSass does not write the file, implementers should write to this path.
+  ADDAPI const char* ADDCALL sass_compiler_get_output_path(struct SassCompiler* compiler);
+
+  // Setter for compiler output path (where to store the result)
+  // Note: LibSass does not write the file, implementers should write to this path.
+  ADDAPI void ADDCALL sass_compiler_set_output_path(struct SassCompiler* compiler, const char* output_path);
+
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
+
+  // Getter for warnings that occurred during any step.
   ADDAPI const char* ADDCALL sass_compiler_get_warn_string(struct SassCompiler* compiler);
+
+  // Getter for output after parsing, compilation and rendering.
   ADDAPI const char* ADDCALL sass_compiler_get_output_string(struct SassCompiler* compiler);
+
+  // Getter for footer string containing optional source-map (embedded or link).
   ADDAPI const char* ADDCALL sass_compiler_get_footer_string(struct SassCompiler* compiler);
+
+  // Getter for string containing the optional source-mapping.
   ADDAPI const char* ADDCALL sass_compiler_get_srcmap_string(struct SassCompiler* compiler);
 
-  // Setters for source-map options
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
+
+  // Setter for source-map mode (how to embed or not embed the source-map).
+  ADDAPI void ADDCALL sass_compiler_set_srcmap_mode(struct SassCompiler* compiler, enum SassSrcMapMode mode);
+
+  // Setter for source-map path (where to store the source-mapping).
+  // Note: if path is not explicitly given, we will deduct one from input path.
+  // Note: LibSass does not write the file, implementers should write to this path.
   ADDAPI void ADDCALL sass_compiler_set_srcmap_path(struct SassCompiler* compiler, const char* path);
+
+  // Setter for source-map root (simply passed to the resulting srcmap info).
+  // Note: if not given, no root attribute will be added to the srcmap info object.
   ADDAPI void ADDCALL sass_compiler_set_srcmap_root(struct SassCompiler* compiler, const char* root);
-  ADDAPI void ADDCALL sass_compiler_set_srcmap_mode(struct SassCompiler* compiler, enum SassSrcMapMode mode);
+
+  // Setter for source-map file-url option (renders urls in srcmap as `file://` urls)
   ADDAPI void ADDCALL sass_compiler_set_srcmap_file_urls(struct SassCompiler* compiler, bool enable);
+
+  // Setter for source-map embed-contents option (includes full sources in the srcmap info)
   ADDAPI void ADDCALL sass_compiler_set_srcmap_embed_contents(struct SassCompiler* compiler, bool enable);
 
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
+
+  // Getter to return the number of all included files.
   ADDAPI size_t ADDCALL sass_compiler_get_included_files_count(struct SassCompiler* compiler);
+
+  // Getter to return path to the included file at position `n`.
   ADDAPI const char* ADDCALL sass_compiler_get_included_file_path(struct SassCompiler* compiler, size_t n);
 
-  ADDAPI struct SassImport* ADDCALL sass_compiler_get_last_import(struct SassCompiler* compiler);
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
 
-#ifdef __cplusplus
-} // EO extern "C".
-#endif
-
-#ifdef __cplusplus
-namespace Sass {
-extern "C" {
-#endif
+  // Getter for current import context. Use `SassImport` functions to query the state.
+  ADDAPI const struct SassImport* ADDCALL sass_compiler_get_last_import(struct SassCompiler* compiler);
 
   // Returns pointer to error object associated with compiler.
   // Will be valid until the associated compiler is destroyed.
   ADDAPI const struct SassError* ADDCALL sass_compiler_get_error(struct SassCompiler* compiler);
-  ADDAPI const char* ADDCALL sass_compiler_get_stderr(struct SassCompiler* compiler);
-
-
 
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
 
-    // ADDAPI void ADDCALL sass_compiler_set_input_path(struct SassCompiler* compiler, const char* input_path);
-    // ADDAPI void ADDCALL sass_compiler_set_source_map_file(struct SassCompiler* compiler, const char* source_map_file);
-    // ADDAPI void ADDCALL sass_compiler_set_source_map_root(struct SassCompiler* compiler, const char* source_map_root);
+  // Resolve a file relative to last import or include paths in the sass option struct.
+  ADDAPI char* ADDCALL sass_compiler_find_file(const char* path, struct SassCompiler* compiler);
 
+  // Resolve an include relative to last import or include paths in the sass option struct.
+  // This will do a lookup as LibSass would do internally (partials, different extensions).
+  // ToDo: Check if we should add `includeIndex` option to check for directory index files!?
+  ADDAPI char* ADDCALL sass_compiler_find_include(const char* path, struct SassCompiler* compiler);
 
+  /////////////////////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
 } // EO extern "C".
-} // EO namespace Sass
 #endif
 
 #endif