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

1016
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 {
font-family: 'Bitstream Vera Sans Mono', 'DejaVu Sans Mono', Courier, monospace;
font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', Courier, monospace;
}
table {

10
doc/easejs.texi
View File

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

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

@ -1,18 +1,18 @@
,---------------------------------------, ,-----------------------------------,
| Per Instance of C\_0 | | Per Instance of C\_1 |
| | | |
| ,---------, ,---------, ,---------, | | ,---------, ,---------, |
| | V\_0\^0 | | V\_0\^1 | | V\_0\^2 | | | | V\_1\^0 | | V\_1\^1 | |
| `---------` `---------` `---------` | | `---------` `---------` |
| | | | | | | | |
| | ,-------, | | | | ,-------, | |
| `--------| P\_0 |--------` | | `------| P\_1 |------` |
| `-------` | | `-------` |
`-------------------|-------------------` `-----------------|-----------------`
| |
,-------, ,-------,
| C\_0 | | C\_1 |
`-------` `-------`
,-------------------------------------, ,---------------------------------,
| Per Instance of C\_0 | | Per Instance of C\_1 |
| | | |
| ,---------, ,---------, ,---------, | | ,---------, ,---------, |
| | V\_0\^0 | | V\_0\^1 | | V\_0\^2 | | | | V\_1\^0 | | V\_1\^1 | |
| `---------` `---------` `---------` | | `---------` `---------` |
| | | | | | | | |
| | ,-------, | | | | ,-------, | |
| `-------| P\_0 |-------` | | `-----| P\_1 |-----` |
| `-------` | | `-------` |
`------------------|------------------` `----------------|----------------`
| |
,-------, ,-------,
| C\_0 | | C\_1 |
`-------` `-------`
[\_ denotes subscript and \^ denotes superscript]

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

13
doc/interactive.js
View File

@ -39,12 +39,15 @@ jqueryCheck( function()
$( document ).ready( function()
{
// syntax highlighting for code samples
$( '.verbatim, .samp, .code, .example' ).each( function( i, element )
{
hljs.highlightBlock( element, ' ' );
} );
$( '.verbatim, .samp, .code, .example' ).each(
function( i, 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 $this = $( this );

10
doc/license.texi
View File

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

315
doc/mkeywords.texi
View File

@ -1,21 +1,22 @@
@c This document is part of the GNU ease.js manual.
@c Copyright (C) 2011, 2013, 2014 Mike Gerwitz
@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 or any later version published by the Free Software Foundation;
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
@c Texts. A copy of the license is included in the section entitled ``GNU
@c Free Documentation License''.
@c under the terms of the GNU Free Documentation License, Version 1.3 or
@c any later version published by the Free Software Foundation; with no
@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c A copy of the license is included in the section entitled ``GNU Free
@c Documentation License''.
@node Member Keywords
@chapter Member Keywords
Keywords are defined within the context of the @dfn{definition object}
(@pxref{dfnobj,,Definition Object}). In the sections that follow, let @var{C}
denote a class that contains the definition object @var{dfn}, which in turn
contains @var{keywords} within the declaration of method @var{name}, whose
definition is denoted by @var{value}.
(@pxref{dfnobj,,Definition Object}). In the sections that follow, let
@var{C} denote a class that contains the definition object @var{dfn}, which
in turn contains @var{keywords} within the declaration of method @var{name},
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
@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
Modifiers}).
@item @code{protected}
@tab Places member @var{name} into the protected API for @var{C} (@pxref{Access
Modifiers}).
@tab Places member @var{name} into the protected API for @var{C}
(@pxref{Access Modifiers}).
@item @code{private}
@tab Places member @var{name} into the private API for @var{C} (@pxref{Access
Modifiers}).
@tab Places member @var{name} into the private API for @var{C}
(@pxref{Access Modifiers}).
@item @code{static}
@tab Binds member @var{name} to class @var{C} rather than instance of @var{C}.
Member data shared with each instance of type @var{C}. @xref{Static Members}.
@tab Binds member @var{name} to class @var{C} rather than instance of
@var{C}. Member data shared with each instance of type @var{C}.
@xref{Static Members}.
@item @code{abstract}
@tab Declares member @var{name} and defers definition to subtype. @var{value}
is interpreted as an argument list and must be of type @code{array}. May only be
used with methods. Member @var{name} must be part of @var{dfn} of either an
@tab Declares member @var{name} and defers definition to subtype.
@var{value} is interpreted as an argument list and must be of type
@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}.
@item @code{const}
@tab Defines an immutable property @var{name}. May not be used with methods or
getters/setters. @xref{Constants}.
@tab Defines an immutable property @var{name}. May not be used with methods
or getters/setters. @xref{Constants}.
@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.
@xref{Inheritance}.
@item @code{override}
@tab Overrides method @var{name} of supertype of @var{C} with @var{value}. May
only override virtual methods. May only be used with methods.
@tab Overrides method @var{name} of supertype of @var{C} with @var{value}.
May only override virtual methods. May only be used with methods.
@xref{Inheritance}.
@item @code{proxy}
@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}
@end float
Not all keywords are supported by each member and some keywords conflict with
each other. More information can be found in the appropriate sections as
mentioned above in @ref{t:keywords}.
Not all keywords are supported by each member and some keywords conflict
with each other. More information can be found in the appropriate sections
as mentioned above in @ref{t:keywords}.
@menu
* Access Modifiers:: Control the context in which members may be accessed
@ -67,8 +70,9 @@ mentioned above in @ref{t:keywords}.
@section Access Modifiers
@dfn{Access modifiers}, when provided in @var{keywords}, alter the interface
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
member may be accessed, listed here from the most permissive to the least:
interfaces, or levels of @dfn{visibility}, that dictate the context from
which a member may be accessed, listed here from the most permissive to the
least:
@table @dfn
@item public
@ -91,17 +95,17 @@ Not accessible outside of @var{C} or any instance of @var{C}. @emph{Not}
@headitem Keyword @tab Description
@item @code{public}
@tab
Places member @var{name} in public interface (accessible outside of @var{C} or
instance of @var{C}; accessible by subtypes). Implied if no other access
Places member @var{name} in public interface (accessible outside of @var{C}
or instance of @var{C}; accessible by subtypes). Implied if no other access
modifier is provided.
@item @code{protected}
@tab
Places member @var{name} in protected interface (accessible only within @var{C}
or instance of @var{C}; accessible by subtypes).
Places member @var{name} in protected interface (accessible only within
@var{C} or instance of @var{C}; accessible by subtypes).
@item @code{private}
@tab
Places member @var{name} in private interface (accessible only within @var{C} or
instance of @var{C}; not accessible by subtypes).
Places member @var{name} in private interface (accessible only within
@var{C} or instance of @var{C}; not accessible by subtypes).
@end multitable
@caption{Access modifiers}
@end float
@ -110,10 +114,11 @@ Access modifiers have the following properties:
@itemize
@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
If no access modifier is provided in @var{keywords} for any member @var{name},
member @var{name} is implicitly @code{public}.
If no access modifier is provided in @var{keywords} for any member
@var{name}, member @var{name} is implicitly @code{public}.
@end itemize
@menu
@ -125,87 +130,92 @@ member @var{name} is implicitly @code{public}.
@subsection Discussion
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
model provides limited means of encapsulating data. Since functions limit scope,
they may be used to mimic private members; these are often referred to as
@dfn{privileged members}. However, declaring classes in this manner tends be
messy, which has the consequence of increasing maintenance costs and reducing
the benefit of the implementation. ease.js aims to provide an elegant
implementation that is both a pleasure to work with and able to support
protected members.
model provides limited means of encapsulating data. Since functions limit
scope, they may be used to mimic private members; these are often referred
to as @dfn{privileged members}. However, declaring classes in this manner
tends be messy, which has the consequence of increasing maintenance costs
and reducing the benefit of the implementation. ease.js aims to provide an
elegant implementation that is both a pleasure to work with and able to
support protected members.
By default, all members are public. This means that the members can be accessed
and modified from within an instance as well as from outside of it. Subtypes
(classes that inherit from it; @pxref{Inheritance}) will inherit public members.
Public methods expose an API by which users may use your class. Public
properties, however, should be less common in practice for a very important
reason, which is explored throughout the remainder of this section.
By default, all members are public. This means that the members can be
accessed and modified from within an instance as well as from outside of it.
Subtypes (classes that inherit from it; @pxref{Inheritance}) will inherit
public members. Public methods expose an API by which users may use your
class. Public properties, however, should be less common in practice for a
very important reason, which is explored throughout the remainder of this
section.
@anchor{Encapsulation}
@subsubsection Encapsulation
@dfn{Encapsulation} is the act of hiding information within a class or instance.
Classes should be thought of black boxes; we want them to do their job, but we
should not concern ourselves with @emph{how} they do their job. Encapsulation
takes a great deal of complexity out of an implementation and allows the
developer to focus on accomplishing the task by focusing on the implementing in
terms of the problem domain.
@dfn{Encapsulation} is the act of hiding information within a class or
instance. Classes should be thought of black boxes; we want them to do
their job, but we should not concern ourselves with @emph{how} they do their
job. Encapsulation takes a great deal of complexity out of an implementation
and allows the developer to focus on accomplishing the task by focusing on
the implementing in terms of the problem domain.
For example - consider a class named @var{Dog} which has a method @code{walk()}.
To walk a dog, we simply call @code{Dog().walk()}. The @code{walk()} method
could be doing anything. In the case of a real dog, perhaps it will send a
message to the dog's brain, perform the necessary processing to determine how
that command should be handled and communicate the result to the limbs. The
limbs will communicate back the information they receive from their nerves,
which will be processed by the brain to determine when they hit the ground,
thereby triggering additional actions and the further movement of the other
legs. This could be a terribly complicated implementation if we had to worry
about how all of this was done.
For example - consider a class named @var{Dog} which has a method
@code{walk()}. To walk a dog, we simply call @code{Dog().walk()}. The
@code{walk()} method could be doing anything. In the case of a real dog,
perhaps it will send a message to the dog's brain, perform the necessary
processing to determine how that command should be handled and communicate
the result to the limbs. The limbs will communicate back the information
they receive from their nerves, which will be processed by the brain to
determine when they hit the ground, thereby triggering additional actions
and the further movement of the other legs. This could be a terribly
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
legs - their current position, their velocity, the state of each of the muscles,
etc. This state pertains only to the operations performed by the dog. Exposing
this state to everyone wouldn't be terribly useful. Indeed, if this information
was exposed, it would complicate the implementation. What if someone decided to
alter this state in the middle of a walking operation? Or what if the developer
implementing @var{Dog} relied on this state in order to determine when the leg
reached a certain position, but later versions of @var{Dog} decided to alter the
algorithm, thereby changing those properties?
In addition to the actual walking algorithm, we have the state of each of
the legs - their current position, their velocity, the state of each of the
muscles, etc. This state pertains only to the operations performed by the
dog. Exposing this state to everyone wouldn't be terribly useful. Indeed, if
this information was exposed, it would complicate the implementation. What
if someone decided to alter this state in the middle of a walking operation?
Or what if the developer implementing @var{Dog} relied on this state in
order to determine when the leg reached a certain position, but later
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
very simple interface@footnote{One would argue that this isn't necessary a good
thing. What if additional flexibility was needed? @var{Dog}, in the sense of
this example, can be thought of as a Facade (GoF). One could provide more
flexibility by composing @var{Dog} of, say, @var{Leg} instances, a @var{Brain},
etc. However, encapsulation still remains a factor. Each of those components
would encapsulate their own data.}. Rather than the developer having to be
concerned with moving each of the dog's legs, all they have to do is understand
that the dog is being walked.
By preventing these details from being exposed, we present the developer
with a very simple interface@footnote{One would argue that this isn't
necessary a good thing. What if additional flexibility was needed?
@var{Dog}, in the sense of this example, can be thought of as a Facade
(GoF). One could provide more flexibility by composing @var{Dog} of, say,
@var{Leg} instances, a @var{Brain}, etc. However, encapsulation still
remains a factor. Each of those components would encapsulate their own
data.}. Rather than the developer having to be concerned with moving each of
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
mind:
@itemize
@item
When attempting to determine the best access modifier (@pxref{Access Modifiers})
to use for a member, start with the least level of visibility (@code{private})
and work your way up if necessary.
When attempting to determine the best access modifier (@pxref{Access
Modifiers}) to use for a member, start with the least level of visibility
(@code{private}) and work your way up if necessary.
@item
If your member is not private, be sure that you can justify your choice.
@itemize
@item
If protected - why do subclasses need access to that data? Is there a better
way to accomplish the same task without breaking encapsulation?
If protected - why do subclasses need access to that data? Is there a
better way to accomplish the same task without breaking encapsulation?
@item
If public - is this member necessary to use the class externally? In the case
of a method - does it make sense to be part of a public API? If a property -
why is that data not encapsulated? Should you consider an accessor method?
If public - is this member necessary to use the class externally? In the
case of a method - does it make sense to be part of a public API? If a
property - why is that data not encapsulated? Should you consider an
accessor method?
@end itemize
@end itemize
@node Access Modifiers Example
@subsection Example
Let's consider our @var{Dog} class in more detail. We will not go so far as to
implement an entire nervous system in our example. Instead, let's think of our
@var{Dog} similar to a wind-up toy:
Let's consider our @var{Dog} class in more detail. We will not go so far as
to implement an entire nervous system in our example. Instead, let's think
of our @var{Dog} similar to a wind-up toy:
@float Figure, f:encapsulation
@verbatim
@ -257,23 +267,23 @@ Class( 'Dog',
@end float
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
separate legs that need to be moved individually. The dog must also first stand
before it can be walked, but it can only stand if it's sitting. Detailed tasks
such as these occur all the time in classes, but they are hidden from the
developer using the public API. The developer should not be concerned with all
of the legs. Worrying about such details brings the developer outside of the
problem domain and into a @emph{new} problem domain - how to get the dog to
walk.
complicated than the developer may have originally expected. The dog has
four separate legs that need to be moved individually. The dog must also
first stand before it can be walked, but it can only stand if it's sitting.
Detailed tasks such as these occur all the time in classes, but they are
hidden from the developer using the public API. The developer should not be
concerned with all of the legs. Worrying about such details brings the
developer outside of the problem domain and into a @emph{new} problem domain
- how to get the dog to walk.
@subsection Private Members
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
of visibility (and consequently the @emph{highest} level of encapsulation). By
convention, we prefix private members with an underscore. Private members are
available @emph{only to the class that defined it} and are not available outside
the class.
@var{Dog} class (@pxref{f:encapsulation,}) are private. This is the lowest
level of visibility (and consequently the @emph{highest} level of
encapsulation). By convention, we prefix private members with an underscore.
Private members are available @emph{only to the class that defined it} and
are not available outside the class.
@float Figure, f:encapsulation-call-priv
@verbatim
@ -286,16 +296,18 @@ the class.
@end float
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
don't care about what the dog is made up of. Legs, fur, tail, teeth, tongue, etc
(@pxref{f:encapsulation,}). This is to ensure we look at the dog as a whole;
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.
Encapsulating those details also ensures that they will not be tampered with,
which will keep the dog in a consistent, predictable state.
Encapsulating those details also ensures that they will not be tampered
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
@var{TwoLeggedDog} to represent a dog that was trained to walk only on two feet.
We could approach this in a couple different ways. The first way would be to
prevent the front legs from moving. What happens when we explore that approach:
Private members cannot be inherited. Let's say we want to make a class
called @var{TwoLeggedDog} to represent a dog that was trained to walk only
on two feet. We could approach this in a couple different ways. The first
way would be to prevent the front legs from moving. What happens when we
explore that approach:
@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
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,
private methods are not inherited. Rather than overriding the parent's
@var{_moveFrontLeg} method, you are instead @emph{defining a new method}, with
the name @var{_moveFrontLeg}. The old method will still be called. Instead, we
would have to override the public @var{walk} method to prevent our dog from
moving his front feet.
@emph{the dog's front legs still move}! This is because, as mentioned
before, private methods are not inherited. Rather than overriding the
parent's @var{_moveFrontLeg} method, you are instead @emph{defining a new
method}, with the name @var{_moveFrontLeg}. The old method will still be
called. Instead, we would have to override the public @var{walk} method to
prevent our dog from moving his front feet.
@subsection Protected Members
Protected members are often misunderstood. Many developers will declare all
of their members as either public or protected under the misconception that they
may as well allow subclasses to override whatever functionality they want. This
makes the class more flexible.
of their members as either public or protected under the misconception that
they may as well allow subclasses to override whatever functionality they
want. This makes the class more flexible.
While it is true that the class becomes more flexible to work with for subtypes,
this is a dangerous practice. In fact, doing so @emph{violates encapsulation}.
Let's reconsider the levels of visibility in this manner:
While it is true that the class becomes more flexible to work with for
subtypes, this is a dangerous practice. In fact, doing so @emph{violates
encapsulation}. Let's reconsider the levels of visibility in this manner:
@table @strong
@item public
@ -347,19 +359,20 @@ Provides an API for @emph{the class itself}.
@end table
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
acts as a peephole in our black box. We don't want people spying into our
internals. Subtypes shouldn't care about the dog's implementation either.
subtypes. If we simply expose all members to any subclass that comes by,
that acts as a peephole in our black box. We don't want people spying into
our internals. Subtypes shouldn't care about the dog's implementation
either.
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,
we can move up to try protected members. Remember not to make a member public
unless you wish it to be accessible to the entire world.
provide subtypes with the ability to access or override methods. In that
case, we can move up to try protected members. Remember not to make a
member public unless you wish it to be accessible to the entire world.
@var{Dog} (@pxref{f:encapsulation,}) defined a single method as protected -
@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
subtype, @var{LazyDog}, which refuses to stand.
subtypes. Since it is inherited, it may also be overridden. Let's define
another subtype, @var{LazyDog}, which refuses to stand.
@float Figure, f:encapsulation-inherit-prot
@verbatim
@ -381,19 +394,19 @@ subtype, @var{LazyDog}, which refuses to stand.
@caption{Protected members are inherited by subtypes}
@end float
There are a couple important things to be noted from the above example. Firstly,
we are able to override the @code{walk()} method, because it was inherited.
Secondly, since @code{rollOver()} was also inherited from the parent, we are
able to call that method, resulting in an upside-down dog that refuses to stand
up, just moving his feet.
There are a couple important things to be noted from the above example.
Firstly, we are able to override the @code{walk()} method, because it was
inherited. Secondly, since @code{rollOver()} was also inherited from the
parent, we are able to call that method, resulting in an upside-down dog
that refuses to stand up, just moving his feet.
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
to that variable. Since it is private, it was not inherited. However, since the
@code{rollOver()} method is called within the context of the @var{Dog} class,
the @emph{method} has access to the private member, allowing our dog to
successfully roll over. If, on the other hand, we were to override
@code{rollOver()}, our code would @emph{not} have access to that private object.
Calling @samp{this.__super()} from within the overridden method would, however,
call the parent method, which would again have access to its parent's private
members.
private property of @var{Dog} -- @var{_body}. Our subclass does not have
access to that variable. Since it is private, it was not inherited. However,
since the @code{rollOver()} method is called within the context of the
@var{Dog} class, the @emph{method} has access to the private member,
allowing our dog to successfully roll over. If, on the other hand, we were
to override @code{rollOver()}, our code would @emph{not} have access to that
private object. Calling @samp{this.__super()} from within the overridden
method would, however, call the parent method, which would again have access
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 Copyright (C) 2011, 2013, 2014 Mike Gerwitz
@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 or any later version published by the Free Software Foundation;
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
@c Texts. A copy of the license is included in the section entitled ``GNU
@c Free Documentation License''.
@c under the terms of the GNU Free Documentation License, Version 1.3 or
@c any later version published by the Free Software Foundation; with no
@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c A copy of the license is included in the section entitled ``GNU Free
@c Documentation License''.
@node Source Tree
@appendix Source Tree
@ -19,7 +19,8 @@ follow along.
doc/ lib/ test/ tools/
@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
@item ./
@ -27,8 +28,8 @@ The root directory contains basic project files, such as @file{README},
@file{Makefile} and @file{index.js}.
@item doc/
Contains documentation source files (you are currently reading part of it - the
manual).
Contains documentation source files (you are currently reading part of it -
the manual).
@item lib/
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.
@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
Useful information for those looking to modify/contribute to the project.
@item README.md
Serves as a quick reference for the project, in markdown@footnote{See
@uref{http://en.wikipedia.org/wiki/Markdown}.} format. This format was chosen
because it is displayed nicely on GitHub.
@uref{http://en.wikipedia.org/wiki/Markdown}.} format. This format was
chosen because it is displayed nicely on GitHub.
@item README.todo
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
tracker at @uref{http://easejs.org/bugs}).
out, take a look at this file to see what needs to be done. (See also the
bug tracker at @uref{http://easejs.org/bugs}).
@end table
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
@section Doc Directory
The @file{doc/} directory contains the source files for the manual. The source
files are in Texinfo@footnote{See @uref{http://www.gnu.org/software/texinfo/}.}
format. Instructions for compiling the documentation are included later in this
chapter.
The @file{doc/} directory contains the source files for the manual. The
source files are in Texinfo@footnote{See
@uref{http://www.gnu.org/software/texinfo/}.} format. Instructions for
compiling the documentation are included later in this chapter.
API documentation is @emph{not} included in this directory. It is generated from
the source code.
API documentation is @emph{not} included in this directory. It is generated
from the source code.
@node Lib Directory
@section Lib Directory
The @file{lib/} directory contains the source code for the project. Each source
file represents a single CommonJS module, often containing a prototype, and is
written in JavaScript. Additional information about each of the modules can be
found in the header of each file.
The @file{lib/} directory contains the source code for the project. Each
source file represents a single CommonJS module, often containing a
prototype, and is written in JavaScript. Additional information about each
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
files. @file{index.js}, in the root directory, contains mappings to these files
where necessary, exposing the useful portions of the API for general use. You
can use ease.js without even recognizing that the @file{lib/} directory even
exists.
Unless you are developing for ease.js, you needn't concern yourself with
these files. @file{index.js}, in the root directory, contains mappings to
these files where necessary, exposing the useful portions of the API for
general use. You can use ease.js without even recognizing that the
@file{lib/} directory even exists.
@node Test Directory
@section Test Directory
The @file{test/} directory contains all the unit tests for the project. ease.js
follows a test-driven development model; every single aspect of the framework is
tested to ensure that features work as intended both server-side and across all
supported web browsers. The tests also serve as regression tests, ensuring that
bugs are not introduced for anything that has been covered. These tests should
also give outside developers confidence; if a developer makes a modification to
ease.js and does not cause any failing tests, it's likely that their change
didn't have negative consequences on the integrity of the framework.
The @file{test/} directory contains all the unit tests for the project.
ease.js follows a test-driven development model; every single aspect of the
framework is tested to ensure that features work as intended both
server-side and across all supported web browsers. The tests also serve as
regression tests, ensuring that bugs are not introduced for anything that
has been covered. These tests should also give outside developers
confidence; if a developer makes a modification to ease.js and does not
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
cases. Tests written in the original format are prefixed with @samp{test-},
followed by the name of the module, followed optionally by the specific part of
the module that is being tested. Newer test cases are prefixed with the
prototype name of the unit being tested, followed by @samp{Test.js}. If there
are a number of test cases for a given prototype, any number of tests will be
included (with the same suffix) in a directory with the same name as the
prototype. The tests are written in JavaScript and use Node.js's @file{assert}
module. Newer tests use a test case system that was developed to suit the needs
of the project (still using the @file{assert} module). They may be run
individually or all at once during the build process.
ease.js is currently in a transition period in regards to the style of the
test cases. Tests written in the original format are prefixed with
@samp{test-}, followed by the name of the module, followed optionally by the
specific part of the module that is being tested. Newer test cases are
prefixed with the prototype name of the unit being tested, followed by
@samp{Test.js}. If there are a number of test cases for a given prototype,
any number of tests will be included (with the same suffix) in a directory
with the same name as the prototype. The tests are written in JavaScript and
use Node.js's @file{assert} module. Newer tests use a test case system that
was developed to suit the needs of the project (still using the
@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
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
@section Tools Directory
The @file{tools/} directory contains scripts and data necessary for the build
process. The tools are shell scripts that may be run independently of the build
process if you find them to be useful. The remaining files are data to accompany
those tools.
The @file{tools/} directory contains scripts and data necessary for the
build process. The tools are shell scripts that may be run independently of
the build process if you find them to be useful. The remaining files are
data to accompany those tools.
@table @file
@item combine
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
in the web browser. The contents are stripped of trailing commas using the
@command{rmtrail} tool. The resulting file is @emph{not} minified; the user can
use whatever process he/she wishes to do so. In the future, minification will be
part of the build script.
requested, the tests are also wrapped and concatenated so that they may be
run in the web browser. The contents are stripped of trailing commas using
the @command{rmtrail} tool. The resulting file is @emph{not} minified; the
user can use whatever process he/she wishes to do so. In the future,
minification will be part of the build script.
@item rmtrail
Removes trailing commas from object and array definitions. Reads from standard
in. @emph{This script is not intelligent.} It was designed to work with ease.js.
It does not, for example, check to ensure that it is not removing commas from
within strings. This would not be a difficult addition, but is currently
unnecessary. Use caution when using this tool outside of ease.js.
Removes trailing commas from object and array definitions. Reads from
standard in. @emph{This script is not intelligent.} It was designed to work
with ease.js. It does not, for example, check to ensure that it is not
removing commas from within strings. This would not be a difficult addition,
but is currently unnecessary. Use caution when using this tool outside of
ease.js.
@item minify.js
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.
@item browser-test.html
Skeleton page to be used after the build process. Runs ease.js unit tests in the
web browser and reports any failures. This is very important to ensure that
ease.js operates consistently between all supported browsers. The tests that are
run are the same exact tests that are run server-side.
Skeleton page to be used after the build process. Runs ease.js unit tests in
the web browser and reports any failures. This is very important to ensure
that ease.js operates consistently between all supported browsers. The tests
that are run are the same exact tests that are run server-side.
@item combine-test.tpl
Contains a client-side implementation of any modules required for testing. This
file contains mainly assertions. It is included by the @command{combine} script
when tests are requested.
Contains a client-side implementation of any modules required for testing.
This file contains mainly assertions. It is included by the
@command{combine} script when tests are requested.
@item combine.tpl
Contains the basic functionality required to get CommonJS modules working
client-side. This is a very basic implementation, only doing what is necessary
for ease.js to work properly. It is not meant to be a solution for all of your
client-side CommonJS problems.
client-side. This is a very basic implementation, only doing what is
necessary for ease.js to work properly. It is not meant to be a solution for
all of your client-side CommonJS problems.
@item license.tpl
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
source code, you are welcome to add additional text. See the @file{LICENSE} file
in the root directory for more information on what is permitted.
source code, you are welcome to add additional text. See the @file{LICENSE}
file in the root directory for more information on what is permitted.
@end table
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
unnecessary features that ease.js does not need to make use of. Therefore, you
may need to adapt them to your own project and individual needs should you
decide to use them in your own projects.
unnecessary features that ease.js does not need to make use of. Therefore,
you may need to adapt them to your own project and individual needs should
you decide to use them in your own projects.