TypescriptPreprocessor
TypeScript JavaScript
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
dec
src
webstormSettings
.gitignore
README.md
package.json
tsp.icon.png

README.md

TypescriptPreprocessor

A typescript preprocessor helper based on simple attachable plugins.

Avaliable Plugins:

  • @embed -> embeds png,svg,js,txt into a png library file.
  • @source -> adds more than one source folder to classpath.
  • @import -> use cls.ass.packages as imports. Automatically resolves relative reference paths.
  • @define -> use cls.ass.packages as definition imports. Automatically resolves relative reference paths to .d.ts files.

Dependencies

TypescriptPreprocessor uses many dependecies but one [ node-canvas ] needs Cairo as a backed Canvas implementation for NodeJS so:

Unless previously installed you'll need Cairo!!!.

Cairo download & instalation instructions

( Installed it with ports without problems but sometimes is a little complicated to get Cairo installed )

Installation

sudo npm install -g tsp

EMFILE max files open error

If you get an EMFILE max files open error during install. You need to CHANGE the max open files opened to a higher value with the command:

$ sudo ulimit -n 1024

This is only a temporally fix but it gets the work done!

Command line usage

Usage: tsp --root projectRootDir -source inputFile

Options:
  -r, --root     Project Root dir
  -s, --source   Source file
  -i, --install  Install Preprocessor to project

WebStorm Integration##

###ToolbarIcon and ExternalTools:###

To install the ExternalTools & Toolbar integration:

  • Open Webstorm.
  • Goto to file import settings.
  • Localize the file TSPSettings.jar located at webstormSettings/TSPSettings.jar and load it.
  • Restart. Done!!

Now every time you need to process a xxxx.lib.tsp, sources.tsp or any .ts file containing @import/@define directives you can tap the new icon [TS] in the toolbar to get the preprocessing done ;-)

Getting started

Preparing a new TSP project

First you need to install the tool to your current project.

$ cd /path/to/your/project
$ tsp --install

A typical setup will involve adding two files to your project: config.tsp and the sources.tsp

config.tsp

Here you can configure some plugin preferences

{
	"root": "/path/to/your/project",
	"pluginData": {
		"SourcePaths": {
			"sources": [
				// DO NOT TOUCH
				// Here will be the project source
				// folders where TSP will search for
				// classes & definitions
			]
		},
		"ImportsToReference": {
			"enableUndo": false
			//By default @import will remove the @import directive
			//after processing.
			//Set to true to leave it untouched   
		},
		"DefinitionToReference": {
			"enableUndo": false
			//By default @define will remove the @define directive
			//after processing.
			//Set to true to leave it untouched 				
		}
	}
}

sources.tsp

Use this file to define the TSP project sourceFolders. When TSP finds a ///@import or ///@define directive it will search across all the sourceFolders to test if it can find the import/define file.

In the next example I have defined 2 main sourceFolders: src and otherSourceFolder.

Defining multiple source folders

(for now...) Source folders must be relative to the project root

///<!SOURCE_FOLDER_PATHS>
///@source /src
///@source /otherSourceFolder

Command line processing:

$ tsp --root /path/to/your/project --source sources.tsp

Embending content

To use the embed directives you must create a file named xxxx.lib.tsp.

The resulting png file name will be xxxx.lib.png

The @embed & @embedLibrary directives provides a simple way of generating a library of "media elements", allowing to embed inside the resulting png image:

Command line processing:

$ tsp --root /path/to/your/project --source /path/to/your/xxxxx.lib.tsp

@embedLibrary Usage

( You must declare the @embedLibrary before any @embed directive )

The @embedLibrary directive lets us specify:

  • The resulting library export name
  • The method for "Texture Packing"
  • The optimization method of the resulting png file

Usage inside xxxx.lib.tsp:( pay attention to the ///@embed… format )

///@embedLibrary{name:'LibraryExportedName',sort:'area',compression:'none'}
options
name: The resulting library export name
sort: The method for "Texture Binary Packing"

  * maxside [Default]
  * width
  * height
  * area

compression: The optimization method of the resulting png file 

  * none
  * low
  * med
  * high
  * best

@embed Usage

( You must declare the @embed after the @embedLibrary directive )

The @embed directive lets us add an element to the current library:

///@embedLibrary{name:'LibraryExportedName',sort:'area',compression:'none'}
///@embed { src:'sourceFile.png', member:'myPNG' }
///@embed { src:'sourceFile.js',  member:'myJS' }
///@embed { src:'sourceFile.svg', member:'mySVG_PNG', format:'png' }
///@embed { src:'sourceFile.svg', member:'mySVG_CTX', format:'ctx' }	
options
///@embed { src:'sourceFile.svg', member:'mySVG_CTX', format:'ctx' }

src: The source file to include
member: The exported library member name
format: Used only in svg files to specify the output format.

  * png => converts the svg to a png image and includes it in the lib.
  * ctx => converts the svg to a js file containing a class
           that you can use to render the svg to a canvas

Loading back the library

For loading back the elemens from the library you need to use the TypescriptPreprocessor-Loader library.

Example code:

$LIB.load('demo.lib.png').on(pulsar.events.Event.COMPLETE, onLoaded );
function onLoaded()
{
	// Reference to our current loaded library
	// Remeber that the name must correspond to the one
	// you assigned in the
	// @embedLibrary{ name:'xxxx' ...
	var myLib = $LIB('TestLibrary');
	
	// returns the master library png image [HTMLImageElement]
	var libraryImage = myLib.getLibImage(); 
	
	// returns "myCanvasElement" as a [HTMLCanvasElement] 
	var canvasElement = myLib.getCanvas("myCanvasElement");
	
	// returns "myImageElement" as a [HTMLImageElement]
	var myImageElement = myLib.getImage("myImageElement");
	
	// returns "myCustomCode" as a string
	var myCustomCode = myLib.getCode("myCustomCode");
	
	// returns "myShapeElement" as a pulsar.lib.shapes.Shape instance
	var myShapeElement = myLib.getShape("myShapeElement");
	
	// injects "myCssCode" into the DOM
	var myCssCode = myLib.injectCss("myCssCode");
	
	// injects "myJSCode" into the DOM
	var myJSCode = myLib.injectScript("myJSCode");

}

In depth TypescriptPreprocessor-Loader usage: http://xperiments.github.io/TypescriptPreprocessor/

TS Language Directives

@import & @define directives:

Translates @import @define with package names to relative ///<reference path="…."/>

///@import es.xperiments.Demo
///@define es.xperiments.Demo

becomes:

///<reference path='src/es/xperiments/demo.ts'/>
///<reference path='src/es/xperiments/demo.d.ts'/>

Also you can configure the "enableUndo" property inside the tsp.config.js to let the preprocessor to no remove the original directive. This way you can easely revert to the original @import @define directive.

///@import es.xperiments.Demo
///@define es.xperiments.Demo

becomes:

///<reference path='src/es/xperiments/demo.ts'/>@import es.xperiments.Demo
///<reference path='src/es/xperiments/demo.d.ts'/>@define es.xperiments.Demo 

Command line processing:

$ tsp --root /path/to/your/project --source /path/to/your/xxxxx.ts