opal 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3a9bf851ab7303452422a1822f7a2f312f4b2797
-  data.tar.gz: 01582cdf5ce1c13f075e52f6fb2905b761817e28
+  metadata.gz: 0494f5ca3ec281015d5da6f2ebbc77efb60be8c1
+  data.tar.gz: 852eea5baed0f69c1e5ae1f927ffa732f088c849
 SHA512:
-  metadata.gz: b41fd0b62ece98c9a117dd185ccc20708c751de45878c4fc4498f8125c76ec6f61227577ea4be1a472ae54e0658b4e23f45bccd4faf3c2a939c34135b9ecc7ca
-  data.tar.gz: 1d021c3b6eea6eacc2ac7e9081fe079a5bcf454fbba2ada078b1e42b14675503c01065524ae84eaa948f7e7f0a78c2547e920e297f1197747313cdc07a41c44a
+  metadata.gz: 1476886b7df5b2044e99300f34430b497de8f4792d3a2d5db801ab6a64fc0c85c82e5145d7364d2ac29d4ce774e7d083ad1c333a03c21c7815b158373a0a2fb2
+  data.tar.gz: 4475446f440e51146edd1acac3c2767b81ab00f9480b77bab9c7596877910a085e4201d52068aefc8f72279be9fdf7c2a68f73ab7f1fb8b28ca82dfdf8017c89

data/CHANGELOG.md

@@ -1,4 +1,14 @@
-## edge (upcoming 0.7)
+## edge (upcoming 0.7.1)
+
+*    CLI options `-d` and `-v` now set respectively `$DEBUG` and `$VERBOSE`
+
+*   Fixed a bug that would make the `-v` CLI option wait for STDIN input
+
+*   Add the `-E` / `--no-exit` CLI option to skip implicit `Kernel#exit` call
+
+*   Now the CLI implicitly calls `Kernel#exit` at the end of the script, thus making `at_exit` blocks be respected.
+
+## 0.7.0 2015-02-01
 
 *   Stop keyword-arg variable names leaking to global javascript scope
 

data/lib/opal/cli.rb

@@ -7,7 +7,7 @@ module Opal
   class CLI
     attr_reader :options, :file, :compiler_options, :evals, :load_paths, :argv,
                 :output, :requires, :gems, :stubs, :verbose, :port, :preload,
-                :filename
+                :filename, :debug, :no_exit
 
     def compile?
       @compile
@@ -36,6 +36,7 @@ module Opal
       @compile    = !!options.delete(:compile)
       @sexp       = options.delete(:sexp)
       @file       = options.delete(:file)
+      @no_exit    = options.delete(:no_exit)
       @argv       = options.delete(:argv)       || []
       @evals      = options.delete(:evals)      || []
       @requires   = options.delete(:requires)   || []
@@ -45,6 +46,7 @@ module Opal
       @preload    = options.delete(:preload)    || []
       @output     = options.delete(:output)     || self.class.stdout || $stdout
       @verbose    = options.fetch(:verbose, false); options.delete(:verbose)
+      @debug      = options.fetch(:debug, false);   options.delete(:debug)
       @filename   = options.fetch(:filename) { @file && @file.path }; options.delete(:filename)
       @skip_opal_require = options.delete(:skip_opal_require)
       @compiler_options = Hash[
@@ -95,6 +97,10 @@ module Opal
 
       preload.each { |path| builder.build_require(path) }
 
+      # FLAGS
+      builder.build_str '$VERBOSE = true', '(flags)' if verbose
+      builder.build_str '$DEBUG = true', '(flags)' if debug
+
       # REQUIRES: -r
       requires.each do |local_require|
         builder.build(local_require)
@@ -108,6 +114,8 @@ module Opal
         end
       end
 
+      builder.build_str 'Kernel.exit', '(exit)' unless no_exit
+
       builder.to_s
     end
 

data/lib/opal/cli_options.rb

@@ -12,11 +12,16 @@ module Opal
 
       on('-v', '--verbose', 'print version number, then turn on verbose mode') do
         print_version
-        options[:verbose] = true # TODO: print some warnings when verbose = true
+        exit if ARGV.empty?
+        options[:verbose] = true
       end
 
-      on('--verbose', 'turn on verbose mode') do
-        options[:verbose] = true # TODO: print some warnings when verbose = true
+      on('--verbose', 'turn on verbose mode (set $VERBOSE to true)') do
+        options[:verbose] = true
+      end
+
+      on('-d', '--debug', 'turn on debug mode (set $DEBUG to true)') do
+        options[:debug] = true
       end
 
       on('--version', 'Print the version') do
@@ -88,6 +93,10 @@ module Opal
         options[:port] = port.to_i
       end
 
+      on('--no-exit', 'Do not append a Kernel#exit at the end of file') do |no_exit|
+        options[:no_exit] = true
+      end
+
 
       section 'Compilation Options:'
 

data/lib/opal/cli_runners/nodejs.rb

@@ -1,4 +1,5 @@
 require 'opal/cli_runners'
+require 'opal/paths'
 
 module Opal
   module CliRunners
@@ -13,7 +14,7 @@ module Opal
       end
 
       def node_modules
-        File.expand_path("../../../../node_modules", __FILE__)
+        File.expand_path('../stdlib/nodejs/node_modules', ::Opal.gem_dir)
       end
 
       def run(code, argv)
@@ -29,7 +30,7 @@ module Opal
 
       # Let's support fake IO objects like StringIO
       def system_with_output(env, *cmd)
-        if (io_output = IO.try_convert(output))
+        if IO.try_convert(output)
           system(env,*cmd)
           @exit_status = $?.exitstatus
           return

data/lib/opal/version.rb

@@ -1,3 +1,3 @@
 module Opal
-  VERSION = '0.7.0'
+  VERSION = '0.7.1'
 end

data/opal/corelib/kernel.rb

@@ -149,6 +149,13 @@ module Kernel
     `self === other`
   end
 
+  def exit(status = true)
+    $__at_exit__.reverse.each(&:call) if $__at_exit__
+    status = 0 if `status === true` # it's in JS because it can be null/undef
+    `Opal.exit(status);`
+    nil
+  end
+
   def extend(*mods)
     %x{
       var singleton = #{singleton_class};

data/opal/corelib/runtime.js

@@ -43,6 +43,10 @@
   // Globals table
   Opal.gvars = {};
 
+  // Exit function, this should be replaced by platform specific implementation
+  // (See nodejs and phantom for examples)
+  Opal.exit = function(status) { if (Opal.gvars.DEBUG) console.log('Exited with status '+status); };
+
   /**
     Get a constant on the given scope. Every class and module in Opal has a
     scope used to store, and inherit, constants. For example, the top level

data/spec/lib/cli_spec.rb

@@ -40,6 +40,22 @@ describe Opal::CLI do
     end
   end
 
+  describe ':no_exit option' do
+    context 'when false' do
+      let(:options) { {no_exit: false, compile: true, evals: ['']} }
+      it 'appends a Kernel#exit at the end of the source' do
+        expect_output_of{ subject.run }.to include(".$exit()")
+      end
+    end
+
+    context 'when true' do
+      let(:options) { {no_exit: true, compile: true, evals: ['']} }
+      it 'appends a Kernel#exit at the end of the source' do
+        expect_output_of{ subject.run }.not_to include(".$exit();")
+      end
+    end
+  end
+
   describe ':requires options' do
     context 'with an absolute path' do
       let(:options) { {:requires => [file], :evals => ['']} }

data/stdlib/nodejs.rb

@@ -1,8 +1,7 @@
 module NodeJS
 end
 
-require 'nodejs/runtime'
+require 'nodejs/kernel'
 require 'nodejs/file'
 require 'nodejs/dir'
 require 'nodejs/io'
-require 'nodejs/process'

data/stdlib/nodejs/{process.rb → kernel.rb}

@@ -1,8 +1,7 @@
+`Opal.exit = process.exit`
+
 module Kernel
-  def exit(status = true)
-    $__at_exit__.reverse.each(&:call) if $__at_exit__
-    `process.exit(status === true ? 0 : status)`
-  end
+  NODE_REQUIRE = `require`
 
   def caller
     %x{
@@ -16,6 +15,10 @@ module Kernel
       return stack.$split("\n").slice(3);
     }
   end
+
+  def node_require(path)
+    `#{NODE_REQUIRE}(#{path.to_str})`
+  end
 end
 
 ARGV = `process.argv.slice(2)`

data/stdlib/nodejs/node_modules/.bin/js-yaml

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+
+'use strict';
+
+
+// stdlib
+var fs    = require('fs');
+
+
+// 3rd-party
+var argparse = require('argparse');
+
+
+// internal
+var yaml = require('..');
+
+
+////////////////////////////////////////////////////////////////////////////////
+
+
+var cli = new argparse.ArgumentParser({
+  prog:     'js-yaml',
+  version:  require('../package.json').version,
+  addHelp:  true
+});
+
+
+cli.addArgument(['-c', '--compact'], {
+  help:   'Display errors in compact mode',
+  action: 'storeTrue'
+});
+
+
+// deprecated (not needed after we removed output colors)
+// option suppressed, but not completely removed for compatibility
+cli.addArgument(['-j', '--to-json'], {
+  help:   argparse.Const.SUPPRESS,
+  dest:   'json',
+  action: 'storeTrue'
+});
+
+
+cli.addArgument(['-t', '--trace'], {
+  help:   'Show stack trace on error',
+  action: 'storeTrue'
+});
+
+cli.addArgument(['file'], {
+  help:   'File to read, utf-8 encoded without BOM',
+  nargs:  '?',
+  defaultValue: '-'
+});
+
+
+////////////////////////////////////////////////////////////////////////////////
+
+
+var options = cli.parseArgs();
+
+
+////////////////////////////////////////////////////////////////////////////////
+
+function readFile(filename, encoding, callback) {
+  if (options.file === '-') {
+    // read from stdin
+
+    var chunks = [];
+
+    process.stdin.on('data', function(chunk) {
+      chunks.push(chunk);
+    });
+
+    process.stdin.on('end', function() {
+      return callback(null, Buffer.concat(chunks).toString(encoding));
+    });
+  } else {
+    fs.readFile(filename, encoding, callback);
+  }
+}
+
+readFile(options.file, 'utf8', function (error, input) {
+  var output, isYaml;
+
+  if (error) {
+    if ('ENOENT' === error.code) {
+      console.error('File not found: ' + options.file);
+      process.exit(2);
+    }
+
+    console.error(
+      options.trace && error.stack ||
+      error.message ||
+      String(error));
+
+    process.exit(1);
+  }
+
+  try {
+    output = JSON.parse(input);
+    isYaml = false;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      try {
+        output = [];
+        yaml.loadAll(input, function (doc) { output.push(doc); }, {});
+        isYaml = true;
+
+        if (0 === output.length) {
+          output = null;
+        } else if (1 === output.length) {
+          output = output[0];
+        }
+      } catch (error) {
+        if (options.trace && error.stack) {
+          console.error(error.stack);
+        } else {
+          console.error(error.toString(options.compact));
+        }
+
+        process.exit(1);
+      }
+    } else {
+      console.error(
+        options.trace && error.stack ||
+        error.message ||
+        String(error));
+
+      process.exit(1);
+    }
+  }
+
+  if (isYaml) {
+    console.log(JSON.stringify(output, null, '  '));
+  } else {
+    console.log(yaml.dump(output));
+  }
+
+  process.exit(0);
+});

data/stdlib/nodejs/node_modules/glob/LICENSE

@@ -0,0 +1,15 @@
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/stdlib/nodejs/node_modules/glob/README.md

@@ -0,0 +1,357 @@
+[![Build Status](https://travis-ci.org/isaacs/node-glob.svg?branch=master)](https://travis-ci.org/isaacs/node-glob/) [![Dependency Status](https://david-dm.org/isaacs/node-glob.svg)](https://david-dm.org/isaacs/node-glob) [![devDependency Status](https://david-dm.org/isaacs/node-glob/dev-status.svg)](https://david-dm.org/isaacs/node-glob#info=devDependencies) [![optionalDependency Status](https://david-dm.org/isaacs/node-glob/optional-status.svg)](https://david-dm.org/isaacs/node-glob#info=optionalDependencies)
+
+# Glob
+
+Match files using the patterns the shell uses, like stars and stuff.
+
+This is a glob implementation in JavaScript.  It uses the `minimatch`
+library to do its matching.
+
+![](oh-my-glob.gif)
+
+## Usage
+
+```javascript
+var glob = require("glob")
+
+// options is optional
+glob("**/*.js", options, function (er, files) {
+  // files is an array of filenames.
+  // If the `nonull` option is set, and nothing
+  // was found, then files is ["**/*.js"]
+  // er is an error object or null.
+})
+```
+
+## Glob Primer
+
+"Globs" are the patterns you type when you do stuff like `ls *.js` on
+the command line, or put `build/*` in a `.gitignore` file.
+
+Before parsing the path part patterns, braced sections are expanded
+into a set.  Braced sections start with `{` and end with `}`, with any
+number of comma-delimited sections within.  Braced sections may contain
+slash characters, so `a{/b/c,bcd}` would expand into `a/b/c` and `abcd`.
+
+The following characters have special magic meaning when used in a
+path portion:
+
+* `*` Matches 0 or more characters in a single path portion
+* `?` Matches 1 character
+* `[...]` Matches a range of characters, similar to a RegExp range.
+  If the first character of the range is `!` or `^` then it matches
+  any character not in the range.
+* `!(pattern|pattern|pattern)` Matches anything that does not match
+  any of the patterns provided.
+* `?(pattern|pattern|pattern)` Matches zero or one occurrence of the
+  patterns provided.
+* `+(pattern|pattern|pattern)` Matches one or more occurrences of the
+  patterns provided.
+* `*(a|b|c)` Matches zero or more occurrences of the patterns provided
+* `@(pattern|pat*|pat?erN)` Matches exactly one of the patterns
+  provided
+* `**` If a "globstar" is alone in a path portion, then it matches
+  zero or more directories and subdirectories searching for matches.
+  It does not crawl symlinked directories.
+
+### Dots
+
+If a file or directory path portion has a `.` as the first character,
+then it will not match any glob pattern unless that pattern's
+corresponding path part also has a `.` as its first character.
+
+For example, the pattern `a/.*/c` would match the file at `a/.b/c`.
+However the pattern `a/*/c` would not, because `*` does not start with
+a dot character.
+
+You can make glob treat dots as normal characters by setting
+`dot:true` in the options.
+
+### Basename Matching
+
+If you set `matchBase:true` in the options, and the pattern has no
+slashes in it, then it will seek for any file anywhere in the tree
+with a matching basename.  For example, `*.js` would match
+`test/simple/basic.js`.
+
+### Negation
+
+The intent for negation would be for a pattern starting with `!` to
+match everything that *doesn't* match the supplied pattern.  However,
+the implementation is weird, and for the time being, this should be
+avoided.  The behavior will change or be deprecated in version 5.
+
+### Empty Sets
+
+If no matching files are found, then an empty array is returned.  This
+differs from the shell, where the pattern itself is returned.  For
+example:
+
+    $ echo a*s*d*f
+    a*s*d*f
+
+To get the bash-style behavior, set the `nonull:true` in the options.
+
+### See Also:
+
+* `man sh`
+* `man bash` (Search for "Pattern Matching")
+* `man 3 fnmatch`
+* `man 5 gitignore`
+* [minimatch documentation](https://github.com/isaacs/minimatch)
+
+## glob.hasMagic(pattern, [options])
+
+Returns `true` if there are any special characters in the pattern, and
+`false` otherwise.
+
+Note that the options affect the results.  If `noext:true` is set in
+the options object, then `+(a|b)` will not be considered a magic
+pattern.  If the pattern has a brace expansion, like `a/{b/c,x/y}`
+then that is considered magical, unless `nobrace:true` is set in the
+options.
+
+## glob(pattern, [options], cb)
+
+* `pattern` {String} Pattern to be matched
+* `options` {Object}
+* `cb` {Function}
+  * `err` {Error | null}
+  * `matches` {Array<String>} filenames found matching the pattern
+
+Perform an asynchronous glob search.
+
+## glob.sync(pattern, [options])
+
+* `pattern` {String} Pattern to be matched
+* `options` {Object}
+* return: {Array<String>} filenames found matching the pattern
+
+Perform a synchronous glob search.
+
+## Class: glob.Glob
+
+Create a Glob object by instantiating the `glob.Glob` class.
+
+```javascript
+var Glob = require("glob").Glob
+var mg = new Glob(pattern, options, cb)
+```
+
+It's an EventEmitter, and starts walking the filesystem to find matches
+immediately.
+
+### new glob.Glob(pattern, [options], [cb])
+
+* `pattern` {String} pattern to search for
+* `options` {Object}
+* `cb` {Function} Called when an error occurs, or matches are found
+  * `err` {Error | null}
+  * `matches` {Array<String>} filenames found matching the pattern
+
+Note that if the `sync` flag is set in the options, then matches will
+be immediately available on the `g.found` member.
+
+### Properties
+
+* `minimatch` The minimatch object that the glob uses.
+* `options` The options object passed in.
+* `aborted` Boolean which is set to true when calling `abort()`.  There
+  is no way at this time to continue a glob search after aborting, but
+  you can re-use the statCache to avoid having to duplicate syscalls.
+* `statCache` Collection of all the stat results the glob search
+  performed.
+* `cache` Convenience object.  Each field has the following possible
+  values:
+  * `false` - Path does not exist
+  * `true` - Path exists
+  * `'DIR'` - Path exists, and is not a directory
+  * `'FILE'` - Path exists, and is a directory
+  * `[file, entries, ...]` - Path exists, is a directory, and the
+    array value is the results of `fs.readdir`
+* `statCache` Cache of `fs.stat` results, to prevent statting the same
+  path multiple times.
+* `symlinks` A record of which paths are symbolic links, which is
+  relevant in resolving `**` patterns.
+
+### Events
+
+* `end` When the matching is finished, this is emitted with all the
+  matches found.  If the `nonull` option is set, and no match was found,
+  then the `matches` list contains the original pattern.  The matches
+  are sorted, unless the `nosort` flag is set.
+* `match` Every time a match is found, this is emitted with the matched.
+* `error` Emitted when an unexpected error is encountered, or whenever
+  any fs error occurs if `options.strict` is set.
+* `abort` When `abort()` is called, this event is raised.
+
+### Methods
+
+* `pause` Temporarily stop the search
+* `resume` Resume the search
+* `abort` Stop the search forever
+
+### Options
+
+All the options that can be passed to Minimatch can also be passed to
+Glob to change pattern matching behavior.  Also, some have been added,
+or have glob-specific ramifications.
+
+All options are false by default, unless otherwise noted.
+
+All options are added to the Glob object, as well.
+
+If you are running many `glob` operations, you can pass a Glob object
+as the `options` argument to a subsequent operation to shortcut some
+`stat` and `readdir` calls.  At the very least, you may pass in shared
+`symlinks`, `statCache`, and `cache` options, so that parallel glob
+operations will be sped up by sharing information about the
+filesystem.
+
+* `cwd` The current working directory in which to search.  Defaults
+  to `process.cwd()`.
+* `root` The place where patterns starting with `/` will be mounted
+  onto.  Defaults to `path.resolve(options.cwd, "/")` (`/` on Unix
+  systems, and `C:\` or some such on Windows.)
+* `dot` Include `.dot` files in normal matches and `globstar` matches.
+  Note that an explicit dot in a portion of the pattern will always
+  match dot files.
+* `nomount` By default, a pattern starting with a forward-slash will be
+  "mounted" onto the root setting, so that a valid filesystem path is
+  returned.  Set this flag to disable that behavior.
+* `mark` Add a `/` character to directory matches.  Note that this
+  requires additional stat calls.
+* `nosort` Don't sort the results.
+* `stat` Set to true to stat *all* results.  This reduces performance
+  somewhat, and is completely unnecessary, unless `readdir` is presumed
+  to be an untrustworthy indicator of file existence.
+* `silent` When an unusual error is encountered when attempting to
+  read a directory, a warning will be printed to stderr.  Set the
+  `silent` option to true to suppress these warnings.
+* `strict` When an unusual error is encountered when attempting to
+  read a directory, the process will just continue on in search of
+  other matches.  Set the `strict` option to raise an error in these
+  cases.
+* `cache` See `cache` property above.  Pass in a previously generated
+  cache object to save some fs calls.
+* `statCache` A cache of results of filesystem information, to prevent
+  unnecessary stat calls.  While it should not normally be necessary
+  to set this, you may pass the statCache from one glob() call to the
+  options object of another, if you know that the filesystem will not
+  change between calls.  (See "Race Conditions" below.)
+* `symlinks` A cache of known symbolic links.  You may pass in a
+  previously generated `symlinks` object to save `lstat` calls when
+  resolving `**` matches.
+* `sync` Perform a synchronous glob search.
+* `nounique` In some cases, brace-expanded patterns can result in the
+  same file showing up multiple times in the result set.  By default,
+  this implementation prevents duplicates in the result set.  Set this
+  flag to disable that behavior.
+* `nonull` Set to never return an empty set, instead returning a set
+  containing the pattern itself.  This is the default in glob(3).
+* `debug` Set to enable debug logging in minimatch and glob.
+* `nobrace` Do not expand `{a,b}` and `{1..3}` brace sets.
+* `noglobstar` Do not match `**` against multiple filenames.  (Ie,
+  treat it as a normal `*` instead.)
+* `noext` Do not match `+(a|b)` "extglob" patterns.
+* `nocase` Perform a case-insensitive match.  Note: on
+  case-insensitive filesystems, non-magic patterns will match by
+  default, since `stat` and `readdir` will not raise errors.
+* `matchBase` Perform a basename-only match if the pattern does not
+  contain any slash characters.  That is, `*.js` would be treated as
+  equivalent to `**/*.js`, matching all js files in all directories.
+* `nonegate` Suppress `negate` behavior.  (See below.)
+* `nocomment` Suppress `comment` behavior.  (See below.)
+* `nonull` Return the pattern when no matches are found.
+* `nodir` Do not match directories, only files.
+
+## Comparisons to other fnmatch/glob implementations
+
+While strict compliance with the existing standards is a worthwhile
+goal, some discrepancies exist between node-glob and other
+implementations, and are intentional.
+
+If the pattern starts with a `!` character, then it is negated.  Set the
+`nonegate` flag to suppress this behavior, and treat leading `!`
+characters normally.  This is perhaps relevant if you wish to start the
+pattern with a negative extglob pattern like `!(a|B)`.  Multiple `!`
+characters at the start of a pattern will negate the pattern multiple
+times.
+
+If a pattern starts with `#`, then it is treated as a comment, and
+will not match anything.  Use `\#` to match a literal `#` at the
+start of a line, or set the `nocomment` flag to suppress this behavior.
+
+The double-star character `**` is supported by default, unless the
+`noglobstar` flag is set.  This is supported in the manner of bsdglob
+and bash 4.3, where `**` only has special significance if it is the only
+thing in a path part.  That is, `a/**/b` will match `a/x/y/b`, but
+`a/**b` will not.
+
+Note that symlinked directories are not crawled as part of a `**`,
+though their contents may match against subsequent portions of the
+pattern.  This prevents infinite loops and duplicates and the like.
+
+If an escaped pattern has no matches, and the `nonull` flag is set,
+then glob returns the pattern as-provided, rather than
+interpreting the character escapes.  For example,
+`glob.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
+`"*a?"`.  This is akin to setting the `nullglob` option in bash, except
+that it does not resolve escaped pattern characters.
+
+If brace expansion is not disabled, then it is performed before any
+other interpretation of the glob pattern.  Thus, a pattern like
+`+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
+**first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
+checked for validity.  Since those two are valid, matching proceeds.
+
+## Windows
+
+**Please only use forward-slashes in glob expressions.**
+
+Though windows uses either `/` or `\` as its path separator, only `/`
+characters are used by this glob implementation.  You must use
+forward-slashes **only** in glob expressions.  Back-slashes will always
+be interpreted as escape characters, not path separators.
+
+Results from absolute patterns such as `/foo/*` are mounted onto the
+root setting using `path.join`.  On windows, this will by default result
+in `/foo/*` matching `C:\foo\bar.txt`.
+
+## Race Conditions
+
+Glob searching, by its very nature, is susceptible to race conditions,
+since it relies on directory walking and such.
+
+As a result, it is possible that a file that exists when glob looks for
+it may have been deleted or modified by the time it returns the result.
+
+As part of its internal implementation, this program caches all stat
+and readdir calls that it makes, in order to cut down on system
+overhead.  However, this also makes it even more susceptible to races,
+especially if the cache or statCache objects are reused between glob
+calls.
+
+Users are thus advised not to use a glob result as a guarantee of
+filesystem state in the face of rapid changes.  For the vast majority
+of operations, this is never a problem.
+
+## Contributing
+
+Any change to behavior (including bugfixes) must come with a test.
+
+Patches that fail tests or reduce performance will be rejected.
+
+```
+# to run tests
+npm test
+
+# to re-generate test fixtures
+npm run test-regen
+
+# to benchmark against bash/zsh
+npm run bench
+
+# to profile javascript
+npm run prof
+```