document

deyunanhai edited this page Aug 29, 2012 · 2 revisions
Clone this wiki locally

Table of Contents

Download

git clone git://github.com/deyunanhai/JSAnalysis.git

Install

make && make release

JavaScript Run-time Engine

example

hello word

./js_analysis -e 'println("Hello World!")'
results:
Hello World!

execute JavaScript file test.js:
println("Hello World!");
./js_analysis 'test.js'
results:
Hello World\!

usage

js_analysis [-w] [-s] [-l library floder] [-e script] scriptfile
-w: print warning messages.
-s: execute script from standard input.
-l: add directory to the list of directories to be searched for use
-e: execute script from string.

functions

print void print(str, ... )

    Prints Strings.
    Parameters:
        str: The Strings to be printed.

println void println(str, ... )
    Prints Strings and then terminate the line.
    Parameters:
        str: The Strings to be printed.

exec_file Object exec_file(file)
    Execute JavaScript file and return the result.
    Parameters:
        file: the file to be executed, execute from stdin if this parameter is undefined.
    Returns:
        Javascript file result.

use void use(module)
    Import JavaScript library file.
    Parameters:
        module: the JavaScript library file.

scan_token Array scan_token(file)
    Scan JavaScript file, and return the tokens array.
    Parameters:
        file: the JavaScript file to be scanned, scan from stdin if this parameter is undefined.
    Returns:
        Tokens array.

parse NodeTree parse(file)
    Parse JavaScript file, and return the nodes tree.
    Parameters:
        file: the JavaScript file to be parsed, parse from stdin if this parameter is undefined.
    Returns:
        Nodes tree.

parse NodeTree parse(file)
    Parse JavaScript file, and return the nodes tree.
    Parameters:
        file: the JavaScript file to be parsed, parse from stdin if this parameter is undefined.
    Returns:
        Nodes tree.

properties

__base_dir

    The folder path where the js_analysis file is in.

__global
    Global object.

__files
    The Javascript files to be running.
    (Will be undefined When the Javascript is read from stdin)

public objects

File

    Static Properties
        input a File object that represents the standard input (stdin).
        currentDir a File object that represents the standard output (stdout).
        currentDir a File object that represents the standard error (stderr).
        currentDir a File object referring to the current directory; this property may be set.
        separator the system name separator (slash on UNIX).
    Instance Properties
        length the length of the file in bytes, or the number of entries in the directory. Note: calculating the length of the directory is very expensive.
        parent the directory containing the file.
        path the canonical path to the file.
        name the name of the file.
        isDirectory true if the file is a directory.
        isFile true if the file is a file.
        exists true if the file exists.
        canRead true if the file can be read.
        canWrite true if the file can be written.
        canAppend true if the file is in append mode.
        canReplace true if the file is in replace mode.
        isOpen true if the file is open.
        type a string specifying the type of data or encoding contained in the file. Currently "ascii" (ASCII), "binary" (UTF-8) or "unicode" (UCS-2). (XXX Note -- ASCII might imply ASCIIZ)
        mode a string describing the mode used to open the file.
        creationTime a Date object representing the time when the file was created.
        lastModified a Date object representing the time when the file was last modified.
        size the length of the file in bytes; undefined(?) for directories and pipelines.
        hasRandomAccess true if random access is supported for this file. Binary (UTF-8) files and pipelines (including File.intput) do not support random access.
        hasAutoFlush force a flush on each line break? (readonly)
        position The file position. Writing to the property moves the file pointer.
        isNative True if the file is backed by a native stdio FILE stream. (i.e. file.input, file.output, file.error or a pipeline)
    Methods
        open Opens the file, specifying file mode and type.
        close Closes the file.
        remove Removes the file, provided it is not open.
        copyTo Creates a verbatim copy of the file at a new location.
        renameTo Removes the file.
        flush Flushes the operating system's write buffers for the file and blocks until any pending data has been committed to disk.
        seek Moves the file position pointer forward or backwards.
        read Read a fixed number of bytes from the file.
        readln Read line from the file.
        readAll Read the entire file in, returning an array of lines.
        write Write bytes to the file.
        writeln Write bytes to the file, followed by a line separator, flushing the buffer if file.hasAutoflush.
        writeAll Writes an array of lines to the file, obeying the same semantics as writeln.
        list Get a list of files, potentially matching a regular expression filter, from the file. Only has meaning when the file is a directory.
        mkdir Create a directory. Directory will be created in the same directory as the file, unless the file is a directory, in which case, the directory will be created in that directory. XXX
        toString Returns the canonical path to the file.
        toURL Returns a file:// URL describing the file relative to the local file system. URL is URI-encoded.

others

http://www.ecma-international.org/publications/standards/Ecma-262.htm

Common library

console

functions

log void log(str, ... )

    Log messages.
    Parameters:
        str: The strings to be logged.

info void info(str, ... )
    Log information messages.
    Parameters:
        str: The strings to be logged.

error void error(str, ... )
    Log error messages.
    Parameters:
        str: The strings to be logged.

warn void warn(str, ... )
    Log warnning messages.
    Parameters:
        str: The strings to be logged.

warn void debug(str, ... )
    Log debug messages.
    Parameters:
        str: The strings to be logged.

ex:
    use("console");
    console.log("log");
    console.info("info");
    console.error("error");
    console.warn("warn");
    console.debug("debug");

print_stack_trace void print_stack_trace(err)
    Print error stack trace.
    Parameters:
        err: The Error Object

ex:
    use("console");
    try {
        throw new Error("some error");
    } catch(err) {
        console.print_stack_trace(err);
    }

results:

    test.js:3: some error
    Error("some error")@:0
    @test.js:3

common

functions

print_tree void print_tree(NodeTree)

    Print the node tree
    Parameters:
        NodeTree: object return from parse method.

ex:
    echo "var i=0;" | ./js_analysis -e "use('common');print_tree(parse())"

results:

    LC from L0 ,C0, to L1 ,C8, arity: LIST, op: nop, name: , value:
      VAR from L1 ,C0, to L1 ,C5, arity: LIST, op: defvar, name: , value:
        NAME from L1 ,C4, to L1 ,C5, arity: NAME, op: setname, name: i, value:
          NUMBER from L1 ,C6, to L1 ,C7, arity: NULLARY, op: nop, name: , value: 0

visit_tree void visit_tree(NodeTree, Callback)
    loop the node tree, and execute callback.
    Parameters:
        NodeTree : object return from parse method.
        Callback : callback object that can contains methods below.
            got_var      : var x=1;
            got_call     : func(x,y);
            got_if       : if(condtions) {...} else {...}
            got_function : function(x,y)  {...}
            got_while    : while(conditions) {...}
            got_do       : do {...} while(conditions)
            got_for      : for(;;){...}
            got_switch   : switch(x) {case ... default ...}
            got_try      : try {...} catch(e) {...}
            got_hook     : condition?x:y

ex:
    echo "while(true) {var i=0;}" | ./js_analysis -e "
        use('common');
        visit_tree(parse(), {
        got_var: function(node) {
            print_tree(node);
        }
        });
    "

reults:

    VAR from L1 ,C13, to L1 ,C18, arity: LIST, op: defvar, name: , value:
      NAME from L1 ,C17, to L1 ,C18, arity: NAME, op: setname, name: i, value:
        NUMBER from L1 ,C19, to L1 ,C20, arity: NULLARY, op: nop, name: , value: 0

iterate_tree void iterate_tree(NodeTree, CallbackFunc)
    Iterate the node tree, and execute callback function.
    Parameters:
        NodeTree : object return from parse method.
        CallbackFunc: callback function.

ex:
    echo "var i=0;" | ./js_analysis -e "
      use('common');
      iterate_tree(parse(), function(node) {
        if(node.type == NodeType.NUMBER) print_tree(node);
      });
    "

results:

    NUMBER from L1 ,C6, to L1 ,C7, arity: NULLARY, op: nop, name: , value: 0

print_token void print_token(Token)
    Print Token.
    Parameters:
        Token: object return from scan method.

ex:
    echo "var i=0;" | ./js_analysis -e "use('common');print_token(scan_token()[1])"

results:

    NAME from L1 ,C4, to L1 ,C5, op: name, value: i

print_tokens void print_tokens(Array)
    Print Token.
    Parameters:
        Array<Token>: object return from scan method.

ex:
    echo "var i=0;" | ./js_analysis -e "use('common');print_tokens(scan_token())"

results:

    VAR from L1 ,C0, to L1 ,C3, op: defvar, value:
    NAME from L1 ,C4, to L1 ,C5, op: name, value: i
    ASSIGN from L1 ,C5, to L1 ,C6, op: nop, value:
    NUMBER from L1 ,C6, to L1 ,C7, op: nop, value: 0
    SEMI from L1 ,C7, to L1 ,C8, op: defvar, value:

iterate_token void iterate_token(Array, CallbackFunc)
    Iterate the token array, and execute callback function.
    Parameters:
        Array<Token>: object return from scan method.
        CallbackFunc: callback function.

ex:
    echo "var i=0;" | ./js_analysis -e "
      use('common');
      iterate_token(scan_token(), function(token) {
        print_token(token);
      });
    "

results:

    VAR from L1 ,C0, to L1 ,C3, op: defvar, value:
    NAME from L1 ,C4, to L1 ,C5, op: name, value: i
    ASSIGN from L1 ,C5, to L1 ,C6, op: nop, value:
    NUMBER from L1 ,C6, to L1 ,C7, op: nop, value: 0
    SEMI from L1 ,C7, to L1 ,C8, op: defvar, value: