Initial doc update [WIP]

Author: mgreter

docs/api-basics.md

@@ -0,0 +1,81 @@
+## API documentation basics
+
+LibSass as a C-API comes with multiple headers and a shared library.
+The complete API surface is covered by functions and by passing around
+anonymous structures. The implementor does not know any implementation
+detail about the pointers passed around.
+
+### C-API headers
+
+You may include specific headers directly, which have been split into
+groups as we saw fit, or you can simply include the main `sass.h` header.
+
+### List of C-API headers
+
+- sass/base.h - Includes basic headers and sets a few definitions.
+- sass/fwdecl.h - Forward declares all known anonymous structures.
+- sass/enums.h - Enums for e.g. config options exposed on the C-API.
+- sass/error.h - C-API functions to access `SassError` structs.
+- sass/import.h - C-API functions to access `SassImport` structs.
+- sass/importer.h - C-API functions to access `SassImporter` structs.
+- sass/traces.h - C-API functions to access `SassTrace` structs.
+- sass/values.h - C-API functions to access `SassValue` structs.
+- sass/variable.h - C-API functions to access scoped variables.
+- sass/version.h - Header including hardcoded LibSass version.
+
+## Anonymous structure pointers
+
+LibSass returns and consumes anonymous structure pointers on its C-API.
+Internally those are often directly mapped to an instance of a C++ object.
+Since we don't want implementors to know anything about the implementation
+details, we forward declare named structs (e.g. `SassCompiler`), but never
+provide any implementation for it. LibSass will simply cast a pointer from
+the c++ side to the anonymous struct and relies on the C-API to pass it
+back as expected to the corresponding functions. There the pointer will
+be statically casted back to the actual implementation. Since we provide
+a unique anonymous struct for every internal type, this should be safe as
+compilers should catch the case when arguments mismatch on the C-API side.
+
+### List of anonymous structure pointers
+
+These structs have no real implementation are only passed around as pointers.
+Internally in LibSass those pointers represent mostly different c++ objects.
+
+- struct SassTrace - An single stack-trace object to get further information
+- struct SassError - An error object to get further information
+- struct SassCompiler - Main object to hold state for whole compilation phase.
+- struct SassFunction - Custom function object holding callback and cookie.
+- struct SassSource - Imported source with associated import and resolved path.
+- struct SassSrcSpan - Parser state for column, line and source information.
+- struct SassImport - Single import for entry point or returned by custom importer.
+- struct SassImporter - Custom importer function to be hooked into our loading.
+- struct SassImportList - Custom importers can return a list of imports.
+- struct SassMapIterator - Object to support iteration API over map objects.
+
+## Why using c++11 (or gcc4.4 compatibility)
+
+Since LibSass 3.0 we started to use more and more c++11 features. Some just
+creeped in, others were utilized deliberately. With LibSass 4.0 I took the
+decision to fully utilize whatever c++11 could offer. The main reason to
+fully embrace c++11 is the move semantics it brings. Earlier we also tried
+to support compilers that only had partial c++11 support (e.g. gnu++0x).
+
+With LibSass 4.0 we don't really support this target anymore!
+
+Note: currently the LibSass 4.0 release is on going, the target
+compiler should be gcc 4.8 as it should fully support c++11.
+
+## Binary distributions in linkage issues
+
+LibSass itself does not have any official binary distribution. The main reason for
+this is because it is nearly impossible to do so reliably for each and every
+thinkable operating system. Since LibSass is written in c++ we e.g. depend on the
+compilers c++ runtime library. On windows this problem is a bit less problematic,
+and there is a semi-official installer for it. But on Linux this e.g. is also
+depending on the used libc library. Since linux offers a choice here, a binary
+distribution made with glibc may not be compatible on a system that use musl.
+
+By now LibSass is readily available on a lot of linux systems by their
+internal packet managers, so please try to install it that way. Alternatively
+try to install a recent compiler (e.g. gcc or clang) and compile it from source,
+preferably via the autotools way to ensure correct linkage of your external tool.

docs/api-context-example.md renamed to docs/api-compiler-example.md

@@ -2,7 +2,7 @@
 
 ```C:data.c
 #include <stdio.h>
-#include "sass/context.h"
+#include <sass/context.h>
 
 int main( int argc, const char* argv[] )
 {

docs/api-compiler.md

@@ -0,0 +1,172 @@
+## Sass Compiler API
+
+Sass Compiler is the main object for the Sass compilation process.
+It keeps the state between different stages of the process, which is
+split in three main stages: parsing, compiling and rendering.
+
+The regular life-time of a compiler will mostly look like this:
+- Create new compiler object
+- Set various configuration options
+- Set one compilation entry point
+- Call the parse function
+- Call the compile function
+- Call the render function
+- Process the results
+
+The split between parse, compile and render is done because there
+are certain cases where we might want to omit certain phases. One
+example would be the init phase for a watcher to get all includes.
+
+### Sass Compiler API
+
+```C
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+// Create a new LibSass compiler context
+struct SassCompiler* sass_make_compiler();
+
+// Release all memory allocated with the compiler
+void sass_delete_compiler(struct SassCompiler* compiler);
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+// Parse the entry point and potentially all imports within.
+void sass_compiler_parse(struct SassCompiler* compiler);
+
+// Evaluate the parsed entry point and store resulting ast-tree.
+void sass_compiler_compile(struct SassCompiler* compiler);
+
+// Render the evaluated ast-tree to get the final output string.
+void sass_compiler_render(struct SassCompiler* compiler);
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+// Add additional include paths where LibSass will look for includes.
+// Note: the passed in `paths` can be path separated (`;` on windows, `:` otherwise).
+void 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).
+void 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.
+void 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.
+void 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
+void sass_compiler_add_custom_function(struct SassCompiler* compiler, struct SassFunction* function);
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+// Setter for output style (see `enum SassOutputStyle` for possible options).
+void sass_compiler_set_output_style(struct SassCompiler* compiler, enum SassOutputStyle output_style);
+
+// Setter for logging style (see `enum SassLoggerStyle` for possible options).
+void sass_compiler_set_logger_style(struct SassCompiler* compiler, enum SassLoggerStyle log_style);
+
+// Getter for compiler precision (how floating point numbers are truncated).
+int sass_compiler_get_precision(struct SassCompiler* compiler);
+
+// Setter for compiler precision (how floating point numbers are truncated).
+void sass_compiler_set_precision(struct SassCompiler* compiler, int precision);
+
+// Getter for compiler entry point (which file or data to parse first).
+struct SassImport* sass_compiler_get_entry_point(struct SassCompiler* compiler);
+
+// Setter for compiler entry point (which file or data to parse first).
+void sass_compiler_set_entry_point(struct SassCompiler* compiler, struct SassImport* import);
+
+// Getter for compiler output path (where to store the result)
+// Note: LibSass does not write the file, implementers should write to this path.
+const char* 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.
+void sass_compiler_set_output_path(struct SassCompiler* compiler, const char* output_path);
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+// Getter for warnings that occurred during any step.
+const char* sass_compiler_get_warn_string(struct SassCompiler* compiler);
+
+// Getter for output after parsing, compilation and rendering.
+const char* sass_compiler_get_output_string(struct SassCompiler* compiler);
+
+// Getter for footer string containing optional source-map (embedded or link).
+const char* sass_compiler_get_footer_string(struct SassCompiler* compiler);
+
+// Getter for string containing the optional source-mapping.
+const char* sass_compiler_get_srcmap_string(struct SassCompiler* compiler);
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+// Setter for source-map mode (how to embed or not embed the source-map).
+void 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.
+void 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.
+void sass_compiler_set_srcmap_root(struct SassCompiler* compiler, const char* root);
+
+// Setter for source-map file-url option (renders urls in srcmap as `file://` urls)
+void 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)
+void sass_compiler_set_srcmap_embed_contents(struct SassCompiler* compiler, bool enable);
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+// Getter to return the number of all included files.
+size_t sass_compiler_get_included_files_count(struct SassCompiler* compiler);
+
+// Getter to return path to the included file at position `n`.
+const char* sass_compiler_get_included_file_path(struct SassCompiler* compiler, size_t n);
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+// Getter for current import context. Use `SassImport` functions to query the state.
+const struct SassImport* 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.
+const struct SassError* sass_compiler_get_error(struct SassCompiler* compiler);
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+// Resolve a file relative to last import or include paths in the sass option struct.
+char* 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!?
+char* sass_compiler_find_include(const char* path, struct SassCompiler* compiler);
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+```