README.txt
1JSBase
2=======
3
4What is it?
5------------
6
7This is a collection of bits of JavaScript helper functionality, to solve
8common problems encountered when programming JavaScript code. The library was
9mostly written because I needed certain generic functionality available for
10using in different JS projects, but will be valuable for anyone writing JS
11code. The strenghts of this library are:
12
13 * everything is written in 'modules', which provide their own namespace and
14 are seperately loadable (certain modules do depend on others, but I tried
15 to keep this down to a minimum)
16
17 * care has been taken that it's possible to use this library *at any time,
18 on any platform*, by not depending on any variables being available, or
19 isolating the instances where a variable (for instance 'window') is
20 required
21
22 * the library should not clash with other libraries
23
24 * no overriding or extending of built-in data types or functionality
25
26 * the library is light-weight, and has no impact on the way the JS is
27 written, although it shows some patterns to use concerning 'OO' programming
28 in JS, it does not make the code harder to read or understand for people
29 that don't know the library by using or enforcing complex patterns
30
31 * the functionality in this library can, with the exception of few very
32 browser-specific functions, can be used in any JS environment (e.g. the
33 unit tests are ran using SpiderMonkey, see 'unit tests' below)
34
35 * the library is simple and self-explanatory (of course this is not an excuse
36 for not providing documentation! my excuse for that is lack of time...)
37
38What kind of functionality should I expect?
39--------------------------------------------
40
41This library provides solutions to problems in the core language (e.g.
42functions to deal more easily with arrays and strings) and somewhat lower level
43problems in JS environments (e.g. a cross-platform print() function to write to
44stdout or the document in some way). There are some helpers to solve browser
45incompatibility problems (e.g. a 'getXMLHttpRequest()' function and
46cross-browser event handling) and wrappers for things that are just very badly
47implemented in browsers (e.g. a schedule() function which you can pass a
48normal callable and additional arguments to, a wrapper to solve the problem
49where 'this' in a method body refers to something else than the object a method
50is implemented on and proper exception classes).
51
52More detailed description of the modules
53------------------------------------------
54
55The modules, with a short description:
56
57 * array.js
58
59 a set of functions to help with arrays, basically stuff that the JS core
60 should have provided for
61
62 * exception.js
63
64 this provides the Exception base class and some subclasses, the excepsions
65 raised by the library use these to allow distinguishing between different
66 exceptions more easily, and also they provide a traceback if the platform
67 allows that (mainly Mozilla-related platforms)
68
69 * function.js
70
71 this currently provides a single function, that helps fixing the 'this'
72 problem, where 'this' inside methods points to something else than the
73 object which the methods are defined on (happens e.g. on event handling
74 in browsers)
75
76 * misclib.js
77
78 a set of miscellaneous functionality, such as a schedule() method for
79 scheduling function calls (to replace window.setTimeout), cross-browser
80 event handling (also fixing memory leaks in IE), a repr() function to
81 create string representations of objects (also recursively, if desired),
82 a dir() function to view the attributes of objects, and a print() function
83 that makes messages visible in different ways, depending on the platform
84 you're on (allowing for presenting text to a user both in browsers and
85 command line environments)
86
87 * number.js
88
89 number related functions
90
91 * server.js
92
93 cross-browser server interaction, some higher-level 'AJAX'-related
94 functions
95
96 * string.js
97
98 string related functions
99
100 * testing.js
101
102 functionality to help debugging and testing your applications, it both
103 harbours a couple of helper functions you can call from your code, as
104 functionality to unit-test that code (with py.test integration, see below)
105
106Unit testing
107-------------
108
109The 'testing.js' module contains some functions that can be used to write very
110simple unit tests (see the module for more information for now). Also there's
111a 'conftest.py' and some stuff in the 'testing' dir that allows you to run
112JavaScript unit tests using the Python 'py.test' unit test runner, part of the
113`py lib`_ library.
114
115.. _`py lib`: http://codespeak.net/py
116
117Other files
118------------
119
120The other files in the directory are documentation and license information
121and such, and unit tests for the package and related files.
122
123Note
124----
125
126Note that the library is currently not in a state in which it can be considered
127a complete solution: it merely provides me personally the stuff I needed the
128period I used it... Hopefully at some point it will be complete enough to use
129by others, but right now don't expect it to solve all your general JS problems
130yet.
131
132Questions, bug reports, etc.
133-----------------------------
134
135If you have questions, bug reports, patches or remarks, please send an email
136to johnny@johnnydebris.net.
137
138