sassc 2.0.0 → 2.4.0

data/ext/libsass/docs/build.md

@@ -1,97 +0,0 @@
-`libsass` is only a library and does not do much on its own. You need an implementation that you can use from the [command line][6]. Or some [bindings|Implementations][9] to use it within your favorite programming language. You should be able to get [`sassc`][6] running by following the instructions in this guide.
-
-Before starting, see [setup dev environment](setup-environment.md).
-
-Building on different Operating Systems
---
-
-We try to keep the code as OS independent and standard compliant as possible. Reading files from the file-system has some OS depending code, but will ultimately fall back to a posix compatible implementation. We do use some `C++11` features, but are so far only committed to use `unordered_map`. This means you will need a pretty recent compiler on most systems (gcc 4.5 seems to be the minimum).
-
-### Building on Linux (and other *nix flavors)
-
-Linux is the main target for `libsass` and we support two ways to build `libsass` here. The old plain makefiles should still work on most systems (including MinGW), while the autotools build is preferred if you want to create a [system library] (experimental).
-
-- [Building with makefiles][1]
-- [Building with autotools][2]
-
-### Building on Windows (experimental)
-
-Windows build support was added very recently and should be considered experimental. Credits go to @darrenkopp and @am11 for their work on getting `libsass` and `sassc` to compile with visual studio!
-
-- [Building with MinGW][3]
-- [Building with Visual Studio][11]
-
-### Building on Max OS X (untested)
-
-Works the same as on linux, but you can also install LibSass via `homebrew`.
-
-- [Building on Mac OS X][10]
-
-### Building a system library (experimental)
-
-Since `libsass` is a library, it makes sense to install it as a shared library on your system. On linux this means creating a `.so` library via autotools. This should work pretty well already, but we are not yet committed to keep the ABI 100% stable. This should be the case once we increase the version number for the library to 1.0.0 or higher. On Windows you should be able get a `dll` by creating a shared build with MinGW. There is currently no target in the MSVC project files to do this.
-
-- [Building shared system library][4]
-
-Compiling with clang instead of gcc
---
-
-To use clang you just need to set the appropriate environment variables:
-
-```bash
-export CC=/usr/bin/clang
-export CXX=/usr/bin/clang++
-```
-
-Running the spec test-suite
---
-
-We constantly and automatically test `libsass` against the official [spec test-suite][5]. To do this we need to have a test-runner (which is written in ruby) and a command-line tool ([`sassc`][6]) to run the tests. Therefore we need to additionally compile `sassc`. To do this, the build files of all three projects need to work together. This may not have the same quality for all build flavors. You definitely need to have ruby (2.1?) installed (version 1.9 seems to cause problems at least on windows). You also need some gems installed:
-
-```bash
-ruby -v
-gem install minitest
-# should be optional
-gem install minitap
-```
-
-Including the LibSass version
---
-
-There is a function in `libsass` to query the current version. This has to be defined at compile time. We use a C macro for this, which can be defined by calling `g++ -DLIBSASS_VERSION="\"x.y.z.\""`. The two quotes are necessary, since it needs to end up as a valid C string. Normally you do not need to do anything if you use the makefiles or autotools. They will try to fetch the version via git directly. If you only have the sources without the git repo, you can pass the version as an environment variable to `make` or `configure`:
-
-```
-export LIBSASS_VERSION="x.y.z."
-```
-
-Continuous Integration
---
-
-We use two CI services to automatically test all commits against the latest [spec test-suite][5].
-
-- [LibSass on Travis-CI (linux)][7]
-[![Build Status](https://travis-ci.org/sass/libsass.png?branch=master)](https://travis-ci.org/sass/libsass)
-- [LibSass on AppVeyor (windows)][8]
-[![Build status](https://ci.appveyor.com/api/projects/status/github/sass/libsass?svg=true)](https://ci.appveyor.com/project/mgreter/libsass-513/branch/master)
-
-Why not using CMake?
---
-
-There were some efforts to get `libsass` to compile with CMake, which should make it easier to create build files for linux and windows. Unfortunately this was not completed. But we are certainly open for PRs!
-
-Miscellaneous
---
-
-- [Ebuilds for Gentoo Linux](build-on-gentoo.md)
-
-[1]: build-with-makefiles.md
-[2]: build-with-autotools.md
-[3]: build-with-mingw.md
-[4]: build-shared-library.md
-[5]: https://github.com/sass/sass-spec
-[6]: https://github.com/sass/sassc
-[7]: https://github.com/sass/libsass/blob/master/.travis.yml
-[8]: https://github.com/sass/libsass/blob/master/appveyor.yml
-[9]: implementations.md
-[10]: build-on-darwin.md
-[11]: build-with-visual-studio.md

data/ext/libsass/docs/compatibility-plan.md

@@ -1,48 +0,0 @@
-This document is to serve as a living, changing plan for getting LibSass caught up with Ruby Sass.
-
-_Note: an "s" preceeding a version number is specifying a Ruby Sass version. Without an s, it's a version of LibSass._
-
-# Goal
-**Our goal is to reach full s3.4 compatibility as soon as possible. LibSass version 3.4 will behave just like Ruby Sass 3.4**
-
-I highlight the goal, because there are some things that are *not* currently priorities. To be clear, they WILL be priorities, but they are not at the moment:
-
-* Performance Improvements
-* Extensibility
-
-The overriding goal is correctness.
-
-## Verifying Correctness
-LibSass uses the spec for its testing. The spec was originally based off s3.2 tests. Many things have changed in Ruby Sass since then and some of the tests need to be updated and changed in order to get them to match both LibSass and Ruby Sass.
-
-Until this project is complete, the spec will be primarily a place to test LibSass. By the time LibSass reaches 3.4, it is our goal that sass-spec will be fully usable as an official testing source for ALL implementations of Sass.
-
-## Version Naming
-Until LibSass reaches parity with Ruby Sass, we will be aggressively bumping versions, and LibSass 3.4 will be the peer to Ruby Sass 3.4 in every way.
-
-# Release Plan
-
-## 3.0
-The goal of 3.0 is to introduce some of the most demanded features for LibSass. That is, we are focusing on issues and features that have kept adoption down. This is a mongrel release wrt which version of Sass it's targeting. It's often a mixture of 3.2 / 3.3 / 3.4 behaviours. This is not ideal, but it's favourable to not existing. Targeting 3.4 strictly during this release would mean we never actually release.
-
-# 3.1
-The goal of 3.1 is to update all the passing specs to agree with 3.4. This will not be a complete representation of s3.4 (aka, there will me missing features), but the goal is to change existing features and implemented features to match 3.4 behaviour.
-
-By the end of this, the sass-spec must pass against 3.4.
-
-Major issues:
-* Variable Scoping
-* Color Handling
-* Precision
-
-# 3.2
-This version will focus on edge case fixes. There are a LOT of edge cases in the _todo_ tests and this is the release where we hunt those down like dogs (not that we want to hurt dogs, it's just a figure of speech in English).
-
-# 3.3
-Dress rehearsal. When we are 99% sure that we've fixed the main issues keeping us from saying we are compliant in s3.4 behaviour.
-
-# 3.4
-Compass Compatibility. We need to be able to work with Compass and all the other libraries out there. At this point, we are calling LibSass "mature"
-
-# Beyond 3.4
-Obviously, there is matching Sass 3.5 behaviour. But, beyond that, we'll want to focus on performance, stability, and error handling. These can always be improved upon and are the life's work of an open source project. We'll have to work closely with Sass in the future.

data/ext/libsass/docs/contributing.md

@@ -1,17 +0,0 @@
-First of all, welcome! Thanks for even reading this page. If you're here, you're probably wondering what you can do to help make the LibSass project even more awesome. And, even having that feeling means you are awesome!
-
-## I'm a programmer
-
-Awesome! We need your help. The best thing to do is go find issues that are tagged with both "bug" and "test written". We do spec driven development here and these issues have a test that's written already in the sass-spec project. Go find the test by going to sass-spec/spec/LibSass-todo-issues/issue_XXX/ where XXX is the issue number. Write the code, and compile, and then issue a pull request referencing the issue. We'll quickly verify it and get it merged in!
-
-To get your dev environment setup, check out our article on [Setup-Dev-Environment](setup-environment.md).
-
-## I'm not a backend programmer
-
-COOL! We also need your help. Doing [Issue-Triage](triage.md) is a big deal and something we need constant help with. That means helping to verify issues, write tests for them, and make sure they are getting fixed. It's being part of the smiling face of the project.
-
-Also, we need help with the Sass-Spec project itself. Just people to organize, refactor, and understand the tests in there.
-
-## I don't know what a computer is?
-
-Hmm.... well, it's the thing you are looking at right now. Ummm... check out training courses! Then, come back and join us!

data/ext/libsass/docs/custom-functions-internal.md

@@ -1,122 +0,0 @@
-# Developer Documentation
-
-Custom functions are internally represented by `struct Sass_C_Function_Descriptor`.
-
-## Sass_C_Function_Descriptor
-
-```C
-struct Sass_C_Function_Descriptor {
-  const char*      signature;
-  Sass_C_Function  function;
-  void*            cookie;
-};
-```
-
-- `signature`: The function declaration, like `foo($bar, $baz:1)`
-- `function`:  Reference to the C function callback
-- `cookie`:    any pointer you want to attach
-
-### signature
-
-The signature defines how the function can be invoked. It also declares which arguments are required and which are optional.  Required arguments will be enforced by LibSass and a Sass error is thrown in the event a call as missing an argument. Optional arguments only need to be present when you want to overwrite the default value.
-
-    foo($bar, $baz: 2)
-
-In this example, `$bar` is required and will error if not passed. `$baz` is optional and the default value of it is 2. A call like `foo(10)` is therefore equal to `foo(10, 2)`, while `foo()` will produce an error.
-
-### function
-
-The callback function needs to be of the following form:
-
-```C
-union Sass_Value* call_sass_function(
-    const union Sass_Value* s_args,
-    void*                   cookie
-) {
-  return sass_clone_value(s_args);
-}
-```
-
-### cookie
-
-The cookie can hold any pointer you want. In the `perl-libsass` implementation it holds the structure with the reference of the actual registered callback into the perl interpreter. Before that call `perl-libsass` will convert all `Sass_Values` to corresponding perl data types (so they can be used natively inside the perl interpretor). The callback can also return a `Sass_Value`. In `perl-libsass` the actual function returns a perl value, which has to be converted before `libsass` can work with it again!
-
-## Sass_Values
-
-```C
-// allocate memory (copies passed strings)
-union Sass_Value* sass_make_null    (void);
-union Sass_Value* sass_make_boolean (bool val);
-union Sass_Value* sass_make_string  (const char* val);
-union Sass_Value* sass_make_qstring (const char* val);
-union Sass_Value* sass_make_number  (double val, const char* unit);
-union Sass_Value* sass_make_color   (double r, double g, double b, double a);
-union Sass_Value* sass_make_list    (size_t len, enum Sass_Separator sep, bool is_bracketed);
-union Sass_Value* sass_make_map     (size_t len);
-union Sass_Value* sass_make_error   (const char* msg);
-union Sass_Value* sass_make_warning (const char* msg);
-
-// Make a deep cloned copy of the given sass value
-union Sass_Value* sass_clone_value (const union Sass_Value* val);
-
-// deallocate memory (incl. all copied memory)
-void sass_delete_value (const union Sass_Value* val);
-```
-
-## Example main.c
-
-```C
-#include <stdio.h>
-#include <stdint.h>
-#include "sass/context.h"
-
-union Sass_Value* call_fn_foo(const union Sass_Value* s_args, void* cookie)
-{
-  // we actually abuse the void* to store an "int"
-  return sass_make_number((size_t)cookie, "px");
-}
-
-int main( int argc, const char* argv[] )
-{
-
-  // get the input file from first argument or use default
-  const char* input = argc > 1 ? argv[1] : "styles.scss";
-
-  // create the file context and get all related structs
-  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
-  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
-  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
-
-  // 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);
-  sass_function_set_list_entry(fn_list, 0, fn_foo);
-  sass_option_set_c_functions(ctx_opt, fn_list);
-
-  // context is set up, call the compile step now
-  int status = sass_compile_file_context(file_ctx);
-
-  // print the result or the error to the stdout
-  if (status == 0) puts(sass_context_get_output_string(ctx));
-  else puts(sass_context_get_error_message(ctx));
-
-  // release allocated memory
-  sass_delete_file_context(file_ctx);
-
-  // exit status
-  return status;
-
-}
-```
-
-## Compile main.c
-
-```bash
-gcc -c main.c -o main.o
-gcc -o sample main.o -lsass
-echo "foo { margin: foo(); }" > foo.scss
-./sample foo.scss => "foo { margin: 42px }"
-```

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.