Features
Jasy uses a full scripting language to define tasks. This allows the widest flexibility for the developer.
Instead of being limited to a configuration like DSL you can interact with data and methods like in a real programming languages (in fact you are writing your tasks in Python 3). Developers are able to modify results from one method and pass the result into a second method. This kind of flexibility allows Jasy being used in a wide array of projects and situations.
In Jasy you define tasks which are callable from the outside aka on the command line. But the key is one can also have other custom methods and classes one can make use of. It's possible to import any features and modules offered by the standard Python library or locally installed packages e.g. via pip.
Tasks support having parameters. These are automatically offered on the command line via jasy taskname --optionname optionvalue etc.
Each Jasy project is able to define requirements to other projects. These requirements are solved recursively and duplicates (projects with the same name) are filtered out. Projects can also be overridden by projects being higher in the dependency chain.
Jasy supports a set of layouts inside projects. For adding support for the various 3rd party libraries and frameworks Jasy is able to use a custom set of files and is able to files to internal file IDs (basically the exported name of a file e.g. jQuery exports $). There is a Jasy Compat project showcasing how to integrate jQuery, QUnit, Modernizr and Co using a Jasy configuration.
Some projects are using custom build routines which applies some kind of magic to the code before concatting single files (aka adding intro/outro content, patching files with version numbers, etc.). For these cases Jasy is able to define setup routines which should be executed whenever a project is initially used or updated.
Jasy can automatically clone Git projects by all supported URLs from private and public repositories. It uses so called shallow clones to improve download speed and reduced disk space usage. Jasy is smart enough to update branches automatically on every run (reducing the hassle with typical Git sub modules) while keeping tagged versions in their original state. Switching between versions is as easy as updating the configuration file and pushing the change to that file to the server. All other users of the projects will download the new version of the dependency automatically with the next time they execute Jasy.
Each project in Jasy is able to share actual Python code with other projects. This is conveniently pre-configurd. One only has to add a jasylibrary.py to the root folder of a project and add the @share decorator to methods which should be shared to the outside. The exported methods will be part of an object called like the project name in the jasyscript.py of the including project.
Jasy is able to execute tasks from another project in the local context.
Jasy has deep JavaScript language support through being based on a full-blown parser which itself is based on the mature Spidermonkey parser from Mozilla. Jasy even fully supports upcoming features like generators, array comprehension, etc. of JavaScript 1.8. During that process Jasy generates a easy to process AST. This AST can be used to transform the original code for e.g. API documentation, code formatting, code linting, optimization, etc. Comments are attached to the generated AST nodes during parsing the actual code.
Reliable, automatic dependency analysis for JavaScript is built in. Automatically sorts files by their requirements. Dependency analysis happens with permutations applied (e.g. debug builds might contain classes deployment builds might not contain).
The compressor feature in Jasy removes white space, comments and any formatting from original code using the AST generated by the parser.
The optimizer feature in Jasy processes the AST before passing it to the compressor. It does a lot of things known from other JavaScript compressors as well. Generally speaking it optimizes code in a very stable fashion and results in comparable output file sizes like UglifyJS or Closure Compiler. It out performs YUI Compressor, qooxdoo's generator and other older tools by a wide margin.
In detail this means:
- Dead code elimination removes unreachable code in
if/elseblocks, conditional statements?:,switch/caseandAND/ORoperators. - Supports comparison of hard-coded or permutation added values for
boolean,numberandstringtypes. - Groups single
varstatements into blocks. - Removes needless blocks (with just one statement)
- Automatically combines strings and numbers (e.g. "Version " + 1.3 => "Version 1.3")
- Optimizes if(-else) statements with expressions as content
- Translates if-statements without else using
&&or||operators - Translates if-statements with else using conditional operator
? :(especially worth with returns/assignments)
- Translates if-statements without else using
- Removes needless else (if previous if-block ends with a return/throw statement)
- Removes needless parens based on priority analysis on the AST
- Renames file private variables (starting with double underscore by convention)
The asset feature in Jasy allows for referencing assets (images, fonts, style sheets, ...) via internal IDs instead of URLs or relative paths. This makes adding support for things like CDNs a breeze later on and easily supports different kind of deployment structures.
In Jasy assets are included by having a JavaScript file requiring them. This means that you are able to define which assets a specific JavaScript class is requiring and only if that class is included into the build the required assets are indexed/copied as well.
Note: The asset managment requires the Core Library on the client side to offer the required APIs. To make use of the AssetManager is Jasy projects have to require this library in their configuration.
Meta data for assets can be automatically pushed to the client as well. Currently this is implemented to send image sizes to the client. This allows for layouting these images without actually having loaded them which is quite useful for building DOM structures in memory.
Note: In the future we might add information like video codecs, play duration, file size, etc. The implementation is pretty extensible for supporting these things.
During the deployment of assets all files used by the current list of JavaScript files are copied over to the destination folder. The resulting folder is self contained and all relevant assets - even from different projects - are merged into that exact folder.
Jasy supports image sprite. This consists of two parts:
- Creating image sprites and required configuration files from folders of images (via scripting). This uses intelligent packing algortithms to optimize the memory and size of these images automatically.
- Using configuration files (could also be hand written instead of generated) to determine which images are part of an image sprite and pushing that info to the client.
On the client only the separate files are being used – not the image sprite name. Jasy takes care of publishing that knowledge to the client. This means that image sprites can be enabled later during development as well - and that without changing a single line of code.
Jasy allows defining and using sprite animations via simple configuration files. These files store the information about how such a animated image is layouted e.g. how many rows and columns are there or whether a fully custom layout is used. Identical to image sprites there are some nice APIs on the client side offered by the Core Library. These allows accessing a specific frame of an animated image. These return the position and size of the section of the image to render.
Note: Image animations could be also stored inside image sprites. Offsets are correctly handled even in that more complex scenario.
Permutations in Jasy are basically a feature to mutate code and dependencies based on the state of configuration fields. Jasy automatically build permutation objects based on all (configured) possible values of each activated field. For example there might be these fields:
-
engine:webkit,gecko,trident,presto -
debug:true,false -
device:smartphone,tablet,desktop,tv
This configuration would generate a list of 4*2*3 = 24 permutation objects covering all possible values. For every permutation in this list Jasy is able to create separate files, separate folder structures, separate application bundles, etc. This is totally flexible and is fully scriptable in the jasyscript.py.
The JavaScript API in Jasy is also able to use permutation data to mutate JavaScript code and this way dependencies to other classes (dependency tracking is done after applying permutations). Basically every method on a class object is able to handle an incoming permutation object and is able to return data based on the mutated code.
Note: Regarding performance: Permutations and their effect on the code is heavily cached. Jasy figures out which fields are accessed in each class, only applies relevant permutations and caches the results individually.
The locale support in Jasy is build on the industry standard CLDR data (fully included in the Jasy distribution package) used by Microsoft, Oracle, IBM and Co as well. It contains information about date and number formats, calendars, sorting priorities, etc.
Jasy rebuilds the XML files of each locale into an Jasy-enabled project which is dynamically added during processing the permutations ("locale" is one built-in permutatiomn option).
The classes generated by Jasy are super modular and make use of the dependency handling in Jasy. The application developer is able to just use the e.g. long date format info without the other available information and no additional overhead. All data is exported under the locale namespace.
Locale data is always using a fallback chain. It exports data starting with the defined locale e.g. de_AT and fills in the gaps with a fallback to a language only version e.g. de and the root defintion as the general fallback. This means that all data should basically export somewhat comparable data. Still it might make sense to add some JavaScript classes on top of these raw data classes to make working with the data itself more convenient.
Translations via Gettext are pretty much standard in the open source world and are available in many programming languages (PHP, Python, …) and Frameworks. Jasy builds on top of polib to offer an integrated support for translations build on data available in so called po files. Jasy supports the full range of features supported by the PO file format e.g. multi plural forms / rules, context translations, etc.
Translations follow the same logic as locales falling back from full locale de_AT to language de to original text (used in implementation).
Jasy is able to patch the original code with translated strings. This is a pretty powerful feature with a lot of benefits:
- Reducing overhead calling methods like
tr,trn, etc and this way improving performance. - Reducing data transfer to client (no original text anymore, to map to lookup original text for translation)
- Replacing template constructs with
%1etc. into string concats for better performance e.g."Hello %1"is translated into"Hello " + variable.
Translation features require a client side API offered by the Core Library with these methods:
core.locale.Translate.tr(message, args)core.locale.Translate.trc(context, message, args)core.locale.Translate.trn(singularMessage, pluralMessage, args)
Use these methods for translating your application together with the infrastructure Jasy offers.
Jasy is able to generate API data from JavaScript projects. The data could be rendered by the API Browser or any other custom application which is able to read and render JSON files.
Jasy generates API data from different JavaScript declarations (Core Library, plain JavaScript, …). When using Core Jasy supports the following features:
- Supports classes, mixins, interfaces, events and properties.
- Most of these features are not easily available in other libraries than Core but the support for these kind of things is pretty generic and could be extended to support other libraries as well.
- Supports links to native types like
String,Array, etc. - Merges polyfills to target classes e.g.
String.prototypeeven if source file is named differently.
Jasy supports package documentation to allow projects to define introduction documentation for every package/namespace. Just put readme.md or package.md into a folder with other JavaScript files and it will be used as package documentation. This package documentation is typically shown when selecting a package (typically visualized as a folder) instead of class/module.
Jasy translates Markdown content into HTML and applies syntax highlighting to code sections. It uses GitHub's extended high performance Sundown Markdown parser and the widely used Pygments for syntax highlighting. Pygments supports alot of other languages than JavaScript, too. So no problem to have PHP example code in your API docs as well.
Support for tags to easily marking classes, modules, methods etc. is built in as well. That's useful for marking properties like deprecated, overridden, new, etc.
The internal web server allows for easily setting up a local web server to deliver the local Jasy based application to the web browser or remote machines. The propose of this server is to make local development easier.
Jasy is able to define different routes to different targets. It's easy to mix local file delivery with remote mirroring under the same server. Each root works on a top level entry point e.g. /github, /s3, /cdn, ...
Jasy supports proxying and mirroring remote server requests and using a full offline feature it can also work from cache only without requiring the original mirrored server. This feature is super useful for slow remote servers, for testing machines under different domains (fix CORS issues), etc. The
Jasy's web server comes with a good set of additional mime types to support typical HTML5 features like HTML5 AppCache, web fonts and modern video formats.
For setting up new projects Jasy comes with a pretty powerful scaffolding feature. Scaffolding works like a skeleton or boilerplate project but offers on-top configuration to make that new project directly usable after creation.
Jasy supports modifiying the original code of the skeleton to match the requirements of the new project. It automatically replaces placeholders in all files by the actual values defined via questions or command line parameters.
The skeleton is able to define questions for confiuguration. These can be answered interactively during project creation or pre-defined via command line parameters. Questions can also be interactive and fine tune the original skeleton in quite powerful ways. For that Jasy supports a custom jasycreate.py for writing down custom code which is executed on the files copied over from the skeleton.
New projects can be created by remote hosted projects via Git URLs. Jasy will automatically clone the repository into a new temporary folder and copies over and configures an existing skeleton from this "origin" project.
A lot of Jasy's functionality is built upon a so-called binary cache based on shelve. This system uses a single cache file per project, intensively caches access and write to the memory and improved IO on most system by a large extend compared to single file based implementations.
Jasy supports either YAML or JSON files for configuration and works fine mixing both configuration file types (e.g. using JSON in one project and YAML in another).
Jasy's logging infrastructure supports auto structuring mesages. It supports colorizing output for terminals.
The doctor in Jasy offer a self inspection infrastructure to verify whether all required components are installed and up-to-date.
An easy to use API makes it possible doing simple file operations with Unix like commands. The file manager also offers some magic regarding placeholders in file names so that you can easily make use of the current permutation checksum, prefix, etc.
Jasy has a pretty good support for Git repository and is able to clone them, figuring out the current branch, updating them, etc.
Jasy integrates a pretty powerful Markdown implementation. This is mainly used by the API generator but can be used to transform other Markdown files in custom tasks as well.
The output manager is the central instance to manage all optimization and formatting of generated files e.g. adding line breaks to JavaScript, indent JSON, etc.
Tasks in Jasy are the main coding block of jasyscript.py files. All methods decorated with the task method are made publically available on the command line. The documentation of these methods and their exact signature is automatically shown on the help screen as well.