Edit the docs to emphasize ShellStrings and Pipes

The introduction of ShellStrings is a pretty big change, since a lot of people rely on the old behavior of strings have the .to() method (here’s an example from our friends over at dthree/cash).

We might want to consider adding that back in to the String.prototype for now, and give a deprecation warning, since this might be a big impediment to users migrating to the new version. Or, if we decide to keep it as-is, we should document it a bit more clearly, and make it obvious for how people can create a file with the syntax:

ShellString('some text').to('file.txt');

Also, I think pipes are one of the more useful features in ShellJS v0.7, so these should probably be advertised better in the docs.

On a related note, it might be worth starting guides in the wiki pages about how to migrate from version to version. We’ve been introducing quite a few breaking changes, so it might ease the transition for users to have these breaking changes highlighted (and not only buried in the changelog with all the features/bug fixes/etc.).

[nfischer]

I consider global commands (rm, etc.) just as “bad” as extending String, honestly, so if I didn’t want any of that in a project, I wouldn’t import global.

@dthree I agree with the reasoning there. I was considering suggesting exactly that. This provides convenience for those who want it, but keeps the pollution at 0 for when that’s preferred. This would actually be fairly easy to implement, as well.

Then we can also add a ‘noConflict’ method.

@ariporad What do you mean by a ‘noConflict’ method?

The idea I’m leaning toward right now is:

• Always have individual commands return ShellStrings, not regular JS strings
• If using require('shelljs'), do not extend String.prototype
• If using require('shelljs/global'), allow any JS string to have the .to() and .toEnd() methods only (not the other pipe methods). These methods are really ideally used after some other command anyway (like grep('o', 'file.txt').sed(/o/g, 'a')). This stays backwards compatible for that kind of require, which is the real motivation.

Thoughts?

[nfischer]

Everything discussed in this thread has been addressed, so I’m closing this. Please reopen if you have any issues with the current state of the docs (otherwise, these will be the official docs for v0.7 until the next release).