migrate to new shorter variable names as a simpler way to handle old …

…deprecated strings versions of ARGUMENTS/VARS

README.rst

@@ -19,11 +19,25 @@ And add it as a compiler to pipeline in your django `settings.py`::
 To add source maps during development (or any other browserify args)::
 
     if DEBUG:
-        PIPELINE['BROWSERIFY_ARGUMENTS'] = ['-d']
+        PIPELINE['BROWSERIFY_ARGS'] = ['-d']
 
-To add variable assignments before the browserify command::
+Passing arguments as an array makes sure they are safely unambiguous, but the way browserify lets you pass nested arguments within brackets can make this very tedious::
+    
+    # this is very unreadable, and hard to maintain!
+    PIPELINE['BROWSERIFY_ARGS'] = ['--transform', '[', 'babelify', '--presets', '[', 'es2015', 'react', ']', '--plugins', '[', 'transform-object-rest-spread', 'transform-class-properties', ']', ']']
+
+To avoid this, when you know that no individual argument has a space within it, simply split the arguments yourself::
+
+    # the easy way :-)
+    PIPELINE['BROWSERIFY_ARGS'] = "--transform [ babelify --presets [ es2015 react ] --plugins [ transform-object-rest-spread transform-class-properties ] ]".split()
+
+
+To set environment varaibles specific to the browserify command::
+
+    PIPELINE['BROWSERIFY_ENV'] = {'NODE_ENV':'production'}
+
+(Note that for an actual production build, this example is not sufficient. You'll probably want to use a transform like loose-envify so the minifier can optimize out debug statements. Browserify doesn't usually pass environment variables like that shown above into the compiled code; but it may effect the runtime behavior of browserify itself.)
 
-    PIPELINE['BROWSERIFY_VARS'] = {'NODE_ENV':'production'}
 
 **Important:** give your entry-point file a `.browserify.js` extension::
 

pipeline_browserify/compiler.py

@@ -2,6 +2,7 @@
 from django.conf import settings
 from django.core.exceptions import SuspiciousFileOperation
 from pipeline.exceptions import CompilerError
+from warnings import warn
 
 class BrowserifyCompiler(SubProcessCompiler):
     output_extension = 'browserified.js'
@@ -26,23 +27,27 @@ def simple_execute_command(self, cmd, **kwargs):
     def _get_cmd_parts(self):
         pipeline_settings = getattr(settings, 'PIPELINE', {})
         tool = pipeline_settings.get('BROWSERIFY_BINARY', "/usr/bin/env browserify")
-        args = pipeline_settings.get('BROWSERIFY_ARGUMENTS', [])
-        if not isinstance(args, list):
-            args = args.split()
 
-        env = pipeline_settings.get('BROWSERIFY_VARS', {})
-        if not isinstance(env, dict):
-            env = dict(map(lambda s: s.split('='), env.split()))
-        if len(env):
-            # even if there's custom variables, we need to pass along the original environment
+        old_args = pipeline_settings.get('BROWSERIFY_ARGUMENTS', '')
+        if old_args:
+            warn("You are using the string-based BROWSERIFY_ARGUMENTS setting. Please migrate to providing a list of arguments via BROWSERIFY_ARGS instead.", DeprecationWarning)
+            args = old_args.split()
+        else:
+            args = pipeline_settings.get('BROWSERIFY_ARGS', [])
+
+        old_env = pipeline_settings.get('BROWSERIFY_VARS', '')
+        if old_env:
+            warn("You are using the string-based BROWSERIFY_VARS setting. Please migrate to providing a dict of environment variables via BROWSERIFY_ENV instead.", DeprecationWarning)
+            env = dict(map(lambda s: s.split('='), old_env.split()))
+        else:
+            env = pipeline_settings.get('BROWSERIFY_ENV', None)
+        if env:
+            # when there's custom variables, we need to explicitly pass along the original environment
             import os
             _env = {}
             _env.update(os.environ)
             _env.update(env)
             env = _env
-        else:
-            # drop any empty dict and let subprocess retain environment automatically
-            env = None
 
         return tool, args, env