Subversion Repositories Applications.papyrus

/*

	Copyright (c) 2004-2006, The Dojo Foundation

	All Rights Reserved.

	Licensed under the Academic Free License version 2.1 or above OR the

	modified BSD license. For more information on Dojo licensing, see:

		http://dojotoolkit.org/community/licensing.shtml

*/

dojo.provide("dojo.docs");

dojo.require("dojo.io.*");

dojo.require("dojo.event.topic");

dojo.require("dojo.rpc.JotService");

dojo.require("dojo.dom");

dojo.require("dojo.uri.Uri");

dojo.require("dojo.Deferred");

dojo.require("dojo.DeferredList");

/*

 * TODO:

 *

 * Package summary needs to compensate for "is"

 * Handle host environments

 * Deal with dojo.widget weirdness

 * Parse parameters

 * Limit function parameters to only the valid ones (Involves packing parameters onto meta during rewriting)

 *

 */

dojo.docs = new function() {

	this._url = dojo.uri.dojoUri("docscripts");

	this._rpc = new dojo.rpc.JotService;

	this._rpc.serviceUrl = dojo.uri.dojoUri("docscripts/jsonrpc.php");

};

dojo.lang.mixin(dojo.docs, {

	_count: 0,

	_callbacks: {function_names: []},

	_cache: {}, // Saves the JSON objects in cache

	require: function(/*String*/ require, /*bool*/ sync) {

		dojo.debug("require(): " + require);

		var parts = require.split("/");

		var size = parts.length;

		var deferred = new dojo.Deferred;

		var args = {

			mimetype: "text/json",

			load: function(type, data){

				dojo.debug("require(): loaded for " + require);

				if(parts[0] != "function_names") {

					for(var i = 0, part; part = parts[i]; i++){

						data = data[part];

					}

				}

				deferred.callback(data);

			},

			error: function(){

				deferred.errback();

			}

		};

		if(location.protocol == "file:"){

			if(size){

				if(parts[parts.length - 1] == "documentation"){

					parts[parts.length - 1] = "meta";

				}

				if(parts[0] == "function_names"){

					args.url = [this._url, "local_json", "function_names"].join("/");

				}else{

					var dirs = parts[0].split(".");

					args.url = [this._url, "local_json", dirs[0]].join("/");

					if(dirs.length > 1){

						args.url = [args.url, dirs[1]].join(".");

					}

				}

			}

		}

		dojo.io.bind(args);

		return deferred;

	},

	getFunctionNames: function(){

		return this.require("function_names"); // dojo.Deferred

	},

	unFormat: function(/*String*/ string){

		var fString = string;

		if(string.charAt(string.length - 1) == "_"){

			fString = [string.substring(0, string.length - 1), "*"].join("");

		}

		return fString;

	},

	getMeta: function(/*String*/ pkg, /*String*/ name, /*Function*/ callback, /*String?*/ id){

		// summary: Gets information about a function in regards to its meta data

		if(typeof name == "function"){

			// pId: a

			// pkg: ignore

			id = callback;

			callback = name;

			name = pkg;

			pkg = null;

			dojo.debug("getMeta(" + name + ")");

		}else{

			dojo.debug("getMeta(" + pkg + "/" + name + ")");

		}

		if(!id){

			id = "_";

		}

	},

	_withPkg: function(/*String*/ type, /*Object*/ data, /*Object*/ evt, /*Object*/ input, /*String*/ newType){

		dojo.debug("_withPkg(" + evt.name + ") has package: " + data[0]);

		evt.pkg = data[0];

		if("load" == type && evt.pkg){

			evt.type = newType;

		}else{

			if(evt.callbacks && evt.callbacks.length){

				evt.callbacks.shift()("error", {}, evt, evt.input);

			}

		}

	},

	_gotMeta: function(/*String*/ type, /*Object*/ data, /*Object*/ evt){

		dojo.debug("_gotMeta(" + evt.name + ")");

		var cached = dojo.docs._getCache(evt.pkg, evt.name, "meta", "functions", evt.id);

		if(cached.summary){

			data.summary = cached.summary;

		}

		if(evt.callbacks && evt.callbacks.length){

			evt.callbacks.shift()(type, data, evt, evt.input);

		}

	},

	getSrc: function(/*String*/ name, /*Function*/ callback, /*String?*/ id){

		// summary: Gets src file (created by the doc parser)

		dojo.debug("getSrc(" + name + ")");

		if(!id){

			id = "_";

		}

	},

	getDoc: function(/*String*/ name, /*Function*/ callback, /*String?*/ id){

		// summary: Gets external documentation stored on Jot for a given function

		dojo.debug("getDoc(" + name  + ")");

		if(!id){

			id = "_";

		}

		var input = {};

		input.type = "doc";

		input.name = name;

		input.callbacks = [callback];

	},

	_gotDoc: function(/*String*/ type, /*Array*/ data, /*Object*/ evt, /*Object*/ input){

		dojo.debug("_gotDoc(" + evt.type + ")");

		evt[evt.type] = data;

		if(evt.expects && evt.expects.doc){

			for(var i = 0, expect; expect = evt.expects.doc[i]; i++){

				if(!(expect in evt)){

					dojo.debug("_gotDoc() waiting for more data");

					return;

				}

			}

		}

		var cache = dojo.docs._getCache(evt.pkg, "meta", "functions", evt.name, evt.id, "meta");

		var description = evt.fn.description;

		cache.description = description;

		data = {

			returns: evt.fn.returns,

			id: evt.id,

			variables: []

		}

		if(!cache.parameters){

			cache.parameters = {};

		}

		for(var i = 0, param; param = evt.param[i]; i++){

			var fName = param["DocParamForm/name"];

			if(!cache.parameters[fName]){

				cache.parameters[fName] = {};

			}

			cache.parameters[fName].description = param["DocParamForm/desc"]

		}

		data.description = cache.description;

		data.parameters = cache.parameters;

		evt.type = "doc";

		if(evt.callbacks && evt.callbacks.length){

			evt.callbacks.shift()("load", data, evt, input);

		}

	},

	getPkgDoc: function(/*String*/ name, /*Function*/ callback){

		// summary: Gets external documentation stored on Jot for a given package

		dojo.debug("getPkgDoc(" + name + ")");

		var input = {};

	},

	getPkgInfo: function(/*String*/ name, /*Function*/ callback){

		// summary: Gets a combination of the metadata and external documentation for a given package

		dojo.debug("getPkgInfo(" + name + ")");

		var input = {

			expects: {

				pkginfo: ["pkgmeta", "pkgdoc"]

			},

			callback: callback

		};

		dojo.docs.getPkgMeta(input, name, dojo.docs._getPkgInfo);

		dojo.docs.getPkgDoc(input, name, dojo.docs._getPkgInfo);

	},

	_getPkgInfo: function(/*String*/ type, /*Object*/ data, /*Object*/ evt){

		dojo.debug("_getPkgInfo() for " + evt.type);

		var input = {};

		var results = {};

		if(typeof key == "object"){

			input = key;

			input[evt.type] = data;

			if(input.expects && input.expects.pkginfo){

				for(var i = 0, expect; expect = input.expects.pkginfo[i]; i++){

					if(!(expect in input)){

						dojo.debug("_getPkgInfo() waiting for more data");

						return;

					}

				}

			}

			results = input.pkgmeta;

			results.description = input.pkgdoc;

		}

		if(input.callback){

			input.callback("load", results, evt);

		}

	},

	getInfo: function(/*String*/ name, /*Function*/ callback){

		dojo.debug("getInfo(" + name + ")");

		var input = {

			expects: {

				"info": ["meta", "doc"]

			},

			callback: callback

		}

		dojo.docs.getMeta(input, name, dojo.docs._getInfo);

		dojo.docs.getDoc(input, name, dojo.docs._getInfo);

	},

	_getInfo: function(/*String*/ type, /*String*/ data, /*Object*/ evt, /*Object*/ input){

		dojo.debug("_getInfo(" + evt.type + ")");

		if(input && input.expects && input.expects.info){

			input[evt.type] = data;

			for(var i = 0, expect; expect = input.expects.info[i]; i++){

				if(!(expect in input)){

					dojo.debug("_getInfo() waiting for more data");

					return;

				}

			}

		}

		if(input.callback){

			input.callback("load", dojo.docs._getCache(evt.pkg, "meta", "functions", evt.name, evt.id, "meta"), evt, input);

		}

	},

	_getMainText: function(/*String*/ text){

		// summary: Grabs the innerHTML from a Jot Rech Text node

		dojo.debug("_getMainText()");

		return text.replace(/^<html[^<]*>/, "").replace(/<\/html>$/, "").replace(/<\w+\s*\/>/g, "");

	},

	getPackageMeta: function(/*Object*/ input){

		dojo.debug("getPackageMeta(): " + input.package);

		return this.require(input.package + "/meta", input.sync);

	},

	getFunctionMeta: function(/*Object*/ input){

		var package = input.package || "";

		var name = input.name;

		var id = input.id || "_";

		dojo.debug("getFunctionMeta(): " + name);

		if(!name) return;

		if(package){

			return this.require(package + "/meta/functions/" + name + "/" + id + "/meta");

		}else{

			this.getFunctionNames();

		}

	},

	getFunctionDocumentation: function(/*Object*/ input){

		var package = input.package || "";

		var name = input.name;

		var id = input.id || "_";

		dojo.debug("getFunctionDocumentation(): " + name);

		if(!name) return;

		if(package){

			return this.require(package + "/meta/functions/" + name + "/" + id + "/documentation");

		}

	},

	_onDocSearch: function(/*Object*/ input){

		var _this = this;

		var name = input.name.toLowerCase();

		if(!name) return;

		this.getFunctionNames().addCallback(function(data){

			dojo.debug("_onDocSearch(): function names loaded for " + name);

			var output = [];

			var list = [];

			var closure = function(pkg, fn) {

				return function(data){

					dojo.debug("_onDocSearch(): package meta loaded for: " + pkg);

					if(data.functions){

						var functions = data.functions;

						for(var key in functions){

							if(fn == key){

								var ids = functions[key];

								for(var id in ids){

									var fnMeta = ids[id];

									output.push({

										package: pkg,

										name: fn,

										id: id,

										summary: fnMeta.summary

									});

								}

							}

						}

					}

					return output;

				}

			}

			pkgLoop:

			for(var pkg in data){

				if(pkg.toLowerCase() == name){

					name = pkg;

					dojo.debug("_onDocSearch found a package");

					//dojo.docs._onDocSelectPackage(input);

					return;

				}

				for(var i = 0, fn; fn = data[pkg][i]; i++){

					if(fn.toLowerCase().indexOf(name) != -1){

						dojo.debug("_onDocSearch(): Search matched " + fn);

						var meta = _this.getPackageMeta({package: pkg});

						meta.addCallback(closure(pkg, fn));

						list.push(meta);

						// Build a list of all packages that need to be loaded and their loaded state.

						continue pkgLoop;

					}

				}

			}

			list = new dojo.DeferredList(list);

			list.addCallback(function(results){

				dojo.debug("_onDocSearch(): All packages loaded");

				_this._printFunctionResults(results[0][1]);

			});

		});

	},

	_onDocSearchFn: function(/*String*/ type, /*Array*/ data, /*Object*/ evt){

		dojo.debug("_onDocSearchFn(" + evt.name + ")");

		var name = evt.name || evt.pkg;

		dojo.debug("_onDocSearchFn found a function");

		evt.pkgs = packages;

		evt.pkg = name;

		evt.loaded = 0;

		for(var i = 0, pkg; pkg = packages[i]; i++){

			dojo.docs.getPkgMeta(evt, pkg, dojo.docs._onDocResults);

		}

	},

	_onPkgResults: function(/*String*/ type, /*Object*/ data, /*Object*/ evt, /*Object*/ input){

		dojo.debug("_onPkgResults(" + evt.type + ")");

		var description = "";

		var path = "";

		var methods = {};

		var requires = {};

		if(input){

			input[evt.type] = data;

			if(input.expects && input.expects.pkgresults){

				for(var i = 0, expect; expect = input.expects.pkgresults[i]; i++){

					if(!(expect in input)){

						dojo.debug("_onPkgResults() waiting for more data");

						return;

					}

				}

			}

			path = input.pkgdoc.path;

			description = input.pkgdoc.description;

			methods = input.pkgmeta.methods;

			requires = input.pkgmeta.requires;

		}

		var pkg = evt.name.replace("_", "*");

		var results = {

			path: path,

			description: description,

			size: 0,

			methods: [],

			pkg: pkg,

			requires: requires

		}

		var rePrivate = /_[^.]+$/;

		for(var method in methods){

			if(!rePrivate.test(method)){

				for(var pId in methods[method]){

					results.methods.push({

						pkg: pkg,

						name: method,

						id: pId,

						summary: methods[method][pId].summary

					})

				}

			}

		}

		results.size = results.methods.length;

		dojo.docs._printPkgResult(results);

	},

	_onDocResults: function(/*String*/ type, /*Object*/ data, /*Object*/ evt, /*Object*/ input){

		dojo.debug("_onDocResults(" + evt.name + "/" + input.pkg + ") " + type);

		++input.loaded;

		if(input.loaded == input.pkgs.length){

			var pkgs = input.pkgs;

			var name = input.pkg;

			var results = {methods: []};

			var rePrivate = /_[^.]+$/;

			data = dojo.docs._cache;

			for(var i = 0, pkg; pkg = pkgs[i]; i++){

				var methods = dojo.docs._getCache(pkg, "meta", "methods");

				for(var fn in methods){

					if(fn.toLowerCase().indexOf(name) == -1){

						continue;

					}

					if(fn != "requires" && !rePrivate.test(fn)){

						for(var pId in methods[fn]){

							var result = {

								pkg: pkg,

								name: fn,

								id: "_",

								summary: ""

							}

							if(methods[fn][pId].summary){

								result.summary = methods[fn][pId].summary;

							}

							results.methods.push(result);

						}

					}

				}

			}

			dojo.debug("Publishing docResults");

			dojo.docs._printFnResults(results);

		}

	},

	_printFunctionResults: function(results){

		dojo.debug("_printFnResults(): called");

		// summary: Call this function to send the /docs/function/results topic

	},

	_printPkgResult: function(results){

		dojo.debug("_printPkgResult(): called");

	},

	_onDocSelectFunction: function(/*Object*/ input){

		// summary: Get doc, meta, and src

		var name = input.name;

		var package = input.package || "";

		var id = input.id || "_";

		dojo.debug("_onDocSelectFunction(" + name + ")");

		if(!name || !package) return false;

		var pkgMeta = this.getPackageMeta({package: package});

		var meta = this.getFunctionMeta({package: package, name: name, id: id});

		var doc = this.getFunctionDocumentation({package: package, name: name, id: id});

		var list = new dojo.DeferredList([pkgMeta, meta, doc]);

		list.addCallback(function(results){

			dojo.debug("_onDocSelectFunction() loaded");

			for(var i = 0, result; result = results[i]; i++){

				dojo.debugShallow(result[1]);

			}

		});

		return list;

	},

	_onDocSelectPackage: function(/*Object*/ input){

		dojo.debug("_onDocSelectPackage(" + input.name + ")")

		input.expects = {

			"pkgresults": ["pkgmeta", "pkgdoc"]

		};

		dojo.docs.getPkgMeta(input, input.name, dojo.docs._onPkgResults);

		dojo.docs.getPkgDoc(input, input.name, dojo.docs._onPkgResults);

	},

	_onDocSelectResults: function(/*String*/ type, /*Object*/ data, /*Object*/ evt, /*Object*/ input){

		dojo.debug("_onDocSelectResults(" + evt.type + ", " + evt.name + ")");

		if(evt.type == "meta"){

			dojo.docs.getPkgMeta(input, evt.pkg, dojo.docs._onDocSelectResults);

		}

		if(input){

			input[evt.type] = data;

			if(input.expects && input.expects.docresults){

				for(var i = 0, expect; expect = input.expects.docresults[i]; i++){

					if(!(expect in input)){

						dojo.debug("_onDocSelectResults() waiting for more data");

						return;

					}

				}

			}

		}

		dojo.docs._printFunctionDetail(input);

	},

	_printFunctionDetail: function(results) {

		// summary: Call this function to send the /docs/function/detail topic event

	},

	selectFunction: function(/*String*/ name, /*String?*/ id){

		// summary: The combined information

	},

	savePackage: function(/*Object*/ callbackObject, /*String*/ callback, /*Object*/ parameters){

		dojo.event.kwConnect({

			srcObj: dojo.docs,

			srcFunc: "_savedPkgRpc",

			targetObj: callbackObject,

			targetFunc: callback,

			once: true

		});

		var props = {};

		var cache = dojo.docs._getCache(parameters.pkg, "meta");

		var i = 1;

		if(!cache.path){

			var path = "id";

			props[["pname", i].join("")] = "DocPkgForm/require";

			props[["pvalue", i++].join("")] = parameters.pkg;

		}else{

			var path = cache.path;

		}

		props.form = "//DocPkgForm";

		props.path = ["/WikiHome/DojoDotDoc/", path].join("");

		if(parameters.description){

			props[["pname", i].join("")] = "main/text";

			props[["pvalue", i++].join("")] = parameters.description;

		}

		dojo.docs._rpc.callRemote("saveForm",	props).addCallbacks(dojo.docs._pkgRpc, dojo.docs._pkgRpc);

	},

	_pkgRpc: function(data){

		if(data.name){

			dojo.docs._getCache(data["DocPkgForm/require"], "meta").path = data.name;

			dojo.docs._savedPkgRpc("load");

		}else{

			dojo.docs._savedPkgRpc("error");

		}

	},

	_savedPkgRpc: function(type){

	},

	functionPackages: function(/*String*/ name, /*Function*/ callback, /*Object*/ input){

		// summary: Gets the package associated with a function and stores it in the .pkg value of input

		dojo.debug("functionPackages() name: " + name);

		if(!input){

			input = {};

		}

		if(!input.callbacks){

			input.callbacks = [];

		}

		input.type = "function_names";

		input.name = name;

		input.callbacks.unshift(callback);

		input.callbacks.unshift(dojo.docs._functionPackages);

	},

	_functionPackages: function(/*String*/ type, /*Array*/ data, /*Object*/ evt){

		dojo.debug("_functionPackages() name: " + evt.name);

		evt.pkg = '';

		var results = [];

		var data = dojo.docs._cache['function_names'];

		for(var key in data){

			if(dojo.lang.inArray(data[key], evt.name)){

				dojo.debug("_functionPackages() package: " + key);

				results.push(key);

			}

		}

		if(evt.callbacks && evt.callbacks.length){

			evt.callbacks.shift()(type, results, evt, evt.input);

		}

	},

	setUserName: function(/*String*/ name){

		dojo.docs._userName = name;

		if(name && dojo.docs._password){

			dojo.docs._logIn();

		}

	},

	setPassword: function(/*String*/ password){

		dojo.docs._password = password;

		if(password && dojo.docs._userName){

			dojo.docs._logIn();

		}

	},

	_logIn: function(){

		dojo.io.bind({

			url: dojo.docs._rpc.serviceUrl.toString(),

			method: "post",

			mimetype: "text/json",

			content: {

				username: dojo.docs._userName,

				password: dojo.docs._password

			},

			load: function(type, data){

				if(data.error){

					dojo.docs.logInSuccess();

				}else{

					dojo.docs.logInFailure();

				}

			},

			error: function(){

				dojo.docs.logInFailure();

			}

		});

	},

	logInSuccess: function(){},

	logInFailure: function(){},

	_set: function(/*Object*/ base, /*String...*/ keys, /*String*/ value){

		var args = [];

		for(var i = 0, arg; arg = arguments[i]; i++){

			args.push(arg);

		}

		if(args.length < 3) return;

		base = args.shift();

		value = args.pop();

		var key = args.pop();

		for(var i = 0, arg; arg = args[i]; i++){

			if(typeof base[arg] != "object"){

				base[arg] = {};

			}

			base = base[arg];

		}

		base[key] = value;

	},

	_getCache: function(/*String...*/ keys){

		var obj = dojo.docs._cache;

		for(var i = 0; i < arguments.length; i++){

			var arg = arguments[i];

			if(!obj[arg]){

				obj[arg] = {};

			}

			obj = obj[arg];

		}

		return obj;

	}

});

dojo.event.topic.subscribe("/docs/search", dojo.docs, "_onDocSearch");

dojo.event.topic.subscribe("/docs/function/select", dojo.docs, "_onDocSelectFunction");

dojo.event.topic.subscribe("/docs/package/select", dojo.docs, "_onDocSelectPackage");

dojo.event.topic.registerPublisher("/docs/function/results", dojo.docs, "_printFunctionResults");

dojo.event.topic.registerPublisher("/docs/function/detail", dojo.docs, "_printFunctionDetail");

dojo.event.topic.registerPublisher("/docs/package/detail", dojo.docs, "_printPkgResult");