Merge pull request #39 from electricimp/develop

2.3.0

Author: Pavel Petroshenko

.gitignore

@@ -2,3 +2,7 @@ node_modules
 _private
 .idea
 .builder-cache
+**/.*.swp
+**/.*.swo
+input
+output

README.md

@@ -16,6 +16,7 @@
     - [@repeat](#repeat)
     - [@if – @elseif – @else](#if--elseif--else)
     - [@error](#error)
+    - [@warning](#warning)
   - [Filters](#filters)
   - [Expressions](#expressions)
     - [Types](#types)
@@ -25,7 +26,7 @@
     - [Member Expressions](#member-expressions)
     - [Conditional Expressions](#conditional-expressions)
     - [Variables](#variables)
-      - [Variable Definition Order](#variables-definition-order)
+      - [Variable Definition Order](#variable-definition-order)
       - [\_\_LINE\_\_](#__line__)
       - [\_\_FILE\_\_](#__file__)
       - [\_\_PATH\_\_](#__path__)
@@ -34,6 +35,8 @@
   - [Comments](#comments)
 - [Usage](#usage)
   - [Running](#running)
+  - [Including JavaScript Libraries](#including-javascript-libraries)
+    - [Binding the Context Object Correctly](#binding-the-context-object-correctly)
   - [Cache for Remote Includes](#cache-for-remote-includes)
 - [Testing](#testing)
 - [License](#license)
@@ -350,6 +353,29 @@ Emits an error.
 <b>@endif</b>
 </pre>
 
+### @warning
+
+<pre>
+<b>@warning</b> <i>&lt;message:expression&gt;</i>
+</pre>
+
+Emits a warning.
+
+#### Example
+
+<pre>
+<b>@if</b> PLATFORM == "platform1"
+  // platform 1 code
+<b>@elseif</b> PLATFORM == "platform2"
+  // platform 2 code
+<b>@elseif</b> PLATFORM == "platform3"
+  // platform 3 code
+<b>@else</b>
+  <b>@warning</b> "Building for default platform"
+  // default platform code
+<b>@endif</b>
+</pre>
+
 ## Filters
 
 The `|` operator (filter) allows you to pass a value through any of the supported functions.
@@ -507,6 +533,20 @@ will print the home directory path of the current user of the system where *Buil
 - <code>min(<i>&lt;numbers&gt;</i>)</code>
 - <code>max(<i>&lt;numbers&gt;</i>)</code>
 - <code>abs(<i>&lt;number&gt;</i>)</code>
+- String functions: the following string functions, based on the JavaScript methods of the same names, are available under the namespace `S`. The first argument to each function is always the string to be operated on. For documentation on the remaining arguments, please see the documentation for JavaScript string methods [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).
+  - <code>S.concat()</code>
+  - <code>S.endsWith()</code>
+  - <code>S.includes()</code>
+  - <code>S.repeat()</code>
+  - <code>S.split()</code>
+  - <code>S.startsWith()</code>
+  - <code>S.substr()</code>
+  - <code>S.substring()</code>
+  - <code>S.toLowerCase()</code>
+  - <code>S.toUpperCase()</code>
+  - <code>S.trim()</code>
+  - <code>S.trimLeft()</code>
+  - <code>S.trimRight()</code>
 
 ## Comments
 
@@ -565,6 +605,70 @@ Lines starting with `@` followed by space or a line break are treated as comment
   * <code>--cache</code> or <code>-c</code> &mdash; enable cache for remote files.
   * <code>--clear-cache</code> &mdash; remove cache before builder starts running.
   * <code>--cache-exclude-list <i>&lt;path_to_file&gt;</i></code> &mdash; path to exclude list file.
+  * <code>--lib(s) <i>&lt;path_to_file|path_to_directory|glob&gt;</i></code> &mdash; path to JavaScript file to include as libraries
+
+## Including JavaScript Libraries
+
+Builder can accept JavaScript libraries to add functionality to its global namespace. The library should export an object, the properties of which will be merged into the global namespace. For example, to include a function to convert strings to uppercase, define your library file like so:
+
+```js
+module.exports = {
+  upper: (s) => s.toUpperCase()
+};
+```
+
+Include directives, such as the following example, in your input file:
+
+```
+@{upper("warning:")}
+@{upper(include("warning.txt"))}
+```
+
+Run builder with the option `--lib path/to/your/lib/file`.
+
+### Binding the Context Object Correctly
+
+**Note** Functions called by Builder will be called with their *this* argument set to a Builder context object. Within the context object, Builder [variables](#variables) like `__FILE__`, [functions](#functions) like `max()`, and other included library functions will be made available at the top level. Variables defined in your input code with `@macro` or `@set` will be available under the key *globals*.
+
+Ignoring the binding of *this* may cause unexpected behavior, for example when calling methods on objects. Take the following example library:
+
+```js
+class MyClass {
+  constructor(str) {
+    this._str = str;
+  }
+
+  getStr() {
+    return this._str;
+  }
+}
+
+myObject = MyClass("my text");
+
+module.exports = {
+  myObject
+};
+```
+
+Attempting to use this library with the directive `@{myObject.getStr()}` will not deliver the expected behavior because *this* in *getStr()* will be set to a Builder context object and not to *myObject*. When calling class methods ensure they have been bound to the correct value of *this*:
+
+```js
+class MyClass {
+  constructor(str) {
+    this._str = str;
+  }
+
+  getStr() {
+    return this._str;
+  }
+}
+
+myObject = MyClass("my text");
+
+module.exports = {
+  getStr: myObject.getStr.bind(myObject)
+};
+```
 
 ## Cache for Remote Includes
 

package.json

@@ -7,7 +7,8 @@
     "pleasebuild": "src/cli.js"
   },
   "scripts": {
-    "test": "node_modules/jasmine/bin/jasmine.js"
+    "test": "node_modules/jasmine/bin/jasmine.js",
+    "build": "src/cli.js input"
   },
   "repository": {
     "type": "git",
@@ -22,6 +23,7 @@
   "dependencies": {
     "clone": "^1.0.2",
     "github": "^0.2.4",
+    "glob": "^7.1.2",
     "jsep": "^0.3.1",
     "request": "^2.71.0",
     "minimatch": "^3.0.4",
@@ -33,6 +35,7 @@
     "jasmine": "^2.4.1",
     "jasmine-diff-matchers": "^2.0.0",
     "jasmine-expect": "^2.0.2",
-    "log": "^1.4.0"
+    "log": "^1.4.0",
+    "fixture-stdout": "^0.2.1"
   }
 }

spec/AstParser/incorrect-syntax.spec.js

@@ -86,6 +86,15 @@ describe('Tokenizer', () => {
     }
   });
 
+  it('should detect incorrect @warning syntax', () => {
+    try {
+      parser.parse(`@warning`);
+      fail();
+    } catch (e) {
+      expect(e.message).toBe('Syntax error in @warning (main:1)');
+    }
+  });
+
   it('should detect incorrect @else syntax', () => {
     try {
       parser.parse(`@if 1\n@else 0\n@endif`);

spec/Expression/filters.spec.js

@@ -15,22 +15,22 @@ describe('Expression', () => {
   beforeEach(() => {
     expression = new Expression();
     context = {};
-    context.max = (args, context) => {
-      return Math.abs.apply(Math, args);
+    context.max = function() {
+      return Math.max.apply(Math, [].slice.call(arguments));
     };
   });
 
-  it('should suppor filter operator with call invocation', () => {
+  it('should support filter operator with call invocation', () => {
     const res = expression.evaluate('5|max(1,2)', context);
     expect(res).toBe(5);
   });
 
-  it('should suppor filter operator without call invocation #1', () => {
+  it('should support filter operator without call invocation #1', () => {
     const res = expression.evaluate('5|max', context);
     expect(res).toBe(5);
   });
 
-  it('should suppor filter operator without call invocation #2', () => {
+  it('should support filter operator without call invocation #2', () => {
     const res = expression.evaluate('5|("m" + "ax")', context);
     expect(res).toBe(5);
   });

spec/Expression/misc.spec.js

@@ -18,7 +18,8 @@ describe('Expression', () => {
 
     // create Math.* function
     const mathFunction = (name) => {
-      return (args, context) => {
+      return function() {
+        const args = [].slice.call(arguments);
         if (args.length < 1) {
           throw new Error('Wrong number of arguments for ' + name + '()');
         }

spec/Machine/basic.spec.js

@@ -6,6 +6,8 @@
 
 require('jasmine-expect');
 
+const Fixture = require('fixture-stdout');
+const stderrFixture = new Fixture({ stream: process.stderr });
 const init = require('./init')('main');
 const Machine = require('../../src/Machine');
 
@@ -81,6 +83,32 @@ describe('Machine', () => {
     }
   });
 
+  it('should handle @warning directives', (done) => {
+    // Our warning message
+    const text = 'abc';
+    // What we expect to be logged to STDERR
+    const yellowTextLine = `\x1b[33m${text}\u001b[39m\n`;
+    try {
+      // Capture STDERR messages
+      stderrFixture.capture(message => {
+        try {
+          expect(message).toBe(yellowTextLine);
+          // Release STDERR
+          stderrFixture.release();
+          done();
+        } catch (e) {
+          fail(e);
+        }
+        // Returning false prevents message actually being logged to STDERR
+        return false;
+      });
+
+      machine.execute(`@warning "${text}"`);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
   it('should not allow macro redeclaration', () => {
     try {
       machine.execute(`@macro A()\n@endmacro\n@macro A()\n@endmacro`);

spec/Machine/init.js

@@ -13,7 +13,13 @@ module.exports = (sampleFile) => {
   return {
 
     createMachine: () => {
-      const builder = new Builder();
+      // File listing libs to include
+      const libFile = `${path.dirname(sampleFile)}/libs`;
+      let libs = [];
+      if (fs.existsSync(libFile)) {
+        libs = fs.readFileSync(libFile).toString().split('\n').map(l => `${path.dirname(sampleFile)}/${l}`);
+      }
+      const builder = new Builder({ libs });
       builder.logger = new Log(process.env.SPEC_LOGLEVEL || 'error');
       builder.machine.readers.github.username = process.env.SPEC_GITHUB_USERNAME;
       builder.machine.readers.github.token = process.env.SPEC_GITHUB_PASSWORD || process.env.SPEC_GITHUB_TOKEN;

spec/Machine/sample-12-spec.js

@@ -0,0 +1,37 @@
+// Copyright (c) 2016-2017 Electric Imp
+// This file is licensed under the MIT License
+// http://opensource.org/licenses/MIT
+
+'use strict';
+
+require('jasmine-expect');
+const Fixture = require('fixture-stdout');
+
+const FILE = __dirname + '/../fixtures/sample-12/input.nut';
+const init = require('./init')(FILE);
+const stdoutFixture = new Fixture({ stream: process.stdout });
+
+describe('Machine', () => {
+  let machine, result, resultWithLC;
+
+  beforeEach(() => {
+    machine = init.createMachine();
+    result = init.getResult();
+  });
+
+  it('should exhibit the expeted behaviour when including user-defined Javascript libraries', (done) => {
+    stdoutFixture.capture(message => {
+      try {
+        expect(message).toBe("Hello world!\n");
+        // Release STDOUT
+        stdoutFixture.release();
+        done();
+      } catch (e) {
+        fail(e);
+      }
+      // Returning false prevents message actually being logged to STDOUT
+      return false;
+    });
+    expect(machine.execute('@include "input.nut"')).toBe(result);
+  });
+});

spec/Machine/sample-13-spec.js

@@ -0,0 +1,24 @@
+// Copyright (c) 2016-2017 Electric Imp
+// This file is licensed under the MIT License
+// http://opensource.org/licenses/MIT
+
+'use strict';
+
+require('jasmine-expect');
+const Fixture = require('fixture-stdout');
+
+const FILE = __dirname + '/../fixtures/sample-13/input.nut';
+const init = require('./init')(FILE);
+
+describe('Machine', () => {
+  let machine, result;
+
+  beforeEach(() => {
+    machine = init.createMachine();
+    result = init.getResult();
+  });
+
+  it('should exhibit the expeted behaviour when including user-defined Javascript libraries', () => {
+    expect(machine.execute('@include "input.nut"')).toBe(result);
+  });
+});

spec/Machine/sample-14-spec.js

@@ -0,0 +1,24 @@
+// Copyright (c) 2016-2017 Electric Imp
+// This file is licensed under the MIT License
+// http://opensource.org/licenses/MIT
+
+'use strict';
+
+require('jasmine-expect');
+const Fixture = require('fixture-stdout');
+
+const FILE = __dirname + '/../fixtures/sample-14/input.nut';
+const init = require('./init')(FILE);
+
+describe('Machine', () => {
+  let machine, result;
+
+  beforeEach(() => {
+    machine = init.createMachine();
+    result = init.getResult();
+  });
+
+  it('should exhibit the expeted behaviour when including user-defined Javascript libraries', () => {
+    expect(machine.execute('@include "input.nut"')).toBe(result);
+  });
+});