Source code

CERNY

This is the file that provides the core functionality of the Cerny.js library: interception, type checking, logging, dependency declaration, configuration and dictionaries.

To use the Cerny.js library this file must be included in your page. The configuration file (a copy of cerny.conf.js) must be included beforehand.

Some conventions used:

  • If a current function or member is overwritten in a script, e.g. 'insertBefore', but will be referred to later, the new name of the member is composed of an underscore followed by the old name, e.g. '_insertBefore'.
  • If a simple name is not possible due to keyword restrictions, the name is proceeded by an underscore, e.g. '_delete'.
  • If a function takes arbitrarily many arguments, the documentation for these parameters must be called 'arguments'.
  • If the documentation for a function does not specify a return value, the function returns undefined.

Uses

None

Used by

All, but CERNY.console.*

Functions

ContractViolation

Constructor for a contract violation.

message (string) : the nature of the violation in natural language
return (object) : the violation
Dictionary

Dictionary maker.

A dictionary is a mapping from terms to definitions. Definitions may contain nested terms. The process of evaluating a term is done by lookup .

obj (object) : the obj this dictionary will inherit from
return (object) : a Dictionary object
Logger

Create a logger. For every category there exists exactly one logger.

name (string) : the name of the category
return (object) : the logger for the category identified by name
check

Check whether expr evaluates to true. If not throw a CERNY.ContractViolation . Only to be used in preconditions, postconditions and invariants.

expr (boolean) : the expression to evaluate
message (string) : the message to add to the contract violation
clone

Clone an object. This method is at the moment very limited in its capabilities.

subject (any) : the value to clone
return (any) : a clone of the value
dump

Dump a value for logging purposes. Returns the value of the variable followed by its type in braces. If the variable is a string, the value is enclosed by a single quote.

value (any) : the value to dump
return (string) : a string useful for logging
empty

The empty function.

*/

getResource

Get a resource.

location (string) : the location of the resource
identity

Returns the argument.

arg (any) : argument
return (any) : returns the argument
intercept

Instrument methods of an object for interception. Can be called multiple times with the same effect, only depending on CERNY.Configuration.Interception.active or the passed interceptors.

This function does not work on the window object in IE.

If one overrides methods of an existing object, where interception was already installed with this function and use this function again to intercept the method, the old method will be installed and a information will be logged. This is unfortunate, but is necessary so that interception always has the same effect. Workaround: Use CERNY.method to attach the methods (best to both, but definitely when overriding) instead.

obj (object,function) : the object to intercept methods of
arguments (undefined,string,RegExp,Array) : strings or regexps specifying which functions to intercept. If none are specified all functions are intercepted; or an array of interceptors, if not present configured interceptors are used, if more than one array is given, the last one will be used.
return (Array) : an array of the names of the intercepted functions
isPresent

Check whether an expression is present during runtime.

exp (string) : the expression to check, a string
return (boolean) : false , if the string does not reference anything or the string references undefined
joinFunctions

Join functions into one function. The new function returns the return value of the last function.

arguments (function) : the functions to join
return (function) : the new function
load

Load a script. This function is called in require . It has different implementations in various environments (browser, Rhino [RHI]). The default runtime enviornment is the browser.

location (undefined,string) : the location of the script to load
lookup

Lookup a term in this dictionary.

term (string) : the term to lookup
return (undefined,string) : the value of the term in the dictionary or undefined if the term is unknown
method

Attach a function as a method to an object. This allows to create arbitrarliy many functions around the actual function. It aims for separation of concerns. The interceptors are wrapped around the function starting with the last one. This allows a "natural order", when filling the array regarding dependency. So more basic interceptors (e.g. LogIndenter ) are pushed first.

obj (object) : the obj to attach the function to
name (string) : the name under which the function will be known to the object
func (function) : the function to attach
interceptors (undefined,Array) : the interceptors to use; defaults to CERNY.Configuration.Interception.active
namespace

Create a namespace in CERNY . This function is inspired by the Yahoo! UI Library [YUI].

name (string) : the name of the namespace to create
parentNameSpace (undefined,object) : the parent name space, default is CERNY
object

Prototypal inheritance [DCP]. This alogorithm was developed by Douglas Crockford.

obj (object) : the object to be the prototype of the new object.
return (object) : the new object
post

Specify the conditions that must be met in order to decide whether a function call was a success.

Postcondition is a function which is a sequence of calls to CERNY.check .

this has the same meaning as in the function called.

Postcondition is passed the following parameters:

  1. the return value,
  2. the old version of the object the call is made on, and then
  3. the arguments of the call.

func (function) : the function for which the postcondition is specified
post (function) : the postcondition
pre

Specify the conditions that must be met in order to decide whether a call to func can succeed. These conditions are collected in one function which is called the precondition. The precondition supports the author of a function in communicating the intent of the function to the consumer.

Precondition is a function which is a sequence of calls to CERNY.check .

Precondition is passed the arguments of the call and this has the same meaning as in the function called.

func (function) : the function for which the precondition is specified
pre (function) : the precondition
require

Check for the presence of expressions. Loads an expression by looking it up in the catalog.

script (string) : the script that requires the expression
arguments (undefined,string) : the exressions that are required for further execution
return (Array) : an array of missing expressions with 0 or more items
signature

Specify the signature of a function. The types can be specified either by a string ( "boolean" , "string" , "number" , "object" , "function" , "undefined" , "null" , "any" ) or by a function, against which the actual value will be tested against with instanceof.

In the future it should be possible to specify an object as a type and the prototype chain is inspected for that object. Even more in the future it Cerny schemas could be used.

func (function) : the function to specify the signature for
returnType (string,function,Array) : the type of the return value
arguments (undefined,string,function,Array) : the types of the parameters

History

2007-05-18 : Refactored to use anonymous functions for local namespaces.
2007-05-16 : Added clone, pre, post and the ContractChecker interceptor.
2007-05-03 : CERNY.namespace is returning the created namespace.
2007-04-10 : TypeCheker does not check return value on exceptional calls.
2007-04-03 : Exceptions thrown in intercepted functions are always visible.
2007-04-03 : Loggers got the enabled functions.
2007-04-02 : CERNY.load works for global functions.
2007-03-21 : Logging an info when reapplying interception with CERNY.intercept.
2007-03-21 : Logging name of the logger of the object that is intercepted in CERNY.intercept.
2007-03-16 : Added additional parameter (interceptors) to CERNY.intercept.
2007-03-15 : Added additional parameter (interceptors) to CERNY.method.
2007-03-11 : Added signature, checkType and the TypeChecker interceptor.
2007-03-02 : Added layout and appenders to CERNY.Logger.
2007-03-01 : Moved loggers from CERNY to CERNY.Logger.
2007-02-08 : Fixed bug in intercept, which caused objects to be intercepted.
2006-12-31 : Added the interceptor concept.
2006-12-30 : Added the dump method.
2006-11-10 : Created.

API Documentation for version