Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
VJET/Validation Requirements
Contents
- 1 JSDT parse – produces syntax errors lists
- 2 Translation errors – errors are not reported to user
- 3 Resolution errors – errors are reported to user
- 4 Semantic validation errors
- 5 Syntax validation
- 5.1 Syntax version based on JavaScript 1.6.
- 5.2 We are using the JSDT syntax validation (deals with validation and error recovery)
- 5.3 We need to file bugs to them to fix problem areas.
- 5.4 TODO - Need to double check syntax version
- 5.5 Translation Errors – currently uses ErrorObject – move to IJstProblem
- 6 Semantic Validation Asserts
- 7 BestCodePractices Asserts
- 8 Headless Requirement
- 9 Eclipse Integration
- 10 Misc
- 11 Completions, Proposals, Validations
- 12 General approach and guidelines
- 13 Issues
- 14 Environment Specifics
- 15 Contexts and Scopes
- 16 Scopes
- 17 Relationship to TypeSpace and VJET
- 18 Contexts
- 19 Parsing
- 20 Syntax
- 21 Keywords
- 22 Some of the most common/meaningful errors to catch
- 23 Packages
- 24 VjO Sections
- 25 Access Control and Modifiers
- 26 Who is “this”
- 27 Sections
- 28 Namespace
- 29 Modifiers
- 30 Error Messages
- 31 Misc
- 32 Arrays
- 33 Object Literals
- 34 Type References
- 35 Function References
- 36 Operators
- 37 Statements
- 38 To be figured out
JSDT parse – produces syntax errors lists
Translation errors – errors are not reported to user
Resolution errors – errors are reported to user
Semantic validation errors
Syntax validation
Syntax version based on JavaScript 1.6.
We are using the JSDT syntax validation (deals with validation and error recovery)
We need to file bugs to them to fix problem areas.
TODO - Need to double check syntax version
Translation Errors – currently uses ErrorObject – move to IJstProblem
Semantic Validation Asserts
UniquenessValidator (IJstType and IJstTypeSpace required)
Local
assertUniqueMembers
vjo.ctype("a.b.c")
.protos({
a:1,
a:function(){}
})
.props({
b:1,
b:function(){}
})
assertUniqueParamsAndVariables
a:function(a,a){
var a; a;
}
Redefining variable is wrong
Redefining parameter is wrong
assertUniqueNeedNames
Global
assertUniqueType
vjo.type('a.b.c.A')
.endType();
vjo.type('a.b.c.A')
.endType();
Redefining the type can cause issues
assertNoNativeOverRides
vjo.type('Date')
.endType();
Redefining the native types can cause collisions
assertNoDomOverRides
vjo.type('window')
.endType();
Redefining the dom types can cause collisions
ResolutionValidation (Resolved Jst required)
If Build path is incorrect resolving will fail
assertResolvedNeeds
assertResolvedParamTypes
assertResolvedVarTypes
assertResolvedMethodTypes
assertResolvedPropertyTypes
DependencyValidation (Type + TS)
Local
assertNoUnusedNeeds
this can be problematic if developers use with or eval.
assertValidateUseNeedsAlias
vjo.ctype('partials.NeedsAliasTest')
.needs('partials.Bug2149TypeB', 'MyAlias');
.props({
main: function() { //< public void main (String ... arguments)
this.vj$.Myalias
}
}).endType();
this.vj$.Myalias – is wrong name
AccessValidation (Type + TS)
assertTypeRefCanAccessTargetType
assertMethodRefCanAccessTargetMethod
assertPropertyRefCanAccessTargetProperty
ModifierValidation
assertValidTypeModifiers
vjo.ctype('a.b.c.D') //<public final
public is ok
final is not okay we have vjo method for that
assertValidMethodModifiers
assertValidPropertyModifiers
assertValidVariableModifiers
VJOStructureValidation
RequiredInput
assertTypeHasStringInput
assertValidNeedsInput
assertProtosHasObjectLiteral
assertPropsHasObjectLiteral
assertInitsHasFunction
RequiredStructure
assertEndTypeAtEndOfTypeDef
vjo.type("vjo.example.ExVjoType")
.satisfies("vjo.example.ISatisfier")
.protos({
doIt:function(){
// impl goes here
},
doIt2:function(){
// impl goes here
}});
.endType() is missing after definition of protos
assertETypeRequiredKeywordSet
assertCTypeRequiredKeywordSet
vjo.ctype("a.b.c.D")
.expects()
.endType();
Expects is working
assertMTypeRequiredKeywordSet
BestCodePractices Asserts
These could be Find Bug style but are optional
Headless Requirement
Validation should work without Eclipse UI. Ensuring that all logic is in infrastructure to be used in other other tooling such as CLI or other tooling platform such as Netbeans.
Eclipse Integration
Validation Configuration
Validation Preferences
Enabling/Disabling Validation
Build automatically turns it on but we need way to filter and turn off JS errors.
Manual Validation
Incremental validation
While you type for specific scope
Dependency validation
Using build spec in .project file
Validation filters
Because there are cases where you want to inherit old code you want ways to turn off validation.
3rd party code such as Js from Omniture
Other library code you do not own.
Validation markers
Ability to default problems to error, warning, informational as required.
Extension points for additional custom validation.
Misc
Nested types, all flavors and access control.
Do we support doing an anonymous inner class. This could be done with any ctype, ctype //< abstract or itype.
Completions, Proposals, Validations
There are relationships between these elements. First, lets describe each first.
Examples
if …
what follows must be a left paren.
SomeType. …
what follows are the various static properties and methods.
someInstance. …
what follows are the various instance properties and methods
if (someBoolExpr) { }…
what follows could be an else or some naked-target
somePkg. …
What follows are any types at the somePkg level as well as an subPackages
-
- Scope
These are the varying nested levels in which completions, proposals and validations occur. The scopes themselves are basically a tree, with each branch potentially being represented by a stack. At certain levels, not all branches may be needed or present at a give time.
For example we start with something like this…
Global (native JS types)
VjO Bootstrap
VjO Libs
AJAX
Others
HTML DOM Types
Specific Browser Types
-
- Context
What is the user trying to achieve? Are they typing where a package name is expected, a type, an instance method, a Boolean expr for a conditional etc…
-
- Naked Target
This is the term to describe what is possible in open whitespace where nothing else has been typed yet. For example if we are in the middle of a completed main(…) method, what proposals do you suggest at the …?
main: function(args) {
…
}
-
- Completions
A completion is:
- an interactive authoring aid
- the current type being authored may not be syntactically or semantically complete
- may provide a fragment, skeleton, to complete expression/statement
- can take into account other semantics such as VjO type structure
-
- Proposals
A proposal is:
- an interactive authoring aid
- the current type being authored may not be syntactically or semantically complete
- describes everything that is known at a given scope/context in a source unit
- uses information from the type space
- uses information that can come from syntax options
- normally active at the “dot” in expressions/statements
-
- Validations
- Can take place at authoring time
- Can take place on completed source units
- Needs all the same information that completions and proposals do
- Need to related back to specific line/col numbers for errors
- Detailed messages are essential since errors may be in code that is not familiar to developer (i.e. their change broke code in someone else’s area)
General approach and guidelines
Semantic analysis should pay attention to functionally correct results first and then think of optimizations. This is not to say don’t think about optimizations, it’s just that we have such a limited time to pull this off.
The core data structures are graphs:
- syntax AST
- type space (graph with API’s)
Issues
We haven’t really addressed the cases where JavaScript semantics would be trumped by VjO type semantics. This might occur with Arrays, Strings and various implicit type conversions such as the + operator and Strings or such.
Environment Specifics
Part of the overall validation should take into account:
- Version of JavaScript
- Specific Browser/OS Version combination
Contexts and Scopes
I think we need to better define all the terms we are using to do Semantic Analysis.
Scopes are the levels at which specific elements are defined and/or made available.
Scopes
All of the available information we need
-
- Global (native JS Types)
VjO Bootstrap (vjo, vjo.Class, vjo.Object, vjo.Enum)
AJAX (service engine)
HTML DOM Types (classic DOM)
Specific Browser Types (per browser type)
Package
Type
under package space if we assume “default” name for a package. In actuality, we can just assume top level packages and top level types are at the same space.
Class
Static
Instance
Initializer
Interface
Static
Instance
Initializaer
Enum
Static
Instance
Initializer
Mixin
Static
Instance
OType
Defs
-
- Member
leftSide : rightHandExpr
-
- Method
name: function([args]) [throws A [ ,B ,C…]]
While within a method args trump
Constructor
specific checks with super
-
- Statement
Statements provide a scope where only certain other elements can occur. Much of the statements structure should come from syntactical checks.
-
- Expression
Relationship to TypeSpace and VJET
The validator will live outside of the TS.
The validator will leverage information from the TS.
VJET will use the validator to identify semantic warnings/errors etc… that should be reported to tool.
Validation should also work in batch or build mode where errors would be reported to a log or console. Similar to what javac would do.
Contexts
are the combination of activity and scope something is being validated.
Parsing
Syntax
We need to completely define “what” is catchable in our language grammar that is syntax oriented. For example, are we making sure that you can only use the keyword break in a loop or case statement. We need to know these so that we can determine what part of our processing: syntax, grammar or semantic are where we need to defines constraints and rules.
Keywords
You should avoid using these reserved words and keywords as function or variable names as JavaScript has reserved these words for its own use.
| |||||||
break | continue | do | for | import | new | this | void |
case | default | else | function | in | return | typeof | while |
comment | delete | export | if | label | switch | var | with |
All keywords must not be allowed to be used in:
- package names
- type names (any)
- member names
- method names
- formal argument names
- variable names
- loop variables
| ||
abstract | implements | protected |
boolean | instanceOf | public |
byte | int | short |
char | interface | static |
double | long | synchronized |
false | native | throws |
final | null | transient |
float | package | true |
goto | private |
| ||
catch | enum | throw |
class | extends | try |
const | finally | |
debugger | super |
| ||||
alert | eval | Link | outerHeight | scrollTo |
Anchor | FileUpload | location | outerWidth | Select |
Area | find | Location | Packages | self |
arguments | focus | locationbar | pageXoffset | setInterval |
Array | Form | Math | pageYoffset | setTimeout |
assign | Frame | menubar | parent | status |
blur | frames | MimeType | parseFloat | statusbar |
Boolean | Function | moveBy | parseInt | stop |
Button | getClass | moveTo | Password | String |
callee | Hidden | name | personalbar | Submit |
caller | history | NaN | Plugin | sun |
captureEvents | History | navigate | taint | |
Checkbox | home | navigator | prompt | Text |
clearInterval | Image | Navigator | prototype | Textarea |
clearTimeout | Infinity | netscape | Radio | toolbar |
close | innerHeight | Number | ref | top |
closed | innerWidth | Object | RegExp | toString |
confirm | isFinite | onBlur | releaseEvents | unescape |
constructor | isNan | onError | Reset | untaint |
Date | java | onFocus | resizeBy | unwatch |
defaultStatus | JavaArray | onLoad | resizeTo | valueOf |
document | JavaClass | onUnload | routeEvent | watch |
Document | JavaObject | open | scroll | window |
Element | JavaPackage | opener | scrollbars | Window |
escape | length | Option | scrollBy |
Some of the most common/meaningful errors to catch
-
- Unknown references
In JavaScript the most common errors are related to making a reference to an object or property of an object that does not exist.
This check is at the root of many other checks as well (such as visibility and access control).
-
- Dependency
Based on some dependency mechanism – usually at a project level (ie above the normal Java package/access control levels) means you can’t “see” a specific type.
-
- Access Control
Access control is based on how an elements access is defined and who can see it based on a given access context. This is different from Dependency which says independent of access control whether you have the right to see a type at all.
-
- Methods
Wrong number or arguments
Should or should not return a value
Not returning the correct type
Packages
All of the various VjO types can have a package component to their names. Here are some rules with packages:
- Each subpackage name must not collide with a global set of keywords
- Each subpackage levels namespace must be unique between other subpackage names at that level as well as any other VjO types at that level
VjO Sections
All of the VjO types are composed of sections. These sections describe the specific type being created, various declarations and then a required ending section (.endType()). A section is really a method that takes an Object Literal as an argument.
|
|
Green | Required. Each type starts with a section that says what kind of type we are defining. |
Yellow | Optional. Your type may or may not have this section depending on your needs. |
Red | Disallowed. This section is not valid for the specific type in question |
0 .. n | You can have 0 or more of these sections. A single section can contain multiple definitions for convenience. |
0 .. 1 | You can have 0 or 1 of these sections. |
1 | You must have only one of these sections. |
When looking at the following table, find the type (class, interface, enum, etc…) you are interested in defining. The column for that type describes the sections that are valid for that type. The order of the rows (from top to bottom) for that column, is the order you should follow in your types definition.
|
|
|
|
|
|
vjo-type | |
|
|
|
|
.defs | |
|
|
|
|
.values | |
|
|
|
|
.options | |
|
|
|
|
.needs | |
|
|
|
|
.needsLib | |
|
|
|
|
.inherits | |
|
|
|
|
.satisfies | |
|
|
|
|
.requires | |
|
|
|
|
.expects | |
||||
.mixin | |
|
|
|
|
.mixinProps | |
|
|
|
|
.props | |
|
|
|
|
.protos | |
|
|
|
|
.inits | |
|
|
|
|
.endType | |
|
|
|
|
Access Control and Modifiers
Access control is based on how an elements access is defined and who can see it based on a given access context. This is different from Dependency which says independent of access control whether you have the right to see a type at all.
All access control and modifiers are defined using the structured VjO comment syntax. Applying these access controls and modifiers are leveraged by the VjO build process and VJET.
-
- public
-
- default
-
- protected
-
- private
-
- friend
-
- Access Table
public | protected | <default> | private | abstract | final | transient
Not supported yet | |
ctype | |
|
|
|
|
|
|
etype | |
|
|
|
|
|
|
itype | |
|
|
|
|
|
|
otype | |
|
|
|
|
|
|
mtype | |
|
|
|
|
|
|
member | |
|
|
|
|
|
|
method | |
|
|
|
|
|
|
constructor | |
|
|
|
|
|
|
return type | |
|
|
|
|
|
|
argument | |
|
|
|
|
|
|
local variable | |
|
|
|
|
|
|
for loop variable | |
|
|
|
|
|
|
for in variable | |
|
|
|
|
|
|
Who is “this”
Who does “this” refer to while in the various VjO definition sections? The
|
|
vjo-type | Not applicable |
.options | Not applicable |
.needs | Not applicable |
.needsLib | Not applicable |
.inherits | Not applicable |
.satisfies | Not applicable |
.requires | Not applicable |
.expects | Not applicable |
.mixin | Not applicable |
.mixinProps | Not applicable |
.props | The type being defined (props – statics members) |
.inits | The type being defined (props – statics members) |
.protos | The instance (prototype – instance members) |
.endType | Not applicable |
Sections
Ideally we can use tables to define these validations.
-
- order of sections
-
- certain sections only make sense for certain type
-
- how many of each section can occur
-
- arguments for each section
-
- Each Section
ctype
otype
mtype
itype
etype
options
defs
values
needs
.needs('Proc')
.needs('util.Proc')
.needs(['Proc'])
.needs(['util.Proc'])
.needs(['util.Proc', 'util.Proc2', 'Proc3'])
What is the reason we use an array? This may seem easier for our implementations but not necessarily easier for someone using it.
Having something like a comma-delimited single-string-literal seems easier to type and read.
.needs('util.Proc, util.Proc2, Proc3')
needsLib
inherits
satisfies
requires
expects
mixin
mixinProps
props
protos
inits
endType
Namespace
proper names such as a.b.c.Type
uniqueness – can’t have package a.b.C and a type a.b.C
types must be unique at each package level
Modifiers
-
- abstract
Only ctypes can be abstract
Only instance methods can be defined abstract and only in an abstract ctype
-
- final
ctypes but not abstract ctypes
methods
not constructors
members
arguments
-
- transient (not in use yet)
Error Messages
Misc
Arrays
Object Literals
Type References
Function References
Operators
-
- special
arguments
This is the built in variable for all function invocations.
doit: function(a, b) { //< void doit(int, boolean) {
var avalue = arguments[0] ; //< int
var bvalue = arguments[1] ; //<
}
new
objectName = new objectType(param1 [,param2] ...[,paramN])
Parameters
objectName
Name of the new object instance.
objectType
Object type. It must be a function that defines an object type.
param1...paramN
Property values for the object. These properties are parameters defined for the objectType function.
instanceof
typeof
forms:
- typeof operand
- typeof (operand)
operand can really be any value or reference
This table summarizes the possible return values of typeof:
Type | Result |
Undefined | "undefined" |
Null | "object" |
Boolean | "boolean" |
Number | "number" |
String | "string" |
Host object (provided by the JS environment) | Implementation-dependent |
Function object (implements [[Call]] in ECMA-262 terms) | "function" |
Any other object | "object" |
delete
righthand has to be property or function.
We have issues is whether or not delete should even be allowed on VjO types since those types are based on full typespace consistency.
Dynamic objects created outside of VjO typespace should be ok.
We don’t have the notion of sealed types or sealed objects yet.
-
- Arithmetic
+
-
*
/
%
++
--
-
- Assignment
=
+=
-=
*=
/=
%=
-
- Comparison
==
!=
>
<
>=
<=
-
- Logical
&&
||
!
-
- Conditional (?:)
Statements
-
- if-else
-
- switch
-
- for loop
-
- while loop
-
- break loops
-
- for … in
for (variable in obj) { … }
The variable name becomes a new scoped name.
-
- try … catch
-
- throw
-
- onerror
-
- with
This is a tricky one as it creates a new scope for target object in the with(…)
function foo(){
with(document.forms[0]) {
var x = elements[0].value;
var y = elements[1].value;
with(elements[2]) {
var z = options[selectedIndex].text
}
}
}
To be figured out
JavaScript has built in values such as NaN, null and undefined that need to be thought out in terms of how they fit with our overall typing scheme.
For example an if or while etc… is based on a Boolean expression. However an if (somethingThatIsUndefined) is a common check in JavaScript.