GNU
/
easejs
1
0
Fork 0
Code Releases Activity

Simplified README.md and updated links

perfodd
Mike Gerwitz 2014-01-20 22:53:01 -05:00
parent 05a09763c4
commit ca3ebb53cc
1 changed files with 23 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

224
README.md
View File

@ -1,5 +1,5 @@
<!--
Copyright (C) 2013 Mike Gerwitz
Copyright (C) 2013, 2014 Mike Gerwitz
This file is part of GNU ease.js.
@ -11,9 +11,9 @@
# 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:
@ -24,216 +24,38 @@ Current support includes:
* Visibility (public, protected, and private members)
* Static and constant members
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.
**This project is under active development. Please see the manual for more
information.**
## Documentation
Comprehensive documentation and examples are available on the [GNU
ease.js](https://www.gnu.org/software/easejs) website and in its
[manual](https://www.gnu.org/software/easejs/manual).
## Full Documentation
Full documentation is available at the following URL:
http://easejs.org/manual/ (Multiple Pages)
http://easejs.org/manual.html (Single Page)
## Bug Reports / Feature Requests
Please direct bug reports and feature requests to the bug tracker located at
http://easejs.org/bugs/
Please direct bug reports and feature requests to bug-easejs@gnu.org or the
[project page on Savannah](https://savannah.gnu.org/projects/easejs).
## Why ease.js?
There are already a number of libraries/frameworks that permit basic classical
object-oriented development, so why ease.js? While many of the existing
solutions certainly provide viable solutions, they are largely incomplete. Until
the appearance of ECMAScript 5, many of the features enjoyed by classical OO
developers were elusive to JavaScript. The aim of this project is to provide an
intuitive framework in a CommonJS format which also addresses ES5 issues and is
an all-inclusive solution to OO techniques.
ECMAScript reserves certain keywords that hint at classical OO in future
versions, but said features are uncertain. ease.js will satisfy the classical OO
itch until the time where ECMAScript itself includes it, at which time ease.js
will still be useful for providing a transition in order to support older
browsers. ease.js may also be useful in the future to augment the feature set of
whatever native ECMAScript implementation is decided upon.
## Why Classical OOP in JavaScript?
GNU ease.js was created (historically) for a number of reasons:
### Why Classical OOP in JavaScript?
ease.js was created (historically) for a number of reasons:
* To "ease" object-oriented developers into JavaScript by providing a familiar
environment.
* To "ease" object-oriented developers into JavaScript by providing a
familiar environment.
* To provide the maintenance and development benefits of classical OOP.
* To provide features missing from the language, such as proper encapsulation
through private/protected members, interfaces, traits, intuitive inheritance,
etc.
* To provide features not included in the language, such as proper
encapsulation through private/protected members, interfaces, traits,
intuitive inheritance, and other conveniences.
* To encapsulate the hacks commonly used to perform the above tasks.
Many JS purists believe that classical object-oriented programming should be
left out of the language and one should stick strictly to prototypal
development. While the two are related (both object-oriented), they can be
applied to different problem domains in order to achieve results that are more
natural or intuitive to developers. ease.js works seamlessly with existing
prototypes, allowing the developer to choose whether or not they want to use
"classes".
left out of JavaScript and that one should stick strictly to prototypal
development. While the two are related (they are both object-oriented), they
can be applied to different problem domains in order to achieve results that
are more natural or intuitive to developers; GNU ease.js works seamlessly
with existing prototypes, allowing the developer to choose whether or not
they want to use "classes".
## How to Use
Please note that, as the project is under active development, the API may change
until the first release.
ease.js uses the [CommonJS](http://commonjs.org) module format. In the
examples below, [Node.js](http://nodejs.org) is used.
### Defining Classes
The constructor is provided as the `__construct()` method (influenced by
[PHP](http://php.net)).
````javascript
var Class = require( 'easejs' ).Class;
// anonymous class definition
var Dog = Class(
{
'private _name': '',
'public __construct': function( name )
{
this._name = name;
},
'public bark': function()
{
console.log( 'Woof!' );
},
'public getName': function()
{
return this._name;
}
});
````
The above creates an anonymous class and stores it in the variable ``Dog``. You
have the option of naming class in order to provide more useful error messages
and toString() output:
````javascript
var Dog = Class( 'Dog',
{
// ...
});
````
### Extending Classes
Classes may inherit from one-another. If the supertype was created using
`Class.extend()`, a convenience `extend()` method has been added to it. Classes
that were not created via `Class.extend()` can still be extended by passing it
as the first argument to `Class.extend()`.
Multiple inheritance is not supported. ease.js is very generous with the options
it provides to developers as alternatives, so pick whichever flavor your are
most comfortable with: interfaces, traits or mixins. Multiple inheritance will
*not* be added in the future due to problems which have been addressed by
interfaces and traits.
**Note that traits and mixins are not yet available. They are
planned features and will be available in the future.**
````javascript
var SubFoo = Foo.extend(
{
'public anotherMethod': function()
{
},
});
// if Foo was not created via Class.extend(), this option may be used (has
// the same effect as above, even if Foo was created using Class.extend())
var SubFoo = Class.extend( Foo,
{
'public anotherMethod': function()
{
},
});
````
### Abstract Classes
Abstract classes require that their subtypes implement certain methods. They
cannot be instantiated. Classes are considered to be abstract if they contain
one or more abstract methods and are declared using `AbstractClass` rather than
`Class`. If a class contains abstract methods but is not declared abstract, an
error will result. Similarily, if a class is declared to be abstract and
contains *no* abstract methods, an error will be thrown.
````javascript
var AbstractClass = require( 'easejs' ).AbstractClass;
var AbstractFoo = AbstractClass(
{
// a function may be provided if you wish the subtypes to implement a
// certain number of arguments
'abstract public fooBar': [ 'arg' ],
// alternatively, you needn't supply implementation details
'abstract public fooBar2': [],
});
````
If the abstract method provides implementation details (as shown by
`fooBar()`, subtypes must implement at least that many arguments or an exception
will be thrown. This ensures consistency between supertypes and their subtypes.
Abstract classes can be extended from just as an other class. In order for its
subtype to be instantiated, it must provide concrete implementations of each
abstract method. If any methods are left as abstract, then the subtype too will
be considered abstract and must be declared as such.
````javascript
// can be instantiated because concrete methods are supplied for both
// abstract methods
var ConcreteFoo = Class.extend( AbstractFoo,
{
'public fooBar': function( arg )
{
},
'public fooBar2': function()
{
},
});
// cannot be instantiated because one abstract method remains
var StillAbstractFoo = AbstractClass.extend( AbstractFoo,
{
'public fooBar': function( arg )
{
},
});
````
### Interfaces
Interfaces can be declared in a very similar manner to classes. All members of
an interface are implicitly abstract.
````javascript
var MyType = Interface(
{
'public foo': []
});
````
To implement an interface, use the `implement()` class method:
````javascript
var ConcreteType = Class.implement( MyType ).extend(
{
'public foo': function() {}
});
````
Note that, if a concrete implementation for each method is not provided, the
implementing type must be declared abstract.
## License
ease.js is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software