From 09dd2dae1a751a7de0ebd48fc73595efdfca2581 Mon Sep 17 00:00:00 2001 From: Marcus Stade Date: Mon, 28 Sep 2015 11:20:06 +0200 Subject: [PATCH 1/4] Starting to improve documentation --- GLOSSARY.md | 11 +++++++++++ README.md | 3 +++ SUMMARY.md | 8 ++++++++ man/and.md | 3 +++ man/apply.md | 7 +++++++ man/assert.md | 3 +++ man/call.md | 3 +++ man/compose.md | 3 +++ 8 files changed, 41 insertions(+) create mode 100644 GLOSSARY.md create mode 100644 SUMMARY.md create mode 100644 man/and.md create mode 100644 man/apply.md create mode 100644 man/assert.md create mode 100644 man/call.md create mode 100644 man/compose.md 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/README.md b/README.md index d611369..eda4a29 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ ![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! 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 From a252897a9c3441ca9e5a4962f535397026467b63 Mon Sep 17 00:00:00 2001 From: Marcus Stade Date: Mon, 28 Sep 2015 11:20:48 +0200 Subject: [PATCH 2/4] Added test to check for missing documentation --- test/man.js | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 test/man.js 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 From e4f8718b9abca1f520e0a009d6f81d69f6fed08d Mon Sep 17 00:00:00 2001 From: Marcus Stade Date: Tue, 13 Oct 2015 20:22:50 +0200 Subject: [PATCH 3/4] Update readme --- README.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index eda4a29..f937465 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,37 @@ 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. -[1]: test +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 +``` + +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 ------ From 76e3a0e1b6fab93027c835146fbe158e86bcfb44 Mon Sep 17 00:00:00 2001 From: Marcus Stade Date: Tue, 13 Oct 2015 20:43:17 +0200 Subject: [PATCH 4/4] Add makefile to begin move to a more structured project --- .gitignore | 4 ++-- .travis.yml | 9 ++++++--- Makefile | 36 ++++++++++++++++++++++++++++++++++++ README.md | 4 ++++ package.json | 17 ++++++++--------- 5 files changed, 56 insertions(+), 14 deletions(-) create mode 100644 Makefile 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/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 f937465..0e2e247 100644 --- a/README.md +++ b/README.md @@ -42,3 +42,7 @@ 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/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",