jescalan/accord

(unmaintained) a unified interface for compiled languages and templates in javascript

accord's Issues

Multi Stage Sourcemap Support

In addition to simply accepting input text, each adapter should also accept an object containing input text and a sourcemap, and if the adapter produces a sourcemap of its own, merge it with the incoming sourcemap. Not a super complicated change, nor is it breaking, just want to have it noted here as this will be an important feature down the line.

Add coffee-react engine

https://github.com/jsdf/coffee-react

clientHelpers should return a promise

right now it is the only method that returns a string & for that we need to do sync fs calls (which is lame)

sadly, this would be a breaking change

maintenance?

If maintenance is the only reason why we are making a new lib, then why not just maintain our fork of transformers? It's not like we actually need to wait for ForbesLindesay to accept PRs - I gave up on that months ago and now we just reference our fork directly.

Plus, because it is a fork of an existing library, most changes to transformers can be pulled into our fork, meaning we don't need to duplicate whatever effort goes on in the transformers repo.

Also, by building on what we have, we don't need to modify roots to use a new library (unless we decide to change the interface).

standard way to pass data context to engines

first, thanks for accord! i like the clean separation of adapters via base class and implementations.

if i am understanding correctly, the whole point is to have a unified interface to the various transform engines. in that spirit, the manner in which we currently pass local data/context to the engines is not unified and thus means that switching engines is not as simple as switching the string passed to accord.load. for example, passing data to swig according to the docs is done like so:

var accord = require("accord")
var templater = accord.load("swig")

templater.render("<h1>{{ title }}</h1>", { locals: { title: "Hello" } });

while making the same call to handlebars requires the following (note the data is passed as the options parameter rather than the locals property of the options object as above):

var accord = require("accord")
var templater = accord.load("handlebars")

templater.render("<h1>{{ title }}</h1>", { title: "Hello" });

as you can see the subtle difference causes the accord "interface" to be different depending on which engine is used. and i imagine that for other engines similar differences exist. and while i understand it would be difficult/tedious to abstract every difference between engines, passing context data to an engine IMHO seems common enough that perhaps it should be addressed.

am i following accord's usage/philosophy correctly? and if so, is there any interest in providing a unified way to pass data to engines via accord? an idea: perhaps by providing a data parameter on the accord interface methods, or a property on the ubiquitous options parameter. then each adapter could move the data into the correct spot for consumption by the actual engine, making the interface for providing data to engines unified across accord's supported engines.

thanks again.

Stylus Sourcemaps

This should be integrated into the stylus API: http://learnboost.github.io/stylus/docs/sourcemaps.html

standardize interface for reporting dependencies of each file

This will be useful in the future for telling what files affect the output of a given file. Jade already has some basic reporting for this that we could make available through an interface like this.

Add 6to5 adapter

This is a pretty nice tool, I know there are a number of others like it (traceur being the most popular if I'm not mistaken), but this one has a really nice clean and well documented node API, and solid sourcemap support, so it's a great candidate to be added.

https://6to5.org/docs/usage/api/

stylus relative path bug

opening for this person to make sure it doesnt get lost

gulp-community/gulp-less#164

they have a fix in this PR but it was outside of accord.

renderFile for scss adapter not resolving promise

I'm running node-sass 2.0.1

When I used accord 0.15.2 .scss-files were compiled without a problem. With 0.16.0 my process hangs, seemingly with an unresolved promise.

I think I'll have time to dive into this later today and make a PR. Consider this a placeholder for now

markdown compiler generates duplicate ID's

any markdown headline will take the contents of the headline tag and stringify it into an ID.

So duplicate IDs are quite simple to stumble across.
Not sure what the solution is but just pointing this out.

Using Sass with Roots results in "TypeError: Object.keys called on non-object"

This is due to using 0.14.x with the main Roots runtime; updating it to 0.15.x allows Sass to be used.

throw an error when incorrect options are passed to an adapter

Right now, you can pass pretty much anything you want in the options object. We should be more strict about that and throw an error, because if the options are wrong, there's probably something wrong in the code that's calling accord.

To start, we can just restrict the options being passed to compilers that have a very limited number of options (like CoffeeScript, LiveScript, DogeScript, Coco, and Myth). But eventually I want to expand this to cover most/all of the compilers

Dealing with sourcesContent for source maps

Ok so I have a problem with source maps. The problem is that, in order for a source map to work, it needs to have access to the source through the public server. This means you can do one of two things:

1. Serve the entire source of your project along the compiled files, just so that they can be accessed by source maps
2. Embed the sources into the source maps themselves

I can't understand a situation where the first option would be reasonable, so I'm inclined to say that the second is probably the preferred option. This is kind of a pain and will produce massive files, but at least you don't need to serve the compiled project and the source, because that doesn't even make any sense.

The source maps contain a list of sources anyway, and can have an optional property called sourcesContent, in which you can insert the content of your sources so that you don't have to host everything. My question here is whether accord should deal with sourcesContent or leave this up to whoever is implementing accord. In order to populate this field, you just have to read file on all the sources and fill them in, so it's nothing wildly complex.

standardize error messages

All the compilers give different sorts of error messages. Most of them are awful. Accord should standardize its own set of exceptions and exception-related properties to make this suck less.

To start, the SyntaxError would be an important one, and should have properties like:

• error message (what went wrong)
• line number
• column number
• file path (if it's from a file, rather than stdin)

...and it would be nice if the toString() method printed out the context of the error (like the surrounding lines)

Normalizing error output

This might be a rather big ask, but one of the things I've thought of as I've started to use accord is that, as far as I know, a returned error is not normalized. So things like the file where an error occurred, and row and column number of the error (and message), those would all be arbitrary to the library, would they not be?

If so, I think that means that I'd still have to write a custom error adapter for each engine. Any chance that could be normalized?

support for caching

Some compilers (like HAML) already do this, but it would be nice to have a universal caching mechanism. Thoughts?

Add sourcemap support for minify-css

Clean css supports it, but we don't have support for that interface yet. Should be simple to add!

Add react-tools engine

https://www.npmjs.com/package/react-tools

Add accord.supports function

To run a quick test of whether accord supports a certain compiler without having to load boatloads of stuff.

support multiple engines per compiler

like there are a ton of markdown engines, so it would be nice if we could fallback to a different one if marked isn't avaliable

.editorconfig

you may want one

Add React jsx --> js support

https://www.npmjs.org/package/react-tools

accord.load customPath, what does it do?

I don't get what the custom path in the load function is supposed to do.

The only reference I can find of usage is in this test: https://github.com/jenius/accord/blob/master/test/test.coffee#L27

But that test is completely broken. The engine of the returned adapter is the node path module. I am pretty sure that is not what was intended

Add react-jade engine

https://github.com/jadejs/react-jade

LESS throws error outside of promise

If there's an error with a reference in LESS that doesn't exist, the error will be thrown outside of the promise, so .done() can't deal with it... It's probably because tree.toCSS() isn't wrapped in a try/catch

Add compiler settings

Each compiler should also contain a list of file extensions that it compiles and its output format, for configuration purposes.

Style Language Request - SASS

SASS is one of the most used style languages already.
To support it would be really great, since many good libraries are using it.

Breaking Changes To Be Made

So I'm thinking about some significant breaking changes that I'd like to have made before we hit 1.0, just going to list a few out here. If anyone else has contributions or ideas they are more than welcome!

• Change scss adapter name to sass, since this is the name of the language as a whole, and since it now supports the sass syntax as of the most recent version.
• Remove minify-html, minify-css, and minify-js adapters and make adapters for each individual compiler (html-minifier, clean-css, and uglify-js, respectively). Potentially keep the minify-*s, but only as aliases to a preferred minifier. This will allow for the additon of more minfiers, as there are a few
• Also remove the markdown adapter and change this to marked instead. There are a number of other markdown compilers, and we should not be forcing anyone's hand.
• Full code audit, removing any extra functions or properties that have been introduced by PRs that are either linked to external libraries which are no longer maintained, or cannot be explained fully by the contributor (example: #89)
• Convert to ES6

Less doesn't return an object for sourcemap

According to the docs:

Accord returns all source maps as javascript objects

However, for Less I believe the sourcemap is a string, meaning to normalize the adapter, Accord should probably return JSON.parse(sourcemap) for Less.

allow accord.supports(dep) to account for compiler-specific overrides

so that it can accept 'marked' for 'markdown' (and so forth)

add debug mode

to optionally collect stats on compilation time for each file

Output sourcemaps in consistent format

So right now, every compiler returns the sourcemap however it pleases. While this is true to how the compilers work and less intrusive on accord's part, I'm of the opinion that this is not actually a benefit. My theory is that anyone using accord is probably compiling from a number of different languages, which is why they are using accord, for consistency between them. But if the sourcemaps are all returned in random formats, this makes everything less consistent.

So perhaps we could use this library to parse out the resulting sourcemaps and ensure that they are all returned as JSON with consistent formatting, to make things more consistent across the board.

Match extensions to compilers?

Say I have a list of files in a directory. Is there a way to ask accord which engines compile which file based on file extension? It seems like accord only works with a foreknowledge of exactly which compiler you want to use for one particular file, instead of choosing the engine based on the file (extension).

I poked around at the undocumented accord.all() function, and it looks like it's at least a way to return the LIST of supported compilers (which is essential), but it looks like you'd have to iterate through each one and load the adapter, before reading the "extensions" property. Is that correct? Or is there an easier way?

Stylus: Coerce colors etc

Right now if you want to pass a color into stylus, it needs to pull stylus' class and initialize a custom object with an rgba array. This is an unintuitive pain in the ass. Luckily, we can definitely fix this and make stylus take any normal css color, then just convert it to the stylus format before passing to the adapter. This would probably be a useful addition for a lot of people 😀

Add svgo adapter

https://github.com/svg/svgo
...as an svg to svg renderer for removing crap from SVGs

add property to jobs for specifying if they were isolated

There are a few compilers that are generally isolated, but can be make non-isolated if you pass specific options to them. It would be nice if we could detect isolation on a per-job basis when a compiler isn't inherently isolated.

Can't import css files with stylus

Hi,

I have lots of trouble to import css files with stylus.
Most of the node_modules i made now require to be in stylus overwise i can't import them with gulp-stylus.

I know the path is correct, if you give a wrong path, you'll get a build error, in my case the script doesn't crash, he just write into my app.css the import line :

I can now read this in my app.css
@import './../../node_modules/bootstrap-daterangepicker/daterangepicker-bs3.css';

Where the stylus files from my own library can be imported (i had no other choices to use stylus)

I am using gulp-stylus v1.3.3, which is delegating the job to accord

I also noticed import problem when using simple quotes instead of double quote, but I don't remember why and when.

Readme example typo

https://github.com/jenius/accord/blob/master/readme.md#usage

accord = require 'accord'
stylus = accord.load('jade') # <<< stylus => jade

# render a string
jade.render('body\n  .test') # <<< uses `jade` not `stylus
  .catch(console.error.bind(console))
  .done(console.log.bind(console))

Add jade2php adapter

The compiler interface should be similar, if not identical to jade's, so i would try this myself, but i have no idea how to set up an environmet to code and test accord adapters.
@Jenius could you help me out right there? that would be killer.

https://www.npmjs.com/package/jade-php

should accord.all() be documented?

...or is that a private method?

mustache client compile is broken

this commit from hogan.js is prolly what caused it: twitter/hogan.js@0c67880

Add "inject" to coffeescript options

Ok so this might seem a little crazy, but I think it would be massively useful if we had an extra parameter that would allow js injections into a coffeescript compile. For example:

coffee = accord.load('coffee-script')
coffee.render("foo = 'bar'", { inject: { wow: 'amaze' } })

would yield something like:

(function(){
  var wow, foo;
  wow = 'amaze';
  foo = 'bar';
});

To it would essentially allow you to add in extra variables which would be added at the top of your script. An example of a use case for this would be if you were using roots and wanted to inject a configuration value through app.coffee. There are a few more use cases though that I can think of. This is similar to how html templating engines allow you to add locals, and how some css parsers (like stylus) allow you to add custom variables and functions. There is just no way currently to pipe in extra info from the compile step for coffeescript, and it would be really nice to have that.

add property to compilers for specifying if they are isolated

By isolated I mean their output is independent of other files or the evaluation of potentially stateful functions.

For example, Markdown is always isolated - this is markdown will always compile into <p>this is markdown</p>. Whereas Jade might not be isolated - include another_file could compile into different things depending on the contents of another_file.jade.

This is useful to know because isolated languages can have several optimizations applied to them that wouldn't be possible in non-isolated languages. For example, markdown can be cached (even permanently so long as the version of the compiler doesn't change), certain information can be ignored by the compiler (like the filename), and the compilation itself can be easily off-loaded to another process or even a different machine.

CoffeeScript is another example of an isolated language.

Script Language Request - TypeScript

Could you add the support for TypeScript?

Brainstorming for a better API

So I was thinking about a better API for accord, and I came up with this format using a single function and a fair amount of (well defined) magic...

• compile jade to html
• minify the html

accord(
    from: "jade"
    to: "html"
    string: "h1 blah blah"
    minify: true
)

• compile jade to js (basically what the compileClient function does)
• minify the js

accord(
    from: "jade"
    to: "js"
    string: "h1 blah #{some_var}"
    minify: true
)

• compile ./main.jade to ./main.js (the from language is interpreted from the extension, the to langauge would default to "html" for jade, and we assume that the output is the same file path with a new extension)
• minify the js

accord(
    fromFile: "./main.jade"
    minify: true
)

• compile ./main.jade to ./public/blah.js (languages are interpreted from the extensions)
• minify the js

accord(
    fromFile: "./main.jade"
    toFile: "./public/blah.js"
    minify: true
)

• compile jade to ./public/blah.html (output language is interpreted from the extension)
• minify the js

accord(
    from: "jade"
    toFile: "./public/blah.html"
    string: "h1 blah blah"
    minify: true
)

• convert the html to jade (using html2jade)

accord(
    from: "html"
    to: "jade"
    string: "<h1>meh</h1>"
)

...and all of these would return promises like normal (cause that's already an awesome idea). I think this would be a lot nicer to work with and would certainly make a command-line version easier. Thoughts?

add css-next support

https://cssnext.github.io/

How do we handle breaking changes in compilers?

So until this point, I have been assuming that accord's adapters will stay up to date with the latest versions of each compiler, and this was worked fine. However, it is possible that any given compiler could release a major update that breaks things, and requires accord's adapters to change, therefore making them incompatible with older versions. This could cause peoples' code to break who are using accord and have either not upgraded to the latest version of the compiler because they haven't noticed, or haven't had time to do the migration.

This means any update to a compiler which requires accord to change in any way is technically a breaking change. But I don't think we want to say that any time any adapter hosted by accord has a breaking change, accord also has a breaking change, because this will probably result in very fast versioning to a super high number, and also a lot of major version upgrades that most people don't actually care about because they are not using that adapter.

Just a thought here. I don't think this is an emergency, but it definitely is something to think about.

support for custom adapters

Sometimes you might want to build an adapter for a language that accord does not yet support, or something silly just for your purposes that accord does not plan on supporting. There should be a way to load a custom compiler into accord and use it, as long as you have written an adapter for it.

jade precompiled templates should set a proxy var for window

Currently to access the window you have to use something like

h1 my URL
p #{this.location.orgin}

gross right?!
I propose that we setup the var window to === this.

Thoughts?