sass/libsass — pull request #591 by mgreter (2014-10-29 19:51:38+00:00)
Title: [WIP] Implements embedding source contents in source maps

Implementation fallows [source map spec (v3)] [1].

This is based on PR https://github.com/sass/libsass/pull/443 by @aexmachina

- Inclusion of source contents in source maps.
- Embeding sourceMappingUrl as data uri (Base64)
- Complete source map output generating with json library.

Also streamlined status information for included sources. Added helper function `add_source` to build the storage for the status information, collecting this data:

- `queue`: _Internal_ queue of items to process
- `included_files`: Absolute path to the included file
- `include_links`: Relative path (to `source_map_file`)
- `sources`: The content of the include (is _freed_ on `Context` destruction)
- `source_map.source_index`: Index to access the status info on the `Context`

IMO we could also store the content on each `source_map`, since it will anyway be just a pointer to the data stored in `sources` (that's how the original code by @aexmachina worked). But it was also handy to have direct access to all options and status information. I pass `ctx` to `source_map.generate_source_map` and it will use the index to access the information. I also made the status vectors private, so nobody beside the helper function can mess with it (therefore it should ensure that all of them have always the same size).

I also store the initial include on to these vectors, as it may provide usefull information if needed, and one can simply skip the first entry if only the "real" includes are interesting.

This probably need some discussion, as it adds two new options:

```
+ // embed include contents in maps
+ bool source_map_contents;
+ // embed sourceMappingUrl as data uri
+ bool source_map_embed;
```

The first option enables to inclusion of source contents inside the source map.
The second is used to embed the source map inside the sourceMappingUrl (via data-uri).

Maybe someone has a better idea how to name them. I've choosen `source_map_contents` because the sources will be added to a property named `sourcesContent` (was `source_map_sources` in org. PR).

For `source_map_embed` I had to add a [Base64 encoding library] [2].
@hcatlin: I couldn't find a good library with explicit MIT license, but IMO it should be ok to use:

```
Dedicator recognizes that, once placed in the public domain, the Work may
be freely reproduced, distributed, transmitted, used, modified, built upon, or
otherwise exploited by anyone for any purpose, commercial or non-commercial,
and in any way, including by methods that have not yet been invented or conceived.
```

// CC @xzyfer, @am11: do you think this is already good to go?

[1]: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit?hl=en_US&pli=1&pli=1#heading=h.lmz475t4mvbx
[2]: http://sourceforge.net/projects/libb64