Corrected all line lengths in doc/
Now conforms to tools/linechk's 76-char limitation.perfodd
parent
537ca0d694
commit
4b871dabc8
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
226
doc/about.texi
|
@ -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
1016
doc/classes.texi
File diff suppressed because it is too large
Load Diff
|
@ -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 {
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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]
|
||||
|
||||
|
|
File diff suppressed because it is too large
Load Diff
|
@ -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.
|
||||
|
|
|
@ -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 );
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue