diff --git a/new-api.md b/new-api.md new file mode 100644 index 0000000..1bc138c --- /dev/null +++ b/new-api.md @@ -0,0 +1,325 @@ +# Release v3.0.0 + +## Table of Contents + +* [ Generator ](#generator) + * [ Generator.generate(create) ](#generate) + * [ Generator.isGenerator(test) ](#is-generator) + * [ Generator.toGenerator(constructor, create) ](#to-generator) + * [ Class: Generation ](#class-generation) + * [ new Generation() ](#generation-create) + * [ Generation.definePrototype([descriptor,] properties) ](#generation-define-prototype) + * [ Generation.generate(create) ](#generation-generate) + * [ Generation.isCreation(test) ](#generation-is-creation) + * [ Generation.isGeneration(test) ](#generation-is-generation) + * [ Class: Creation ](#class-creation) + * [ Creation.defineProperties([descriptor,] properties) ](#creation-define-properties) + * [ Creation.getProto() ](#creation-get-proto) + * [ Creation.getSuper() ](#creation-get-super) + + + +# Generator + +An easy to use prototypal inheritance model. + +### Install: +``` +$ npm install generate-js +``` + + +## Generator.generate(create) + +* *create* `Function` Constructor that with inherit form [Generation](#class-generation). +* *return*: `Constructor` The inputed `create` function. + +Returns a new [Generation](#class-generation) that inherits from [Generation](#class-generation). + +Example: +```javascript +var Generator = require('generate-js/new'); + +var Person = Generator.generate( + /* create method */ + function Person(name, age, sex) { + this.name = name || 'no-name'; + this.age = age || 0; + this.sex = sex || 'unknown'; + } +); +``` + + +## Generator.isGenerator(test) + +* *test* `Object` An Object to be tested. +* *return*: `Boolean` `true` or `false`. + +Returns `true` if *test* object inherits from [Generation](#class-generation), `false` otherwise. + + +## Generator.toGenerator(constructor, create) + +* *constructor* `Function` An constructor to be generatorized. +* *create* `Function` Constructor that with inherit form [Generation](#class-generation) and *constructor*. +* *return*: `Constructor` The inputed `create` function. + +Returns a new [Generation](#class-generation) that inherits from [Generation](#class-generation) and *constructor*. + +*NOTE*: Some native constructors can *NOT* be generatorized. + +Example: +```javascript +// generatorize NodeJS' EventEmitter +var Generator = require('generate-js/new'), + events = require('events'); + +var EventEmitter = Generator.toGenerator(events.EventEmitter, function EventEmitter() { + events.EventEmitter.call(this); //call the super constructor +}); + +// new EventEmitter() same as new events.EventEmitter(); + +// new generators can inherit all the abilities of EventEmitter like so. +var MyNewGenerator = EventEmitter.generate( + /* create method */ + function MyNewGenerator() { + EventEmitter.call(this); //call the super constructor + + // your code + } +); + +``` + + +## Class: Generation + +A new Generation that inherits from the Generation that generated it using the [Generation.generate(create)](#generation-generate) method. + + +## new Generation() + +* *return*: `Creation` A new [Creation](#class-creation) that is an instance of *this* [Generation](#generation). + +Creates a new [Creation](#class-creation) that is an instance of *this* [Generation](#generation). + +Example: +```javascript +var jim = new Person('Jim', 10, 'male'); + +jim.name // 'Jim' +jim.age // 10 +jim.sex // 'male' + +jim.sayHello(); // prints out: 'Hello, my name is Jim. What is yours?' +jim.sayBye(); // prints out: 'Goodbye.' + +``` + + +## Generation.definePrototype([descriptor,] properties) + +* *descriptor* `Object` Optional object descriptor that will be applied to all attaching properties. + * *configurable* `Boolean` States weather or not properties will be *configurable*, defaults to `false`. + * *enumerable* `Boolean` States weather or not properties will be *enumerable*, defaults to `false`. + * *writable* `Boolean` States weather or not properties will be *writable*, defaults to `false`. +* *properties* `Object` An object who's properties will be attached to *this* [Generation.prototype](#generation). +* *return*: `Generation` *This* [Generation](#class-generation). + +Defines shared properties for all [Creations](#class-creation) created by *this* [Generation](#class-generation). + +Example: +```javascript +/* + * Defining prototype properties that can be overwritten by Creations using the `=` sign. + */ +Person.definePrototype( + { + writable: true + }, + { + sayHello: function() { + console.log('Hello, my name is ' + this.name + '. What is yours?'); + } + } +); + +/* + * Defining prototype properties that can NOT be overwritten by Creations using the `=` sign. + */ +Person.definePrototype( + { + writable: false + }, + { + sayBye: function() { + console.log('Goodbye.'); + } + } +); + +/* + * Defining prototype properties that use getters and setters. + * NOTE: getter/setter prototype properties can NOT be overwritten by Creations using the `=` sign. + */ +(function(){ + var something = 'something'; + + Person.definePrototype({ + something: { + get: function() { + return something; + }, + set: function (newSomething) { + something = newSomething; + return something; + } + } + }); +}()); + +``` + + +## Generation.generate(create) + +* *create* `Function` Constructor that with inherit form [Generation](#class-generation). +* *return*: `Constructor` The inputed `create` function. + +Returns a new [Generation](#class-generation) that inherits from *this* [Generation](#class-generation). + +Example: +```javascript +var Student = Person.generate( + /* create method */ + function Student(name, age, sex, studentId) { + Person.call(this, name, age, sex); + this.studentId = studentId || 'A0000000000'; + } +); + +Student.definePrototype( + { + writable: true + }, + { + sayHello: function () { + console.log('Sup? My student ID is: ' + this.studentId + '.'); + } + } +); + +var sarah = new Student('Sarah', 17, 'female', 'A0123456789'); + +sarah.name // 'Sarah' +sarah.age // 17 +sarah.sex // 'female' +sarah.studentId // 'A0123456789' + +sarah.sayHello(); // prints out: 'Sup? My student ID is: A0123456789' +sarah.sayBye(); // prints out: 'Goodbye.' + +``` + + +## Generation.isGeneration(test) + +* *test* `Object` An Object to be tested. +* *return*: `Boolean` `true` or `false`. + +Returns `true` if *test* inherits from *this* [Generation](#class-generation), `false` otherwise. + + +## Generation.isCreation(test) + +* *test* `Object` An Object to be tested. +* *return*: `Boolean` `true` or `false`. + +Returns `true` if *test* is an instance of *this* [Generation](#generation), `false` otherwise. + + +## Class: Creation + +A instance [Generation](#generation) that created it using the [new Generation()](#generation-create). + + +## Creation.defineProperties([descriptor,] properties) + +* *descriptor* `Object` Optional object descriptor that will be applied to all attaching properties. + * *configurable* `Boolean` States weather or not properties will be *configurable*, defaults to `false`. + * *enumerable* `Boolean` States weather or not properties will be *enumerable*, defaults to `false`. + * *writable* `Boolean` States weather or not properties will be *writable*, defaults to `false`. +* *properties* `Object` An object who's properties will be attached to *this* [Creation](#class-creation). +* *return*: `Creation` *This* [Creation](#class-creation). + +Defines properties on *this* [Creation](#class-creation). + +Example: +```javascript +/* + * Jim is stubborn and blue will always be his favorite color. + */ +jim.defineProperties( + { + writable: false + }, + { + favoriteColor: 'blue' + } +); + +/* + * Sarah is indecisive and pink may not be her favorite color tomorrow. + */ +sarah.defineProperties( + { + writable: true + }, + { + favoriteColor: 'pink' + } +); + +``` + + +## Creation.getProto() + +* *return*: `Object` Prototype of *this* [Creation](#class-creation). + +Returns the prototype of *this* [Creation](#class-creation). + + +## Creation.getSuper() + +* *return*: `Object` Super prototype of *this* [Creation](#class-creation). + +Returns the super prototype of *this* [Creation](#class-creation). + +## Author: + Michaelangelo Jong + +## License: + The MIT License (MIT) + + Copyright (c) 2014-2016 Michaelangelo Jong + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE.