sproutcore 0.9.13 → 0.9.14

data/jsdoc/app/run.js

@@ -1,144 +1,346 @@
-var VERBOSE = false;
-try {
-	importClass(java.lang.System);
+/**
+ * @fileOverview
+ * A bootstrap script that creates some basic required objects
+ * for loading other scripts.
+ * @author Michael Mathews, micmath@gmail.com
+ * @version $Id: run.js 554 2008-04-01 00:12:25Z micmath $
+ */
+
+/**
+ * @namespace Keep track of any messages from the running script.
+ */
+LOG = {
+  warn: function(msg, e) {
+    if (e) msg = e.fileName+", line "+e.lineNumber+": "+msg;
+    
+    msg = ">> WARNING: "+msg;
+    LOG.warnings.push(msg);
+    if (LOG.out) LOG.out.write(msg+"\n");
+    else print(msg);
+  },
+
+  inform: function(msg) {
+    msg = " > "+msg;
+    if (LOG.out) LOG.out.write(msg+"\n");
+    else if (typeof LOG.verbose != "undefined" && LOG.verbose) print(msg);
+  }
+};
+LOG.warnings = [];
+LOG.verbose = false
+LOG.out = undefined;
+
+/**
+ *  @class Manipulate a filepath.
+ */
+function FilePath(absPath, separator) {
+  this.slash =  separator || "/"; 
+  this.root = this.slash;
+  this.path = [];
+  this.file = "";
+  
+  var parts = absPath.split(/[\\\/]/);
+  if (parts) {
+    if (parts.length) this.root = parts.shift() + this.slash;
+    if (parts.length) this.file =  parts.pop()
+    if (parts.length) this.path = parts;
+  }
+  
+  this.path = this.resolvePath();
+}
+
+/** Collapse any dot-dot or dot items in a filepath. */
+FilePath.prototype.resolvePath = function() {
+  var resolvedPath = [];
+  for (var i = 0; i < this.path.length; i++) {
+    if (this.path[i] == "..") resolvedPath.pop();
+    else if (this.path[i] != ".") resolvedPath.push(this.path[i]);
+  }
+  return resolvedPath;
+}
+
+/** Trim off the filename. */
+FilePath.prototype.toDir = function() {
+  if (this.file) this.file = "";
+  return this;
 }
-catch (e) {
-	throw "RuntimeException: The class java.lang.System is required to run this script.";
+
+/** Go up a directory. */
+FilePath.prototype.upDir = function() {
+  this.toDir();
+  if (this.path.length) this.path.pop();
+  return this;
 }
 
-var __DIR__ = (System.getProperty("jsdoc.dir")||System.getProperty("user.dir"))+Packages.java.io.File.separator;
-
-/** Load required libraries. */
-function require(lib) {
-	var libDirs = ['', __DIR__, __DIR__+'app/', __DIR__+'../'];
-	var libErrors = [];
-	for(var i = 0; i < libDirs.length; i++) {
-		try {
-			var file = new Packages.java.io.File(libDirs[i]+lib);
-			if(!file.exists()) {
-				libErrors.push('Could not find: ['+(libDirs[i]+lib)+']');
-			}
-			else {
-				if (VERBOSE) print("Loading: ["+(libDirs[i]+lib)+"] ...");
-				load(libDirs[i]+lib);
-				return;
-			}
-		}
-		catch (e) {
-			libErrors.push('Error loading: ['+(libDirs[i]+lib)+']');
-		}
-	}
-	for(var i=0; i < libErrors.length; i++) {
-		print("ERROR: ["+libErrors[i]+"]");
-	}
-	quit();
+FilePath.prototype.toString = function() {
+  return this.root
+    + this.path.join(this.slash)
+    + ((this.path.length > 0)? this.slash : "")
+    + this.file;
 }
 
-require("app/JsDoc.js");
-require("app/Util.js");
-
-JsDoc.opt = Util.getOptions(arguments, {d:'directory', t:'template', r:'recurse', x:'ext', p:'private', a:'allfunctions', A:'Allfunctions', e:'encoding', o:'out', h:'help', 'D[]':'define'});
-VERBOSE = JsDoc.opt.v;
-
-require("app/JsIO.js");
-require("app/Symbol.js");
-require("app/JsToke.js");
-require("app/JsParse.js");
-require("app/DocTag.js");
-require("app/Doclet.js");
-require("app/DocFile.js");
-require("app/JsPlate.js");
-
-/** The main function. Called automatically. */
-function Main() {
-	if (JsDoc.opt.o) LOG.out = IO.open(JsDoc.opt.o, true);
-	if (!JsDoc.opt.e) JsDoc.opt.e = "utf-8";
-	IO.setEncoding(JsDoc.opt.e);
-	
-	if (JsDoc.opt.c) {
-		eval('conf = '+IO.readFile(JsDoc.opt.c));
-		
-		for (var c in conf) {
-			if (c !== "D") {
-				JsDoc.opt[c] = conf[c];
-			}
-		}
-	}
-	if (JsDoc.opt.h || JsDoc.opt._.length == 0 || JsDoc.opt.t === true) JsDoc.usage();
-	
-	var ext = ["js"];
-	if (JsDoc.opt.x) ext = JsDoc.opt.x.split(",").map(function(x) {return x.toLowerCase()});
-
-	if (typeof(JsDoc.opt.r) == "boolean") JsDoc.opt.r = 10;
-	else if (!isNaN(parseInt(JsDoc.opt.r))) JsDoc.opt.r = parseInt(JsDoc.opt.r);
-	else JsDoc.opt.r = 1;
-		
-	if (JsDoc.opt.d === true || JsDoc.opt.t === true) { // like when a user enters: -d mydir
-		LOG.warn("Option malformed.");
-		JsDoc.usage();
-	}
-	else if (!JsDoc.opt.d) {
-		JsDoc.opt.d = "js_docs_out";
-	}
-
-	JsDoc.opt.d += (JsDoc.opt.d.indexOf(IO.FileSeparator) == JsDoc.opt.d.length-1)?
-		"" : IO.FileSeparator;
-	LOG.inform("Creating output directory: "+JsDoc.opt.d);
-	IO.makeDir(JsDoc.opt.d);
-	
-	LOG.inform("Scanning for source files: recursion set to "+JsDoc.opt.r+" subdir"+((JsDoc.opt.r==1)?"":"s")+".");
-	function isJs(element, index, array) {
-		var thisExt = element.split(".").pop().toLowerCase();
-		return (ext.indexOf(thisExt) > -1); // we're only interested in files with certain extensions
-	}
-	var srcFiles = [];
-	for (var d = 0; d < JsDoc.opt._.length; d++) {
-		srcFiles = srcFiles.concat(
-			IO.ls(JsDoc.opt._[d], JsDoc.opt.r).filter(isJs)
-		);
-	}
-	
-	LOG.inform(srcFiles.length+" source file"+((srcFiles ==1)?"":"s")+" found:\n\t"+srcFiles.join("\n\t"));
-	var fileGroup = JsDoc.parse(srcFiles, JsDoc.opt);
-	
-	var D = {};
-	if (JsDoc.opt.D) {
-		for (var i = 0; i < JsDoc.opt.D.length; i++) {
-			var defineParts = JsDoc.opt.D[i].split(":", 2);
-			D[defineParts[0]] = defineParts[1];
-		}
-		JsDoc.opt.D = D;
-	}
-	else {
-		JsDoc.opt.D = {};
-	}
-
-	// combine any conf file D options with the commandline D options
-	if (typeof conf != "undefined") for (var c in conf.D) {
-		if (typeof JsDoc.opt.D[c] == "undefined") {
-			JsDoc.opt.D[c] = conf.D[c];
-		}
-	}
-	
-	if (JsDoc.opt.t && IO.exists(JsDoc.opt.t)) {
-		JsDoc.opt.t += (JsDoc.opt.t.indexOf(IO.FileSeparator)==JsDoc.opt.t.length-1)?
-			"" : IO.FileSeparator;
-		LOG.inform("Loading template: "+JsDoc.opt.t+"publish.js");
-		require(JsDoc.opt.t+"publish.js");
-		
-		LOG.inform("Publishing all files...");
-		publish(fileGroup, JsDoc.opt);
-		LOG.inform("Finished.");
-	}
-	else {
-		LOG.warn("Use the -t option to specify a template for formatting.");
-		LOG.warn("Dumping results to stdout.");
-		require("app/Dumper.js");
-		print(Dumper.dump(fileGroup));
-	}
-	
-	if (LOG.out) LOG.out.close();
-	if (LOG.warnings.length > 0) print(LOG.warnings.length+" warnings.");
+/**
+ * Turn a path into just the name of the file.
+ */
+FilePath.fileName = function(path) {
+  var nameStart = Math.max(path.lastIndexOf("/")+1, path.lastIndexOf("\\")+1, 0);
+  return path.substring(nameStart);
 }
 
-Main();
+/**
+ * Get the extension of a filename
+ */
+FilePath.fileExtension = function(filename) {
+   return filename.split(".").pop().toLowerCase();
+};
+
+/**
+ * Turn a path into just the directory part.
+ */
+FilePath.dir = function(path) {
+  var nameStart = Math.max(path.lastIndexOf("/")+1, path.lastIndexOf("\\")+1, 0);
+  return path.substring(0, nameStart-1);
+}
+
+
+importClass(java.lang.System);
+
+/**
+ * @namespace A collection of information about your system.
+ */
+SYS = {
+  /**
+   * Information about your operating system: arch, name, version.
+   * @type string
+   */
+  os: [
+    new String(System.getProperty("os.arch")),
+    new String(System.getProperty("os.name")),
+    new String(System.getProperty("os.version"))
+  ].join(", "),
+  
+  /**
+   * Which way does your slash lean.
+   * @type string
+   */
+  slash: System.getProperty("file.separator")||"/",
+  
+  /**
+   * The path to the working directory where you ran java.
+   * @type string
+   */
+  userDir: new String(System.getProperty("user.dir")),
+  
+  /**
+   * Where is Java's home folder.
+   * @type string
+   */
+  javaHome: new String(System.getProperty("java.home")),
+  
+  /**
+   * The absolute path to the directory containing this script.
+   * @type string
+   */
+  pwd: undefined
+};
+
+// jsrun appends an argument, with the path to here.
+if (arguments[arguments.length-1].match(/^-j=(.+)/)) {
+  if (RegExp.$1.charAt(0) == SYS.slash || RegExp.$1.charAt(1) == ":") { // absolute path to here
+    SYS.pwd = new FilePath(RegExp.$1).toDir().toString();
+  }
+  else { // relative path to here
+    SYS.pwd = new FilePath(SYS.userDir + SYS.slash + RegExp.$1).toDir().toString();
+  }
+  arguments.pop();
+}
+else {
+  print("The run.js script requires you use jsrun.jar.");
+  quit();
+}
+
+// shortcut
+var File = Packages.java.io.File;
+
+/**
+ * @namespace A collection of functions that deal with reading a writing to disk.
+ */
+IO = {
+
+  /**
+   * Create a new file in the given directory, with the given name and contents.
+   */
+  saveFile: function(/**string*/ outDir, /**string*/ fileName, /**string*/ content) {
+    var out = new Packages.java.io.PrintWriter(
+      new Packages.java.io.OutputStreamWriter(
+        new Packages.java.io.FileOutputStream(outDir+SYS.slash+fileName),
+        IO.encoding
+      )
+    );
+    out.write(content);
+    out.flush();
+    out.close();
+  },
+  
+  /**
+   * @type string
+   */
+  readFile: function(/**string*/ path) {
+    if (!IO.exists(path)) {
+      throw "File doesn't exist there: "+path;
+    }
+    return readFile(path, IO.encoding);
+  },
+
+  /**
+   * @param inFile 
+   * @param outDir
+   * @param [fileName=The original filename]
+   */
+  copyFile: function(/**string*/ inFile, /**string*/ outDir, /**string*/ fileName) {
+    if (fileName == null) fileName = FilePath.fileName(inFile);
+  
+    var inFile = new File(inFile);
+    var outFile = new File(outDir+SYS.slash+fileName);
+    
+    var bis = new Packages.java.io.BufferedInputStream(new Packages.java.io.FileInputStream(inFile), 4096);
+    var bos = new Packages.java.io.BufferedOutputStream(new Packages.java.io.FileOutputStream(outFile), 4096);
+    var theChar;
+    while ((theChar = bis.read()) != -1) {
+      bos.write(theChar);
+    }
+    bos.close();
+    bis.close();
+  },
+
+  /**
+   * Creates a series of nested directories.
+   */
+  mkPath: function(/**Array*/ path) {
+    if (path.constructor != Array) path = path.split(/[\\\/]/);
+    var make = "";
+    for (var i = 0, l = path.length; i < l; i++) {
+      make += path[i] + SYS.slash;
+      if (! IO.exists(make)) {
+        IO.makeDir(make);
+      }
+    }
+  },
+  
+  /**
+   * Creates a directory at the given path.
+   */
+  makeDir: function(/**string*/ path) {
+    (new File(path)).mkdir();
+  },
+
+  /**
+   * @type string[]
+   * @param dir The starting directory to look in.
+   * @param [recurse=1] How many levels deep to scan.
+   * @returns An array of all the paths to files in the given dir.
+   */
+  ls: function(/**string*/ dir, /**number*/ recurse, _allFiles, _path) {
+    if (_path === undefined) { // initially
+      var _allFiles = [];
+      var _path = [dir];
+    }
+    if (_path.length == 0) return _allFiles;
+    if (recurse === undefined) recurse = 1;
+    
+    dir = new File(dir);
+    if (!dir.directory) return [String(dir)];
+    var files = dir.list();
+    
+    for (var f = 0; f < files.length; f++) {
+      var file = String(files[f]);
+      if (file.match(/^\.[^\.\/\\]/)) continue; // skip dot files
+  
+      if ((new File(_path.join(SYS.slash)+SYS.slash+file)).list()) { // it's a directory
+        _path.push(file);
+        if (_path.length-1 < recurse) IO.ls(_path.join(SYS.slash), recurse, _allFiles, _path);
+        _path.pop();
+      }
+      else {
+        _allFiles.push((_path.join(SYS.slash)+SYS.slash+file).replace(SYS.slash+SYS.slash, SYS.slash));
+      }
+    }
+  
+    return _allFiles;
+  },
+
+  /**
+   * @type boolean
+   */
+  exists: function(/**string*/ path) {
+    file = new File(path);
+  
+    if (file.isDirectory()){
+      return true;
+    }
+    if (!file.exists()){
+      return false;
+    }
+    if (!file.canRead()){
+      return false;
+    }
+    return true;
+  },
+
+  /**
+   * 
+   */
+  open: function(/**string*/ path, /**string*/ append) {
+    var append = true;
+    var outFile = new File(path);
+    var out = new Packages.java.io.PrintWriter(
+      new Packages.java.io.OutputStreamWriter(
+        new Packages.java.io.FileOutputStream(outFile, append),
+        IO.encoding
+      )
+    );
+    return out;
+  },
+
+  /**
+   * Sets {@link IO.encoding}.
+   * Encoding is used when reading and writing text to files,
+   * and in the meta tags of HTML output.
+   */
+  setEncoding: function(/**string*/ encoding) {
+    if (/ISO-8859-([0-9]+)/i.test(encoding)) {
+      IO.encoding = "ISO8859_"+RegExp.$1;
+    }
+    else {
+      IO.encoding = encoding;
+    }
+  },
+
+  /**
+   * @default "utf-8"
+   * @private
+   */
+  encoding: "utf-8",
+  
+  /**
+   * Load the given script.
+   */
+  include: function(relativePath) {
+    load(SYS.pwd+relativePath);
+  },
+  
+  /**
+   * Loads all scripts from the given directory path.
+   */
+  includeDir: function(path) {
+    if (!path) return;
+    
+    for (var lib = IO.ls(SYS.pwd+path), i = 0; i < lib.length; i++) 
+      load(lib[i]);
+  }
+}
+
+// now run the application
+IO.include("frame.js");
+IO.include("main.js");
+
+main();

data/jsdoc/changes.txt

@@ -0,0 +1,47 @@
+== 2.0.1 ==
+
+  * Fixed bug that prevented @fileOverview tag from being recognized.
+  * Added support for @fieldOf as a synonym for @field plus @memberOf.
+  * Added support for @name tag in a @fileOverview comment to control the displayed name of the file.
+  * Added support for multiple @example tags. ( issue #152 )
+  * Modified style sheet of jsdoc template to make more readable. ( issue #151 )
+  * Fixed bug that prevented @since documentation from displaying correctly when it appeared in a class. ( issue #150 )
+  * Fixed bug that caused inhertited properties to sometimes not resolve correctly. ( issue #144 )
+  * Modified so that trailing whitespace in @example is always trimmed. ( issue #153 )
+  * Added support for elseif to JsPlate. (hat tip to fredck)
+  * Added support for @location urls in the @overview comment to the jsdoc template.
+
+== Changes From Versions 1.4.0 to 2.0.0 ==
+
+  * Upgraded included version of Rhino from 1.6 to 1.7R1.
+  * Removed circular references in parsed documentation objects.
+  * Improved inheritance handling, now properties and events can be inherited same as methods.
+  * Improved handling of cross-file relationships, now having two related objects in separate files is not a problem.
+  * Improved ability to recognize membership of previously defined objects.
+  * Added ability to redefine parsing behavior with plugins.
+  * @methodOf is a synonym for @function and @memberOf.
+  * Added @default to document default values of members that are objects.
+  * Added ability to parse and refer to inner functions.
+  * Fixed bug that appeared when calling a method to set properties of the instance referred to by "this".
+  * Added ability to automatically create links to other symbols.
+  * New "jsdoc" template now produces fully W3C valid XHTML.
+  * Inline parameter type hint comments are now documented.
+  * Fixed error: Locally scoped variables (declared with var) no longer appear as global.
+  * It is now possible to run JsDoc Toolkit from any directory.
+  * Added support for inline {@link ...} tags.
+  * Added support for the -H command-line option to allow for custom content handlers.
+  * Tag names @inherits and @scope changed to @borrows and @lends.
+  ? Combining @constructor in a doclet with @lends now supported.
+  * Multiple @lend tags now supported.
+  * Added support for the @constructs tag, used inside a @lends block.
+  * Added support for the @constant tag.
+  * Fixed bug that prevented the use of [] as a default value.
+  * Added support for the @field tag.
+  * Added support for the @public tag (applied to inner functions).
+  * @namespace tag can now be applied to functions, not just object literals.
+  * Added support for the -s command line option to suppress source code output.
+  * Added new unit test framework.
+  * Underscored symbols are now treated as if they have a @private tag by default.
+  * Improved support for anonymous constructors.
+  * Added support for the nocode meta tag.
+  

data/jsdoc/conf/sample.conf

@@ -0,0 +1,31 @@
+/*
+  This is an example of one way you could set up a configuration file to more
+  conveniently define some commandline options. You might like to do this if
+  you frequently reuse the same options. Note that you don't need to define
+  every option in this file, you can combine a configuration file with
+  additional options on the commandline if your wish.
+  
+  You would include this configuration file by running JsDoc Toolkit like so:
+  java -jar jsrun.jar app/run.js -c=conf/sample.conf
+
+*/
+
+{
+  // source files to use
+  _: ['app/test/jsdoc_test.js'],
+  
+  // document all functions, even uncommented ones
+  a: true,
+  
+  // including those marked @private
+  p: true,
+  
+  // some extra variables I want to include
+  D: {generatedBy: "Michael Mathews", copyright: "2008"},
+  
+  // use this directory as the output directory
+  d: "docs",
+  
+  // use this template
+  t: "templates/sproutcore"
+}

data/jsdoc/java/build.xml

@@ -0,0 +1,36 @@
+<project>
+   <target name="clean">
+        <delete dir="build"/>
+    </target>
+
+    <target name="compile">
+        <mkdir dir="build/classes"/>
+        <javac 
+         srcdir="src" destdir="build/classes"
+         classpath="./classes/js.jar"
+        />
+    </target>
+
+    <target name="jar">
+        <mkdir dir="build/jar"/>
+        <jar destfile="build/jar/jsrun.jar" basedir="build/classes">
+            <manifest>
+               <attribute name="Main-Class" value="JsRun"/>
+               <attribute name="Class-Path" value="./java/classes/js.jar"/>
+            </manifest>
+        </jar>
+    </target>
+    
+    <target name="debugjar">
+        <mkdir dir="build/jar"/>
+        <jar destfile="build/jar/jsdebug.jar" basedir="build/classes">
+            <manifest>
+               <attribute name="Main-Class" value="JsDebugRun"/>
+               <attribute name="Class-Path" value="./java/classes/js.jar"/>
+            </manifest>
+        </jar>
+    </target>
+
+    <target name="clean-build" depends="clean,compile,jar"/>
+    <target name="clean-debug" depends="clean,compile,debugjar"/>
+</project>

data/jsdoc/java/build_1.4.xml

@@ -0,0 +1,36 @@
+<project default="clean-build"><!-- use this build script if you are stuck with ant version 1.4 -->
+   <target name="clean">
+        <delete dir="build"/>
+    </target>
+
+    <target name="compile">
+        <mkdir dir="build/classes"/>
+        <javac 
+         srcdir="src" destdir="build/classes"
+         classpath="./classes/js.jar"
+        />
+    </target>
+
+    <target name="jar">
+        <mkdir dir="build/jar"/>
+        <jar jarfile="build/jar/jsrun.jar" basedir="build/classes">
+            <manifest>
+               <attribute name="Main-Class" value="JsRun"/>
+               <attribute name="Class-Path" value="./java/classes/js.jar"/>
+            </manifest>
+        </jar>
+    </target>
+    
+    <target name="debugjar">
+        <mkdir dir="build/jar"/>
+        <jar jarfile="build/jar/jsdebug.jar" basedir="build/classes">
+            <manifest>
+               <attribute name="Main-Class" value="JsDebugRun"/>
+               <attribute name="Class-Path" value="./java/classes/js.jar"/>
+            </manifest>
+        </jar>
+    </target>
+
+    <target name="clean-build" depends="clean,compile,jar"/>
+    <target name="clean-debug" depends="clean,compile,debugjar"/>
+</project>

data/jsdoc/java/src/JsDebugRun.java

@@ -0,0 +1,21 @@
+/**
+ * A trivial bootstrap class that simply adds the path to the
+ * .js file as an argument to the Rhino call. This little hack
+ * allows the code in the .js file to have access to it's own 
+ * path via the Rhino arguments object. This is necessary to 
+ * allow the .js code to find resource files in a location 
+ * relative to itself.
+ *
+ * USAGE: java -jar jsdebug.jar path/to/file.js
+ */
+public class JsDebugRun {
+  public static void main(String[] args) {
+    String[] jsargs = {"-j="+args[0]};
+    
+    String[] allArgs = new String[jsargs.length + args.length];
+    System.arraycopy(args, 0, allArgs, 0, args.length);
+    System.arraycopy(jsargs, 0, allArgs, args.length ,jsargs.length);
+
+    org.mozilla.javascript.tools.debugger.Main.main(allArgs);
+    }
+}

data/jsdoc/java/src/JsRun.java

@@ -0,0 +1,21 @@
+/**
+ * A trivial bootstrap class that simply adds the path to the
+ * .js file as an argument to the Rhino call. This little hack
+ * allows the code in the .js file to have access to it's own 
+ * path via the Rhino arguments object. This is necessary to 
+ * allow the .js code to find resource files in a location 
+ * relative to itself.
+ *
+ * USAGE: java -jar jsrun.jar path/to/file.js
+ */
+public class JsRun {
+  public static void main(String[] args) {
+    String[] jsargs = {"-j="+args[0]};
+    
+    String[] allArgs = new String[jsargs.length + args.length];
+    System.arraycopy(args, 0, allArgs, 0, args.length);
+    System.arraycopy(jsargs, 0, allArgs, args.length ,jsargs.length);
+
+    org.mozilla.javascript.tools.shell.Main.main(allArgs);
+    }
+}