Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 156 lines (120 sloc) 6.094 kb
a1a33898 » Tauren Mills
2011-08-30 fixed readme
1 # pulverize - Micro-framework aware build tool
0cec123a » Tauren Mills
2011-08-30 initial ideas
2
3 Tired of bloating your latest javascript library with the same code that is already included in many micro-frameworks
4 just because you don't want your library to have any dependencies? Add `pulverize` to your build process and let
5 your users decide what's included!
6
7 Let's say your library needs `isFunction()` and `isString()`. Underscore provides these. So does jQuery. You know that
8 99% of the time, the users of your library will also be using underscore, jquery, zepto, YAHOO.lang, or whatever. But you don't know
9 which one, and you want to let people use it without any dependencies.
10
11 If you are looking for production code, you'll have to come back later. This is currently just the beginnings of
12 an idea and no code is available yet.
13
14 ## The Idea
15
16 Code will be replaced inline during the build process. However, the raw, unprocessed code must be able to run without
17 building it first.
18
19 Tools to consider using:
20
21 * uglify
22 * smoosh
23 * commander.js
24
25 Will have a `pulverize` executable that will look for a `pulverize.json` configuration file in the current directory
26 when run. A path to the config file can be passed as a command line parameter. The config file will declare which
27 micro-framework combinations should be built for. A preliminary config file:
28
29 {
30 "VERSION": "0.0.1",
31 "NAME": "mylib",
32 "IN_DIR": "./src",
33 "DIST_DIR": "./dist",
34 "BUILDS": {
35 "underscore": {
36 libs: ["underscore"]
37 },
38 "jquery": {
39 libs: ["jquery"]
40 },
41 "jqund": {
42 libs: ["jquery","underscore"]
43 }
44 }
45 }
46
47
48 The order libraries are specified in the config file is important and creates the precendence for which function
49 from which framework is used. The config above would create the following files. There would also be an options
50 to uglify the files as well.
51
52 mylib-0.0.1.js
53 mylib-underscore-0.0.1.js
54 mylib-jquery-0.0.1.js
55 mylib-jqund-0.0.1.js
56
57 Need to build an object containing the functions that you utilize in your library. Provide default implementations
58 for all of them. Override the defaults for various micro-frameworks. If an override is not specified, then the
59 default will be included and used. Perhaps something like this?
60
61 PULVERIZE = new Pulverize ['jquery','underscore'],
62 defaults:
63 isFunction: (obj) ->
64 obj and obj.call and obj.apply
65 isObject: (obj) ->
66 cons = obj.constructor
67 cons and 'Object' == cons.name
68 isString: (obj) ->
69 !!(obj == "" or (obj and obj.charCodeAt and obj.substr))
70 underscore:
71 isFunction: _.isFunction
72 isObject: _.isObject
73 isString: _.isString
74 jquery:
75 isFunction: $.isFunction
76
77 This creates a `Pulverize` instance by passing an array of libs and an object containing the functions required by
78 your project. The constructor will add the appropriate functions to the PULVERIZE instance based on the array of
79 libs passed to the contstructor. Hopefully you will be able to call PULVERIZE whatever you want and that the
80 uglify AST will allow us to find `new Pulverize` and determine the name of the variable it is being assigned to.
81 This variable is needed later so that uses in your project code can be replaced.
82
83 Assume your project code is this:
84
85 getUrl = (url) ->
86 return url if PULVERIZE.isString url
87 return url() if PULVERIZE.isFunction url
88 throw 'Invalid URL'
89
90 And you build your project:
91
92 pulverize
93
94 Perhaps allow command line options to build your project with specific frameworks?
95
96 pulverize --lib jquery
97 pulverize --lib jquery --lib underscore
98
99 The resulting code after pulverize is run in default mode would be:
100
101 PULVERIZE =
102 isFunction: (obj) ->
103 obj and obj.call and obj.apply
104 isObject: (obj) ->
105 cons = obj.constructor
106 cons and 'Object' == cons.name
107 isString: (obj) ->
108 !!(obj == "" or (obj and obj.charCodeAt and obj.substr))
109
110 getUrl = (url) ->
111 return url if PULVERIZE.isString url
112 return url() if PULVERIZE.isFunction url
113 throw 'Invalid URL'
114
115 However, if pulverize is run with both jquery and underscore, then the following would
116 be generated:
117
118 getUrl = (url) ->
119 return url if _.isString url
120 return url() if $.isFunction url
121 throw 'Invalid URL'
122
123 The order libraries are specified in the config file or on the command line will create
124 the precendence for which function is used. Because jquery is specified first, the
125 function `$.isFunction` is retained instead of `_.isFunction`.
126
127 Note that we have actually removed code from the output. If no default functions are
128 needed, then the entire PULVERIZE object is never included.
129
130 Will probably need to use uglify's AST to accomplish much of this.
131
132 ## Concerns
133
134 The method signature of helper functions in different micro frameworks might vary. Need
135 to figure out a way to map from the default method signature to the method signature of
136 each micro-framework.
137
138 In other words, if framework A has `doSomething(obj,message)` and framework B has
139 `somethingTodo(message,obj)`, but they both accomplish the same thing, then we need a
140 way to map method signatures properly.
141
142 ## Uses
143
144 I see this being helpful for I18N and L10N. For instance, the jQuery UI DatePicker has
145 functions to `formatDate()` and `parseDate`. There are other frameworks that have
146 similar functions. By using `pulverizer`, all of the code in your project to parse
147 dates could be excluded if the user is using jquery-ui, date.js, or such.
148
149 ## Would be nice
150
151 Doing some kind of "feature detection" on the browser would be cool, but I'm not sure
152 how practical it would be. This would probably involve some sort of small "loader"
153 library that would detect what libraries were available on the client. It would then
154 request the appropriate version of your application based on this information. Again,
155 this needs to be thought through more, as the user could just make sure to put the
156 right version in the `<script>` tag.
157
Something went wrong with that request. Please try again.