sassc 1.8.0.pre2 → 1.8.0

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

@@ -0,0 +1,48 @@
+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

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,120 @@
+# 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* make_sass_boolean (int val);
+union Sass_Value* make_sass_number  (double val, const char* unit);
+union Sass_Value* make_sass_color   (double r, double g, double b, double a);
+union Sass_Value* make_sass_string  (const char* val);
+union Sass_Value* make_sass_list    (size_t len, enum Sass_Separator sep);
+union Sass_Value* make_sass_map     (size_t len);
+union Sass_Value* make_sass_null    ();
+union Sass_Value* make_sass_error   (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/implementations.md

@@ -0,0 +1,49 @@
+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)
+
+### 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)
+
+### 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.go

@@ -0,0 +1,47 @@
+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

@@ -0,0 +1,68 @@
+## 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

@@ -0,0 +1,51 @@
+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.

data/ext/libsass/docs/trace.md

@@ -0,0 +1,26 @@
+## This is proposed interface in https://github.com/sass/libsass/pull/1288
+
+Additional debugging macros with low overhead are available, `TRACE()` and `TRACEINST()`.
+
+Both macros simulate a string stream, so they can be used like this:
+
+    TRACE() << "Reached.";
+
+produces:
+
+    [LibSass] parse_value parser.cpp:1384 Reached.
+
+`TRACE()`
+   logs function name, source filename, source file name to the standard error and the attached
+   stream to the standard error.
+
+`TRACEINST(obj)`
+   logs object instance address, function name, source filename, source file name to the standard error and the attached stream to the standard error, for example:
+
+    TRACEINST(this) << "String_Constant created " << this;
+
+produces:
+
+    [LibSass] 0x8031ba980:String_Constant ./ast.hpp:1371 String_Constant created (0,"auto")
+
+The macros generate output only of `LibSass_TRACE` is set in the environment.

data/ext/libsass/docs/triage.md

@@ -0,0 +1,17 @@
+This is an article about how to help with LibSass issues. Issue triage is a fancy word for explaining how we deal with incoming issues and make sure that the right problems get worked on. The lifecycle of an issue goes like this:
+
+1. Issue is reported by a user.
+2. If the issue seems like a bug, then the "bug" tag is added.
+3. If the reporting user didn't also create a spec test over at sass/sass-spec, the "needs test" tag is added.
+4. Verify that Ruby Sass *does not* have the same bug. LibSass strives to be an exact replica of how Ruby Sass works. If it's an issue that neither project has solved, please close the ticket with the "not in sass" label.
+5. The smallest possible breaking test is created in sass-spec. Cut away any extra information or non-breaking code until the core issue is made clear.
+6. Again, verify that the expected output matches the latest Ruby Sass release. Do this by using your own tool OR by running ./sass-spec.rb in the spec folder and making sure that your test passes!
+7. Create the test cases in sass-spec with the name spec/LibSass-todo-issues/issue_XXX/input.scss and expected_output.css where the XXX is the issue number here.
+8. Commit that test to sass-spec, making sure to reference the issue in the comment message like "Test to demonstrate sass/LibSass#XXX".
+9. Once the spec test exists, remove the "needs test" tag and replace it with "test written".
+10. A C++ developer will then work on the issue and issue a pull request to fix the issue.
+11. A core member verifies that the fix does actually fix the spec tests.
+12. The fix is merged into the project.
+13. The spec is moved from the LibSass-todo-issues folder into LibSass-closed-issues
+14. The issue is closed
+15. Have a soda pop or enjoyable beverage of your choice