Cross-Browser.com

XC is a companion utility for X. XC scans your application files and creates a custom X library file (with optional compression) which contains only those X functions and objects used in your application. XC also allows you to create a library file containing only the X functions and objects you specify.

XC is still in its infancy and is very simple. The format for the project file is very simple. The symbol parser and compression are very simple. These may be (will be) improved but for now XC works well enough to test its utility. I am open to any comments/suggestions you may have.

Now that I've had a chance to use XC I see lots of things I'd like to improve...

The project file format could be better.

I now have all documentation in xml files. This opens up many possibilities. The X Viewer is my first application.

I'm playing with the idea of conditional compilation.

Eventually I'd like to port XC to PHP.

XC is a Win32 command-line program (a VC++ project) written in C. It is invoked as follows:

  xc prj_name

XC will open the file 'prj_name.xcp' in the current directory and create the output files, prj_name.js and prj_name.log, also in the current directory.

Format

; comments are from ';' to end of line
options -cmp -dep +log +dbg ; See option descriptions below.
libpath ..\   ; X library files directory (requires trailing backslash).
appfiles      ; Application file pathnames from next line to end of file.
App file pathname 1
App file pathname 2
...
App file pathname n

Options

Examples

; XC Project: floater_xlib

options
libpath ..\
appfiles
..\..\examples\floater.php
..\..\examples\floater_bar.php

; XC Project: x_anim

options -dep -glb

; If you don't want the library file to be
; compressed then add -cmp to the above options.

libpath lib\

appfiles

x_anim.xcp

; This project file is the only app file fed to XC.
; The following X symbols will be included in the
; library file. They are commented-out so XC will
; not see them as more app files.

; xEllipse
; xParaEq
; xSlideCornerTo

By convention all X functions, objects and global variables begin with 'x' and are camel-cased. All X functions and objects should be put in separate files with the following standard header, where 'xSymbol' is the name of the function or object. The name of the file should be xsymbol.js (use all lower-case for the filename). If you are the author you should use your own copyright info instead of mine. I do not require copyright assignment for code contributions to X.

// xSymbol, Copyright [your date] [your name] ([your URL])
// Part of X, a Cross-Browser Javascript Library, Distributed under the terms of the GNU LGPL

Since XC's compression option removes newlines, you cannot use implicit statement termination. For example in the following the ';' is required because this is an assignment expression...

xObject.prototype.method = function()
{
  // statements...
}; // <- this semicolon is required to support compression

Another example where a semicolon is required in a place where most of us don't usually use a semicolon...

function myObjectPrototype(id)
{
  var img = document.getElementById(id);
  
  img.onmouseover = function()
  {
    this.src = urlOver;
  }; // <- this semicolon is required to support compression
  
  function foo()
  {
  }
}

For every xsymbol.js file there should be an xsymbol.xml file which contains documentation and author copyright statements for xSymbol. All doc files are now in xml. The xml structure I have for now is as follows.

<?xml version="1.0" encoding="ISO-8859-1"?>

<xlib_symbol id=''>

<copyright>Copyright [your date] [your name] ([your URL])</copyright>

<license>Part of X, a Cross-Browser Javascript Library, Distributed under the terms of the GNU LGPL</license>

<groups>
  <grp></grp>
</groups>

<type>Function</type>

<description><![CDATA[]]></description>

<syntax></syntax>

<parameters>
  <par><name></name><note><![CDATA[]]></note></par>
</parameters>

<properties>
  <prop><name></name><note><![CDATA[]]></note></prop>
</properties>

<methods>
  <meth><name></name><note><![CDATA[]]></note></meth>
</methods>

<return><![CDATA[]]></return>

<dependencies>
  <dep></dep>
</dependencies>

<demos>
  <demo><url>http://cross-browser.com/toys/</url><note><![CDATA[Index of all X demos.]]></note></demo>
</demos>

<tests>
  <test><date></date><author>mf</author><url></url><note><![CDATA[]]></note></test>
</tests>

<comments>
  <comment><date></date><author>mf</author><note><![CDATA[]]></note></comment>
</comments>

<revisions>
  <rev><num></num><date></date><author>mf</author><note><![CDATA[]]></note></rev>
</revisions>

</xlib_symbol>

If you would like to write XC in a different language or port it to a different platform please adhere to the general specifications in this file so all XC implementations will be compatible. My XC Win32 C code is available under the terms of the GNU LGPL.

I'll try to come up with a more formal specification. For now I just have a few odd bits of info.

A high-level look at XC's flow of execution:

  Read project file:
    Read options, libpath and appfiles from project file.

  Open log file.

  Read current X version from xversion.js.

  Create symbol table:
    get_valid_syms
      All filenames, minus extensions, in the libpath directory
      which match "x*.js" constitute the set of valid X symbols.
    get_lib_file_deps:
      Update symbol table with dependency info from the X lib file symbols[sym_idx].
      Excludes symbols found in "//" comments.
    
  Get symbols from app files.
    Determine which X lib files get included in the output library
    by searching application files for X symbols.

  Create output lib.
    For every symbol which has 'symbols[sym_idx].inc == true'
    include the corresponding X lib file in the output lib.
    Compression removes all "//" comments but not "/**/" comments.

  Report results.
    Display filenames created and finalize log file.