xpcomcore-rubygem 0.3.1 → 0.3.2

data/xpcomcore/lib/file.js

@@ -0,0 +1,75 @@
+/** 
+ * @fileoverview This file defines the implementation of our File object.
+ */
+
+/**
+ * @class File class used for things such as creating filesystem paths, reading files, etc.
+ */
+function File() {};
+
+/** 
+ * @class Exception representing an error loading a file.
+ * @extends Error
+ * @constructor
+ * @param {String} message The error message to be given for this exception.
+ * @returns {Error}
+ */
+File.NoSuchFileError = function(message) {
+  var err = new Error(message);
+  err.name = "File.NoSuchFileError";
+  return err;
+};
+
+/** 
+ * Joins the given string arguments together using the operating system's native path
+ * separator.
+ * @param {String[]} components Set of strings to join together.
+ * @returns {String} The resulting path.
+ */
+File.join = function() {
+  var file = new XPCBuiltins.nsILocalFile(arguments[0]);
+  
+  for(var i = 1; i < arguments.length; i++) {
+    file.append(arguments[i]);
+  }
+  
+  return file.path;
+};
+
+/** 
+ * Reads the given number of bytes (or the entire contents if the argument is ommitted)
+ * from the specified file
+ * @param {String} filePath Path to a file.
+ * @param {int} [maxBytes] Number of bytes to read from the file. Defaults to entire file.
+ * @returns {String} The data read from the given file.
+ */
+File.read = function(filePath, maxBytes) {
+  var file = new XPCBuiltins.nsILocalFile(filePath);
+
+  if (!file.exists()) { throw(new File.NoSuchFileError("No such file or directory - " + filePath)); };
+
+  var fileInputStream = $Cc["@mozilla.org/network/file-input-stream;1"].createInstance($Ci.nsIFileInputStream);
+  fileInputStream.init(file, -1, -1, 0);
+  
+  var binaryInputStream = $Cc["@mozilla.org/binaryinputstream;1"].createInstance($Ci.nsIBinaryInputStream);
+  binaryInputStream.setInputStream(fileInputStream);
+  
+  try {
+    return binaryInputStream.readBytes((maxBytes == null) ? binaryInputStream.available() : maxBytes);
+  } catch (e if e.result == $Cr.NS_ERROR_FAILURE) {
+    // FIXME - hack
+    // If we hit this, we're probably trying to read from a special device like a pipe. Fall back to
+    // reading a byte at a time and returning when we likely hit EOF (as indicated by another exception)
+    var output = '';
+    while (true) {
+      try {
+        output = output + binaryInputStream.readBytes((maxBytes == null) ? 1 : maxBytes);
+        if (maxBytes != null) { return output; }
+      } catch (e if e.result == $Cr.NS_ERROR_FAILURE) {
+        return output;
+      }
+    };
+  } finally {
+    binaryInputStream.close();
+  }
+};

data/xpcomcore/lib/kernel.js

@@ -0,0 +1,243 @@
+/** 
+ * @fileoverview This file specifies a set of globally useful features/shortcuts
+ * and defines our "Kernel" object, which is the base for doing a lot of simple
+ * things with XPCOMCore such as loading in other files and printing to the
+ * console.
+ */
+
+/** 
+ * @class Exception representing an error loading a file.
+ * @extends Error
+ * @constructor
+ * @param {String} message The error message to be given for this exception.
+ * @returns {Error}
+ */
+function LoadError(message) {
+  var err = new Error(message);
+  err.name = arguments.callee.name;
+  return err;
+};
+
+/** 
+ * @class Exception representing an error determining what the path to the currently executing file is.
+ * @extends Error
+ * @constructor
+ * @param {String} message The error message to be given for this exception.
+ * @returns {Error}
+ */
+function SelfConceptError(message) {
+  var err = new Error(message);
+  err.name = arguments.callee.name;
+  return err;
+};
+
+/**
+ * A pseudo-constructor to make JSDoc happy and actually document things in {@link Kernel}.
+ * If this method is called with an argument, all properties from {@link Kernel} are taken
+ * and defined as the return value of getter methods set on the given object.
+ * @class Our central 'class' containing a lot of properties and methods we need to
+ * build the rest of XPCOMCore on top of.
+ * @param {Object} mixinScope Optional argument, any object to mix {@link Kernel}'s properties
+ * into.
+ * @return The prototype object of the Kernel function.
+ */
+function Kernel(mixinScope) {
+  var myPrototype = arguments.callee.prototype;
+  if (mixinScope) {
+    // FIXME - figure out a better way than this object jammed in here to special case our
+    // methods we really want to be calling getters when they're mixed in.
+    var callingGetters = {'$CURRENT_FILE': {defaultArgs: [2]}, '$CURRENT_DIRECTORY': {defaultArgs: [3] }};
+    var makeGetter = function(attr) { return function() { return myPrototype[attr]; } };
+    var makeCallingGetter = function(attr, argsArray) { 
+      return function() { 
+        return myPrototype[attr].apply(this, argsArray); 
+      }
+    };
+        
+    for (var p in myPrototype) { 
+      if (callingGetters[p]) {
+        mixinScope.__defineGetter__(p, makeCallingGetter(p, callingGetters[p].defaultArgs || []));
+      } else {
+        mixinScope.__defineGetter__(p, makeGetter(p)); 
+      }
+    };
+    
+    // Load up our standard library into the mixinScope.
+    var standardLibraries = ['file', 'sys', 'xpc_builtins'];
+    var standardLibraryLoader = function() {
+      standardLibraries.forEach(function(library) { require(library); }, this);
+    };
+    standardLibraryLoader.call(mixinScope);
+  };
+  return myPrototype;
+};
+
+Kernel.prototype = {
+  /** 
+   * A shortcut constant to Components.classes.
+   */
+  $Cc: Components.classes,
+
+  /** 
+   * A shortcut constant to Components.interfaces.
+   */
+  $Ci: Components.interfaces,
+
+  /** 
+   * A shortcut constant to Components.results.
+   */
+  $Cr: Components.results,
+
+  /** 
+   * A shortcut constant to Components.utils.
+   */
+  $Cu: Components.utils,
+  
+  /** 
+   * Taking inspiration from Ruby, this defines the set of paths to check when
+   * trying to load a file via either {@link Kernel#load} or {@link Kernel#require}.
+   * @type Array
+   */
+  $LOAD_PATH: [XPCOMCoreConfig.getProperty('libRoot')],
+
+  /** 
+   * Taking inspiration from Ruby, this defines the currently loaded files that
+   * have been loaded through {@link Kernel#require}.
+   * @type Array
+   */
+  $LOADED_FEATURES: ["kernel.js"],
+  
+  /** 
+   * Taking inspiration from Ruby, this method tries to determine the filesystem path to
+   * the caller code of this method.
+   * NOTE - when {@link Kernel} is mixed into an object, this function gets mixed in via
+   * a special case behaviour that makes it a getter that actually calls the function 
+   * rather than returning the function object itself. This is to facilitate being able
+   * to call '$CURRENT_FILE' in your code rather than '$CURRENT_FILE()'. The stackTraversalDepth
+   * parameter is there for this reason, since we need to traverse the stack further than
+   * normal to find the calling scope than we normally would.
+   * @returns {String} The path to the current file
+   * @param {int} stackTraversalDepth Optional argument, how far to look up the stack to
+   * figure out who called us. The default is usually safe.
+   * @throws {SelfConceptError} Thrown when we can't figure out what the filesystem
+   * path to the current file is.
+   */
+  $CURRENT_FILE: function(stackTraversalDepth) {
+    try {
+      var stackTraversalDepth = stackTraversalDepth || 1;
+      var ioService = $Cc["@mozilla.org/network/io-service;1"].getService($Ci.nsIIOService);
+      // FIXME - UGH. This is so seedy.
+      // Traverse up the stack as far as needed to get our caller's stack frame. Sometimes we need to
+      // traverse more than one level up, like when this function is actually called from a getter
+      // property that references it.
+      var callerStack = Components.stack;
+      for (var i = 0; i < stackTraversalDepth; i++) {
+        callerStack = callerStack.caller;
+      }
+      // Split based on the stupid fucking " -> " Gecko puts in the filename and get the last entry
+      var ostensiblyUs = callerStack.filename.split(" -> ").slice(-1);
+      var callerFileURI = ioService.newURI(ostensiblyUs, null, null);
+      // QI for an nsIFileURL which lets us get a handle on an actual file attribute and automagically does
+      // resource: URL resolution for us
+      callerFileURI.QueryInterface($Ci.nsIFileURL);
+      // And theoretically, we can now get a handle on an nsIFile and return the path of that.
+      return callerFileURI.file.path;
+    } catch(e) {
+      throw(new SelfConceptError("The filesystem location of the current file could not be determined. -- " + e));
+    }
+  },
+  
+  /** 
+   * This method tries to determine the filesystem path to parent directory of the caller 
+   * code of this method NOTE - see the note on $CURRENT_FILE, as the same applies here.
+   * @returns {String} The path to the current directory
+   * @param {int} stackTraversalDepth Optional argument, how far to look up the stack to
+   * figure out who called us. The default is usually safe.
+   * @throws {SelfConceptError} Thrown when we can't figure out what the filesystem
+   * path to the parent directory of the current file is.
+   */
+  $CURRENT_DIRECTORY: function(stackTraversalDepth) {
+    var stackTraversalDepth = stackTraversalDepth || 2;
+    var currentFilePath = Kernel.prototype.$CURRENT_FILE(stackTraversalDepth);
+    
+    var file = new XPCBuiltins.nsILocalFile(currentFilePath);
+    return file.parent.path;
+  },
+  
+  /**
+   * Returns a reference to an object allowing for get()/set() on environment variables.
+   * @type nsIEnvironment
+   */
+   
+  $ENV: Components.classes["@mozilla.org/process/environment;1"].getService(Components.interfaces.nsIEnvironment),
+  
+  /** 
+   * Prints a string to standard out, without a trailing newline.
+   * @param {String} str String to print to standard out.
+   */
+  print: function(str) {
+    dump(str);
+  },
+  
+  /** 
+   * Prints a string to standard out, with a trailing newline.
+   * @param {String} str String to print to standard out.
+   */
+  puts: function(str) {
+    print(str + "\n");
+  },
+  
+  /**
+   * Searches {@link Kernel#$LOAD_PATH} for files to load into the current global scope.
+   * Files loaded via this method will not be added to {@link Kernel#$LOADED_FEATURES} and hence
+   * can be repeatedly loaded and executed.
+   * @param {String} featurePath Full or relative path including file extension to try and load.
+   * @returns {Boolean} True if the file was loaded succesfully
+   * @throws {LoadError} Thrown when we can't find the specified file in any directories specified
+   * in {@link Kernel#$LOAD_PATH}.
+   */
+  load: function(featurePath) {
+    var loader = $Cc["@mozilla.org/moz/jssubscript-loader;1"].getService($Ci.mozIJSSubScriptLoader);
+    var foundFile = null;
+    // FIXME - so this is kinda shitty. We have an empty entry here so we default to just trying to load 
+    // from an absolute path
+    var loadPath = $LOAD_PATH.concat([""]);
+    var loadPathLength = loadPath.length;
+    // FIXME - mozilla bug here. if i use foreach on array it ignores the granted security privileges
+    for (var i = 0; i < loadPathLength; i++) {
+      var potentialFile = $Cc["@mozilla.org/file/local;1"].createInstance($Ci.nsILocalFile);
+      potentialFile.initWithPath(loadPath[i] + "/" + featurePath);
+      if (potentialFile.exists()) { 
+        foundFile = potentialFile; 
+        break;
+      }
+    };
+    if (foundFile) {
+      foundFile.normalize();
+      loader.loadSubScript("file://" + encodeURI(foundFile.path));
+      return true;
+    } else {
+      throw(new LoadError("no such file to load -- " + featurePath));
+    }
+  },
+
+  /**
+   * Searches {@link Kernel#$LOAD_PATH} for features to load into the current global scope.
+   * Files loaded via this method will be added to {@link Kernel#$LOADED_FEATURES} and hence two 
+   * consecutive calls to this method will not load and execute the code twice.
+   * @returns {Boolean} True if successful, false if the specified feature has already been required.
+   * @param {String} featurePath Full or relative path without the file extension to try and require.
+   * @throws {LoadError} Thrown when we can't find the specified feature in any directories specified
+   * in {@link Kernel#$LOAD_PATH}.
+   */  
+  require: function(feature) {
+    var jsFeature = feature + ".js";
+    if ($LOADED_FEATURES.indexOf(jsFeature) == -1) {
+      load(jsFeature);
+      $LOADED_FEATURES.push(jsFeature);
+      return true;
+    } else {
+      return false;
+    }
+  }
+};

data/xpcomcore/lib/sys.js

@@ -0,0 +1,52 @@
+/** 
+ * @fileoverview This file defines the implementation of our Sys namespace.
+ */
+
+/**
+ * @namespace Sys namespace used for things such as executing external commands.
+ */
+ 
+var Sys = {
+  
+  /** 
+   * This getter returns the current temp directory as returned by the XPCOM directory service.
+   * @returns {String} The path to the temp directory
+   */
+  get tempDir() {
+    return $Cc["@mozilla.org/file/directory_service;1"].getService($Ci.nsIProperties).get("TmpD", $Ci.nsIFile).path;
+  },
+  
+  /** 
+   * Runs the command given as the first parameter with the arguments given as the remaining
+   * parameters and returns an object containing the exit status (as the exitStatus property)
+   * and command output (as the output property).
+   * @param {String[]} parameters First parameter is command name, rest are arguments to
+   * invoke the command with.
+   * @returns {Object} Object with 'exitStatus' and 'output' properties.
+   */
+  run: function() {
+    var tempDir = Sys.tempDir;
+    var popenHelper = File.join(XPCOMCoreConfig.getProperty('binRoot'), "popen_helper.sh");
+    var file = new XPCBuiltins.nsILocalFile(popenHelper);
+
+    var process = $Cc["@mozilla.org/process/util;1"].createInstance($Ci.nsIProcess);
+    process.init(file);
+    
+    var args = Array.prototype.slice.call(arguments);
+    var procArgs = [tempDir, "stdout"].concat(args);
+    
+    process.run(false, procArgs, procArgs.length);
+    
+    var outputPipe = File.join(tempDir, process.pid + ".stdout.pipe");
+    var outputPipeFile = new XPCBuiltins.nsILocalFile(outputPipe);
+    
+    var output = null;
+    while (!outputPipeFile.exists()) {
+      null;
+    };
+    
+    output = File.read(outputPipe);
+    
+    return({exitStatus: process.exitValue, output: output});
+  }
+};

data/xpcomcore/lib/xpc_builtins.js

@@ -0,0 +1,13 @@
+/** 
+ * @fileoverview This file defines the implementation of our XPCBuiltins namespace.
+ */
+
+/**
+ * @namespace XPCBuiltins namespace used for holding constructors for standard XPCOM objects.
+ */
+ 
+var XPCBuiltins = {
+  
+  nsILocalFile: Components.Constructor("@mozilla.org/file/local;1", $Ci.nsILocalFile, "initWithPath")
+  
+};

data/xpcomcore/test/file_test.js

@@ -0,0 +1,27 @@
+XULTestCase.create("File Test", function(setup, teardown, test) {
+
+  test("File.join should properly put together strings", function() {
+    this.assertEqual($CURRENT_FILE, File.join($CURRENT_DIRECTORY, "file_test.js"));
+  });
+  
+  test("File.read without a maxBytes argument should read the entire contents of a file if it exists", function() {
+    this.assertEqual("var love = true;", File.read(File.join($CURRENT_DIRECTORY, "fixtures", "love.js")));
+  });  
+
+  test("File.read with a maxBytes argument should read the given number of bytes from a file", function() {
+    this.assertEqual("var love", File.read(File.join($CURRENT_DIRECTORY, "fixtures", "love.js"), 8));
+  });
+  
+  test("File.read with a maxBytes argument of 0 shouldn't throw an exception", function() {
+    this.assertEqual("", File.read(File.join($CURRENT_DIRECTORY, "fixtures", "love.js"), 0));
+  });
+  
+  test("File.read with an empty file shouldn't throw an exception", function() {
+    this.assertEqual("", File.read(File.join($CURRENT_DIRECTORY, "fixtures", "empty")));
+  });
+  
+  test("File.read with a non-existent file should throw an exception", function() {
+    this.assertRaise("File.NoSuchFileError", function(){ File.read("/tmp/ohmanihopethisfiledoesntexist"); });
+  });
+  
+});

data/xpcomcore/test/fixtures/love.js

@@ -0,0 +1 @@
+var love = true;

data/xpcomcore/test/fixtures/mad_love.js

@@ -0,0 +1 @@
+var mad_love = true;

data/xpcomcore/test/fixtures/mad_world.js

@@ -0,0 +1 @@
+var mad_world = true;

data/xpcomcore/test/fixtures/syntax_error.js

@@ -0,0 +1 @@
+var ;

data/xpcomcore/test/kernel_test.js

@@ -0,0 +1,95 @@
+XULTestCase.create("Kernel Test", function(setup, teardown, test) {
+  setup(function() {
+    $LOAD_PATH.push(File.join($CURRENT_DIRECTORY, "fixtures"));
+  });
+  
+  test("Kernel() function should mix its properties into the passed in scope", function(){
+    var newScope = {};
+    this.assertNotEqual(0, Kernel.prototype.__count__);
+    this.assertEqual(0, newScope.__count__);
+    Kernel(newScope);
+    this.assertEqual(Kernel.prototype.__count__, newScope.__count__);
+  });
+  
+  
+  test("$CURRENT_FILE should be exposed as a getter that returns a value that is not a function", function(){
+    this.assertNotEqual("function", typeof($CURRENT_FILE));
+  });
+
+  test("$CURRENT_FILE should end in kernel_test.js", function(){
+    this.assertMatch(/kernel_test.js$/, $CURRENT_FILE);
+  });
+
+
+  test("$CURRENT_DIRECTORY should be exposed as a getter that returns a value that is not a function", function(){
+    this.assertNotEqual("function", typeof($CURRENT_DIRECTORY));
+  });
+
+  test("$CURRENT_DIRECTORY should end in test", function(){
+    this.assertMatch(/test$/, $CURRENT_DIRECTORY);
+  });
+  
+  
+  test("load should throw an exception when you give it a non-existent resource", function() {
+    this.assertRaise("LoadError", function() {
+      load("some-junk");
+    });
+  });
+
+  test("load should return true when it can load a file successfully", function() {
+    this.assertEqual(true, load("love.js"));
+  });
+  
+  test("load should bubble up a syntax error if the loaded file is syntactically whack", function() {
+    this.assertRaise("SyntaxError", function() { load("syntax_error.js") });
+  });
+  
+  test("load should allow loading a resource multiple times", function() {
+    load("love.js");
+    this.assertEqual(true, love);
+
+    love = false;
+    load("love.js");
+    this.assertEqual(true, love);
+  });
+  
+  test("load works when using absolute paths", function() {
+    love = false;
+
+    var absolutePath = File.join($CURRENT_DIRECTORY, "fixtures", "love.js");
+    // FIXME: this is unix-only and janky:
+    this.assertMatch(/^\//, absolutePath);
+    
+    load(absolutePath);
+    this.assertEqual(true, love);
+  });
+  
+  
+  test("require should load a file the first time (just like load)", function() {
+    this.assertEqual(true, require("love"));
+  });
+  
+  test("require should return false if the resource has already been loaded", function() {
+    require("mad_love");
+    this.assertEqual(false, require("mad_love"));
+  });
+
+  test("require should not load a resource that's already been loaded", function() {
+    require("mad_world");
+    this.assertEqual(true, mad_world);
+
+    mad_world = false;
+    require("mad_world");
+    this.assertEqual(false, mad_world);
+  });
+  
+  test("should expose a $ENV object that allows for getting environment variables", function() {
+    this.assert($ENV.get('HOME'));
+  });
+  
+  test("should expose a $ENV object that allows for setting environment variables", function() {
+    $ENV.set('XPCOMCORETEST', "testing");
+    this.assertEqual($ENV.get('XPCOMCORETEST'), "testing");
+  });
+  
+});