GNU
/
easejs
1
0
Fork 0
Code Releases Activity

Corrected all line lengths in doc/ 

Now conforms to tools/linechk's 76-char limitation.
perfodd
Mike Gerwitz 2014-01-17 22:27:47 -05:00
parent 537ca0d694
commit 4b871dabc8
14 changed files with 1681 additions and 1568 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -21,7 +21,7 @@ Current support includes:
* Classical inheritance * Classical inheritance
* Abstract classes and methods * Abstract classes and methods
* Interfaces * Interfaces
* Visibility (public, protected and private members) * Visibility (public, protected, and private members)
* Static and constant members * Static and constant members
While the current focus of the project is object-oriented design, it is likely While the current focus of the project is object-oriented design, it is likely

9
doc/Makefile.am
View File

@ -67,8 +67,8 @@ img/%.png: img/%.dia
$(path_doc_output_plain): $(doc_imgs_txt) $(path_doc_output_plain): $(doc_imgs_txt)
makeinfo --plain -I "." "${path_easejs_texi}" -o "$@" makeinfo --plain -I "." "${path_easejs_texi}" -o "$@"
# doc html (multiple pages); override default target to call automake's first # doc html (multiple pages); override default target to call automake's
# and then post-process output (it has no *-hook target support) # first and then post-process output (it has no *-hook target support)
html: html-local html-am $(path_doc_output_html)/$(path_doc_css_ref) html: html-local html-am $(path_doc_output_html)/$(path_doc_css_ref)
sed -i '$(doc_replace)' easejs.html/*.htm? sed -i '$(doc_replace)' easejs.html/*.htm?
@ -76,7 +76,7 @@ html: html-local html-am $(path_doc_output_html)/$(path_doc_css_ref)
html-single: $(path_doc_output_html1) html-single: $(path_doc_output_html1)
$(path_doc_output_html1): html-local $(path_doc_output_html1): html-local
$(MAKEINFO) --no-split --html --css-include="${path_doc_css}" \ $(MAKEINFO) --no-split --html --css-include="${path_doc_css}" \
-I "." -o "$(path_doc_output_html1)" "${path_easejs_texi}" \ -I . -o "$(path_doc_output_html1)" "${path_easejs_texi}" \
&& sed -i '$(doc_replace)' "$(path_doc_output_html1)" && sed -i '$(doc_replace)' "$(path_doc_output_html1)"
# doc images (in build dir) # doc images (in build dir)
@ -103,7 +103,8 @@ img: $(doc_imgs)
plain: $(path_doc_output_plain) plain: $(path_doc_output_plain)
install-plain: plain install-plain: plain
install -d $(DESTDIR)$(docdir) install -d $(DESTDIR)$(docdir)
install -m644 $(path_doc_output_plain) $(DESTDIR)$(docdir)/easejs.txt install -m644 $(path_doc_output_plain) \
$(DESTDIR)$(docdir)/easejs.txt
clean-local: clean-local:
rm -rf $(path_doc_img)/*.png rm -rf $(path_doc_img)/*.png

8
doc/README
View File

@ -2,8 +2,8 @@ The ease.js website uses 3rd-party scripts, described below.
highlight.js highlight.js
------------ ------------
Used for syntax highlighting on both the website itself and in the manual. Uses Used for syntax highlighting on both the website itself and in the manual.
the modified BSD license. Uses the modified BSD license.
Copyright (c) 2006, Ivan Sagalaev Copyright (c) 2006, Ivan Sagalaev
All rights reserved. All rights reserved.
@ -27,5 +27,5 @@ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

226
doc/about.texi
View File

@ -1,18 +1,18 @@
@c This document is part of the GNU ease.js manual. @c This document is part of the GNU ease.js manual.
@c Copyright (C) 2011, 2013 Mike Gerwitz @c Copyright (C) 2011, 2013, 2014 Mike Gerwitz
@c Permission is granted to copy, distribute and/or modify this document @c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
@c or any later version published by the Free Software Foundation; @c any later version published by the Free Software Foundation; with no
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c Texts. A copy of the license is included in the section entitled ``GNU @c A copy of the license is included in the section entitled ``GNU Free
@c Free Documentation License''. @c Documentation License''.
@node About @node About
@unnumbered About GNU ease.js @unnumbered About GNU ease.js
GNU ease.js is a classical object-oriented framework for Javascript, intended to GNU ease.js is a classical object-oriented framework for Javascript,
eliminate boilerplate code and "ease" the transition into JavaScript from other intended to eliminate boilerplate code and ``ease'' the transition into
object-oriented languages. JavaScript from other object-oriented languages.
Current support includes: Current support includes:
@itemize @bullet @itemize @bullet
@ -20,165 +20,171 @@ Current support includes:
@item Classical inheritance @item Classical inheritance
@item Abstract classes and methods @item Abstract classes and methods
@item Interfaces @item Interfaces
@item Visibility (public, protected and private members) @item Visibility (public, protected, and private members)
@item Static, constant and final members @item Static, constant, and final members
@end itemize @end itemize
While the current focus of the project is Object-Oriented design, it is likely While the current focus of the project is Object-Oriented design, it is
that ease.js will expand to other paradigms in the future. likely that ease.js will expand to other paradigms in the future.
@section History @section History
ease.js was initially developed for use at the author's place of employment in ease.js was initially developed for use at the author's place of employment
order to move the familiar concept of object-oriented development over to in order to move the familiar concept of object-oriented development over to
JavaScript for use in robust web applications. JavaScript lacks basic core JavaScript for use in robust web applications. JavaScript lacks basic core
principals of object-oriented development, the most major of which is proper principals of object-oriented development, the most major of which is proper
encapsulation. encapsulation.
The library would be required to work both server and client-side, supporting The library would be required to work both server and client-side,
all major web browsers as far back as Internet Explorer 6. Since it would be supporting all major web browsers as far back as Internet Explorer 6. Since
used in a production system and would be used to develop a core business it would be used in a production system and would be used to develop a core
application, it must also work flawlessly. This meant heavy unit testing. business application, it must also work flawlessly. This meant heavy unit
testing.
The solution was to develop a library that would first work server-side. The The solution was to develop a library that would first work server-side. The
software of choice for server-side JavaScript was @uref{http://nodejs.org, software of choice for server-side JavaScript was @uref{http://nodejs.org,
Node.js}. Node uses the CommonJS format for modules. This provided an intuitive Node.js}. Node uses the CommonJS format for modules. This provided an
means of modularizing the code without use of an Object Oriented development intuitive means of modularizing the code without use of an Object Oriented
style (the closest other option would be Prototypal). ease.js was first development style (the closest other option would be Prototypal). ease.js
developed to work on Node.js. was first developed to work on Node.js.
Moving the code over to the browser is not a difficult concept, since the entire Moving the code over to the browser is not a difficult concept, since the
library relied only on standard JavaScript. A couple important factors had to be entire library relied only on standard JavaScript. A couple important
taken into account, mainly that CommonJS modules don't simply ``work'' factors had to be taken into account, mainly that CommonJS modules don't
client-side without some type of wrapper, not all browsers support ECMAScript 5 simply ``work'' client-side without some type of wrapper, not all browsers
and the assertion system used for tests is a Node.js module. support ECMAScript 5 and the assertion system used for tests is a Node.js
module.
This involved writing a simple script to concatenate all the modules and This involved writing a simple script to concatenate all the modules and
appropriately wrap them in closures, thereby solving the CommonJS issue. The appropriately wrap them in closures, thereby solving the CommonJS issue. The
required assertions were ported over to the client. The only issue was then required assertions were ported over to the client. The only issue was then
ECMAScript 5 support, which with a little thought, the browser could gracefully ECMAScript 5 support, which with a little thought, the browser could
fall back on by sacrificing certain features but leaving the core functionality gracefully fall back on by sacrificing certain features but leaving the core
relatively unscathed. This provides a proper cross-browser implementation and, functionality relatively unscathed. This provides a proper cross-browser
very importantly, allows the unit tests to be run both server and client side. implementation and, very importantly, allows the unit tests to be run both
One can then be confident that ease.js will operate on both the server and a server and client side. One can then be confident that ease.js will operate
wide range of web browsers without having to maintain separate tests for each. on both the server and a wide range of web browsers without having to
maintain separate tests for each.
Needless to say, the development was successful and the project has been used in Needless to say, the development was successful and the project has been
production long before v0.1.0-pre was even conceived. It was thought at the used in production long before v0.1.0-pre was even conceived. It was thought
beginning of the project that versions would be unnecessary, due to its relative at the beginning of the project that versions would be unnecessary, due to
simplicity and fairly basic feature set. The project has since evolved past its its relative simplicity and fairly basic feature set. The project has since
original specification and hopes to introduce a number of exciting features in evolved past its original specification and hopes to introduce a number of
the future. exciting features in the future.
The project is owned and developed independently by Mike Gerwitz. There is no The project is owned and developed independently by Mike Gerwitz. There is
ownership by his employer. no ownership by his employer.
On 22 December 2013, ease.js officially became a part of GNU with the kind help On 22 December 2013, ease.js officially became a part of GNU with the kind
and supervision of Brandon Invergo. help and supervision of Brandon Invergo.
@section Why ease.js? @section Why ease.js?
There already exists a number of different ways to accomplish inheritance and There already exists a number of different ways to accomplish inheritance
various levels of encapsulation in JavaScript. Why ease.js? Though a number of and various levels of encapsulation in JavaScript. Why ease.js? Though a
frameworks did provide class-like definitions, basic inheritance and other minor number of frameworks did provide class-like definitions, basic inheritance
feature sets, none of them seemed to be an all-encompassing solution to providing and other minor feature sets, none of them seemed to be an all-encompassing
a strong framework for Object-Oriented development in JavaScript. solution to providing a strong framework for Object-Oriented development in
JavaScript.
ease.js was first inspired by John Resig's post on "Simple JavasScript ease.js was first inspired by John Resig's post on ``Simple JavasScript
Inheritance"@footnote{John's blog post is available at Inheritance''@footnote{John's blog post is available at
@uref{http://ejohn.org/blog/simple-javascript-inheritance/}.}. This very basic @uref{http://ejohn.org/blog/simple-javascript-inheritance/}.}. This very
example provided a means to define a ``class'' and extend it. It used a basic example provided a means to define a ``class'' and extend it. It used
PHP-style constructor and was intuitive to use. Though it was an excellent a PHP-style constructor and was intuitive to use. Though it was an excellent
alternative to defining and inheriting classes by working directly with alternative to defining and inheriting classes by working directly with
prototypes, it was far from a solid solution. It lacked abstract methods, prototypes, it was far from a solid solution. It lacked abstract methods,
interfaces, encapsulation (visibility) and many other important features. interfaces, encapsulation (visibility), and many other important features.
Another solution was needed. Another solution was needed.
Using John's example as a base concept, ease.js was developed to address those Using John's example as a base concept, ease.js was developed to address
core issues. Importantly, the project needed to fulfill the following goals: those core issues. Importantly, the project needed to fulfill the following
goals:
@table @strong @table @strong
@item Intuitive Class Definitions @item Intuitive Class Definitions
Users of Object-Oriented languages are used to a certain style of class Users of Object-Oriented languages are used to a certain style of class
declaration that is fairly consistent. Class definitions within the framework declaration that is fairly consistent. Class definitions within the
should be reflective of this. A programmer familiar with Object-Oriented framework should be reflective of this. A programmer familiar with
development should be able to look at the code and clearly see what the class is Object-Oriented development should be able to look at the code and clearly
doing and how it is defined. see what the class is doing and how it is defined.
@item Encapsulation @item Encapsulation
The absolute most important concept that ease.js wished to address was that of The absolute most important concept that ease.js wished to address was that
encapsulation. Encapsulation is one of the most important principals of of encapsulation. Encapsulation is one of the most important principals of
Object-Oriented development. This meant implementing a system that would not Object-Oriented development. This meant implementing a system that would not
only support public and private members (which can be done conventionally in only support public and private members (which can be done conventionally in
JavaScript through ``privileged members''), but must also support JavaScript through ``privileged members''), but must also support
@emph{protected} members. Protected members have long been elusive to JavaScript @emph{protected} members. Protected members have long been elusive to
developers. JavaScript developers.
@item Interfaces / Abstract Classes @item Interfaces / Abstract Classes
Interfaces and Abstract Classes are a core concept and facilitate code reuse and Interfaces and Abstract Classes are a core concept and facilitate code reuse
the development of consistent APIs. They also prove to be very useful for and the development of consistent APIs. They also prove to be very useful
polymorphism. Without them, we must trust that the developer has implemented the for polymorphism. Without them, we must trust that the developer has
correct API. If not, it will likely result in confusing runtime errors. implemented the correct API. If not, it will likely result in confusing
We also cannot ensure an object is passed with the expected API through the use runtime errors. We also cannot ensure an object is passed with the expected
of polymorphism. API through the use of polymorphism.
@item Inheritance @item Inheritance
Basic inheritance can be done through use of prototype chains. However, the Basic inheritance can be done through use of prototype chains. However, the
above concepts introduce additional complications. Firstly, we must be able to above concepts introduce additional complications. Firstly, we must be able
implement interfaces. A simple prototype chain cannot do this (an object cannot to implement interfaces. A simple prototype chain cannot do this (an object
have multiple prototypes). Furthermore, protected members must be inherited by cannot have multiple prototypes). Furthermore, protected members must be
subtypes, while making private members unavailable. In the future, when traits inherited by subtypes, while making private members unavailable. In the
are added to the mix, we run into the same problem as we do with interfaces. future, when traits are added to the mix, we run into the same problem as we
do with interfaces.
@item CommonJS, Server and Client @item CommonJS, Server and Client
The framework would have to be used on both the server and client. Server-side, The framework would have to be used on both the server and client.
@uref{http://nodejs.org, Node.js} was chosen. It used a CommonJS format for Server-side, @uref{http://nodejs.org, Node.js} was chosen. It used a
modules. In order to get ease.js working client side, it would have to be CommonJS format for modules. In order to get ease.js working client side, it
wrapped in such a way that the code could remain unchanged and still operate the would have to be wrapped in such a way that the code could remain unchanged
same. Furthermore, all tests written for the framework would have to run both and still operate the same. Furthermore, all tests written for the framework
server and client-side, ensuring a consistent experience on the server and would have to run both server and client-side, ensuring a consistent
across all supported browsers. Support would have to go as far back as Internet experience on the server and across all supported browsers. Support would
Explorer 6 to support legacy systems. have to go as far back as Internet Explorer 6 to support legacy systems.
@item Performance @item Performance
Everyone knows that Object-Oriented programming incurs a performance hit in Everyone knows that Object-Oriented programming incurs a performance hit in
return for numerous benefits. ease.js is not magic; it too would incur a return for numerous benefits. ease.js is not magic; it too would incur a
performance it. This hit must be low. Throughout the entire time the software is performance it. This hit must be low. Throughout the entire time the
running, the hit must be low enough that it is insignificant (less than 1% of software is running, the hit must be low enough that it is insignificant
the total running time). This applies to any time the framework is used - from (less than 1% of the total running time). This applies to any time the
class creation to method invocation. framework is used - from class creation to method invocation.
@item Quality Design @item Quality Design
A quality design for the system is important for a number of reasons. This A quality design for the system is important for a number of reasons. This
includes consistency with other languages and performance considerations. It includes consistency with other languages and performance considerations. It
must also be easily maintainable and extensible. Object-Oriented programming is must also be easily maintainable and extensible. Object-Oriented programming
all about @emph{restricting} what the developer can do. It is important to do so is all about @emph{restricting} what the developer can do. It is important
properly and ensure it is consistent with other languages. If something is to do so properly and ensure it is consistent with other languages. If
inconsistent early on, and that inconsistency is adopted throughout a piece of something is inconsistent early on, and that inconsistency is adopted
software, fixing the inconsistency could potentially result in breaking the throughout a piece of software, fixing the inconsistency could potentially
software. result in breaking the software.
@item Heavily Tested @item Heavily Tested
The framework would be used to develop critical business applications. It needed The framework would be used to develop critical business applications. It
to perform flawlessly. A bug could potentially introduce flaws into the entire needed to perform flawlessly. A bug could potentially introduce flaws into
system. Furthermore, bugs in the framework could create a debugging nightmare, the entire system. Furthermore, bugs in the framework could create a
with developers wondering if the flaw exists in their own software or the debugging nightmare, with developers wondering if the flaw exists in their
framework. This is a framework that would be very tightly coupled with the own software or the framework. This is a framework that would be very
software built atop of it. In order to ensure production quality, the framework tightly coupled with the software built atop of it. In order to ensure
would have to be heavily tested. As such, a test-driven development cycle is production quality, the framework would have to be heavily tested. As such,
preferred. a test-driven development cycle is preferred.
@item Well Documented @item Well Documented
The framework should be intuitive enough that documentation is generally The framework should be intuitive enough that documentation is generally
unneeded, but in the event the developer does need help in implementing the unneeded, but in the event the developer does need help in implementing the
framework in their own software, the help should be readily available. Wasting framework in their own software, the help should be readily available.
time attempting to figure out the framework is both frustrating and increases Wasting time attempting to figure out the framework is both frustrating and
project cost. increases project cost.
@end table @end table
The above are the main factors taken into consideration when first developing The above are the main factors taken into consideration when first
ease.js. There were no existing frameworks that met all of the above criteria. developing ease.js. There were no existing frameworks that met all of the
Therefore, it was determined that ease.js was a valid project that addressed above criteria. Therefore, it was determined that ease.js was a valid
genuine needs for which there was no current, all-encompassing solution. project that addressed genuine needs for which there was no current,
all-encompassing solution.

1008
doc/classes.texi
View File

File diff suppressed because it is too large Load Diff

2
doc/easejs.css
View File

@ -27,7 +27,7 @@ body, .float-caption
} }
.float pre, var { .float pre, var {
font-family: 'Bitstream Vera Sans Mono', 'DejaVu Sans Mono', Courier, monospace; font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', Courier, monospace;
} }
table { table {

10
doc/easejs.texi
View File

@ -2,11 +2,11 @@
@c This document is part of the GNU ease.js manual. @c This document is part of the GNU ease.js manual.
@c Copyright (C) 2011, 2012, 2013 Mike Gerwitz @c Copyright (C) 2011, 2012, 2013 Mike Gerwitz
@c Permission is granted to copy, distribute and/or modify this document @c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
@c or any later version published by the Free Software Foundation; @c any later version published by the Free Software Foundation; with no
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c Texts. A copy of the license is included in the section entitled ``GNU @c A copy of the license is included in the section entitled ``GNU Free
@c Free Documentation License''. @c Documentation License''.
@c %**start of header @c %**start of header
@setfilename easejs.info @setfilename easejs.info

6
doc/img/visobj-collection-wide.txt
View File

@ -1,4 +1,4 @@
,---------------------------------------, ,-----------------------------------, ,-------------------------------------, ,---------------------------------,
| Per Instance of C\_0 | | Per Instance of C\_1 | | Per Instance of C\_0 | | Per Instance of C\_1 |
| | | | | | | |
| ,---------, ,---------, ,---------, | | ,---------, ,---------, | | ,---------, ,---------, ,---------, | | ,---------, ,---------, |
@ -6,9 +6,9 @@
| `---------` `---------` `---------` | | `---------` `---------` | | `---------` `---------` `---------` | | `---------` `---------` |
| | | | | | | | | | | | | | | | | |
| | ,-------, | | | | ,-------, | | | | ,-------, | | | | ,-------, | |
| `--------| P\_0 |--------` | | `------| P\_1 |------` | | `-------| P\_0 |-------` | | `-----| P\_1 |-----` |
| `-------` | | `-------` | | `-------` | | `-------` |
`-------------------|-------------------` `-----------------|-----------------` `------------------|------------------` `----------------|----------------`
| | | |
,-------, ,-------, ,-------, ,-------,
| C\_0 | | C\_1 | | C\_0 | | C\_1 |

1303
doc/impl-details.texi
View File

File diff suppressed because it is too large Load Diff

146
doc/integration.texi
View File

@ -1,11 +1,11 @@
@c This document is part of the GNU ease.js manual. @c This document is part of the GNU ease.js manual.
@c Copyright (C) 2011, 2013, 2014 Mike Gerwitz @c Copyright (C) 2011, 2013, 2014 Mike Gerwitz
@c Permission is granted to copy, distribute and/or modify this document @c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
@c or any later version published by the Free Software Foundation; @c any later version published by the Free Software Foundation; with no
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c Texts. A copy of the license is included in the section entitled ``GNU @c A copy of the license is included in the section entitled ``GNU Free
@c Free Documentation License''. @c Documentation License''.
@node Integration @node Integration
@chapter Integrating GNU ease.js @chapter Integrating GNU ease.js
@ -27,14 +27,15 @@ may not have to build ease.js at all.
@section Getting GNU ease.js @section Getting GNU ease.js
If you simply want to use ease.js in your project, you may be interested in If you simply want to use ease.js in your project, you may be interested in
simply grabbing an archive (tarball, zip, etc), or installing through your simply grabbing an archive (tarball, zip, etc), or installing through your
favorite package manger. More information on those options will become available favorite package manger. More information on those options will become
as ease.js nears its first release. available as ease.js nears its first release.
If you are interested in building ease.js, you need to get a hold of the source If you are interested in building ease.js, you need to get a hold of the
tree. Either download an archive (tarball, zip, etc), or clone the Git source tree. Either download an archive (tarball, zip, etc), or clone the
repository. We will do the latter in the example below. Feel free to clone from Git repository. We will do the latter in the example below. Feel free to
your favorite source. clone from your favorite source.
@c TODO: Savannah
@example @example
# to clone from GitHub (do one or the other, not both) # to clone from GitHub (do one or the other, not both)
$ git clone git://github.com/mikegerwitz/easejs $ git clone git://github.com/mikegerwitz/easejs
@ -52,11 +53,11 @@ Feel free to skip this section if you have no interest in building ease.js
yourself. The build process is fast, and is unnecessary if using ease.js yourself. The build process is fast, and is unnecessary if using ease.js
server-side. server-side.
First, we should clarify what the term ``build'' means in context of ease.js. First, we should clarify what the term ``build'' means in context of
JavaScript is compiled on the fly. That is, we don't actually need to compile it ease.js. JavaScript is compiled on the fly. That is, we don't actually need
manually through a build process. So when we are talking about ``building'' to compile it manually through a build process. So when we are talking about
ease.js, we are not talking about compiling the source code. Rather, we are ``building'' ease.js, we are not talking about compiling the source code.
referring to any of the following: Rather, we are referring to any of the following:
@itemize @itemize
@item @item
@ -66,49 +67,53 @@ Prepare the script for client-side deployment [and testing]
Generate the documentation (manual and API) Generate the documentation (manual and API)
@end itemize @end itemize
In fact, if you're using ease.js server-side with software such as Node.js, you In fact, if you're using ease.js server-side with software such as Node.js,
do not need to build anything at all. You can simply begin using it. you do not need to build anything at all. You can simply begin using it.
The aforementioned are built using @command{make}. The process that is run will The aforementioned are built using @command{make}. The process that is run
vary depending on your system. The command will read @file{Makefile} in the root will vary depending on your system. The command will read @file{Makefile} in
directory and execute the associated command. The following are the targets the root directory and execute the associated command. The following are the
available to you: targets available to you:
@table @command @table @command
@item mkbuild @item mkbuild
Creates the @file{build/} directory, where all output will be stored. This is run Creates the @file{build/} directory, where all output will be stored. This
automatically by any of the targets. is run automatically by any of the targets.
@item combine @item combine
Runs the @command{combine} @ref{Tools Directory, tool} to produce two separate Runs the @command{combine} @ref{Tools Directory, tool} to produce two
files: @file{ease.js}, which can be used to use ease.js within the web browser, separate files: @file{ease.js}, which can be used to use ease.js within the
and @file{ease-full.js}, which permits both using ease.js and running the unit web browser, and @file{ease-full.js}, which permits both using ease.js and
tests within the browser. The output is stored in the @file{build/} directory. running the unit tests within the browser. The output is stored in the
@file{build/} directory.
The unit tests can be run by opening the @file{build/browser-test.html} file in your The unit tests can be run by opening the @file{build/browser-test.html} file
web browser. in your web browser.
@item min @item min
Runs @command{combine} and minifies the resulting combined files. These files Runs @command{combine} and minifies the resulting combined files. These
are output in the @file{build/} directory and are useful for distribution. It is files are output in the @file{build/} directory and are useful for
recommended that you use the minified files in production. distribution. It is recommended that you use the minified files in
production.
@item test @item test
Run unit tests. This will first perform the @command{combine} process and will Run unit tests. This will first perform the @command{combine} process and
also run the tests for the combined script, ensuring that it was properly will also run the tests for the combined script, ensuring that it was
combined. properly combined.
Unit tests will be covered later in the chapter. Unit tests will be covered later in the chapter.
@item doc @item doc
Generates documentation. Currently, only the manual is build. API documentation Generates documentation. Currently, only the manual is build. API
will be added in the near future. The resulting documentation will be stored in documentation will be added in the near future. The resulting documentation
@file{build/doc/}. For your convenience, the manual is output in the following will be stored in @file{build/doc/}. For your convenience, the manual is
forms: PDF, HTML (single page), HTML (multiple pages) and plain text. output in the following forms: PDF, HTML (single page), HTML (multiple
pages) and plain text.
In order to build the documentation, you must have Texinfo installed. You likely In order to build the documentation, you must have Texinfo installed. You
also need LaTeX installed. If you are on a Debian-based system, for example, you likely also need LaTeX installed. If you are on a Debian-based system, for
will likely be able to run the following command to get started: example, you will likely be able to run the following command to get
started:
@example @example
$ sudo apt-get install texlive texinfo $ sudo apt-get install texlive texinfo
@ -116,8 +121,8 @@ will likely be able to run the following command to get started:
@item install @item install
Installs info documentation. Must first build @command{doc-info}. After Installs info documentation. Must first build @command{doc-info}. After
installation, the manual may be viewed from the command line with: @samp{info installation, the manual may be viewed from the command line with:
easejs}. @samp{info easejs}.
@item uninstall @item uninstall
Removes everything from the system that was installed with @command{make Removes everything from the system that was installed with @command{make
@ -130,15 +135,15 @@ Runs all targets, except for clean, install and uninstall.
Cleans up after the build process by removing the @file{build/} directory. Cleans up after the build process by removing the @file{build/} directory.
@end table @end table
If you do not want to build ease.js yourself, you are welcome to download the If you do not want to build ease.js yourself, you are welcome to download
pre-built files. the pre-built files.
@node Including @node Including
@section Including GNU ease.js In Your Projects @section Including GNU ease.js In Your Projects
Using ease.js in your projects should be quick and painless. We'll worry about Using ease.js in your projects should be quick and painless. We'll worry
the details of how to actually @emph{use} ease.js in a bit. For now, let's just about the details of how to actually @emph{use} ease.js in a bit. For now,
worry about how to include it in your project. let's just worry about how to include it in your project.
@menu @menu
* Server-Side Include:: Including ease.js server-side * Server-Side Include:: Including ease.js server-side
@ -147,12 +152,13 @@ worry about how to include it in your project.
@node Server-Side Include @node Server-Side Include
@subsection Server-Side Include @subsection Server-Side Include
ease.js should work with any CommonJS-compliant system. The examples below have ease.js should work with any CommonJS-compliant system. The examples below
been tested with Node.js. Support is not guaranteed with any other software. have been tested with Node.js. Support is not guaranteed with any other
software.
Let's assume that you have installed ease.js somewhere that is accessible to Let's assume that you have installed ease.js somewhere that is accessible to
@code{require.paths}. If you used a tool such as @command{npm}, this should have @code{require.paths}. If you used a tool such as @command{npm}, this should
been done for you. have been done for you.
@float Figure, f:inc-serverside @float Figure, f:inc-serverside
@verbatim @verbatim
@ -163,22 +169,24 @@ var easejs = require( 'easejs' );
@end float @end float
It's important to understand what exactly the above command is doing. We are It's important to understand what exactly the above command is doing. We are
including the @file{easejs/} directory (adjust your path as needed). Inside that including the @file{easejs/} directory (adjust your path as needed). Inside
directory is the @file{index.js} file, which is loaded. The exports of that that directory is the @file{index.js} file, which is loaded. The exports of
module are returned and assigned to the @var{easejs} variable. We will discuss that module are returned and assigned to the @var{easejs} variable. We will
what to actually do with those exports later on. discuss what to actually do with those exports later on.
That's it. You should now have ease.js available to your project. That's it. You should now have ease.js available to your project.
@node Client-Side Include @node Client-Side Include
@subsection Client-Side Include (Web Browser) @subsection Client-Side Include (Web Browser)
ease.js can also be included in the web browser. Not only does this give you a ease.js can also be included in the web browser. Not only does this give you
powerful Object-Oriented framework client-side, but it also facilitates code a powerful Object-Oriented framework client-side, but it also facilitates
reuse by permitting you to reuse your server-side code that depends on ease.js. code reuse by permitting you to reuse your server-side code that depends on
ease.js.
In order for ease.js to operate within the client, you must either download In order for ease.js to operate within the client, you must either download
@file{ease.js} or @ref{Building, build it yourself}. Let's assume that you have @file{ease.js} or @ref{Building, build it yourself}. Let's assume that you
placed @file{ease.js} within the @file{scripts/} directory of your web root. have placed @file{ease.js} within the @file{scripts/} directory of your web
root.
@float Figure, f:inc-clientside @float Figure, f:inc-clientside
@verbatim @verbatim
@ -191,10 +199,10 @@ placed @file{ease.js} within the @file{scripts/} directory of your web root.
@caption{Including ease.js client-side} @caption{Including ease.js client-side}
@end float @end float
Likely, you only want the first one. The unit tests can more easily be run by Likely, you only want the first one. The unit tests can more easily be run
loading @file{build/browser-test.html} in your web browser (@pxref{Building}). by loading @file{build/browser-test.html} in your web browser
(@pxref{Building}).
The script will define a global @var{easejs} variable, which can be used exactly
like the server-side @code{require()} (@pxref{Server-Side Include}). Keep that
in mind when going through the examples in this manual.
The script will define a global @var{easejs} variable, which can be used
exactly like the server-side @code{require()} (@pxref{Server-Side Include}).
Keep that in mind when going through the examples in this manual.

9
doc/interactive.js
View File

@ -39,12 +39,15 @@ jqueryCheck( function()
$( document ).ready( function() $( document ).ready( function()
{ {
// syntax highlighting for code samples // syntax highlighting for code samples
$( '.verbatim, .samp, .code, .example' ).each( function( i, element ) $( '.verbatim, .samp, .code, .example' ).each(
function( i, element )
{ {
hljs.highlightBlock( element, ' ' ); hljs.highlightBlock( element, ' ' );
} ); }
);
// quick-n-dirty sub and super script impl (it is by no means perfect) // quick-n-dirty sub and super script impl (it is by no means
// perfect)
$( 'var:contains("\\")' ).each( function() $( 'var:contains("\\")' ).each( function()
{ {
var $this = $( this ); var $this = $( this );

10
doc/license.texi
View File

@ -9,8 +9,8 @@
@c hence no sectioning command or @node. @c hence no sectioning command or @node.
@display @display
Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software
@uref{http://fsf.org/} Foundation, Inc. @uref{http://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed. of this license document, but changing it is not allowed.
@ -122,9 +122,9 @@ A section ``Entitled XYZ'' means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as ``Acknowledgements'', specific section name mentioned below, such as ``Acknowledgements'',
``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the
of such a section when you modify the Document means that it remains a Title'' of such a section when you modify the Document means that it remains
section ``Entitled XYZ'' according to this definition. a section ``Entitled XYZ'' according to this definition.
The Document may include Warranty Disclaimers next to the notice which The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty states that this License applies to the Document. These Warranty

313
doc/mkeywords.texi
View File

@ -1,21 +1,22 @@
@c This document is part of the GNU ease.js manual. @c This document is part of the GNU ease.js manual.
@c Copyright (C) 2011, 2013, 2014 Mike Gerwitz @c Copyright (C) 2011, 2013, 2014 Mike Gerwitz
@c Permission is granted to copy, distribute and/or modify this document @c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
@c or any later version published by the Free Software Foundation; @c any later version published by the Free Software Foundation; with no
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c Texts. A copy of the license is included in the section entitled ``GNU @c A copy of the license is included in the section entitled ``GNU Free
@c Free Documentation License''. @c Documentation License''.
@node Member Keywords @node Member Keywords
@chapter Member Keywords @chapter Member Keywords
Keywords are defined within the context of the @dfn{definition object} Keywords are defined within the context of the @dfn{definition object}
(@pxref{dfnobj,,Definition Object}). In the sections that follow, let @var{C} (@pxref{dfnobj,,Definition Object}). In the sections that follow, let
denote a class that contains the definition object @var{dfn}, which in turn @var{C} denote a class that contains the definition object @var{dfn}, which
contains @var{keywords} within the declaration of method @var{name}, whose in turn contains @var{keywords} within the declaration of method @var{name},
definition is denoted by @var{value}. whose definition is denoted by @var{value}.
The table below summarizes the available keywords accepted by @var{keywords}. The table below summarizes the available keywords accepted by
@var{keywords}.
@float Table, t:keywords @float Table, t:keywords
@multitable @columnfractions .10 .90 @multitable @columnfractions .10 .90
@ -24,29 +25,31 @@ The table below summarizes the available keywords accepted by @var{keywords}.
@tab Places member @var{name} into the public API for @var{C} (@pxref{Access @tab Places member @var{name} into the public API for @var{C} (@pxref{Access
Modifiers}). Modifiers}).
@item @code{protected} @item @code{protected}
@tab Places member @var{name} into the protected API for @var{C} (@pxref{Access @tab Places member @var{name} into the protected API for @var{C}
Modifiers}). (@pxref{Access Modifiers}).
@item @code{private} @item @code{private}
@tab Places member @var{name} into the private API for @var{C} (@pxref{Access @tab Places member @var{name} into the private API for @var{C}
Modifiers}). (@pxref{Access Modifiers}).
@item @code{static} @item @code{static}
@tab Binds member @var{name} to class @var{C} rather than instance of @var{C}. @tab Binds member @var{name} to class @var{C} rather than instance of
Member data shared with each instance of type @var{C}. @xref{Static Members}. @var{C}. Member data shared with each instance of type @var{C}.
@xref{Static Members}.
@item @code{abstract} @item @code{abstract}
@tab Declares member @var{name} and defers definition to subtype. @var{value} @tab Declares member @var{name} and defers definition to subtype.
is interpreted as an argument list and must be of type @code{array}. May only be @var{value} is interpreted as an argument list and must be of type
used with methods. Member @var{name} must be part of @var{dfn} of either an @code{array}. May only be used with methods. Member @var{name} must be part
of @var{dfn} of either an
@code{Interface} or @code{AbstractClass}. @xref{Abstract Members}. @code{Interface} or @code{AbstractClass}. @xref{Abstract Members}.
@item @code{const} @item @code{const}
@tab Defines an immutable property @var{name}. May not be used with methods or @tab Defines an immutable property @var{name}. May not be used with methods
getters/setters. @xref{Constants}. or getters/setters. @xref{Constants}.
@item @code{virtual} @item @code{virtual}
@tab Declares that method @var{name} may be overridden by subtypes. Methods @tab Declares that method @var{name} may be overridden by subtypes. Methods
without this keyword may not be overridden. May only be used with methods. without this keyword may not be overridden. May only be used with methods.
@xref{Inheritance}. @xref{Inheritance}.
@item @code{override} @item @code{override}
@tab Overrides method @var{name} of supertype of @var{C} with @var{value}. May @tab Overrides method @var{name} of supertype of @var{C} with @var{value}.
only override virtual methods. May only be used with methods. May only override virtual methods. May only be used with methods.
@xref{Inheritance}. @xref{Inheritance}.
@item @code{proxy} @item @code{proxy}
@tab Proxies calls to method @var{name} to the object stored in property @tab Proxies calls to method @var{name} to the object stored in property
@ -55,9 +58,9 @@ only override virtual methods. May only be used with methods.
@caption{Supported keywords} @caption{Supported keywords}
@end float @end float
Not all keywords are supported by each member and some keywords conflict with Not all keywords are supported by each member and some keywords conflict
each other. More information can be found in the appropriate sections as with each other. More information can be found in the appropriate sections
mentioned above in @ref{t:keywords}. as mentioned above in @ref{t:keywords}.
@menu @menu
* Access Modifiers:: Control the context in which members may be accessed * Access Modifiers:: Control the context in which members may be accessed
@ -67,8 +70,9 @@ mentioned above in @ref{t:keywords}.
@section Access Modifiers @section Access Modifiers
@dfn{Access modifiers}, when provided in @var{keywords}, alter the interface @dfn{Access modifiers}, when provided in @var{keywords}, alter the interface
into which the definition of member @var{name} is placed. There are three into which the definition of member @var{name} is placed. There are three
interfaces, or levels of @dfn{visibility}, that dictate the context from which a interfaces, or levels of @dfn{visibility}, that dictate the context from
member may be accessed, listed here from the most permissive to the least: which a member may be accessed, listed here from the most permissive to the
least:
@table @dfn @table @dfn
@item public @item public
@ -91,17 +95,17 @@ Not accessible outside of @var{C} or any instance of @var{C}. @emph{Not}
@headitem Keyword @tab Description @headitem Keyword @tab Description
@item @code{public} @item @code{public}
@tab @tab
Places member @var{name} in public interface (accessible outside of @var{C} or Places member @var{name} in public interface (accessible outside of @var{C}
instance of @var{C}; accessible by subtypes). Implied if no other access or instance of @var{C}; accessible by subtypes). Implied if no other access
modifier is provided. modifier is provided.
@item @code{protected} @item @code{protected}
@tab @tab
Places member @var{name} in protected interface (accessible only within @var{C} Places member @var{name} in protected interface (accessible only within
or instance of @var{C}; accessible by subtypes). @var{C} or instance of @var{C}; accessible by subtypes).
@item @code{private} @item @code{private}
@tab @tab
Places member @var{name} in private interface (accessible only within @var{C} or Places member @var{name} in private interface (accessible only within
instance of @var{C}; not accessible by subtypes). @var{C} or instance of @var{C}; not accessible by subtypes).
@end multitable @end multitable
@caption{Access modifiers} @caption{Access modifiers}
@end float @end float
@ -110,10 +114,11 @@ Access modifiers have the following properties:
@itemize @itemize
@item @item
Only one access modifier may appear in @var{keywords} for any given @var{name}. Only one access modifier may appear in @var{keywords} for any given
@var{name}.
@item @item
If no access modifier is provided in @var{keywords} for any member @var{name}, If no access modifier is provided in @var{keywords} for any member
member @var{name} is implicitly @code{public}. @var{name}, member @var{name} is implicitly @code{public}.
@end itemize @end itemize
@menu @menu
@ -125,87 +130,92 @@ member @var{name} is implicitly @code{public}.
@subsection Discussion @subsection Discussion
One of the major hurdles ease.js aimed to address (indeed, one of the core One of the major hurdles ease.js aimed to address (indeed, one of the core
reasons for its creation) was that of encapsulation. JavaScript's prototypal reasons for its creation) was that of encapsulation. JavaScript's prototypal
model provides limited means of encapsulating data. Since functions limit scope, model provides limited means of encapsulating data. Since functions limit
they may be used to mimic private members; these are often referred to as scope, they may be used to mimic private members; these are often referred
@dfn{privileged members}. However, declaring classes in this manner tends be to as @dfn{privileged members}. However, declaring classes in this manner
messy, which has the consequence of increasing maintenance costs and reducing tends be messy, which has the consequence of increasing maintenance costs
the benefit of the implementation. ease.js aims to provide an elegant and reducing the benefit of the implementation. ease.js aims to provide an
implementation that is both a pleasure to work with and able to support elegant implementation that is both a pleasure to work with and able to
protected members. support protected members.
By default, all members are public. This means that the members can be accessed By default, all members are public. This means that the members can be
and modified from within an instance as well as from outside of it. Subtypes accessed and modified from within an instance as well as from outside of it.
(classes that inherit from it; @pxref{Inheritance}) will inherit public members. Subtypes (classes that inherit from it; @pxref{Inheritance}) will inherit
Public methods expose an API by which users may use your class. Public public members. Public methods expose an API by which users may use your
properties, however, should be less common in practice for a very important class. Public properties, however, should be less common in practice for a
reason, which is explored throughout the remainder of this section. very important reason, which is explored throughout the remainder of this
section.
@anchor{Encapsulation} @anchor{Encapsulation}
@subsubsection Encapsulation @subsubsection Encapsulation
@dfn{Encapsulation} is the act of hiding information within a class or instance. @dfn{Encapsulation} is the act of hiding information within a class or
Classes should be thought of black boxes; we want them to do their job, but we instance. Classes should be thought of black boxes; we want them to do
should not concern ourselves with @emph{how} they do their job. Encapsulation their job, but we should not concern ourselves with @emph{how} they do their
takes a great deal of complexity out of an implementation and allows the job. Encapsulation takes a great deal of complexity out of an implementation
developer to focus on accomplishing the task by focusing on the implementing in and allows the developer to focus on accomplishing the task by focusing on
terms of the problem domain. the implementing in terms of the problem domain.
For example - consider a class named @var{Dog} which has a method @code{walk()}. For example - consider a class named @var{Dog} which has a method
To walk a dog, we simply call @code{Dog().walk()}. The @code{walk()} method @code{walk()}. To walk a dog, we simply call @code{Dog().walk()}. The
could be doing anything. In the case of a real dog, perhaps it will send a @code{walk()} method could be doing anything. In the case of a real dog,
message to the dog's brain, perform the necessary processing to determine how perhaps it will send a message to the dog's brain, perform the necessary
that command should be handled and communicate the result to the limbs. The processing to determine how that command should be handled and communicate
limbs will communicate back the information they receive from their nerves, the result to the limbs. The limbs will communicate back the information
which will be processed by the brain to determine when they hit the ground, they receive from their nerves, which will be processed by the brain to
thereby triggering additional actions and the further movement of the other determine when they hit the ground, thereby triggering additional actions
legs. This could be a terribly complicated implementation if we had to worry and the further movement of the other legs. This could be a terribly
about how all of this was done. complicated implementation if we had to worry about how all of this was
done.
In addition to the actual walking algorithm, we have the state of each of the In addition to the actual walking algorithm, we have the state of each of
legs - their current position, their velocity, the state of each of the muscles, the legs - their current position, their velocity, the state of each of the
etc. This state pertains only to the operations performed by the dog. Exposing muscles, etc. This state pertains only to the operations performed by the
this state to everyone wouldn't be terribly useful. Indeed, if this information dog. Exposing this state to everyone wouldn't be terribly useful. Indeed, if
was exposed, it would complicate the implementation. What if someone decided to this information was exposed, it would complicate the implementation. What
alter this state in the middle of a walking operation? Or what if the developer if someone decided to alter this state in the middle of a walking operation?
implementing @var{Dog} relied on this state in order to determine when the leg Or what if the developer implementing @var{Dog} relied on this state in
reached a certain position, but later versions of @var{Dog} decided to alter the order to determine when the leg reached a certain position, but later
algorithm, thereby changing those properties? versions of @var{Dog} decided to alter the algorithm, thereby changing those
properties?
By preventing these details from being exposed, we present the developer with a By preventing these details from being exposed, we present the developer
very simple interface@footnote{One would argue that this isn't necessary a good with a very simple interface@footnote{One would argue that this isn't
thing. What if additional flexibility was needed? @var{Dog}, in the sense of necessary a good thing. What if additional flexibility was needed?
this example, can be thought of as a Facade (GoF). One could provide more @var{Dog}, in the sense of this example, can be thought of as a Facade
flexibility by composing @var{Dog} of, say, @var{Leg} instances, a @var{Brain}, (GoF). One could provide more flexibility by composing @var{Dog} of, say,
etc. However, encapsulation still remains a factor. Each of those components @var{Leg} instances, a @var{Brain}, etc. However, encapsulation still
would encapsulate their own data.}. Rather than the developer having to be remains a factor. Each of those components would encapsulate their own
concerned with moving each of the dog's legs, all they have to do is understand data.}. Rather than the developer having to be concerned with moving each of
that the dog is being walked. the dog's legs, all they have to do is understand that the dog is being
walked.
When developing your classes, the following best practices should be kept in When developing your classes, the following best practices should be kept in
mind: mind:
@itemize @itemize
@item @item
When attempting to determine the best access modifier (@pxref{Access Modifiers}) When attempting to determine the best access modifier (@pxref{Access
to use for a member, start with the least level of visibility (@code{private}) Modifiers}) to use for a member, start with the least level of visibility
and work your way up if necessary. (@code{private}) and work your way up if necessary.
@item @item
If your member is not private, be sure that you can justify your choice. If your member is not private, be sure that you can justify your choice.
@itemize @itemize
@item @item
If protected - why do subclasses need access to that data? Is there a better If protected - why do subclasses need access to that data? Is there a
way to accomplish the same task without breaking encapsulation? better way to accomplish the same task without breaking encapsulation?
@item @item
If public - is this member necessary to use the class externally? In the case If public - is this member necessary to use the class externally? In the
of a method - does it make sense to be part of a public API? If a property - case of a method - does it make sense to be part of a public API? If a
why is that data not encapsulated? Should you consider an accessor method? property - why is that data not encapsulated? Should you consider an
accessor method?
@end itemize @end itemize
@end itemize @end itemize
@node Access Modifiers Example @node Access Modifiers Example
@subsection Example @subsection Example
Let's consider our @var{Dog} class in more detail. We will not go so far as to Let's consider our @var{Dog} class in more detail. We will not go so far as
implement an entire nervous system in our example. Instead, let's think of our to implement an entire nervous system in our example. Instead, let's think
@var{Dog} similar to a wind-up toy: of our @var{Dog} similar to a wind-up toy:
@float Figure, f:encapsulation @float Figure, f:encapsulation
@verbatim @verbatim
@ -257,23 +267,23 @@ Class( 'Dog',
@end float @end float
As you can see above, the act of making the dog move forward is a bit more As you can see above, the act of making the dog move forward is a bit more
complicated than the developer may have originally expected. The dog has four complicated than the developer may have originally expected. The dog has
separate legs that need to be moved individually. The dog must also first stand four separate legs that need to be moved individually. The dog must also
before it can be walked, but it can only stand if it's sitting. Detailed tasks first stand before it can be walked, but it can only stand if it's sitting.
such as these occur all the time in classes, but they are hidden from the Detailed tasks such as these occur all the time in classes, but they are
developer using the public API. The developer should not be concerned with all hidden from the developer using the public API. The developer should not be
of the legs. Worrying about such details brings the developer outside of the concerned with all of the legs. Worrying about such details brings the
problem domain and into a @emph{new} problem domain - how to get the dog to developer outside of the problem domain and into a @emph{new} problem domain
walk. - how to get the dog to walk.
@subsection Private Members @subsection Private Members
Let's first explore private members. The majority of the members in the Let's first explore private members. The majority of the members in the
@var{Dog} class (@pxref{f:encapsulation,}) are private. This is the lowest level @var{Dog} class (@pxref{f:encapsulation,}) are private. This is the lowest
of visibility (and consequently the @emph{highest} level of encapsulation). By level of visibility (and consequently the @emph{highest} level of
convention, we prefix private members with an underscore. Private members are encapsulation). By convention, we prefix private members with an underscore.
available @emph{only to the class that defined it} and are not available outside Private members are available @emph{only to the class that defined it} and
the class. are not available outside the class.
@float Figure, f:encapsulation-call-priv @float Figure, f:encapsulation-call-priv
@verbatim @verbatim
@ -286,16 +296,18 @@ the class.
@end float @end float
You will notice that the dog's legs are declared private as well You will notice that the dog's legs are declared private as well
(@pxref{f:encapsulation,}). This is to ensure we look at the dog as a whole; we (@pxref{f:encapsulation,}). This is to ensure we look at the dog as a whole;
don't care about what the dog is made up of. Legs, fur, tail, teeth, tongue, etc we don't care about what the dog is made up of. Legs, fur, tail, teeth,
tongue, etc
- they are all irrelevant to our purpose. We just want to walk the dog. - they are all irrelevant to our purpose. We just want to walk the dog.
Encapsulating those details also ensures that they will not be tampered with, Encapsulating those details also ensures that they will not be tampered
which will keep the dog in a consistent, predictable state. with, which will keep the dog in a consistent, predictable state.
Private members cannot be inherited. Let's say we want to make a class called Private members cannot be inherited. Let's say we want to make a class
@var{TwoLeggedDog} to represent a dog that was trained to walk only on two feet. called @var{TwoLeggedDog} to represent a dog that was trained to walk only
We could approach this in a couple different ways. The first way would be to on two feet. We could approach this in a couple different ways. The first
prevent the front legs from moving. What happens when we explore that approach: way would be to prevent the front legs from moving. What happens when we
explore that approach:
@float Figure, f:encapsulation-inherit-priv @float Figure, f:encapsulation-inherit-priv
@ -318,22 +330,22 @@ prevent the front legs from moving. What happens when we explore that approach:
@end float @end float
If you were to attempt to walk a @var{TwoLeggedDog}, you would find that If you were to attempt to walk a @var{TwoLeggedDog}, you would find that
@emph{the dog's front legs still move}! This is because, as mentioned before, @emph{the dog's front legs still move}! This is because, as mentioned
private methods are not inherited. Rather than overriding the parent's before, private methods are not inherited. Rather than overriding the
@var{_moveFrontLeg} method, you are instead @emph{defining a new method}, with parent's @var{_moveFrontLeg} method, you are instead @emph{defining a new
the name @var{_moveFrontLeg}. The old method will still be called. Instead, we method}, with the name @var{_moveFrontLeg}. The old method will still be
would have to override the public @var{walk} method to prevent our dog from called. Instead, we would have to override the public @var{walk} method to
moving his front feet. prevent our dog from moving his front feet.
@subsection Protected Members @subsection Protected Members
Protected members are often misunderstood. Many developers will declare all Protected members are often misunderstood. Many developers will declare all
of their members as either public or protected under the misconception that they of their members as either public or protected under the misconception that
may as well allow subclasses to override whatever functionality they want. This they may as well allow subclasses to override whatever functionality they
makes the class more flexible. want. This makes the class more flexible.
While it is true that the class becomes more flexible to work with for subtypes, While it is true that the class becomes more flexible to work with for
this is a dangerous practice. In fact, doing so @emph{violates encapsulation}. subtypes, this is a dangerous practice. In fact, doing so @emph{violates
Let's reconsider the levels of visibility in this manner: encapsulation}. Let's reconsider the levels of visibility in this manner:
@table @strong @table @strong
@item public @item public
@ -347,19 +359,20 @@ Provides an API for @emph{the class itself}.
@end table @end table
Just as we want to hide data from the public API, we want to do the same for Just as we want to hide data from the public API, we want to do the same for
subtypes. If we simply expose all members to any subclass that comes by, that subtypes. If we simply expose all members to any subclass that comes by,
acts as a peephole in our black box. We don't want people spying into our that acts as a peephole in our black box. We don't want people spying into
internals. Subtypes shouldn't care about the dog's implementation either. our internals. Subtypes shouldn't care about the dog's implementation
either.
Private members should be used whenever possible, unless you are looking to Private members should be used whenever possible, unless you are looking to
provide subtypes with the ability to access or override methods. In that case, provide subtypes with the ability to access or override methods. In that
we can move up to try protected members. Remember not to make a member public case, we can move up to try protected members. Remember not to make a
unless you wish it to be accessible to the entire world. member public unless you wish it to be accessible to the entire world.
@var{Dog} (@pxref{f:encapsulation,}) defined a single method as protected - @var{Dog} (@pxref{f:encapsulation,}) defined a single method as protected -
@code{stand()}. Because the method is protected, it can be inherited by @code{stand()}. Because the method is protected, it can be inherited by
subtypes. Since it is inherited, it may also be overridden. Let's define another subtypes. Since it is inherited, it may also be overridden. Let's define
subtype, @var{LazyDog}, which refuses to stand. another subtype, @var{LazyDog}, which refuses to stand.
@float Figure, f:encapsulation-inherit-prot @float Figure, f:encapsulation-inherit-prot
@verbatim @verbatim
@ -381,19 +394,19 @@ subtype, @var{LazyDog}, which refuses to stand.
@caption{Protected members are inherited by subtypes} @caption{Protected members are inherited by subtypes}
@end float @end float
There are a couple important things to be noted from the above example. Firstly, There are a couple important things to be noted from the above example.
we are able to override the @code{walk()} method, because it was inherited. Firstly, we are able to override the @code{walk()} method, because it was
Secondly, since @code{rollOver()} was also inherited from the parent, we are inherited. Secondly, since @code{rollOver()} was also inherited from the
able to call that method, resulting in an upside-down dog that refuses to stand parent, we are able to call that method, resulting in an upside-down dog
up, just moving his feet. that refuses to stand up, just moving his feet.
Another important detail to notice is that @code{Dog.rollOver()} accesses a Another important detail to notice is that @code{Dog.rollOver()} accesses a
private property of @var{Dog} -- @var{_body}. Our subclass does not have access private property of @var{Dog} -- @var{_body}. Our subclass does not have
to that variable. Since it is private, it was not inherited. However, since the access to that variable. Since it is private, it was not inherited. However,
@code{rollOver()} method is called within the context of the @var{Dog} class, since the @code{rollOver()} method is called within the context of the
the @emph{method} has access to the private member, allowing our dog to @var{Dog} class, the @emph{method} has access to the private member,
successfully roll over. If, on the other hand, we were to override allowing our dog to successfully roll over. If, on the other hand, we were
@code{rollOver()}, our code would @emph{not} have access to that private object. to override @code{rollOver()}, our code would @emph{not} have access to that
Calling @samp{this.__super()} from within the overridden method would, however, private object. Calling @samp{this.__super()} from within the overridden
call the parent method, which would again have access to its parent's private method would, however, call the parent method, which would again have access
members. to its parent's private members.

159
doc/source-tree.texi
View File

@ -1,11 +1,11 @@
@c This document is part of the GNU ease.js manual. @c This document is part of the GNU ease.js manual.
@c Copyright (C) 2011, 2013, 2014 Mike Gerwitz @c Copyright (C) 2011, 2013, 2014 Mike Gerwitz
@c Permission is granted to copy, distribute and/or modify this document @c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
@c or any later version published by the Free Software Foundation; @c any later version published by the Free Software Foundation; with no
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c Texts. A copy of the license is included in the section entitled ``GNU @c A copy of the license is included in the section entitled ``GNU Free
@c Free Documentation License''. @c Documentation License''.
@node Source Tree @node Source Tree
@appendix Source Tree @appendix Source Tree
@ -19,7 +19,8 @@ follow along.
doc/ lib/ test/ tools/ doc/ lib/ test/ tools/
@end example @end example
The project contains four main directories in addition to the root directory: The project contains four main directories in addition to the root
directory:
@table @file @table @file
@item ./ @item ./
@ -27,8 +28,8 @@ The root directory contains basic project files, such as @file{README},
@file{Makefile} and @file{index.js}. @file{Makefile} and @file{index.js}.
@item doc/ @item doc/
Contains documentation source files (you are currently reading part of it - the Contains documentation source files (you are currently reading part of it -
manual). the manual).
@item lib/ @item lib/
Contains the actual source code for the various modules. Contains the actual source code for the various modules.
@ -65,20 +66,21 @@ Contains the project license.
Invoked by the @command{make} command. Used for building ease.js. Invoked by the @command{make} command. Used for building ease.js.
@item package.json @item package.json
Used by @command{npm}, a package manager for Node.js, to automate installation. Used by @command{npm}, a package manager for Node.js, to automate
installation.
@item README.hacking @item README.hacking
Useful information for those looking to modify/contribute to the project. Useful information for those looking to modify/contribute to the project.
@item README.md @item README.md
Serves as a quick reference for the project, in markdown@footnote{See Serves as a quick reference for the project, in markdown@footnote{See
@uref{http://en.wikipedia.org/wiki/Markdown}.} format. This format was chosen @uref{http://en.wikipedia.org/wiki/Markdown}.} format. This format was
because it is displayed nicely on GitHub. chosen because it is displayed nicely on GitHub.
@item README.todo @item README.todo
Incomplete tasks. Future direction of the project. If you're looking to help Incomplete tasks. Future direction of the project. If you're looking to help
out, take a look at this file to see what needs to be done. (See also the bug out, take a look at this file to see what needs to be done. (See also the
tracker at @uref{http://easejs.org/bugs}). bug tracker at @uref{http://easejs.org/bugs}).
@end table @end table
These files will be discussed in further detail when they are actually used. These files will be discussed in further detail when they are actually used.
@ -86,51 +88,53 @@ These files will be discussed in further detail when they are actually used.
@node Doc Directory @node Doc Directory
@section Doc Directory @section Doc Directory
The @file{doc/} directory contains the source files for the manual. The source The @file{doc/} directory contains the source files for the manual. The
files are in Texinfo@footnote{See @uref{http://www.gnu.org/software/texinfo/}.} source files are in Texinfo@footnote{See
format. Instructions for compiling the documentation are included later in this @uref{http://www.gnu.org/software/texinfo/}.} format. Instructions for
chapter. compiling the documentation are included later in this chapter.
API documentation is @emph{not} included in this directory. It is generated from API documentation is @emph{not} included in this directory. It is generated
the source code. from the source code.
@node Lib Directory @node Lib Directory
@section Lib Directory @section Lib Directory
The @file{lib/} directory contains the source code for the project. Each source The @file{lib/} directory contains the source code for the project. Each
file represents a single CommonJS module, often containing a prototype, and is source file represents a single CommonJS module, often containing a
written in JavaScript. Additional information about each of the modules can be prototype, and is written in JavaScript. Additional information about each
found in the header of each file. of the modules can be found in the header of each file.
Unless you are developing for ease.js, you needn't concern yourself with these Unless you are developing for ease.js, you needn't concern yourself with
files. @file{index.js}, in the root directory, contains mappings to these files these files. @file{index.js}, in the root directory, contains mappings to
where necessary, exposing the useful portions of the API for general use. You these files where necessary, exposing the useful portions of the API for
can use ease.js without even recognizing that the @file{lib/} directory even general use. You can use ease.js without even recognizing that the
exists. @file{lib/} directory even exists.
@node Test Directory @node Test Directory
@section Test Directory @section Test Directory
The @file{test/} directory contains all the unit tests for the project. ease.js The @file{test/} directory contains all the unit tests for the project.
follows a test-driven development model; every single aspect of the framework is ease.js follows a test-driven development model; every single aspect of the
tested to ensure that features work as intended both server-side and across all framework is tested to ensure that features work as intended both
supported web browsers. The tests also serve as regression tests, ensuring that server-side and across all supported web browsers. The tests also serve as
bugs are not introduced for anything that has been covered. These tests should regression tests, ensuring that bugs are not introduced for anything that
also give outside developers confidence; if a developer makes a modification to has been covered. These tests should also give outside developers
ease.js and does not cause any failing tests, it's likely that their change confidence; if a developer makes a modification to ease.js and does not
didn't have negative consequences on the integrity of the framework. cause any failing tests, it's likely that their change didn't have negative
consequences on the integrity of the framework.
ease.js is currently in a transition period in regards to the style of the test ease.js is currently in a transition period in regards to the style of the
cases. Tests written in the original format are prefixed with @samp{test-}, test cases. Tests written in the original format are prefixed with
followed by the name of the module, followed optionally by the specific part of @samp{test-}, followed by the name of the module, followed optionally by the
the module that is being tested. Newer test cases are prefixed with the specific part of the module that is being tested. Newer test cases are
prototype name of the unit being tested, followed by @samp{Test.js}. If there prefixed with the prototype name of the unit being tested, followed by
are a number of test cases for a given prototype, any number of tests will be @samp{Test.js}. If there are a number of test cases for a given prototype,
included (with the same suffix) in a directory with the same name as the any number of tests will be included (with the same suffix) in a directory
prototype. The tests are written in JavaScript and use Node.js's @file{assert} with the same name as the prototype. The tests are written in JavaScript and
module. Newer tests use a test case system that was developed to suit the needs use Node.js's @file{assert} module. Newer tests use a test case system that
of the project (still using the @file{assert} module). They may be run was developed to suit the needs of the project (still using the
individually or all at once during the build process. @file{assert} module). They may be run individually or all at once during
the build process.
Developers interested in contributing to ease.js can aid in this transition Developers interested in contributing to ease.js can aid in this transition
process by helping to move all @file{test-*} tests over to the new test case process by helping to move all @file{test-*} tests over to the new test case
@ -142,26 +146,27 @@ performance tests used for benchmarking.
@node Tools Directory @node Tools Directory
@section Tools Directory @section Tools Directory
The @file{tools/} directory contains scripts and data necessary for the build The @file{tools/} directory contains scripts and data necessary for the
process. The tools are shell scripts that may be run independently of the build build process. The tools are shell scripts that may be run independently of
process if you find them to be useful. The remaining files are data to accompany the build process if you find them to be useful. The remaining files are
those tools. data to accompany those tools.
@table @file @table @file
@item combine @item combine
Concatenates all the modules and wraps them for client-side deployment. If Concatenates all the modules and wraps them for client-side deployment. If
requested, the tests are also wrapped and concatenated so that they may be run requested, the tests are also wrapped and concatenated so that they may be
in the web browser. The contents are stripped of trailing commas using the run in the web browser. The contents are stripped of trailing commas using
@command{rmtrail} tool. The resulting file is @emph{not} minified; the user can the @command{rmtrail} tool. The resulting file is @emph{not} minified; the
use whatever process he/she wishes to do so. In the future, minification will be user can use whatever process he/she wishes to do so. In the future,
part of the build script. minification will be part of the build script.
@item rmtrail @item rmtrail
Removes trailing commas from object and array definitions. Reads from standard Removes trailing commas from object and array definitions. Reads from
in. @emph{This script is not intelligent.} It was designed to work with ease.js. standard in. @emph{This script is not intelligent.} It was designed to work
It does not, for example, check to ensure that it is not removing commas from with ease.js. It does not, for example, check to ensure that it is not
within strings. This would not be a difficult addition, but is currently removing commas from within strings. This would not be a difficult addition,
unnecessary. Use caution when using this tool outside of ease.js. but is currently unnecessary. Use caution when using this tool outside of
ease.js.
@item minify.js @item minify.js
Responsible for receiving input from stdin and writing minified output to Responsible for receiving input from stdin and writing minified output to
@ -169,33 +174,31 @@ stdout. This script uses UglifyJS to minify source files for distribution,
improving download times. improving download times.
@item browser-test.html @item browser-test.html
Skeleton page to be used after the build process. Runs ease.js unit tests in the Skeleton page to be used after the build process. Runs ease.js unit tests in
web browser and reports any failures. This is very important to ensure that the web browser and reports any failures. This is very important to ensure
ease.js operates consistently between all supported browsers. The tests that are that ease.js operates consistently between all supported browsers. The tests
run are the same exact tests that are run server-side. that are run are the same exact tests that are run server-side.
@item combine-test.tpl @item combine-test.tpl
Contains a client-side implementation of any modules required for testing. This Contains a client-side implementation of any modules required for testing.
file contains mainly assertions. It is included by the @command{combine} script This file contains mainly assertions. It is included by the
when tests are requested. @command{combine} script when tests are requested.
@item combine.tpl @item combine.tpl
Contains the basic functionality required to get CommonJS modules working Contains the basic functionality required to get CommonJS modules working
client-side. This is a very basic implementation, only doing what is necessary client-side. This is a very basic implementation, only doing what is
for ease.js to work properly. It is not meant to be a solution for all of your necessary for ease.js to work properly. It is not meant to be a solution for
client-side CommonJS problems. all of your client-side CommonJS problems.
@item license.tpl @item license.tpl
Contains the license that is to appear atop every combined file, including Contains the license that is to appear atop every combined file, including
minified. The original text must remain in tact. If you make changes to the minified. The original text must remain in tact. If you make changes to the
source code, you are welcome to add additional text. See the @file{LICENSE} file source code, you are welcome to add additional text. See the @file{LICENSE}
in the root directory for more information on what is permitted. file in the root directory for more information on what is permitted.
@end table @end table
While the tools may be useful outside of ease.js in some regard, please note While the tools may be useful outside of ease.js in some regard, please note
that they have been tailored especially for ease.js. They do not contain that they have been tailored especially for ease.js. They do not contain
unnecessary features that ease.js does not need to make use of. Therefore, you unnecessary features that ease.js does not need to make use of. Therefore,
may need to adapt them to your own project and individual needs should you you may need to adapt them to your own project and individual needs should
decide to use them in your own projects. you decide to use them in your own projects.