sassc 2.0.1 → 2.1.0.pre1

data/ext/libsass/docs/dev-ast-memory.md

@@ -1,223 +0,0 @@
-# LibSass smart pointer implementation
-
-LibSass uses smart pointers very similar to `shared_ptr` known
-by Boost or C++11. Implementation is a bit less modular since
-it was not needed. Various compile time debug options are
-available if you need to debug memory life-cycles.
-
-
-## Memory Classes
-
-### SharedObj
-
-Base class for the actual node implementations. This ensures
-that every object has a reference counter and other values.
-
-```c++
-class AST_Node : public SharedObj { ... };
-```
-
-### SharedPtr (base class for SharedImpl)
-
-Base class that holds on to the pointer. The reference counter
-is stored inside the pointer object directly (`SharedObj`).
-
-### SharedImpl (inherits from SharedPtr)
-
-This is the main base class for objects you use in your code. It
-will make sure that the memory it points at will be deleted once
-all copies to the same object/memory go out of scope.
-
-```c++
-Class* pointer = new Class(...);
-SharedImpl<Class> obj(pointer);
-```
-
-To spare the developer of typing the templated class every time,
-we created typedefs for each available AST Node specialization.
-
-```c++
-typedef SharedImpl<Number> Number_Obj;
-Number_Obj number = SASS_MEMORY_NEW(...);
-```
-
-
-## Memory life-cycles
-
-### Pointer pickups
-
-I often use the terminology of "pickup". This means the moment when
-a raw pointer not under any control is assigned to a reference counted
-object (`XYZ_Obj = XYZ_Ptr`). From that point on memory will be
-automatically released once the object goes out of scope (but only
-if the reference counter reaches zero). Main point beeing, you don't
-have to worry about memory management yourself.
-
-### Object detach
-
-Sometimes we can't return reference counted objects directly (see
-invalid covariant return types problems below). But we often still
-need to use reference objects inside a function to avoid leaks when
-something throws. For this you can use `detach`, which basically
-detaches the pointer memory from the reference counted object. So
-when the reference counted object goes out of scope, it will not
-free the attached memory. You are now again in charge of freeing
-the memory (just assign it to a reference counted object again).
-
-
-## Circular references
-
-Reference counted memory implementations are prone to circular references.
-This can be addressed by using a multi generation garbage collector. But
-for our use-case that seems overkill. There is no way so far for users
-(sass code) to create circular references. Therefore we can code around
-this possible issue. But developers should be aware of this limitation.
-
-There are AFAIR two places where circular references could happen. One is
-the `sources` member on every `Selector`. The other one can happen in the
-extend code (Node handling). The easy way to avoid this is to only assign
-complete object clones to these members. If you know the objects lifetime
-is longer than the reference you create, you can also just store the raw
-pointer. Once needed this could be solved with weak pointers.
-
-
-## Addressing the invalid covariant return types problems
-
-If you are not familiar with the mentioned problem, you may want
-to read up on covariant return types and virtual functions, i.e.
-
-- http://stackoverflow.com/questions/6924754/return-type-covariance-with-smart-pointers
-- http://stackoverflow.com/questions/196733/how-can-i-use-covariant-return-types-with-smart-pointers
-- http://stackoverflow.com/questions/2687790/how-to-accomplish-covariant-return-types-when-returning-a-shared-ptr
-
-We hit this issue at least with the CRTP visitor pattern (eval, expand,
-listize and so forth). This means we cannot return reference counted
-objects directly. We are forced to return raw pointers or we would need
-to have a lot of explicit and expensive upcasts by callers/consumers.
-
-### Simple functions that allocate new AST Nodes
-
-In the parser step we often create new objects and can just return a
-unique pointer (meaning ownership clearly shifts back to the caller).
-The caller/consumer is responsible that the memory is freed.
-
-```c++
-typedef Number* Number_Ptr;
-int parse_integer() {
-  ... // do the parsing
-  return 42;
-}
-Number_Ptr parse_number() {
-  Number_Ptr p_nr = SASS_MEMORY_NEW(...);
-  p_nr->value(parse_integer());
-  return p_nr;
-}
-Number_Obj nr = parse_number();
-```
-
-The above would be the encouraged pattern for such simple cases.
-
-### Allocate new AST Nodes in functions that can throw
-
-There is a major caveat with the previous example, considering this
-more real-life implementation that throws an error. The throw may
-happen deep down in another function. Holding raw pointers that
-we need to free would leak in this case.
-
-```c++
-int parse_integer() {
-  ... // do the parsing
-  if (error) throw(error);
-  return 42;
-}
-```
-
-With this `parse_integer` function the previous example would leak memory.
-I guess it is pretty obvious, as the allocated memory will not be freed,
-as it was never assigned to a SharedObj value. Therefore the above code
-would better be written as:
-
-```c++
-typedef Number* Number_Ptr;
-int parse_integer() {
-  ... // do the parsing
-  if (error) throw(error);
-  return 42;
-}
-// this leaks due to pointer return
-// should return Number_Obj instead
-// though not possible for virtuals!
-Number_Ptr parse_number() {
-  Number_Obj nr = SASS_MEMORY_NEW(...);
-  nr->value(parse_integer()); // throws
-  return &nr; // Ptr from Obj
-}
-Number_Obj nr = parse_number();
-// will now be freed automatically
-```
-
-The example above unfortunately will not work as is, since we return a
-`Number_Ptr` from that function. Therefore the object allocated inside
-the function is already gone when it is picked up again by the caller.
-The easy fix for the given simplified use case would be to change the
-return type of `parse_number` to `Number_Obj`. Indeed we do it exactly
-this way in the parser. But as stated above, this will not work for
-virtual functions due to invalid covariant return types!
-
-### Return managed objects from virtual functions
-
-The easy fix would be to just create a new copy on the heap and return
-that. But this seems like a very inelegant solution to this problem. I
-mean why can't we just tell the object to treat it like a newly allocated
-object? And indeed we can. I've added a `detach` method that will tell
-the object to survive deallocation until the next pickup. This means
-that it will leak if it is not picked up by consumer.
-
-```c++
-typedef Number* Number_Ptr;
-int parse_integer() {
-  ... // do the parsing
-  if (error) throw(error);
-  return 42;
-}
-Number_Ptr parse_number() {
-  Number_Obj nr = SASS_MEMORY_NEW(...);
-  nr->value(parse_integer()); // throws
-  return nr.detach();
-}
-Number_Obj nr = parse_number();
-// will now be freed automatically
-```
-
-
-## Compile time debug options
-
-To enable memory debugging you need to define `DEBUG_SHARED_PTR`.
-This can i.e. be done in `include/sass/base.h`
-
-```c++
-define DEBUG_SHARED_PTR
-```
-
-This will print lost memory on exit to stderr. You can also use
-`setDbg(true)` on sepecific variables to emit reference counter
-increase, decrease and other events.
-
-
-## Why reinvent the wheel when there is `shared_ptr` from C++11
-
-First, implementing a smart pointer class is not really that hard. It
-was indeed also a learning experience for myself. But there are more
-profound advantages:
-
-- Better GCC 4.4 compatibility (which most code still has OOTB)
-- Not thread safe (give us some free performance on some compiler)
-- Beeing able to track memory allocations for debugging purposes
-- Adding additional features if needed (as seen in `detach`)
-- Optional: optimized weak pointer implementation possible
-
-### Thread Safety
-
-As said above, this is not thread safe currently. But we don't need
-this ATM anyway. And I guess we probably never will share AST Nodes
-across different threads.

data/ext/libsass/docs/implementations.md

@@ -1,56 +0,0 @@
-There are several implementations of `libsass` for a variety of languages. Here are just a few of them. Note, some implementations may or may not be up to date. We have not verified whether they work.
-
-### C
-* [sassc](https://github.com/hcatlin/sassc)
-
-### Crystal
-* [sass.cr](https://github.com/straight-shoota/sass.cr)
-
-### Elixir
-* [sass.ex](https://github.com/scottdavis/sass.ex)
-
-### Go
-* [go-libsass](https://github.com/wellington/go-libsass)
-* [go_sass](https://github.com/suapapa/go_sass)
-* [go-sass](https://github.com/SamWhited/go-sass)
-
-### Lua
-* [lua-sass](https://github.com/craigbarnes/lua-sass)
-
-### .NET
-* [libsass-net](https://github.com/darrenkopp/libsass-net)
-* [NSass](https://github.com/TBAPI-0KA/NSass)
-* [Sass.Net](https://github.com/andyalm/Sass.Net)
-
-### node.js
-* [node-sass](https://github.com/andrew/node-sass)
-
-### Java
-* [libsass-maven-plugin](https://github.com/warmuuh/libsass-maven-plugin)
-* [jsass](https://github.com/bit3/jsass)
-
-### JavaScript
-* [sass.js](https://github.com/medialize/sass.js)
-
-### Perl
-* [CSS::Sass](https://github.com/caldwell/CSS-Sass)
-* [Text::Sass::XS](https://github.com/ysasaki/Text-Sass-XS)
-
-### PHP
-* [sassphp](https://github.com/sensational/sassphp)
-* [php-sass](https://github.com/lesstif/php-sass)
-
-### Python
-* [libsass-python](https://github.com/dahlia/libsass-python)
-* [SassPython](https://github.com/marianoguerra/SassPython)
-* [pylibsass](https://github.com/rsenk330/pylibsass)
-* [python-scss](https://github.com/pistolero/python-scss)
-
-### Ruby
-* [sassruby](https://github.com/hcatlin/sassruby)
-
-### Scala
-* [Sass-Scala](https://github.com/kkung/Sass-Scala)
-
-### Tcl
-* [tclsass](https://github.com/flightaware/tclsass)

data/ext/libsass/docs/plugins.md

@@ -1,47 +0,0 @@
-Plugins are shared object files (.so on *nix and .dll on win) that can be loaded by LibSass on runtime. Currently we only provide a way to load internal/custom functions from plugins. In the future we probably will also add a way to provide custom importers via plugins (needs more refactoring to [support multiple importers with some kind of priority system](https://github.com/sass/libsass/issues/962)).
-
-## plugin.cpp
-
-```C++
-#include <cstring>
-#include <iostream>
-#include <stdint.h>
-#include "sass_values.h"
-
-union Sass_Value* ADDCALL call_fn_foo(const union Sass_Value* s_args, void* cookie)
-{
-  // we actually abuse the void* to store an "int"
-  return sass_make_number((intptr_t)cookie, "px");
-}
-
-extern "C" const char* ADDCALL libsass_get_version() {
-  return libsass_version();
-}
-
-extern "C" Sass_C_Function_List ADDCALL libsass_load_functions()
-{
-  // allocate a custom function caller
-  Sass_C_Function_Callback fn_foo =
-    sass_make_function("foo()", call_fn_foo, (void*)42);
-  // create list of all custom functions
-  Sass_C_Function_List fn_list = sass_make_function_list(1);
-  // put the only function in this plugin to the list
-  sass_function_set_list_entry(fn_list, 0, fn_foo);
-  // return the list
-  return fn_list;
-}
-```
-
-To compile the plugin you need to have LibSass already built as a shared library (to link against it). The commands below expect the shared library in the `lib` sub-directory (`-Llib`). The plugin and the main LibSass process should "consume" the same shared LibSass library on runtime. It will propably also work if they use different LibSass versions. In this case we check if the major versions are compatible (i.e. 3.1.3 and 3.1.1 would be considered compatible).
-
-## Compile with gcc on linux
-
-```bash
-g++ -O2 -shared plugin.cpp -o plugin.so -fPIC -Llib -lsass
-```
-
-## Compile with mingw on windows
-
-```bash
-g++ -O2 -shared plugin.cpp -o plugin.dll -Llib -lsass
-```

data/ext/libsass/docs/setup-environment.md

@@ -1,68 +0,0 @@
-## Requirements
-In order to install and setup your local development environment, there are some prerequisites:
-
-* git
-* gcc/clang/llvm (Linux: build tools, Mac OS X: XCode w/ Command Line Tools)
-* ruby w/ bundler
-
-OS X:
-First you'll need to install XCode which you can now get from the AppStore installed on your mac. After you download that and run it, then run this on the command line:
-
-````
-xcode-select --install
-````
-
-## Cloning the Projects
-
-First, clone the project and then add a line to your `~/.bash_profile` that will let other programs know where the LibSass dev files are.
-
-````
-git clone git@github.com:sass/libsass.git
-cd libsass
-echo "export SASS_LIBSASS_PATH=$(pwd)" >> ~/.bash_profile
-
-````
-
-Then, if you run the "bootstrap" script, it should clone all the other required projects.
-
-````
-./script/bootstrap
-````
-
-You should now have a `sass-spec` and `sassc` folder within the libsass folder. Both of these are clones of their respective git projects. If you want to do a pull request, remember to work in those folders. For instance, if you want to add a test (see other documentation for how to do that), make sure to commit it to your *fork* of the sass-spec github project. Also, whenever you are running tests, make sure to `pull` from the origin! We want to make sure we are testing against the newest libsass, sassc, and sass-spec!
-
-Now, try and see if you can build the project. We do that with the `make` command.
-
-````
-make
-````
-
-At this point, if you get an error, something is most likely wrong with your compiler installation. Yikes. It's hard to cover how to fix this in an article. Feel free to open an issue and we'll try and help! But, remember, before you do that, googling the error message is your friend! Many problems are solved quickly that way.
-
-## Running The Spec Against LibSass
-
-Then, to run the spec against LibSass, just run:
-
-````
-./script/spec
-````
-
-If you get an error about `SASS_LIBSASS_PATH`, you may still need to set a variable pointing to the libsass folder, like this:
-
-````
-export SASS_LIBSASS_PATH=/Users/you/path/libsass
-````
-
-...where the latter part is to the `libsass` directory you've cloned. You can get this path by typing `pwd` in the Terminal
-
-## Running the Spec Against Ruby Sass
-
-Go into the sass-spec folder that should have been cloned earlier with the "bootstrap" command. Run the following.
-
-````
-bundle install
-./sass-spec.rb
-````
-
-Voila! Now you are testing against Sass too!
-

data/ext/libsass/docs/source-map-internals.md

@@ -1,51 +0,0 @@
-This document is mainly intended for developers!
-
-# Documenting some of the source map internals
-
-Since source maps are somewhat a black box to all LibSass maintainers, [I](@mgreter) will try to document my findings with source maps in LibSass, as I come across them. This document will also brievely explain how LibSass parses the source and how it outputs the result.
-
-The main storage for SourceMap mappings is the `mappings` vector:
-
-```
-# in source_map.hpp
-vector<Mapping> mappings
-# in mappings.hpp
-struct Mapping ...
-  Position original_position;
-  Position generated_position;
-```
-
-## Every parsed token has its source associated
-
-LibSass uses a lexical parser. Whenever LibSass finds a token of interest, it creates a specific `AST_Node`, which will hold a reference to the input source with line/column information. `AST_Node` is the base class for all parsed items. They are declared in `ast.hpp` and are used in `parser.hpp`. Here a simple example:
-
-```
-if (lex< custom_property_name >()) {
-  Sass::String* prop = new (ctx.mem) String_Constant(path, source_position, lexed);
-  return new (ctx.mem) Declaration(path, prop->position(), prop, ...);
-}
-```
-
-## How is the `source_position` calculated
-
-This is automatically done with `lex` in `parser.hpp`. Whenever something is lexed, the `source_position` is updated. But be aware that `source_position` points to the begining of the parsed text. If you need a mapping for the position where the parsing ended, you need to add another call to `lex` (to match nothing)!
-
-```
-lex< exactly < empty_str > >();
-end = new (ctx.mem) String_Constant(path, source_position, lexed);
-```
-
-## How are mappings for the output created
-
-So far we have collected all needed data for all tokens in the input stream. We can now use this information to create mappings when we put things into the output stream. Mappings are created via the `add_mappings` method:
-
-```
-# in source_map.hpp
-void add_mapping(AST_Node* node);
-```
-
-This method is called in two places:
-- `Inspect::append_to_buffer`
-- `Output_[Nested|Compressed]::append_to_buffer`
-
-Mappings can only be created for things that have been parsed into a `AST_Node`. Otherwise we do not have the information to create the mappings, which is the reason why LibSass currently only maps the most important tokens in source maps.