So you've decided you want to give ansuzjs a try? I'm flattered. Really, I am.
The purpose of this document is to prepare you for the road ahead. There's a lot of functionality packed into this little library, but that doesn't necessarily mean it will be easy to use.
My aim in producing this software was to make it easier to define extremely complex functions with very little code. While I think I've succeeded in creating something worthwhile, you will still need to understand how these functions behave in order to use them.
Before exploring the individual functions, I'll provide a bit of an overview:
As I write this, wikipedia defines metaprogramming as:
...the writing of computer programs with the ability to treat programs as their data.
Javascript has two notable features which make it quite suitable as a metaprogramming language:
- Functions are first class objects.
- Functions have a
toStringmethod, which allows us to inspect the source of any function at runtime.
ansuzjs leverages the first characteristic to provide high level functions which makes function creation easier. In particular, there are functions for:
- currying
- lazy evaluation
- backtracking (in progress)
It leverages the second property to provide two functions which will allow you to reshape the library so as to only include the functions you are using:
ansuz.depsaccepts a list of functions. It inspects the functions in your running library (as strings), and searches for annotations detailing that function's dependencies. It recurses through the resulting dependency tree, and returns an array of unique function names (the dependencies of your functions).ansuz.compileaccepts a list of functions, and returns a string which can be written to file and used independently of the original ansuz.js source.
I decided to implement these functions because as much as I hate software bloat, the software ultimately became easier to manage by throwing it all in together. deps and compile allow me to work on one file, and programmatically extract only the functions I need for any given task. This isn't really a concern for serverside code, but since ansuzjs is an isomorphic library, I wanted to make it easy to ship subsets of the library for use in clientside code.
ansuzjs is 100% vanilla. There are no external dependencies, and I intend to keep it that way. If you want to hack on ansuzjs, I recommend using the test cases I've included. They're written using the buster framework, which you can install manually using:
npm install busterIf you add or change functions, remember that you will need to annotate them with their dependencies in order to use ansuz.deps. Do so by including a comment at the top of the function:
var foo=function(){
// the annotation is a single line comment containing an array
// leave no spaces between the double slash and the square brace
// do not enclose the function name single or double quotes.
//[bar,baz]
// additional dependency annotations beyond the first will be ignored
//[this,has,no,effect]
return bar(baz());
}Accepts an array and an index, _cut_s the array like a deck of cards, return both halves, concatenated in reverse order.
$.cut([0,1,2,3,4],2);
// [2,3,4,0,1]Takes an array and returns a generator which cycles through the elements of the array when called. Infinite, since it never exceeds the bounds of the array.
var g=$.cycle([1,3,3,7]);
g();
g();
g();
g();
g();
g();
// 1,3,3,7,1,3ansuz.deps(dependencyArray[,libraryName])
deps takes an array of dependencies, and an object as a second optional argument (defaults to using 'ansuz'). It accesses the named functions within the provided object, and inspects them for ansuz-style dependency annotations™.
It returns a list of unique dependencies which does not include the initial functions whose dependencies you were interested in. The returned value is the name of the function, not the function itself.
$.deps(['weightedArray'])
// ['flatten','nullArray','key']accepts an integer 'r', and returns an integer between zero and r -1.
$.die(3)
// equivalent to $.choose([0,1,2])Accepts an array and returns a generator which, when called, produces the next element in the array, until finally returning undefined.
var g=$.either([5,10,4]);
g(); // 5
g(); // 10
g(); // 4
g(); // undefinedAccepts an array or a proper object, and a second argument.
Returns true if the element is a member of the array or object, and false otherwise.
$.exists([0,1,2,3,4],3); // true
$.exists({x:5,y:7},'y'); // true
$.exists([1,2,3],'pewpew'); // false
$.exists({x:5,b:3},3); // false! it checks by key, not value