You are viewing a plain text version of this content. The canonical link for it is here.
Posted to xap-commits@incubator.apache.org by jm...@apache.org on 2006/06/23 23:51:26 UTC
svn commit: r416838 - in /incubator/xap/trunk/src/xap/session:
DeclarativeArgumentParser.js EventHandler.js
Author: jmargaris
Date: Fri Jun 23 16:51:26 2006
New Revision: 416838
URL: http://svn.apache.org/viewvc?rev=416838&view=rev
Log:
Documentation, got rid of some simple wrapper methods that didn't
really accomplish anything except take up space
Modified:
incubator/xap/trunk/src/xap/session/DeclarativeArgumentParser.js
incubator/xap/trunk/src/xap/session/EventHandler.js
Modified: incubator/xap/trunk/src/xap/session/DeclarativeArgumentParser.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/session/DeclarativeArgumentParser.js?rev=416838&r1=416837&r2=416838&view=diff
==============================================================================
--- incubator/xap/trunk/src/xap/session/DeclarativeArgumentParser.js (original)
+++ incubator/xap/trunk/src/xap/session/DeclarativeArgumentParser.js Fri Jun 23 16:51:26 2006
@@ -15,20 +15,69 @@
*
*/
- /**
- *
- * Placeholder functionality only for now.
+/**
+ * @fileoverview A class that parses out arguments and argument strings
+ * used to invoke methods from XML.
+ *
+ * @author jmargaris
*
- * @author Jmargaris
*/
+
+//TODO this needs a ton more testing.
+//TODO what package does this belong in?
-//-----------------------------------------------------------------------
-// Constructors.
-//-----------------------------------------------------------------------
+/**
+ * Creates a DeclarativeArgumentParser
+ *
+ * @class DeclarativeArgumentParser is used to handle arguments in XML
+ * declaritive method calls. For example:<br><br>
+ * <code>
+ * onCommand=mco:myMco.doSomething( this.text, someOtherElement, true, 5)
+ * </code>
+ * <br>
+ * <br>
+ * Here we want to run to doSomething() method on myMco, and pass it a variety
+ * of arguments. This class helps us parse out the argument string.
+ * <br><br>
+ * This class will look for the following types of arguments:
+ * <ol>
+ * <li>CONTAINER:OBJECT - resolves to an object with the given name in the given
+ * container, for example <code>mco:myMco</code>.</li>
+ * <li>CONTAINER:OBJECT.METHOD(....) - runs the method on the given object
+ * and resolves to the return value of that method.</li>
+ * <li>true - resolves to a true boolean</li>
+ * <li>false - resolves to a false boolean.</li>
+ * <li>event - resolves to the clientEvent object</li>
+ * <li>event.PROPERTY - resolves to a property on the client event object, TODO
+ * THIS DOESN'T WORK YET.</li>
+ * <li>NUMBER- resolves to a number if the parseFloat() method
+ * gets a valid result.</li>
+ * <li>this - resolves to the XML element the event took place on</li>
+ * <li>this.ATTRIBUTE - resolves to the given attribute on the element</li>
+ * <li>ELEMENT_NAME - resolves to an element in the UI dom with the given name.</li>
+ * <li>ELEMENT_NAME.ATTRIBUTE - resolves to an attribute on the
+ * element in the UI dom with the given name.</li>
+ * <li>'xxxx' - resolves to a string</li>
+ * <li>"xxx" - resolves to a string</li>
+ * </ol>
+ *
+ * Note there is a bit of overlap here in that you can't have an element
+ * with ID '5' or 'true' or 'this' without that causing problems, as those
+ * will resolve to a number, boolean and current element instead of the
+ * element with that actual ID.
+ *
+ * <br><br>
+ * This class attempts to be efficient in that it loops through the entire
+ * string once only. We could use regular expressions here (?) but that gets tricky
+ * with nested calls and things like that.
+ *
+ *
+ */
function DeclarativeArgumentParser( session ) {
this._session = session;
}
+/** @private */
DeclarativeArgumentParser.s_log = LogFactory.getLog("Argument Parser");
//-----------------------------------------------------------------------
// Public Methods.
@@ -41,46 +90,40 @@
}
/**
- * Parses out the next argument in an MCO call.
- *
+ * Parses out an argument from a given string and index. Note that
+ * an initial event call like macro:myMacro.execute() can be run
+ * using this method as it will evaluate that string and return the result. This
+ * is the case because our argument strings allow nested calls.
+ * <br><br>
* This will always return a non-null ParseResult, but the parseObject
* can be null if there are no more args to parse out. In that case the
* ParseResult should indicate why the parse finished
- *
- *
+ * <br><br>
* This will parse out the argument and forward to the terminating
* character, filling in the terminating index and the termination reason.
- *
+ * <br>
* The reasons can be:
* this.xxx = end of string (reached end of parseable stuff)
* this.xxx ) = closing paren reached
* this.xxx , = comma reached
- *
+ * <br><br>
* If you are in a parseArguments call anything other than closing paren
* reached should be a problem!
- *
- * Note that for MCOs you can have something like:
- * mco://myMco.do() ,
- *
- * (or for strings 'xxx' ,
- *
- * In this case we still forward to the ',' even though we KNOW the .do()
- * ended the mco call. We still have to forward to the argument termination
- * delineator or things go haywire.
+ * <br><br>
*
* Possible things that can happen here:
* 1: We hit some whitespace followed by a ',' - error
- * 2: We hit some whitespace folloed by a ')' - that's ok there may be no more args
+ * 2: We hit some whitespace followed by a ')' - that's ok there may be no more args
* 3: We hit ' or " and parse out a string
* 4: we hit '(' and assume this is an MCO parse
*
*
- * @param args A string that we are looking for the next arg in
- * @param startIndex the index in the string to start looking at
- * @param sourceElement
- * @return asd
- * @throws EscapeSyntaxException
- * @throws McoException
+ * @param {String} args A string that we are looking for the next arg in
+ * @param {Number} startIndex the index in the string to start looking at
+ * @param {XapElement} sourceElement The current element that 'this' should refer to
+ * @param {ClientEvent} clientEvent The current event that 'event' should refer to.
+ * @return {ParseResult} A ParseResult object that wraps the argument we resolved.
+ * @throws BaseException if something goes wrong..
*/
@@ -100,14 +143,14 @@
if (parseResult!=null){
if (c==','){
DeclarativeArgumentParser.s_log.debug("HIt a comma, returning arg" + arg);
- parseResult.setTerminatingIndex(nextChar);
- parseResult.setParseStatus(ParseResult.COMMA_ENCOUNTERED);
+ parseResult._terminatingIndex = nextChar;
+ parseResult._parseStatus = ParseResult.COMMA_ENCOUNTERED;
return parseResult;
}
else if (c==')'){
DeclarativeArgumentParser.s_log.debug("HIt a close paren, returning arg" + arg);
- parseResult.setTerminatingIndex(nextChar);
- parseResult.setParseStatus(ParseResult.CLOSING_PAREN);
+ parseResult._terminatingIndex = nextChar;
+ parseResult._parseStatus = ParseResult.CLOSING_PAREN;
return parseResult;
}
else if (xap.util.Character.isWhitespace(c)){
@@ -129,7 +172,7 @@
if ( (c=='\"' || c=='\'') && arg.trim().length==0){
DeclarativeArgumentParser.s_log.debug("Hit an open string char, parsing string");
parseResult = this._parseString(args,nextChar, c);
- nextChar = this._parseResult.getTerminatingIndex();
+ nextChar = this._parseResult._terminatingIndex;
}
//if we get an '(' anywhere it means this must be an 'mco' call of some sort
@@ -172,13 +215,13 @@
DeclarativeArgumentParser.s_log.debug("Firing an object event");
var callResult =
- this._fireObjectEvent(containerName,mcoName,methodName,mcoCallResult.getResultObject());
+ this._fireObjectEvent(containerName,mcoName,methodName,mcoCallResult._resultObject);
DeclarativeArgumentParser.s_log.debug("Object event returned : " + callResult);
- parseResult = new ParseResult(callResult,mcoCallResult.getTerminatingIndex());
+ parseResult = new ParseResult(callResult,mcoCallResult._terminatingIndex);
- nextChar = mcoCallResult.getTerminatingIndex();
+ nextChar = mcoCallResult._terminatingIndex;
}
//if we hit a comma we must have had a plain old literal
@@ -238,15 +281,19 @@
//if there was a parse result just set the terminating index up properly
else{
DeclarativeArgumentParser.s_log.debug("Exited loop with a parse result");
- parseResult.setTerminatingIndex(args.length-1);
- parseResult.setParseStatus(ParseResult.END_OF_STRING);
+ parseResult._terminatingIndex = args.length-1;
+ parseResult._parseStatus = ParseResult.END_OF_STRING;
return parseResult;
}
}
-
+/**
+ * Parses out a set of arguments contained in an argument string,
+ * returning a ParseResult that wraps an array of resolved values.
+ * @private
+ */
DeclarativeArgumentParser.prototype._parseArguments = function( argumentsString, sourceElement, index, clientEvent){
DeclarativeArgumentParser.s_log.debug("Parse arguments: " + argumentsString + " at index " + index);
var args = new Array();
@@ -258,12 +305,12 @@
//why do we do +1 here? because if the last terminating character
//was , we need to start our search one AFTER the comma!
var result = this.parseArgument(argumentsString,argumentStart+1,sourceElement, clientEvent);
- DeclarativeArgumentParser.s_log.debug("Got back result " + result.getResultObject());
- if (result.getResultObject()!=null){
- args.push(result.getResultObject());
- DeclarativeArgumentParser.s_log.debug("Push result: " + result.getResultObject());
- argumentStart = result.getTerminatingIndex();
- if (result.getParseStatus()==ParseResult.CLOSING_PAREN){
+ DeclarativeArgumentParser.s_log.debug("Got back result " + result._resultObject);
+ if (result._resultObject!=null){
+ args.push(result._resultObject);
+ DeclarativeArgumentParser.s_log.debug("Push result: " + result._resultObject);
+ argumentStart = result._terminatingIndex;
+ if (result._parseStatus==ParseResult.CLOSING_PAREN){
break;
}
}
@@ -271,7 +318,7 @@
//if the result was null it could be because it ended with ')'
//or it could be end of string, which would be an error
else{
- if (result.getParseStatus()!=ParseResult.CLOSING_PAREN){
+ if (result._parseStatus!=ParseResult.CLOSING_PAREN){
//TODO
throw new BaseException("Bad paramter string " + argumentsString);
}
@@ -288,18 +335,26 @@
/**
- * Converts a literal into an MCO argument object. This will deal with
- * things in the form:
+ * Converts a non-string literal into a resolved argument.
+ * This will handle:
+ * <br>
+ * this<br>
+ * this.attName<br>
+ * ID<br>
+ * ID.attName<br>
+ * true<br>
+ * false<br>
+ * 5 (a number)<br>
+ * CONTAINER.OBJECT_NAME<br>
+ * This does not include CONTAINER:OBJECT_NAME.METHOD(...),
+ * that is handled elsewhere.
+ *
+ * TODO our use of MCO everywhere is bad, this is really any object
+ * call. Also "stringToMcoArg" should be "literalToArg?"
*
- * this
- * this.attName
- * ID
- * ID.attName
- * true
- * false
- * 5
- * 5.0
- * This does not include nested argument calls like mco://myMco.do()
+ * @throws BaseException if something goes wrong.
+ *
+ * @private
*/
DeclarativeArgumentParser.prototype._stringToMcoArgument =
function(arg, thisElement, clientEvent){
@@ -386,13 +441,16 @@
/**
+ *
* Fires off the object event
- * @param containerName Name of the container the object is in, can be null
+ * @param containerName Name of the container the object is in
* @param mcoName Name of the mco
* @param methodName Name of the method
- * @param arguments array of args
- * @return asd
- * @throws McoException
+ * @param args array of args
+ * @return The result of the method call.
+ * @throws BaseException If something bad happens...
+ *
+ * @private
*/
DeclarativeArgumentParser.prototype._fireObjectEvent = function(containerName, mcoName,
methodName, args){
@@ -433,15 +491,14 @@
}
/**
- * Parses a string out of a mco argument string.
- * If you have an mco call like:
- * mco://myMco.do (x,y,z) this expects
- * "(x,y,z)" as the string.
+ *
+ * Parses a string out of a object argument string.
*
- * @param args The FULL mco parameter string
+ * @param args The string we look into to find this string in question.
* @param startIndex The index where this argument starts
* @param terminatingCharacter The character ( " or ') that starts and ends the string
- * @throws EscapeSyntaxException
+ * @throws BaseException if something bad happens...
+ * @private
*/
DeclarativeArgumentParser.prototype._parseString = function(args, startIndex, terminatingCharacter){
@@ -449,7 +506,7 @@
DeclarativeArgumentParser.s_log.debug("Parse string :" + args + " at start index " + startIndex);
var result = new ParseResult(null,startIndex);
var arg = new String();
- startIndex++; //first must be a "
+ startIndex++; //first must be a " or '
//TODO escaping!
//select the right escape syntax for the terminating char
@@ -463,8 +520,8 @@
//if we got the terminating char we are done
if (c==terminatingCharacter){
DeclarativeArgumentParser.s_log.debug("Hit terminating char " + c + " result string=" + arg);
- result.setResultObject(arg);
- result.setTerminatingIndex(nextChar);
+ result._resultObject = arg;
+ result._terminatingIndex = nextChar;
break;
}
else{
@@ -486,7 +543,7 @@
//1: we reached a closing " or ', in which case we are good
//2: we reached the end of the args string, which means our args
//string is mis-formatted, in which case result._result will be null.
- if (result.getResultObject()==null){
+ if (result._resultObject==null){
throw new BaseException("Bad string that we parsed: " + args + " at index " + startIndex--);
}
@@ -498,39 +555,20 @@
-
+//TODO remove all these wrapper get/set methods?
function ParseResult( resultObject, index, status ){
- this.setResultObject(resultObject);
- this.setTerminatingIndex(index);
- this.setParseStatus(status);
+
+ /** The result of the parse */
+ this._resultObject = resultObject;
+
+ /** The index the parse terminated at in the original string. */
+ this._terminatingIndex = index;
+
+ /** The reason the parse finished, one of the class constants. */
+ this._parseStatus = status;
}
ParseResult.CLOSING_PAREN = 1;
ParseResult.END_OF_STRING = 2;
ParseResult.NO_INFORMATION = 0;
-ParseResult.COMMA_ENCOUNTERED = 3;
-
-
-ParseResult.prototype.setParseStatus = function( status ){
- this._parseStatus = status;
-}
-
-ParseResult.prototype.getParseStatus = function( ){
- return this._parseStatus;
-}
-
-ParseResult.prototype.setTerminatingIndex = function( index ){
- this._terminatingIndex = index;
-}
-
-ParseResult.prototype.getTerminatingIndex = function( ){
- return this._terminatingIndex;
-}
-
-ParseResult.prototype.setResultObject = function( o ){
- this._resultObject = o;
-}
-
-ParseResult.prototype.getResultObject = function( ){
- return this._resultObject;
-}
\ No newline at end of file
+ParseResult.COMMA_ENCOUNTERED = 3;
\ No newline at end of file
Modified: incubator/xap/trunk/src/xap/session/EventHandler.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/session/EventHandler.js?rev=416838&r1=416837&r2=416838&view=diff
==============================================================================
--- incubator/xap/trunk/src/xap/session/EventHandler.js (original)
+++ incubator/xap/trunk/src/xap/session/EventHandler.js Fri Jun 23 16:51:26 2006
@@ -107,7 +107,7 @@
//as they can be imbedded in other arugments etc
var parseResult =
this._session.getDeclarativeArgumentParser().parseArgument(eventValue,0,eventElement, clientEvent);
- return parseResult.getResultObject();
+ return parseResult._resultObject;
}
/**