UI5TypescriptDefinitionParser
Parses Typescript from the UI5 documentation
Usage
Install
- Go to console and run
npm install
(make sure node.js is installed and referenced in PATH <- Windows only) - Install gulp (
npm install gulp -g
)
Use
Create a nodejs server application and import the module Parser:
import { Parser } from "./Parser";
let p = new Parser("./config.json");
return p.GenerateDeclarations();
Settings
All settings are configured in the config.json file, which path can be given to the parser.
1. Fetching API.json
The parser will first try to get locally cached files. If it does not find any it will try and get them from the hana.ondemand source.
"connection": {
"root": "https://openui5.hana.ondemand.com/test-resources",
"endpoints": [
"sap/m/designtime/api.json",
"sap/ui/core/designtime/api.json",
"sap/tnt/designtime/api.json",
"sap/ui/commons/designtime/api.json",
"sap/ui/demokit/designtime/api.json",
"sap/ui/dt/designtime/api.json",
"sap/ui/layout/designtime/api.json",
"sap/ui/suite/designtime/api.json",
"sap/ui/table/designtime/api.json",
"sap/ui/unified/designtime/api.json",
"sap/ui/ux3/designtime/api.json",
"sap/uxap/designtime/api.json"
]
},
You can find these files after the first run in the apis
folder generated by the parser. You can prevent caching by setting it to false:
"cacheApis": true,
2. Preprocessing
The preprocessing will modify the loaded api.json objects (no files are modified) using the jsonpath package. Thus, it uses json path to get the desired parameters specified by jsonpath
. In the subscript filter javascript can be used (for example regex).
After that it will apply the function given in script
. The scriptfunction always gets a val variable, which has to be manipulated and returned. The logger will output the caught object in debug level or set a breakpoint in the debugwrapper in the parser.ts, if you are running it with a debugger.
In addition a comment can be provided to describe what is happening in the log output.
This example will set all methods except extend and getMetadata for all modules starting with sap/m/
to not static:
"preProcessing": {
"correctStaticSapM": {
"comment": "Replaces incorrect static values in sap/m",
"script": "if(val.name) val.static = false;",
"jsonpath":
"$.symbols[?(@.kind == 'class' && @.module.startsWith('sap/m/'))].methods[?(@.static == true && @.name.match(/^(?!extend|getMetadata).*$/))]"
}, ...
}
3. Parsing
The parsing process goes through the loaded api docs, takes all exported symbols and combines them to valid typings. Via config you have multiple ways to adjust the process.
3.1 Types and parameter name replacements / fixes
To fix some bugs in parameter names (for example usage of html tags or other not-allowed figures for variable and parameter names) the cleanParamNames
section can be used:
"cleanParamNames": {
"<code>vData</code>": "vData",
"<your-page-object-name>": "[key: string]"
},
The property name is the parameter to replace and gets replaced by the value (which has to be a string). Example:
class a {
public testMethod(<code>vData</code>: string): void;
}
The method above would not be compilable for the parser. Using the replacement, the <code>vData</code>
will be replaced with the proper "vData"
name:
class a {
public testMethod(vData: string): void;
}
This will be applied to all function/method parameters in all classes, namespaces, etc.
3.2 Type Map
The type map is the same as the cleanParameterNames
. It will replace wrong types, in all classes, namespaces, enums, etc. The key will be the type to replace, the value will be the replacement
"typeMap": {
"*": "any",
"any[]": "any[]",
"array": "any[]",
Example:
class a {
public testMethod(data: *): void;
}
will be replaced by
class a {
public testMethod(data: any): void;
}
3.3 Parsing enums
Enums will be parsed using the template enums.d.ts.hb
. The template uses Handlebars syntax and the raw symbol:
interface ISymbol {
// enum
kind: string;
// sap.m.BackgroundDesign
name: string;
// BackgroundDesign
basename: string;
// sap/m/library.js
resource: string;
// sap/m/library or sap.m.library if not modular
module: string;
// BackgroundDesign
export: string;
// true
static: boolean;
// public, private, recstricted or protected
visibility: string;
// Description text
description: string;
// The properties the enum uses
properties: IProperty[];
}
interface IProperty {
// Solid
name: string;
// public, private, restricted or protected
visibility: string;
// true or false
static: boolean;
// any type, basetype or other sap.ui.... type
type: string;
// any description
description: string;
}
The files will all be put out in the out folder and enums subfolder. All enums will be declared ambient.
3.4 Parsing namespaces
Uses ParsedNamespace
class and namespace.d.ts.hb
template. All namespaces are ambient (thus, always available).
3.5 Parsing interfaces
Uses ParsedClass
class and interface.d.ts.hb
template. All interfaces are ambient (thus, always available).
3.6 Parsing classes
Uses ParsedClass
class and either classAmbient.d.ts.hb
template, if the class is ambient (module
of Symbol in the api json is separated with dots .
instead of slashes /
), otherwise it uses classModule.d.ts.hb
.
a) Establishing Inheritance
After getting all classes (that means the ParsedClass objects are instanciated), the parser will start with base classes that have no base class and work its way up until the inheritance hierarchy is established.
b) Creating Overloads
After the class inheritance is done, the parser will start to get all overloaded methods and try to adjust them so they can be overloaded. Furthermore leading optional parameters are resolved as overloads. Tailing optional method parameters are left with ?
.
4. Postprocessing
Postprocessing will be going through all output files and replace whole text sections either using strings or regular expressions. The key will be the path to the file starting from the output folder. The value is an array with all replacements that should be done in the file.
Example for a string:
"namespaces/sap.ui.core.BusyIndicator": [
{
"searchString": "declare namespace {} {",
"replacement": "declare namespace sap.ui.core.BusyIndicator {"
}
],
Example for a regex:
"classes/sap/ui/model/Model": [
{
"searchString": "(\\W)Model([^\\w\\/\\.'`<])",
"replacement": "$1Model<T>$2",
"isRegex": true,
"regexFlags": "g"
}
]
to replace with a regex isRegex
has to be set to true and optionally a flag can be set (as the global flag above).
Also globs can be used:
"namespaces/**/*": [
{
"searchString":
"sap\\.ui\\.core\\.(?:Control|Element|BusyIndicator|Component|mvc\\.Controller|mvc\\.View|mvc\\.Fragment|Fragment|Core|mvc\\.HTMLView|mvc\\.JSONView|mvc\\.JSView|tmpl\\.Template|mvc\\.TemplateView|mvc\\.XMLView)([^\\w])",
"replacement": "{}$1",
"isRegex": true,
"regexFlags": "g"
},
]
5. Custom Handlebars extensions
To put in some custom handlebars extensions just modify the file handlebarsExtensions.ts