burst.Lang Class Reference

Detailed Description

Scoping class containing static functions which provide basic functionality that is not part of the ECMAScript standard, but might have been.

(This differs from fix_ecma.js, which attempts to make builtin objects compliant with the standard.)

Static Public Member Functions

String gensym ()

Generate a unique symbol.

Object cond (Array condarray)

A Lisp-like cond operator.

Array argumentsToArray (Arguments args)

Convert an ECMAScript Arguments into a real Array, so join and other Array methods will work.

String argumentsJoin (Arguments args, String sep)

Convenience which converts Arguments to an Array and calls join, all in one step.

Array keys (Object o)

return an Array of the keys in the associative array (using "for in")

Boolean isSpecified (Object o)

true if and only if v is not null and not undefined

Boolean isArray (Object o)

True if and only if o is an Array.

Boolean isString (Object o)

True if and only if o is a string primative or a String object.

Boolean isPrimitive (Object o)

True if and only if o is not an object (such as string or function), or is an object but is a builtin object (such as Array or RegExp).

Boolean isKeyword (String s)

Whether the string s is an ECMAScript keyword (such as 'else').

Boolean isReserved (String s)

Whether the string s is an ECMAScript reserved word (such as 'volatile').

Boolean isLegalIdentifier (String s)

Whether the string s is a legal ECMAScript identifier.

String uneval (Object o)

Produce a string which when eval'd should produce the same object.

String unevalFunctionCall (Function func, Object scopeobj, String symname)

Produce a String which when eval'd will call the function func with no arguments.

String functionName (Function func)

Determine a function's name (returning 'anonymous' if none).

Array functionArgumentNames (Function func)

Return an Array of String declared argument names.

String functionBody (Function func)

Return the function's body as a String.

String formatStackFrame (Function func)

Format a single stack frame, as given by a Function object.

Function functionCaller (Function f)

Return the Function object for the caller of the provided Function object, which must be somewhere in the current stack.

Array getCallers (Number skip, Function op)

A recursive utility which accumulates the result of calling the function op on each of the stack frames above us, skipping the initial skip frames.

Array getCallerNames (Number skip)

Utility which calls burst.Lang.getCallers to accumulate just the function names into an Array.

String getCallerName (Number skip)

Get the function name skip levels up the stack.

Array getCallerArguments (Number skip)

Utility which calls burst.Lang.getCallers to accumulate the arguments variable at each level.

String getStackTrace (Number skip)

Return stack trace as a EOL-separated String.

Object callNoStrict (Function func)

Call the provided function with strict warnings turned off.

void securityEnableRead_moz ()

Enable universal file reading on Mozilla.

Object createActiveXObject (Object progid_obj, String progid_key, String what)

A utility for creating an ActiveXObject when the correct ProgID for the environment is not known.

Member Function Documentation

Object burst.Lang.callNoStrict ( Function func ) [static]

Call the provided function with strict warnings turned off.
If that isn't possible, just calls the function. Returns the result of the function.

Object burst.Lang.cond ( Array condarray ) [static]

A Lisp-like cond operator.
It takes an Array with an even number of elements, which are considered pairs. It returns the first rhs value whose lhs is true. Note that it doesn't invoke or eval anything.
Parameters:

condarray array of alternating boolean expressions and corresponding values.

Returns:
Returns null if nothing is true.

Object burst.Lang.createActiveXObject ( Object progid_obj,

String progid_key,

String what

) [static]

A utility for creating an ActiveXObject when the correct ProgID for the environment is not known.
if progid_obj[progid_key] is an Array, it iterates through, attempting new ActiveXObject(progid) on each, until successful. Then it goes back and sets the value so that next time it doesn't have to rediscover the correct one. Lastly, it returns the created object.

Parameters:

progid_obj The object that has the member with name progid_key

progid_key The key to lookup the progid list (or value)

what Used in any error messages.

Exceptions:

BurstError If no progid in the list succeeds.

(unknown) Whatever new ActiveXObject(id) might do.

Returns:
The created object

String burst.Lang.formatStackFrame ( Function func ) [static]

Format a single stack frame, as given by a Function object.
The format is: "funcname(argname1: argv1, argname2: argv2)" The greater of actual and declared arguments are given.
This relies on burst.Lang.uneval to display argument values.
This relies on Function.arguments, which is deprecated.

Array burst.Lang.functionArgumentNames ( Function func ) [static]

Return an Array of String declared argument names.
This is implemented by parsing the Function.toString() result, which is not standardized in ECMAScript, so this may not work.

String burst.Lang.functionBody ( Function func ) [static]

Return the function's body as a String.
Does not include the surrounding {}.
This is implemented by parsing the Function.toString() result, which is not standardized in ECMAScript, so this may not work.
Note that this might not match the actual original body. For example, IE seems to add any missing trailing semi-colon.

Function burst.Lang.functionCaller ( Function f ) [static]

Return the Function object for the caller of the provided Function object, which must be somewhere in the current stack.
Returns null if called at top-level.
This will rely either on Function.caller or on Arguments.caller, neither of which is required to exist by standard ECMAScript. If neither is available, it just returns undefined.

IE: has both. IE5Mac: has both. Mozilla: has Function.caller, not Arguments.caller. Error has a .stack member. Opera: has neither. Some native errors have a stack trace in the message. KHTML: has neither.
Opera has neither Function.caller nor Arguments.caller. A possible workaround for Opera might be based on the fact that exceptions thrown by the interpreter (but not from an explicit "throw") have a message string with a substring starting with 'Backtrace:'. This differs from Mozilla's Error.stack, which is a distinct object member (not part of message), and is available for user exceptions.

String burst.Lang.functionName ( Function func ) [static]

Determine a function's name (returning 'anonymous' if none).
This is implemented by parsing the Function.toString() result, which is not standardized in ECMAScript, so this may not work.

String burst.Lang.gensym ( ) [static]

Generate a unique symbol.
It is globally unique (a single internal counter is used), so it doesn't much matter what object you may attach it to.

Array burst.Lang.getCallerArguments ( Number skip ) [static]

Utility which calls burst.Lang.getCallers to accumulate the arguments variable at each level.
It converts each arguments to an Array. It therefore returns an Array of Arrays.

Array burst.Lang.getCallers ( Number skip,

Function op

) [static]

A recursive utility which accumulates the result of calling the function op on each of the stack frames above us, skipping the initial skip frames.
If op is not specified, it just accumulates the Function objects themselves.

Parameters:

skip Number of frames to skip, default 0 (which excludes this function too).

op Optional

String burst.Lang.getStackTrace ( Number skip ) [static]

Return stack trace as a EOL-separated String.
Formatting of each line is done by burst.Lang.formatStackFrame.
Note that Moz Error objects have a .stack member variable. And JScript dotnet Exception.StackTrace()
Parameters:

skip Number of stack frames to skip, default 0 (which still excludes getStackTrace itself).

Boolean burst.Lang.isLegalIdentifier ( String s ) [static]

Whether the string s is a legal ECMAScript identifier.

Todo:
Are non-reserved words such as NaN, Infinity, window, eval, String legal identifiers? Can they be used as object initializer keys?

void burst.Lang.securityEnableRead_moz ( ) [static]

Enable universal file reading on Mozilla.

Todo:
In a Mozilla browser, will this always cause a popup confirmation?

Browser Security

So far this library has little support related to security APIs.
Here is a brief introduction to the builtin security constraints in IE and Mozilla:
Mozilla calls their rule the "same origin policy", while Microsoft calls theirs "cross-frame security". On paper, they are the same.
The rule requires the same protocol (http and https differ), the same host (a.foo.com and b.foo.com differ), and the same port (80 and 8000 differ). Two documents can be from different hosts within the same top-level domain if the document.domain is set to be the same. See:

http://www.dardenhome.com/js/x362952.htm
http://www.mozilla.org/projects/security/components/same-origin.html
http://msdn.microsoft.com/workshop/author/om/xframe_scripting_security.asp
http://msdn.microsoft.com/workshop/author/dhtml/sec_dhtml.asp

Generally, DomDocument and HttpRequest objects are subject to the restrictions as the browser generally. However, versions of both the IE XMLHTTP and the Mozilla XMLHttpRequest objects have been show to be vulnerable to an exploit in which the initial url response is a redirect to a known local file:

Mozilla: http://security.greymagic.com/adv/gm001-ns/
IE: http://www.xs4all.nl/~jkuperus/bug.htm

Script signing is a bit of a morass:

http://www.visi.com/~hoju/mozilla/signed/linkstatuscheck.html

Netscape has an API which relies on Java to ask for greater privilege:

http://www.dardenhome.com/js/x656605.htm
http://www.mozilla.org/xmlextras/
netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead");
It is apparently necessary to do this for example if you want to issue an "http:" request when the current document has a "file:" location.

String burst.Lang.uneval ( Object o ) [static]

Produce a string which when eval'd should produce the same object.
Note that this does not retain any properties associated with a String, Function, or Array (as if they were a normal Object).
This has no protectection against self-referential objects, and no support for repeated objects.
Note that NS4.6 and above has Object.toSource() which does roughly the same thing, but that is not part of ECMAScript 262-3

String burst.Lang.unevalFunctionCall ( Function func,

Object scopeobj,

String symname

) [static]

Produce a String which when eval'd will call the function func with no arguments.
This is useful for creating strings that may be set in DOM attributes for event handlers, when the circumstances don't allow for a Function value. You can prepend the the result with 'parent.' if for example the expression is to be used in a child popup or frame.
Parameters:

func The Function to call.

scopeobj Optional. Defaults to window (or the global object).

symname Optional. Defaults to burst.Lang.gensym().

The documentation for this class was generated from the following file:

Lang.java

Generated on Tue Nov 30 04:03:08 2004 for BurstProject by

1.3.4


Static Public Member Functions
String	gensym ()
	Generate a unique symbol.
Object	cond (Array condarray)
	A Lisp-like cond operator.
Array	argumentsToArray (Arguments args)
	Convert an ECMAScript Arguments into a real Array, so join and other Array methods will work.
String	argumentsJoin (Arguments args, String sep)
	Convenience which converts Arguments to an Array and calls join, all in one step.
Array	keys (Object o)
	return an Array of the keys in the associative array (using "for in")
Boolean	isSpecified (Object o)
	true if and only if v is not null and not undefined
Boolean	isArray (Object o)
	True if and only if o is an Array.
Boolean	isString (Object o)
	True if and only if o is a string primative or a String object.
Boolean	isPrimitive (Object o)
	True if and only if o is not an object (such as string or function), or is an object but is a builtin object (such as Array or RegExp).
Boolean	isKeyword (String s)
	Whether the string s is an ECMAScript keyword (such as 'else').
Boolean	isReserved (String s)
	Whether the string s is an ECMAScript reserved word (such as 'volatile').
Boolean	isLegalIdentifier (String s)
	Whether the string s is a legal ECMAScript identifier.
String	uneval (Object o)
	Produce a string which when eval'd should produce the same object.
String	unevalFunctionCall (Function func, Object scopeobj, String symname)
	Produce a String which when eval'd will call the function func with no arguments.
String	functionName (Function func)
	Determine a function's name (returning 'anonymous' if none).
Array	functionArgumentNames (Function func)
	Return an Array of String declared argument names.
String	functionBody (Function func)
	Return the function's body as a String.
String	formatStackFrame (Function func)
	Format a single stack frame, as given by a Function object.
Function	functionCaller (Function f)
	Return the Function object for the caller of the provided Function object, which must be somewhere in the current stack.
Array	getCallers (Number skip, Function op)
	A recursive utility which accumulates the result of calling the function op on each of the stack frames above us, skipping the initial skip frames.
Array	getCallerNames (Number skip)
	Utility which calls burst.Lang.getCallers to accumulate just the function names into an Array.
String	getCallerName (Number skip)
	Get the function name skip levels up the stack.
Array	getCallerArguments (Number skip)
	Utility which calls burst.Lang.getCallers to accumulate the arguments variable at each level.
String	getStackTrace (Number skip)
	Return stack trace as a EOL-separated String.
Object	callNoStrict (Function func)
	Call the provided function with strict warnings turned off.
void	securityEnableRead_moz ()
	Enable universal file reading on Mozilla.
Object	createActiveXObject (Object progid_obj, String progid_key, String what)
	A utility for creating an ActiveXObject when the correct ProgID for the environment is not known.