Index

N4JS Design Specification

2019-08-08 13:15:33 CEST
version 0.9

Table of Contents

1. Introduction
- 1.1. Notation
- 1.2. IDE Components
  - 1.2.1. Naming Conventions
2. Eclipse Setup
- 2.1. System Requirements
- 2.2. Contribute
  - 2.2.1. Eclipse Installer
    - 2.2.1.1. Changing the Setup Script
  - 2.2.2. Manual IDE Configuration
3. Release Engineering
- 3.1. Nightly build on Eclipse infrastructure
- 3.2. Build the N4JS IDE from command line
- 3.3. Updating frameworks and dependencies
  - 3.3.1. Update of Eclipse, EMF, Xtext, etc.
  - 3.3.2. Update of the embedded JRE
4. Tips and Tricks
- 4.1. Naming
- 4.2. Logging
- 4.3. Cancellation Handling
- 4.4. Caching
- 4.5. Dependency Injection
- 4.6. Miscellaneous
5. Parser
- 5.1. Overview
- 5.2. N4JS Parser
- 5.3. Parser Generation Post-Processing
- 5.4. Modifiers
- 5.5. Conflict Resolutions
  - 5.5.1. Reserved Keywords vs. Identifier Names
  - 5.5.2. Operators and Generics
- 5.6. Content-Assist Parser
6. Type System
- 6.1. Type Model and Grammar
- 6.2. Type System Implementation
- 6.3. Type Inference of AST
- 6.4. Structural Typing
7. Type Index
- 7.1. Design Rationale
  - 7.1.1. Getting the Xtext Index (IResourceDescriptions) Content
- 7.2. Design Overview
- 7.3. N4JS Resource Load States
- 7.4. Types Builder
- 7.5. Incremental Builder (Overview)
- 7.6. Dirty state handling
  - 7.6.1. Use case: Restoring types from user data
  - 7.6.2. Use case: Updating the Xtext index
8. Project Model
- 8.1. Package.json File
- 8.2. Accessing Project Information
- 8.3. Caching
  - 8.3.1. Caching of ExternalLibraryWorkspace
  - 8.3.2. Caching of N4JSProjectsStateHelper
- 8.4. WildcardPathFilter
- 8.5. ProjectUtils
9. Binding
- 9.1. Design Rationale
- 9.2. Binding to Members
- 9.3. Getter / Setter Binding
- 9.4. Static Member Binding
- 9.5. Enumeration Literals Binding
- 9.6. Accessibility of types and members
- 9.7. Member Scope Example
- 9.8. Scoping for Members of Composed Type (Union/Intersection) Example
- 9.9. Structurally References Types
- 9.10. Building
- 9.11. Proxies and Proxy Resolution (Overview)
10. Validation
- 10.1. Validation overview
- 10.2. Validation control flow
- 10.3. Issue IDs and Messages
- 10.4. Usage Pattern
- 10.5. Links
11. References
- 11.1. Use cases
- 11.2. Calculation algorithm
  - 11.2.1. Xtext default implementation
  - 11.2.2. N4JS implementation
- 11.3. Performance Of Dependency Calculation
- 11.4. Kinds of references
  - 11.4.1. Cross References to be ignored
  - 11.4.2. Cross References to be handled
- 11.5. Transitive dependencies
- 11.6. Find references
  - 11.6.1. Background
  - 11.6.2. How Find References Work
12. Compilation
- 12.1. Introduction
- 12.2. Generators
- 12.3. Transpilers
- 12.4. N4JS-to-EcmaScript Transpiler
- 12.5. n4jsc Headless Compiler Interface
  - 12.5.1. building the headless compiler
13. Execution
- 13.1. N4JS Project Execution And Linking Model
  - 13.1.1. N4JS Execution With NodeJS
- 13.2. N4JS Execution And Linking File
  - 13.2.1. NodeJS Specific ELF
- 13.3. Runners
- 13.4. Legacy Execution Engine
- 13.5. Design
  - 13.5.1. Usage Outside N4JSIDE
    - 13.5.1.1. Use Node with Maven
  - 13.5.2. Usage Inside N4JSIDE
- 13.6. Runtime Injection
14. Tests
- 14.1. Performance Tests
  - 14.1.1. Synthetic Performance Tests
- 14.2. ECMA Tests
  - 14.2.1. Grammar Tests
    - 14.2.1.1. Negative Tests
    - 14.2.1.2. Test Exclusion
- 14.3. Integration Tests
- 14.4. Test Helpers
  - 14.4.1. Parameterized N4JS tests
- 14.5. Issue Suppression
- 14.6. Xpect Tests
- 14.7. Xpect Proposal Tests
- 14.8. Apply Proposal And Execute Tests
- 14.9. Organize Imports Test
  - 14.9.1. organizeImports
- 14.10. Access Control Test
- 14.11. Smoke Tests
  - 14.11.1. How to handle smoke test errors?
  - 14.11.2. SmokeTester and ExceptionAnalyzer
- 14.12. UI Tests with SWTBot
  - 14.12.1. Writing SWTBot Tests
  - 14.12.2. Running SWTBot Tests
- 14.13. Debugging UI Tests
  - 14.13.1. Connecting to the X-server on the build-node
  - 14.13.2. Tools to investigate the java-stack
15. UI Concepts
- 15.1. User Interface Concepts
  - 15.1.1. Eclipse UI Concepts
  - 15.1.2. Non-Eclipse UI Concepts
- 15.2. User Interface Resources
  - 15.2.1. Icons
16. Formatting
- 16.1. Objective
  - 16.1.1. Formatting Comments
- 16.2. Architecture
  - 16.2.1. Implementation example
- 16.3. Formatter Implementation Guidelines
- 16.4. Configuration
- 16.5. UI Integration
- 16.6. Unit Testing with Xpect
17. External Libraries
- 17.1. Major Components
- 17.2. Headless External Library Support
  - 17.2.1. Custom npm settings
- 17.3. Future Work
  - 17.3.1. Multiple Dependency Scope
  - 17.3.2. Run Tests from TestLibrary
18. JSON Support
- 18.1. JSON Parser
- 18.2. JSON Language Extensions
  - 18.2.1. JSON Validator Extensions
    - 18.2.1.1. File-Specific Validator Extensions
    - 18.2.1.2. Declarative JSON Validator Extensions
  - 18.2.2. JSON Resource Description Strategy
19. JSDoc
- 19.1. Design Rationale
  - 19.1.1. General Design
  - 19.1.2. Type Expressions
20. DocExporter
- 20.1. Specification Exporter
21. Rename Refactoring
- 21.1. Rename Refactoring UI interaction
- 21.2. RenameElementProcessor interaction
22. Flow Graphs
- 22.1. Flow graphs overview
- 22.2. Dataflow
  - 22.2.1. Dataflow graph
  - 22.2.2. Dataflow analyses
    - 22.2.2.1. Def→Def / Def→Nothing analysis
    - 22.2.2.2. Def|Use←Decl analysis
23. Publish npms
- 23.1. Publish n4js-libs to during maven build
Appendix A: Hints
- A.1. Xtext Injection
  - A.1.1. Multiple Injectors and Singletons
    - A.1.1.1. Avoiding duplicate singletons
      - A.1.1.1.1. Defining binding in the shared injector
      - A.1.1.1.2. Defining binding in the custom injector
  - A.1.2. Dependency Injection Hints
- A.2. Eclipse
  - A.2.1. Show the current Xtext index
  - A.2.2. Plug-in spy
- A.3. Maven
  - A.3.1. How to check for Maven MOJO updates
Appendix B: Module Loading
- B.1. Dependency Management
- B.2. ECMAScript Modules
  - B.2.1. ES5 Modules Systems
  - B.2.2. ES6 Modules
- B.3. ECMAScript Module Loaders
  - B.3.1. ES6 Module Loaders
  - B.3.2. Polyfills for ES6 Module Loaders
- B.4. Case Study : TypeScript
  - B.4.1. ES6 Modules Support
  - B.4.2. TypeScript and Module Loading
- B.5. Cyclic Dependencies
- B.6. System.register as transpilation target
- B.7. CommonJS as transpilation target
Appendix C: License
Appendix D: Acronyms
Appendix E: Bibliography and Footnotes

Appendix D: Acronyms

CDep

Compile-Time Dependency

RDep

Run-Time Dependency

LDep

Load-Time Dependency

IDep

Initialization-Time Dependency

EDep

Execution-Time Dependency

AC

Acceptance Criteria

ANTLR

ANother Tool for Language Recognition

API

Application Programming Interface

AST

Abstract Syntax Tree

ASI

Automatic Semicolon Insertion

AST

Abstract Syntax Tree

BNF

Backus-Naur Form

CA

Content-Assist

CSP

Constraint Satisfaction Problem

CLI

Command Line Interface

DOM

Document Object Model

DSL

Domain Specific Language

EBNF

Extended Backus-Naur Form

EMF

Eclipse Modeling Framework

EPL

Eclipse Public License

FQN

Fully Qualified Name

GLB

Greatest Lower Bound, also known as infimum

GPL

GNU General Public License

IDE

Integrated Development Environment

IDL

Interface Definition Language

LSP

Liskov Substitution Principle

LUB

Least Upper Bound, also known as supremum

N4JS

NumberFour JavaScript

UI

User Interface

UML

Unified Modeling Language

VM

Virtual Machine

XML

Extensible Markup Language

XSLT

XSL Transformations

XSL

Extensible Stylesheet Language

WYSIWYG

What You See Is What You Get

WLOG

without loss of generality