A base module with which to create a custom file formatter.
This module is fairly simple, and on it's own, doesn't do much. However, it allows you to therefore do anything.
A base formatter has a very simple API, which is a
format method and a
Why would you want this sort of thing? Mainly, we're using it as a piece of our check-source-formatter module and our convert-bootstrap-2-to-3 module.
$ npm install --save content-formatter
Creating a formatter
var Formatter = ;var JSFormatter = Formatter;var jsFormatter = 'test.js';var fs = ;var contents = fs;var newContents = jsFormatter;
One thing you may notice in the above example is that you need to handle reading the content on your own. This is so that you have more flexibility on where your content comes from (perhaps you're reading from a database, or some other data source).
Formatter.create takes an object that, at the bare minimum, requires only 2 properties:
This method returns the constructor of your custom formatter.
You can think of
includes as the test that gets run over what ever path you pass into the constructor (and in the same way that the path could be anything, the
includes could also be any sort of test for that path).
This allows you to specify that you want your formatter to only run on certain types of data.
Also of note, in addition to
includes, you can also pass an
excludes regex, which will allow you to negate the
For instance, if you wanted to include all
.js files, but exclude any minified files, you could do something like
However, just using those two properties doesn't give you much by way of functionality.
So the other properties you can pass into
constructor (this will be used as the constructor of your formatter, instead of the default one) and
prototype, which is an object you can add the instance methods of your formatter on.
So, for instance:
var Formatter = ;var JSFormatter = Formatter;var jsFormatter = 'test.js';// 'This is a constructor'console;// 'foo_bar'console;// 'This is a shell script'// '#! /usr/bin/env node'
This may seem like a really verbose way to handle such a simple use case, but this module is mainly designed as a base API layer to enforce a certain contract.
If you do not wish to pass a
constructor, but yet want to have a method called when you instantiate the object (for instance, if the pomp and circumstance of always having to do
return Formatter.apply(this, arguments); get's old), then you can define an
init method on the
prototype object, and when you call
new formatter('foo.js'), it will be called with the same arguments passed into the constructor.
Getting the appropriate formatter
Let's say you have a bunch of formatters defined in your code, but don't want to check each one manually to see if it should format the contents of the path.
Formatter.get is a static method that will loop through all registered formatters and return to you an instance of the first one that passes the
It accepts all of the arguments that a normal
Formatter constructor would have, but it instantiates the class for you, and gives you back that instance.
For example, using the module from above:
var Formatter = ;var jsFormatter = Formatter;jsFormatter;
path logger flags
The constructor of the
Formatter expects to take a path, and optionally, a custom logger can be passed, as well as flags to the formatter.
The only flag that is currently used (by
force, which will force the formatter to run, even if the
excludes tell it not to.
This is the powerhouse of the formatter, and it's wide open for you to do anything with it. You can delegate to other methods, and do anything you please. By default, it expects a string of contents, and to return new contents (though, your implementation could always allow for a callback to be passed that could return the new contents).
This is the basic logging method. If no custom logger was passed in, it will default to
Formatter.DEFAULT_LOGGER, which, by default, is set to
Formatter.DEFAULT_LOGGER can be passed any object that has a
log method on it.
By default, the log method takes the following arguments:
What's eventually passed to the internal logger though, is the following:
line, msg, path, type, props
Your implementation can overwrite this, and send whatever it likes, but we use this most commonly with logging out which line is causing an issue. But again, that's just the defaults.
- I'm currently thinking through a way for multiple formatters to run, instead of having it be only one per include type.
- I would like to also remove the requirement of passing an ID for a formatter. If multiple filters eventually can run, it's pointless to have an ID (even now, I think it isn't really needed).
MIT © Nate Cavanaugh