Skip to content

Commit 4e48b4e

Browse files
author
Michaelangelo Jong
authored
Create new-api.md
1 parent c280449 commit 4e48b4e

1 file changed

Lines changed: 325 additions & 0 deletions

File tree

‎new-api.md‎

Lines changed: 325 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,325 @@
1+
# Release v3.0.0
2+
3+
## Table of Contents
4+
5+
* [ Generator ](#generator)
6+
* [ Generator.generate(create) ](#generate)
7+
* [ Generator.isGenerator(test) ](#is-generator)
8+
* [ Generator.toGenerator(constructor, create) ](#to-generator)
9+
* [ Class: Generation ](#class-generation)
10+
* [ new Generation() ](#generation-create)
11+
* [ Generation.definePrototype([descriptor,] properties) ](#generation-define-prototype)
12+
* [ Generation.generate(create) ](#generation-generate)
13+
* [ Generation.isCreation(test) ](#generation-is-creation)
14+
* [ Generation.isGeneration(test) ](#generation-is-generation)
15+
* [ Class: Creation ](#class-creation)
16+
* [ Creation.defineProperties([descriptor,] properties) ](#creation-define-properties)
17+
* [ Creation.getProto() ](#creation-get-proto)
18+
* [ Creation.getSuper() ](#creation-get-super)
19+
20+
21+
<a name="generator"></a>
22+
# Generator
23+
24+
An easy to use prototypal inheritance model.
25+
26+
### Install:
27+
```
28+
$ npm install generate-js
29+
```
30+
31+
<a name="generate"></a>
32+
## Generator.generate(create)
33+
34+
* *create* `Function` Constructor that with inherit form [Generation](#class-generation).
35+
* *return*: `Constructor` The inputed `create` function.
36+
37+
Returns a new [Generation](#class-generation) that inherits from [Generation](#class-generation).
38+
39+
Example:
40+
```javascript
41+
var Generator = require('generate-js/new');
42+
43+
var Person = Generator.generate(
44+
/* create method */
45+
function Person(name, age, sex) {
46+
this.name = name || 'no-name';
47+
this.age = age || 0;
48+
this.sex = sex || 'unknown';
49+
}
50+
);
51+
```
52+
53+
<a name="is-generator"></a>
54+
## Generator.isGenerator(test)
55+
56+
* *test* `Object` An Object to be tested.
57+
* *return*: `Boolean` `true` or `false`.
58+
59+
Returns `true` if *test* object inherits from [Generation](#class-generation), `false` otherwise.
60+
61+
<a name="to-generator"></a>
62+
## Generator.toGenerator(constructor, create)
63+
64+
* *constructor* `Function` An constructor to be generatorized.
65+
* *create* `Function` Constructor that with inherit form [Generation](#class-generation) and *constructor*.
66+
* *return*: `Constructor` The inputed `create` function.
67+
68+
Returns a new [Generation](#class-generation) that inherits from [Generation](#class-generation) and *constructor*.
69+
70+
*NOTE*: Some native constructors can *NOT* be generatorized.
71+
72+
Example:
73+
```javascript
74+
// generatorize NodeJS' EventEmitter
75+
var Generator = require('generate-js/new'),
76+
events = require('events');
77+
78+
var EventEmitter = Generator.toGenerator(events.EventEmitter, function EventEmitter() {
79+
events.EventEmitter.call(this); //call the super constructor
80+
});
81+
82+
// new EventEmitter() same as new events.EventEmitter();
83+
84+
// new generators can inherit all the abilities of EventEmitter like so.
85+
var MyNewGenerator = EventEmitter.generate(
86+
/* create method */
87+
function MyNewGenerator() {
88+
EventEmitter.call(this); //call the super constructor
89+
90+
// your code
91+
}
92+
);
93+
94+
```
95+
96+
<a name="class-generation"></a>
97+
## Class: Generation
98+
99+
A new Generation that inherits from the Generation that generated it using the [Generation.generate(create)](#generation-generate) method.
100+
101+
<a name="generation-create"></a>
102+
## new Generation()
103+
104+
* *return*: `Creation` A new [Creation](#class-creation) that is an instance of *this* [Generation](#generation).
105+
106+
Creates a new [Creation](#class-creation) that is an instance of *this* [Generation](#generation).
107+
108+
Example:
109+
```javascript
110+
var jim = new Person('Jim', 10, 'male');
111+
112+
jim.name // 'Jim'
113+
jim.age // 10
114+
jim.sex // 'male'
115+
116+
jim.sayHello(); // prints out: 'Hello, my name is Jim. What is yours?'
117+
jim.sayBye(); // prints out: 'Goodbye.'
118+
119+
```
120+
121+
<a name="generation-define-prototype"></a>
122+
## Generation.definePrototype([descriptor,] properties)
123+
124+
* *descriptor* `Object` Optional object descriptor that will be applied to all attaching properties.
125+
* *configurable* `Boolean` States weather or not properties will be *configurable*, defaults to `false`.
126+
* *enumerable* `Boolean` States weather or not properties will be *enumerable*, defaults to `false`.
127+
* *writable* `Boolean` States weather or not properties will be *writable*, defaults to `false`.
128+
* *properties* `Object` An object who's properties will be attached to *this* [Generation.prototype](#generation).
129+
* *return*: `Generation` *This* [Generation](#class-generation).
130+
131+
Defines shared properties for all [Creations](#class-creation) created by *this* [Generation](#class-generation).
132+
133+
Example:
134+
```javascript
135+
/*
136+
* Defining prototype properties that can be overwritten by Creations using the `=` sign.
137+
*/
138+
Person.definePrototype(
139+
{
140+
writable: true
141+
},
142+
{
143+
sayHello: function() {
144+
console.log('Hello, my name is ' + this.name + '. What is yours?');
145+
}
146+
}
147+
);
148+
149+
/*
150+
* Defining prototype properties that can NOT be overwritten by Creations using the `=` sign.
151+
*/
152+
Person.definePrototype(
153+
{
154+
writable: false
155+
},
156+
{
157+
sayBye: function() {
158+
console.log('Goodbye.');
159+
}
160+
}
161+
);
162+
163+
/*
164+
* Defining prototype properties that use getters and setters.
165+
* NOTE: getter/setter prototype properties can NOT be overwritten by Creations using the `=` sign.
166+
*/
167+
(function(){
168+
var something = 'something';
169+
170+
Person.definePrototype({
171+
something: {
172+
get: function() {
173+
return something;
174+
},
175+
set: function (newSomething) {
176+
something = newSomething;
177+
return something;
178+
}
179+
}
180+
});
181+
}());
182+
183+
```
184+
185+
<a name="generation-generate"></a>
186+
## Generation.generate(create)
187+
188+
* *create* `Function` Constructor that with inherit form [Generation](#class-generation).
189+
* *return*: `Constructor` The inputed `create` function.
190+
191+
Returns a new [Generation](#class-generation) that inherits from *this* [Generation](#class-generation).
192+
193+
Example:
194+
```javascript
195+
var Student = Person.generate(
196+
/* create method */
197+
function Student(name, age, sex, studentId) {
198+
Person.call(this, name, age, sex);
199+
this.studentId = studentId || 'A0000000000';
200+
}
201+
);
202+
203+
Student.definePrototype(
204+
{
205+
writable: true
206+
},
207+
{
208+
sayHello: function () {
209+
console.log('Sup? My student ID is: ' + this.studentId + '.');
210+
}
211+
}
212+
);
213+
214+
var sarah = new Student('Sarah', 17, 'female', 'A0123456789');
215+
216+
sarah.name // 'Sarah'
217+
sarah.age // 17
218+
sarah.sex // 'female'
219+
sarah.studentId // 'A0123456789'
220+
221+
sarah.sayHello(); // prints out: 'Sup? My student ID is: A0123456789'
222+
sarah.sayBye(); // prints out: 'Goodbye.'
223+
224+
```
225+
226+
<a name="generation-is-generation"></a>
227+
## Generation.isGeneration(test)
228+
229+
* *test* `Object` An Object to be tested.
230+
* *return*: `Boolean` `true` or `false`.
231+
232+
Returns `true` if *test* inherits from *this* [Generation](#class-generation), `false` otherwise.
233+
234+
<a name="generation-is-creation"></a>
235+
## Generation.isCreation(test)
236+
237+
* *test* `Object` An Object to be tested.
238+
* *return*: `Boolean` `true` or `false`.
239+
240+
Returns `true` if *test* is an instance of *this* [Generation](#generation), `false` otherwise.
241+
242+
<a name="class-creation"></a>
243+
## Class: Creation
244+
245+
A instance [Generation](#generation) that created it using the [new Generation()](#generation-create).
246+
247+
<a name="creation-define-properties"></a>
248+
## Creation.defineProperties([descriptor,] properties)
249+
250+
* *descriptor* `Object` Optional object descriptor that will be applied to all attaching properties.
251+
* *configurable* `Boolean` States weather or not properties will be *configurable*, defaults to `false`.
252+
* *enumerable* `Boolean` States weather or not properties will be *enumerable*, defaults to `false`.
253+
* *writable* `Boolean` States weather or not properties will be *writable*, defaults to `false`.
254+
* *properties* `Object` An object who's properties will be attached to *this* [Creation](#class-creation).
255+
* *return*: `Creation` *This* [Creation](#class-creation).
256+
257+
Defines properties on *this* [Creation](#class-creation).
258+
259+
Example:
260+
```javascript
261+
/*
262+
* Jim is stubborn and blue will always be his favorite color.
263+
*/
264+
jim.defineProperties(
265+
{
266+
writable: false
267+
},
268+
{
269+
favoriteColor: 'blue'
270+
}
271+
);
272+
273+
/*
274+
* Sarah is indecisive and pink may not be her favorite color tomorrow.
275+
*/
276+
sarah.defineProperties(
277+
{
278+
writable: true
279+
},
280+
{
281+
favoriteColor: 'pink'
282+
}
283+
);
284+
285+
```
286+
287+
<a name="creation-get-proto"></a>
288+
## Creation.getProto()
289+
290+
* *return*: `Object` Prototype of *this* [Creation](#class-creation).
291+
292+
Returns the prototype of *this* [Creation](#class-creation).
293+
294+
<a name="creation-get-super"></a>
295+
## Creation.getSuper()
296+
297+
* *return*: `Object` Super prototype of *this* [Creation](#class-creation).
298+
299+
Returns the super prototype of *this* [Creation](#class-creation).
300+
301+
## Author:
302+
Michaelangelo Jong
303+
304+
## License:
305+
The MIT License (MIT)
306+
307+
Copyright (c) 2014-2016 Michaelangelo Jong
308+
309+
Permission is hereby granted, free of charge, to any person obtaining a copy
310+
of this software and associated documentation files (the "Software"), to deal
311+
in the Software without restriction, including without limitation the rights
312+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
313+
copies of the Software, and to permit persons to whom the Software is
314+
furnished to do so, subject to the following conditions:
315+
316+
The above copyright notice and this permission notice shall be included in all
317+
copies or substantial portions of the Software.
318+
319+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
320+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
321+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
322+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
323+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
324+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
325+
SOFTWARE.

0 commit comments

Comments
 (0)