Implement custom readers

[callumlocke]

(Closing #862 in favour of this one, on advice of @mgreter.)

A 'custom reader' is like a custom importer, but it's job is simply to retrieve a file at a specific path.

So when libsass hits a line like @import 'foo', libsass will use its regular logic to resolve this to a list of potential file paths (/some/load/path/foo.scss, /some/load/path/_foo.scss ...), and then it will invoke the custom reader multiple times (for each of the potential paths in turn, stopping when the custom reader returns some SCSS).

(This is different from a custom importer, which gets invoked only once per @import, and it is given just the raw import name (eg 'foo') and expected to figure out possible disk locations by itself.)

The benefit is for people who just want to intercept filesystem calls (e.g. to preprocess data) without having to duplicate libsass's built in 'load paths' logic.

[callumlocke]

Note: I only use node-sass and don't know anything about how it talks to libsass, so I don't know if this feature would have a significant overhead (calling a custom callback multiple times per import)... if it's not feasible perf-wise then close this :)

[drewwells]

What's the purpose of a custom reader? It understands additional import paths, it translates one syntax to another syntax ie. .sass to .scss?

[callumlocke]

The purpose is for preprocessing, or just for performance (reading files from your own in-memory cache). Either way, it's just a way to prevent Sass accessing the disk directly.

This is already (mostly) possible with custom importers, but those aren't great if you just want to use libsass's default logic for resolving an @import statement to a list of potential file paths (i.e. relative to all the configured load paths, and including different variants like _-prefixing and different extensions etc, in a particular order of precedence...) – you have to replicate all this logic yourself.

[drewwells]

From Wellington, I do the grunt work of reading in files concat together then pass the big string of files to the libsass data compiler. It's done this way as you mentioned to achieve better caching, and to support multiple input streams (stdin, file, HTTP). In the process of this, libsass has no context for what filename/line number is being processed, so those have to be resolved in the implementation. Custom reader would be a HUGE improvement.

Bear with me, as this comment is getting long. If implementors could build up a config object for the data compiler, it would add considerable flexibility to the reader.

Today to do custom reading:

1. generate big string
2. set string to data compiler config
3. execute data compiler
4. Process sass maps, line numbers, and error line numbers manually

Custom Reader:

1. Create data compiler with array of inputs (structs)
2. implementation reads string from file, process
3. Create input object, add definition (filename), position (line number), content (scss)
4. Append input object to array of inputs
5. Repeat 3-4 for each input stream
6. Execute data compiler

Or is this already possible with custom importers?

[strarsis]

Can such a custom reader re-use the libsass parser, too, when reading the file in question?
Using an extra instance of libass just to get the AST for the imports would double the parse time.
Caching/invalidation tools like gulp-progeny use regexps to extract the used import paths.
A full libsass parser, preferably the same one as used for processing the sass anyway,
would be able to handle all possible cases including syntax error messages.

With best regards

[mgreter]

I created a collective ticket to keep track this and other "non-urgent" feature requests, in order to keep the issue tracker a bit more clean for the more 1st aid issues. I would like to encourage everybody interested in this particular feature to add their comments into this closed issue anyway.

Thanks for your understanding and your contribution!