document limitations jcubic#182

Author: jcubic

README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/badge/npm-1.0.0%E2%80%93beta.14-blue.svg)](https://www.npmjs.com/package/@jcubic/lips)
 ![1.0.0 Complete](https://img.shields.io/github/milestones/progress-percent/jcubic/lips/1?label=1.0.0%20Complete)
-[![travis](https://travis-ci.com/jcubic/lips.svg?branch=devel&a8c8b394c40212aa9829e7e03f3e4750cf110813)](https://travis-ci.com/jcubic/lips)
+[![travis](https://travis-ci.com/jcubic/lips.svg?branch=devel&2b11dbcbf8069977208a6ff4a0757fe77b592f5d)](https://travis-ci.com/jcubic/lips)
 [![Coverage Status](https://coveralls.io/repos/github/jcubic/lips/badge.svg?branch=devel&bbffc3b45ac48fb918c597ba56678937)](https://coveralls.io/github/jcubic/lips?branch=devel)
 [![Join Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jcubic/lips)
 [![GitHub license](https://img.shields.io/github/license/jcubic/lips.svg)](https://github.com/jcubic/lips/blob/master/LICENSE)
@@ -181,6 +181,27 @@ chmod a+x foo.scm
 
 Executables also return a S-Expression according to SRFI-176 use `lips --version` or `lips -V`.
 
+## Limitations
+Because LIPS is tree walking interpreter sometimes it may be slow. Especially if you want to
+process long arrays and use callback function. If the array is quite large each pice of code
+inside the callback may slow down the processing. For example see:
+
+script [reference.scm](https://github.com/jcubic/lips/blob/devel/scripts/reference.scm)
+
+That generates reference documentation for all builtin functions and macros.
+The slow part is `(names.sort name-compare)` (`Array::sort`) that take quite time to calculate,
+because the array with functions and macros is quite large. If you came into performance issue,
+you can write the part of the code in JavaScript. If you want to do this in LIPS Scheme you can use
+something like this:
+
+```scheme
+(let ((fn (self.eval "(function(a, b) {
+                         /* any complex code in JS */
+                         return a.localeCompare(b);
+                      })")))
+   (arr.sort fn))
+```
+
 ## Links
 * [Gitter Chat](https://gitter.im/jcubic/lips)
 * [LISP: Scheme in JavaScript Git Repository](https://github.com/jcubic/lips)

templates/README.md

@@ -181,6 +181,27 @@ chmod a+x foo.scm
 
 Executables also return a S-Expression according to SRFI-176 use `lips --version` or `lips -V`.
 
+## Limitations
+Because LIPS is tree walking interpreter sometimes it may be slow. Especially if you want to
+process long arrays and use callback function. If the array is quite large each pice of code
+inside the callback may slow down the processing. For example see:
+
+script [reference.scm](https://github.com/jcubic/lips/blob/{{BRANCH}}/scripts/reference.scm)
+
+That generates reference documentation for all builtin functions and macros.
+The slow part is `(names.sort name-compare)` (`Array::sort`) that take quite time to calculate,
+because the array with functions and macros is quite large. If you came into performance issue,
+you can write the part of the code in JavaScript. If you want to do this in LIPS Scheme you can use
+something like this:
+
+```scheme
+(let ((fn (self.eval "(function(a, b) {
+                         /* any complex code in JS */
+                         return a.localeCompare(b);
+                      })")))
+   (arr.sort fn))
+```
+
 ## Links
 * [Gitter Chat](https://gitter.im/jcubic/lips)
 * [LISP: Scheme in JavaScript Git Repository](https://github.com/jcubic/lips)