[X3D-Public] Script field naming, proposed specification changes

[Don Brutzman]

Today we continued work on Javascript naming of inputOutput field naming.
No replies were received from the list.

Offending statement from 4.3.5.4:

> If the function represents an inputOutput field, the name of the function
> shall be the same name as the field declaration, without the set_ or _changed modifiers.

Proposed correction sentences:

	If a function represents an inputOutput field, the name of the corresponding function
	shall be the name as the field declaration with the set_ modifier prepended.
	To access the value of the inputOutput field, the name of the field itself shall be used
	without the _changed modifier.

We will also change and test the example in this paragraph from

EXAMPLE  The following Script node has one writable field whose name is start:
Script {
    eventIn SFBool start
    url "ecmascript: function start(value, timestamp) { ... }"
}

to something like

EXAMPLE  The following Script node has two fields capable of receiving events:
Script {
    inputOnly   SFBool startMeUp
    inputOutput SFBool started  false
    url "ecmascript:
	function startMeUp(value, timestamp)
	{
		started = true; // etc.
	}
	function set_started(value, timestamp)
	{
	  // this step gets handled automatically by browser upon event receipt
	  // started = value;

	  // additional code can go here
	  if (started) Browser.println ('here we go');
	}"
}

The problem statement and proposed correction have been entered as Mantis bug 525.
http://www.web3d.org/membership/login/mantis/view.php?id=525

Likely specification additions to prevent pathological cases:

	It is an error to simultaneously define fields that result in overloaded (i.e. duplicated) method names.

	EXAMPLE The following is erroneous:
	Script {
	    inputOnly   SFBool set_overloadedField
	    inputOutput SFBool overloadedField false
	}

	It is also an error to simultaneously define a method that directly matches and overloads an inputOutput field name.

	EXAMPLE The following is erroneous, the method should instead be named set_overloadedField2:
	Script {
	    inputOutput SFBool overloadedField2 false
	    url "ecmascript: function overloadedField2 (value, timestamp) { ... }"
	}

We are preparing an ISO new work item proposal that will result in a new Edition of
this specification.  So further comments on the Javascript language binding are welcome.

* Oliver, you send the following note about Bitmanagement implementation on 23 March. *
Can you please confirm that this is a satisfactory resolution which your company can implement.

We also need to change all of the related examples saying eventIn to inputOnly, etc.
Len will enter another Mantis bug on that.

On 3/23/2012 3:24 AM, Oliver Neubauer wrote:
> Hello Dave,
> 
> thanks for your very detailed explanation of you problem and your feature request.
> 
> First I will comment your Background Proto. I tried it and it works in BS Contact 8.000 with the initial yellow background colour defined in the ProtoInstance. The second assignment from the TouchSensor didn't work because you had a script error in your Proto definition. The new assigned color didn't execute the function set_color, because it is not linked to this function. In the Spec for scripts is written
> http://www.web3d.org/files/specifications/19777-1/V3.0/Part1/concepts.html#ReceivingEvents
> 
> "If the function represents an inputOutput field, the name of the function shall be the same name as the field declaration, without the/set_/or/_changed/modifiers."
> 
> Removing the set_ prefix the function is called and the skycolor of the background is changed. [...]

We will be happy to hear your reactions.

The previously posted problem summary follows for continuity, with minor clarifications inserted.

On 4/11/2012 9:04 AM, Don Brutzman wrote:
> Dick, Len and I discussed several topics today on a teleconference.
> [...]
> - We did some more forensics on the naming of Ecmascript methods for
> 	fields in javascript for the Script node.
> 
> Problem statement:  field accessor methods need to have a different name than the field itself.  Some javascript implementations confound the field object and the method object when the names are the same.
> 
> Fix summary:
> a. Set methods for a field should be called set_fieldName.
> b. If an output event is sent, is is called fieldname_changed.
> c. Within the script, current value is referred to as fieldName

This remains an accurate summary.

> Discussion:
> -- This was a hot topic during and following Web3D 2009 Symposium in Darmstadt
> -- Agreement diagram attached which listed options and priorities
> -- No Mantis bug found
> -- We searched mail archives but could not find the thread or the proposed change prose, will continue looking
> -- If we can't find the prior change-proposal prose, we will regenerate it
> -- Can anyone else find the email thread?
> -- We will make plans for a new ISO project and amendment change document for 19777-1
> -- We believe that Instant Reality and Xj3D have implemented this change but BS Contact has not, conformance reports welcome

Most actions in progress.  If browser companies want another meeting on this, great.

> Reference:
> 
> http://www.web3d.org/files/specifications/19777-1/V3.0/Part1/concepts.html#ReceivingEvents
>> 4.3.5.4 Receiving events
>>
>> Events sent to the containing node are passed to the corresponding ECMAScript function in the script. The function's name is the same as the field and is passed two arguments. If the function represents an inputOutput field, the name of the function shall be the same name as the field declaration, without the set_ or _changed modifiers.

*The preceding sentence is the offending definition.*

> The value of the event is passed as the first argument and the timestamp of the event is passed as the second argument. The type of the value is the same as the type of the event and the type of the timestamp is SFTime. 4.3.4.3 X3D field to ECMAScript variable conversion provides a description of how X3D types appear in ECMAScript. The values of the parameters have no visibility outside the function.
>>
>> If there is no corresponding ECMAScript function in the script, the browser's behaviour is to silently ignore the event.
>>
>> EXAMPLE  The following Script node has one writable field whose name is start:
>>
>> Script {
>>      eventIn SFBool start
>>      url "ecmascript: function start(value, timestamp) { ... }"
>> }

note that the eventIn should be inputOnly; correctly handled above.

>> When the start event is received, the start() function is executed.
> 
> Comments welcome.

all the best, Don
-- 
Don Brutzman  Naval Postgraduate School, Code USW/Br       brutzman at nps.edu
Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA   +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman