Boo Documentation - Read the Docs · Boo provides a thin layer on top of these semantics for making deﬁning objects in terms of other objects easier and sweeter. The derive method

Boo DocumentationRelease 1.2.0

Quildreen Motta

December 16, 2012

CONTENTS

i

ii

Boo Documentation, Release 1.2.0

Boo provides easy-modo prototypical inheritance and object composition for JavaScript, through mixins and prototypecloning.

CONTENTS 1


2 CONTENTS

CHAPTER

ONE

GUIDES

• Discover Boo A tour through Boo’s concepts and how you can leverage them to structure better your code-base.• API Reference A quick reference on the minimal Boo’s API, including plenty of usage examples and cross-

references.

1.1 Discover Boo

This document will guide you through the concepts abstracted by the Boo library, so you can leverage them to betterstructure your code-base.

1.1.1 Table of Contents

Overview

Boo is an object orientation library that abstracts the semantics of prototypical inheritance, as implemented byJavaScript, so they can be explored with a more usable interface.

This aims to make programs both easier to extend and better structured, such that they can be more modular and easierto understand for people reading the code — one of the main goals for all OrpheOS projects.

The additional expressiveness are mostly syntatic abstractions to the already expressive framework for code structura-tion provided by the language, which is that of prototypical inheritance. Boo takes that very feature and provides a thinlayer over it for making it easier to define objects in terms of other objects, but also provides a series of new primitivesto do general object composition — the latter, however, poses some overhead on the code since it’s not supportednatively by the language.

Note: The document assumes that the reader is familiar with all the particularities of JavaScript’s implementation ofprototypical inheritance. Although Boo itself abstracts prototypical inheritance and deals with it in a high-level way,the underlying semantics are left untouched, and need to be understood in order to structure one’s code better.

For an explanation of the semantics in details, you can refer to this blog post on the subject: Understanding JavaScriptOOP. There are also other takes on JavaScript’s implementation of prototypical OOP, which you may refer to. At anyrate, an understanding of the underlying semantics — sans constructors — will be assumed hereinafter.

Mixins

The first level of abstraction defined in Boo is carried by mixins, which we define as parent-less objects that can becopied into other objects freely. That is, Boo will never care about the [[Prototype]] of mixins, or even take a peek at

3

http://killdream.github.com/blog/2011/10/understanding-javascript-oop/index.html

http://killdream.github.com/blog/2011/10/understanding-javascript-oop/index.html


properties set at those level.

So, we can see mixins as plain objects that provide properties meant to be included in other objects. For example,given an object x with a single property a, an object y with a single property b, we could make an object z that is amix of another plain object (say one with a single property c), and the previous x and y objects:

var x = { a: 1 }var y = { b: 2 }var z = boo.extend({ c: 3 }, x, y)console.log(z)// => { a: 1, b: 2, c: 3 }

We can think about extend as something along the lines of: take this first object, then copies all own properties ofthe other objects into it. It’s a destructive operation, in which the first object will be modified in place, rather thanyielding a brand-new object.

However, the extend method, and those who build upon it have some particularities that we will discuss in thefollowing sections.

Data-objects

As you should know, if you set an Object as the value of a property slot in JavaScript, that only makes a shallow copyof the Object. That is, messing with the fields of that object will affect all copies of it. This is usually not what wewant for objects intended as data initialisation — for example, defaults for configuration or factories, — as pushingdata to an Array would also alter the actual array in the default-provider object.

For this reason, Boo allows objects to define their own copying method, so they can deal with these cases whereshallow copying is just a stab-in-the-back. All mixins that implement the method toData will be allowed to handlethe copying process, by returning a brand-new object that will be used instead of the original mixin.

First, we define a default ring object, which will provide all data needed for the ring behaviour. Like an interfacethat only describes values (numbers, strings, lists), not behaviours (functions and methods):

var default_ring = {items: []

, max: 3}

Then we define a general ring behaviour, that relies on the previous conventional interface — an object with anitems array and a numeric max property:

var ring = {// Pushes an item in the ring, keeping it within the maximum items// it can hold.push: function(item) {this.items.push(item)if (this.items.length > this.max)

this.shift() }

// Pops an item from the ring, LIFO style., pop: function() {

return this.items.pop() }}

And with this basic setup we can start creating new objects by composing the two. For example, a new ring is just:

var my_ring = boo.extend({}, ring, default_ring)my_ring.push(1)

4 Chapter 1. Guides


console.log(default_ring.items)// => [ 1 ]

Extending vs Merging

Cases where there’s no target for the mixin inclusion are common with data-objects. Boo provides the mergefunction, as a “pure” extend alternative.

But this is just not right. Since the current definitions mutate the defaults, it can’t really be used as... well, defaults.We need a way of deep copying the data if we need, and handle all the other cases where we’d want more control overwhich data is actually set to the objects including our data-object.

That’s exactly what the toData method does. It lets a data-object handle which properties are exposed and how theyare exposed, by creating a new object:

var default_ring = {items: [], max: 3

, toData: function() {return { items: [], max: this.max }}

}

var my_ring = boo.extend({}, ring, default_ring)my_ring.push(1)console.log(default_ring.items)// => [ ]

Conflict resolution

When mixing objects in the naivë way, naming conflicts may arise. For example, if one attempted to merge a self-implemented list with the above-mentioned ring object, both of which would include a push method, we wouldhave a conflict, given property names must be unique in an object.

The way extend handles these conflicts is by giving the rightmost object the higher precedence, such that:

// uses ‘push’ from ‘ring’var x = boo.merge(list, ring, default_ring)

// uses ‘push’ from ‘list’var x = boo.merge(ring, list, default_ring)

Clones

In prototypical object-oriented languages, cloning is the act of making a brand new instance out of another instance,with the same behaviours but different identities. Boo provides a thin layer on top of these semantics for makingdefining objects in terms of other objects easier and sweeter.

The derive method takes care of setting the [[Prototoype]] link of an object, and optionally extending the newinstance with some mixins. The advantage is that property inheritance is shared and delegative, which makes it bothefficient and extensible:

Since inheritance and instantiation have no real difference in a prototypical language, derive is used for both. Assuch, we could easily make a Token object that spawns new instances freely. The way this works in JavaScriptmakes these particularly sweet:

1.1. Discover Boo 5


var token = {// Constructs new instances of a ‘token’ by simply cloning the// object and extending it with some behaviour. We also do some// processing to set the parent-chain of the tokens.make: function(value, parent) { var instance// Instantiation is done by the derive method, it’ll clone whatever// thing the ‘make’ function was applied to, and extend that thing.instance = boo.derive(this, {

value: value, children: [] })

// Then set the parent-chain of the tokens, which is not really// related to cloning at all.if (parent) parent.children.push(instance)

// And return the instance we just createdreturn instance }

}

To show how this “inheritance” — or rather, behaviour sharing — plays out for structuring programs, we’ll make it sothat a token is able to describe itself and all of its children:

// Returns a whitespace-string with ‘size’ charactersfunction indent(size) {

return size? Array(size).join(0).split(0).join(’ ’): ’’ }

// Returns a general representation of a Tokentoken.toString = function() {

return ’#<Token ’ + this.value + ’>’ }

// Describes a Token and its childrentoken.describe = function(depth) {

depth = depth || 0return indent(depth) + this.toString()

+ this.describe_children(depth + 2) }

// Describes the children of a Tokentoken.describe_children = function(depth) { var descriptions

descriptions = this.children.map(function(token) {return token.describe(depth + 2) })

return descriptions.length? ’ {\n’ + descriptions.join(’\n’) + ’ }\n’: /* empty? */ ’’ }

And then we can define other objects that extend the behaviour of a Token, by the same means we used to create newinstances of Token:

var number = boo.derive(token, {toString: function() {return ’#<Number ’ + this.value + ’>’ }

})

var brace = token.make(’BRACE’)var zero = number.make(0, brace)

brace.describe()// => #<Token BRACE> {// .. #<Number 0> }

6 Chapter 1. Guides


zero.describe()// => #<Number 0>

Object Orientation

The last layer of abstraction defined by boo is a layer on top of the previously discussed primitives: extend and derive.This provides a simple way for developers to structure their code in terms of objects, composition and inheritance.

The boo.Base object provides the developer with two simple methods derive, to inherit from the object as you sawin the Clones section; and make, which constructs new instances of the object, and allowing for separate initialisation.

This allows objects to be easily defined in terms of other objects, by delegative inheritance:

var Animal = boo.Base.derive({name: ’Unknow’

, say: function(thing){ return this.name + ’: ’ + thing }})

var Cat = Animal.derive({init: function(name) {this.name = name }

})

var nyan = Cat.make(’Nyan Cat’)nyan.say(’Nyan nyan nyan~’)// => ’Nyan Cat: Nyan nyan nyan~

Where the derive method is the same as the previously discussed, but relying on this rather than taking a parent.This allows for code to be inherited easily, and shared easily. Note that derive and make both create a brand newobject with the [[Prototype]] of whatever thing they’re applied to.

So, you could write:

var OtherNyan = nyan.clone()

OtherNyan.isPrototypeOf(Nyan)// => True

OtherNyan.say(’Unyuu~’)// => ’Nyan Cat: Unyuu~’

Note: When make is called, init is applied to the new instance. It’s just an imperative method for initialisation, itcan’t, for example, modify the instance that’ll be returned by the make method. You’ll need to overwrite make if youneed that kind of factory method.

1.2 API Reference

This document presents a quick reference of Boo’s public API, with use cases and examples.

1.2.1 {} boo

The boo module provides primitives that abstract the semantics of prototypical object orientation, as implemented byJavaScript, such that these features can be explored with a more usable interface.

1.2. API Reference 7


The module provides such features as the stand-alone functions: extend() and derive(), as well as an Objectinterface that can be extended upon: Base.

Internal

Interfaces

boo.DataObject

type DataObject :: { "to_data" :: () -> Object }

boo.Mixin

type Mixin :: Object | DataObject

Helpers

boo.copy_property(source, target, property)

copy_property! :: Object, target:Object*, String -> target

Copies a property from source to target.

boo.data_obj_p(subject)

data_obj? :: Any -> Bool

Checks if the given subject matches the DataObject interface.

boo.resolve_mixin(object)

resolve_mixin :: Object -> Object

Returns the proper mixin for the given object.

boo.fast_extend(object, mixins)

fast_extend! :: target:Object*, [Mixin] -> target

Extends the target object with the provided mixins, using a right-most precedence rule — when there’s a propertyconflict, the property defined in the last object wins.

DataObject instances are properly handled by the resolve_mixin() function.

Public

Basic primitives

boo.extend(target, mixins...)

8 Chapter 1. Guides


extend!:: Object*, Mixin... -> Object

Extends the target object with the provided mixins, using a right-most precedence rule.

+

boo.merge(mixins...)

merge :: Mixin... -> Object

Creates a new object that merges the provided mixins, using a right-most precedence rule.

+

boo.derive(prototype, mixins...)

derive :: Object, Mixin... -> Object

Creates a new object inheriting from the given prototype and extends the new instance with the providedmixins.

+

Root object

class boo.Base

object Base :: { init! :: @this:Object*, Any... -> thismake :: @this:Object, Any... -> Object <| thisderive :: @this:Object, Any... -> Object <| this

}

The root object for basing all the OOP code. Provides all of Boo’s primitive combinators in an easy and exten-sible OOP-way.

+

Summary

-- Interfacetype DataObject :: { "to_data" :: () -> Object }type Mixin :: Object | DataObject

-- Internalcopy_property! :: Object, target:Object*, String -> targetdata_obj? :: Any -> Boolresolve_mixin :: Object -> Objectfast_extend! :: target:Object*, [Mixin] -> target

-- Publicextend! :: Object*, Mixin... -> Objectmerge :: Mixin... -> Objectderive :: Object, Mixin... -> Objectobject Base :: { init! :: @this:Object*, Any... -> this

make :: @this:Object, Any... -> Object <| this



derive :: @this:Object, Any... -> Object <| this}

λ extend()

boo.extend(target, sources...)

extend :: Object, (Object | DataObject)... -> Object

Extends the target object with the provided mixins, using a right-most precedence rule.

This function copies all properties from the given sources over to the target object. It is an impure function, andthus the target object will be modified in-place — if you’re looking for a pure alternative, you can take a look at λmerge().

var x = { a: 1, b: 2 }boo.extend(x, { c: 3 })x// => { a: 1, b: 2, c: 3 }

Conflict resolution If there’s any conflict, that is, more than one object defines the same property, then the propertyin the right-most object will be used.

boo.extend({ a: 3, b: 2 }, { a: 2, c: 3 }, { a: 1 })// => { a: 1, b: 2, c: 3 }

Data objects Data objects are handled gracefully by extend, by using the object returned by the to_datamethodrather than the given object. This means that an object can control which values to share, and which values to initialisewhen used as a mixin.

var base_collection = { toString: function() {return ’(’ + this.items.join(’ ’) + ’)’ }}

var coll1 = { items: [ 1, 2, 3 ] }var coll2 = { items: [ 1, 2, 3 ]

, to_data: function(){return { items: [] } }}

var instance1 = boo.extend({}, coll1, base_collection)instance1.toString()// => ’(1 2 3)’instance1.items.push(4)coll1.items.toString()// => ’1, 2, 3, 4’

var instance2 = boo.extend({}, coll2, base_collection)instance2.toString()// => ’()’instance2.items.push(4)coll2.items.toString()// => ’1, 2, 3’

10 Chapter 1. Guides


Limitations extend will only be able to copy the own enumerable properties of the source objects, as such,properties that are inherited from a [[Prototype]] link will not be copied over to the target. Likewise, in newerengines, properties that have been declared with a non-enumerable flag will not be copied.

var x = { a: 1 }var y = { a: 2 }var z = { __proto__: x, b: 2 }Object.defineProperty(z, { c: { value: 3, enumerable: false }})boo.extend(y, z)

// => { a: 2, b: 2 }

While this might be a limiting feature in some cases, specially if you’re only targeting newer engines, this allows us tomaintain full backwards compatibility with old engines.

Tutorials and examples

• Yay for Sugary JavaScript OO describes how to use extend and merge to bring the power of mixins toJavaScript.

• The Mixins chapter in the Discover Boo reference also describes the usage of extend and merge for mixinsat length.

Related functionality

λ merge() a pure alternative to extend, useful if you don’t want to modify the target object.

λ merge()

boo.merge(sources...)

merge :: (Object | DataObject)... -> Object

Creates a new object that merges the provided mixins, using a right-most precedence rule.

This function is mostly a convenience for invoking extend() with an empty object as target. Please see the extenddocumentation for information on the core semantics of merge.

var x = { a: 1 }var y = { b: 2 }var z = boo.merge(x, y)// => { a: 1, b: 2 }

x// => { a: 1 }y// => { b: 2 }

Limitations While being pure — the first object passed into the function won’t be changed, — it won’t preserveproperties nor [[Prototype]] chains. In fact, one could think of merge as a target-less extend, where the result is abrand new object that just gathers properties from a range of sources.


λ extend merge is just a convenience for extend. The original function is faster, but impure.


http://killdream.github.com/blog/2011/11/for-sugary-object-oriented-js/index.html#sec-2-1

http://en.wikipedia.org/wiki/Mixin


λ derive()

boo.derive(prototype, sources...)

derive :: Object, (Object | DataObject)... -> Object

Creates a new object inheriting from the given prototype, and extends the new instance with the provided mixins.

This function works as a higher-level alternative to the standard Object.create function. Instead of passing an objectwith property descriptors as the second parameter, you may pass any number of plain JavaScript objects, which willhave their own enumerable properties copied over to the new instance.

var Person = {say:function(thing) {return this.name + ’: ’ + thing }

}

var Sophie = boo.derive(Person, {name: ’Sophie’

})

Sophie.say(’hello.’)// => ’Sophie: hello.’

Limitations derive fills the hole left by Object.create for the end-user, who does not care about settingevery one of their properties’ flags. As such, derive provides a lightweight of creating a new object, setting its[[Prototype]] slot and initialising it with properties, but doesn’t give the user any additional power — all propertieswill be enumerable, configurable and writable.

Only own enumerable properties from the sources is copied over, and conflict resolution works in the same manneras extend()’s.

Tutorials and examples

• Understanding JavaScript OOP describes JavaScript’s particular implementation of Object Orientation — theprototypical model, — which is required to understand the implications of using derive.

• The Object Orientation chapter in the Discover Boo reference describes the usage and implications of deriveat length.


λ extend() The core implementation of derive’s instance initialisation.

{} Base

class boo.Base

Base :: { init! :: @this:Object*, Any... -> this }

The root object for basing all the OOP code. Provides all of Boo’s primitive combinators in an easy and exten-sible OOP-way.


https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/create

http://killdream.github.com/blog/2011/10/understanding-javascript-oop/index.html#sec-3


Creating instancesBase.make()


Constructs new instances of the object the function is being applied to.

+

Base.derive(sources...)

derive :: @this:Object, (Object | DataObject)... -> Object <| this

Constructs a new object that inherits from the object this function is being applied to, and extends it with theprovided mixins.

+

Summaryinit! :: @this:Object*, Any... -> thismake :: @this:Object, Any... -> Object <| thisderive :: @this:Object, Any... -> Object <| this

λ make()Base.make()


Constructs new instances of the object the function is being applied to.This is a generic method that will clone the current object and initialise it with an initialisation method (init). Suchinitialisation method is taken from the object the make method is applied to. This approach makes this method ratherflexible:

var fruit = { init: function(name){ this.name = namethis.bites = 0 }

, eat: function(){ return this.bites++? ’Already eaten.’: /* otherwise */ this.name + ’ is being eaten.’ }}

// This creates a new object with ‘fruit’ as its prototype, and// invokes ‘fruit’s ‘init’ method on it.var apple = Base.make.call(fruit, ’Apple’)

apple.eat()// => ’Apple has been eaten.’apple.eat()// => ’Already eaten.’

// This creates a new object with ‘apple’ as its prototype, and// invokes ‘apple’s ‘init’ method on it. Since apple itself doesn’t// define an ‘init’ method, it’s taken from ‘fruit’.var pie = Base.make.call(apple, ’Apple pie’)pie.eat()// => ’Apple pie has been eaten.’



The generic object on which make will be called should either not implement an init method at all, or match thefollowing interface:

type Initialisable :: { init! :: @this:Object*, Any... -> this }

Limitations While JavaScript’s own new operator allows one to write factory functions that work seamlessly withnew-ful invocations, the make method won’t change the instance depending on what init returns. That is, itdoesn’t use init as a transformer function, but rather as an impure initialisation routine.

If you want to write a factory function, you’ll need to use Base.derive() and invoke the right initialisation routineinstead.

λ derive()Base.derive(sources...)

derive :: @this:Object, (Object | DataObject)... -> Object <| this

Constructs a new object that inherits from the object this function is being applied to, and extends it with theprovided mixins.

Derive provides a thin abstraction layer upon the primitive derive(), with the only difference being that instead oftaking a [[Prototype]] as the first parameter, it uses the object the derive function has been applied to for that.

var Point2d = { x: 0, y: 0 }var Point3d = boo.derive(Point2d, { z: 1 })

// Does mostly the same thing as:var Point2d = Base.derive({ x: 0, y: 0 })var Point3d = Point2d.derive({ z: 1 })


λ derive The derive primitive function documentation page describes the function’s semantics in more details.


CHAPTER

TWO

INSTALLING

With Node.js and NPM, you can do the easy-modo install:

$ npm install boo

# Then require it as usual$ nodenode> var boo = require(’boo’)

In the browser, you have to include the script tag pointing to the boo.js file:

<script src="/path/to/boo.js"></script><script type="text/javascript">

// ‘boo’ is in the global scope now</script>

15


16 Chapter 2. Installing

CHAPTER

THREE

PLATFORM SUPPORT

Boo should support all ECMAScript 5-compliant platforms. It’s been successfully tested in the following platforms:

For the legacy platforms (like IE’s JScript), you’ll have to provide support for the following methods:

• Object.keys

• Object.create

• Object.getPrototypeOf

• Array.prototype.forEach

• Array.prototype.filter

• Array.prototype.indexOf

The nice es5-shim library takes care of handling all of those for you.

17

https://github.com/kriskowal/es5-shim


18 Chapter 3. Platform Support

CHAPTER

FOUR

SUPPORT

Boo uses the Github tracker for tracking bugs and new features.

19

https://github.com/Orphoundation/boo/issues


20 Chapter 4. Support

CHAPTER

FIVE

LICENCE

Boo is licensed under the delicious and premissive MIT licence. You can happily copy, share, modify, sell or whatever— refer to the actual licence text for less information:

$ less LICENCE.txt

# The MIT License## Copyright (c) 2011 Orphoundation## 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.

(END)

21

https://github.com/Orphoundation/boo/raw/master/LICENCE.txt


22 Chapter 5. Licence

PYTHON MODULE INDEX

bboo (ECMAScript 5), ??

23

Documents

Boo Documentation - Read the Docs · Boo provides a thin layer on top of these semantics for making deﬁning objects in terms of other objects easier and sweeter. The derive method