diff --git a/.gitignore b/.gitignore index 26846b6..e67145d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,3 @@ node_modules -coverage -npm-debug.log \ No newline at end of file +npm-debug.log +.nyc_output \ No newline at end of file diff --git a/.travis.yml b/.travis.yml index 2104b26..0bb834c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,6 +1,9 @@ language: node_js node_js: - - "0.11" - - "0.10" + - "node" + - "iojs" + - "4" -after_script: NODE_ENV=test istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage \ No newline at end of file +install: make clean build +script: make test +after_success: make coverage \ No newline at end of file diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..214e8cd --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,11 @@ +# Logically true + +A value is said to be logically true, if it's not strictly equal to `false`, `null`, or `undefined`. + +# Logically false + +A value is said to be logically false, if it's stricly equal to `false`, `null`, or `undefined`. + +# Variadic + +A variadic function takes a variable number of arguments. It may or may not have required arguments, which will precede a variable length list of arguments. \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..582a40e --- /dev/null +++ b/Makefile @@ -0,0 +1,36 @@ +PATH := node_modules/.bin:$(PATH) +SHELL := /bin/bash + +SRC = $(wildcard src/*.js) +LIB = $(SRC:src/%.js=lib/%.js) +TST = $(wildcard test/*.js) $(wildcard test/**/*.js) +NPM = @npm install --local > /dev/null && touch node_modules + +v ?= patch + +node_modules: package.json + $(NPM) +node_modules/%: + $(NPM) + +test: node_modules + @mocha $(TST) + +.nyc_output: node_modules + @nyc $(MAKE) test + +coverage: .nyc_output + @nyc report --reporter=text-lcov | coveralls + +dev: node_modules + @nodemon -q -x "(clear; nyc $(MAKE) test && nyc report) || true" + +release: clean node_modules test + @npm version $(v) + @npm publish + @git push --follow-tags + +clean: + @rm -rf $$(cat .gitignore) + +.PHONY: test coverage dev release clean \ No newline at end of file diff --git a/README.md b/README.md index d611369..0e2e247 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,48 @@ ![Funkis](https://raw.githubusercontent.com/mstade/funkis/master/logo.png) +Funkis +====== + This library aims to be a fully fledged environment for functional programming in JavaScript. It provides a number of functions common to functional programming, ranging from low-level constructs to high-level abstractions. -Funkis is work in progress, and APIs change quickly while the library is still being developed. Please don't use it for anything, or at least do so at your own risk. Beyond the [tests][1] there is no documentation available – good luck! +Funkis is work in progress, and APIs change quickly while the library is still being developed. Please don't use it for anything, or at least do so at your own risk. + +Usage +----- + +Get funkis from npm: + +```bash +npm install --save funkis +``` + +Once installed as a dependency, it is possible to use funkis through the kitchen sink object that holds a reference to all funkis functions: + +```javascript +var f = require('funkis') + +f.and(1, 2, 3) // 3 +``` -[1]: test +Or, if you'd rather, you can depend on the functions directly: + +```javascript +var and = require('funkis/lib/and') + +and(1, 2, 3) // 3 +``` + +Further documentation is available in the [online manual], or the [man] folder. + +[man]: man +[online manual]: http://madebystade.com/funkis/ Status ------ [![Build Status](http://img.shields.io/travis/mstade/funkis.svg?style=flat-square)](https://travis-ci.org/mstade/funkis) [![Coverage Status](http://img.shields.io/coveralls/mstade/funkis.svg?style=flat-square)](https://coveralls.io/r/mstade/funkis?branch=master) + +--- + +[LICENSE](LICENSE) \ No newline at end of file diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..5d35fd6 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,8 @@ +# Summary + +- API reference + - [and](man/and.md) + - [apply](man/apply.md) + - [assert](man/assert.md) + - [call](man/call.md) + - [compose](man/compose.md) \ No newline at end of file diff --git a/man/and.md b/man/and.md new file mode 100644 index 0000000..7792aa3 --- /dev/null +++ b/man/and.md @@ -0,0 +1,3 @@ +# and + +If every given value is logically true, `and` returns the last value; otherwise it returns the first value that was logically false. If a given value is a function, the function will be called with no arguments, and the return value will be used for the test. \ No newline at end of file diff --git a/man/apply.md b/man/apply.md new file mode 100644 index 0000000..1193495 --- /dev/null +++ b/man/apply.md @@ -0,0 +1,7 @@ +# apply + +When given a single argument `fn`, `apply` will call `fn` with no arguments and return its value. + +When given the argument `fn` and an array `args`, then the values in `args` will be passed to `fn` when it is called. + +The value of `this` will be bound to whatever the value of `this` is when `apply` is called. Thus, `apply.bind(obj)(fn)` would bind `fn` to `obj`, unless `fn` has already been bound. \ No newline at end of file diff --git a/man/assert.md b/man/assert.md new file mode 100644 index 0000000..09ec60b --- /dev/null +++ b/man/assert.md @@ -0,0 +1,3 @@ +# assert + +If the first argument `x` passed to `assert` is logically true, the value of `x` is returned. If however, the value of `x` is logically false then `assert` will throw an error. If provided with a second parameter `message`, the thrown error will carry that message. If `message` is an actual `Error` instance, it will be thrown without modification. \ No newline at end of file diff --git a/man/call.md b/man/call.md new file mode 100644 index 0000000..a1977e8 --- /dev/null +++ b/man/call.md @@ -0,0 +1,3 @@ +# call + +The same as [apply](./apply.md), with the notable difference that `call` is variadic. Otherwise the exact same functionality. \ No newline at end of file diff --git a/man/compose.md b/man/compose.md new file mode 100644 index 0000000..573b047 --- /dev/null +++ b/man/compose.md @@ -0,0 +1,3 @@ +# compose + +Returns a composition `fn` of the given functions; that is, a new function which composes all given functions. When called with any number of arguments, `fn` will apply those arguments to the rightmost function given in the composition, whose result will then be applied to the next rightmost function. This process repeats until all functions in the composition have been applied. \ No newline at end of file diff --git a/package.json b/package.json index ced4c7b..b5ebaa1 100644 --- a/package.json +++ b/package.json @@ -3,18 +3,17 @@ "version": "0.2.0", "description": "Functional programming in JavaScript.", "main": "index.js", - "scripts": { - "test": "istanbul test ./node_modules/mocha/bin/_mocha --report html -- -R spec" - }, - "author": "Marcus Stade", + "author": "Marcus Stade (http://madebystade.se)", "license": "MIT", "devDependencies": { - "coveralls": "~2.8.0", - "expect.js": "^0.3.1", - "istanbul": "~0.2.4", - "mocha": "~1.17.1", + "coveralls": "2.8.0", + "expect.js": "0.3.1", + "gitbook-cli": "0.3.6", + "mocha": "1.17.1", "mocha-lcov-reporter": "0.0.1", - "must": "git://github.com/mstade/js-must#throw-error-instance" + "must": "git://github.com/mstade/js-must#throw-error-instance", + "nodemon": "1.7.1", + "nyc": "3.2.2" }, "repository": { "type": "git", diff --git a/test/man.js b/test/man.js new file mode 100644 index 0000000..0624666 --- /dev/null +++ b/test/man.js @@ -0,0 +1,21 @@ +const expect = require('must') + , each = require('../lib/each') + , path = require('path') + , fs = require('fs') + , $ = require('../lib/partial') + +describe('documentation', function() { + it('should exist for all functions', function() { + var names = fs.readdirSync(path.join(__dirname, '../lib')).map(function(file) { + return path.basename(file, '.js') + }) + + each(names, function(name) { + try { + fs.accessSync(__dirname + '/../man/' + name + '.md') + } catch (e) { + throw new Error('No documentation for function `' + name + '` found!') + } + }) + }) +}) \ No newline at end of file