intertext-splitlines - npm Package Compare versions

Comparing version 1.0.0 to 1.1.0

lib/main.js

@@ -35,2 +35,5 @@ (function() {
         return this.isa_optional.boolean(x.decode);
+      },
+      'x.?skip_empty_last is a boolean': function(x) {
+        return this.isa_optional.boolean(x.skip_empty_last);
       }
@@ -43,3 +46,4 @@ }
     splitter: '\n',
-    decode: true
+    decode: true,
+    skip_empty_last: true
   };
@@ -98,4 +102,8 @@
   this.flush = function*(me) {
+    var line;
     if (me.collector != null) {
-      yield decode(me, me.collector);
+      line = decode(me, me.collector);
+      if (!(me.skip_empty_last && line === '')) {
+        yield line;
+      }
       me.collector = null;
@@ -106,4 +114,40 @@ }
 
+  //-----------------------------------------------------------------------------------------------------------
+  this.splitlines = function(settings, ...buffers) {
+    var R, buffer, ctx, i, len, line, ref, ref1, type;
+    buffers = buffers.flat(2e308);
+    switch (type = type_of(settings)) {
+      case 'object':
+      case 'null':
+        null;
+        break;
+      case 'buffer':
+        buffers.unshift(settings);
+        settings = null;
+        break;
+      case 'list':
+        buffers.splice(0, 0, ...(settings.flat(2e308)));
+        settings = null;
+        break;
+      default:
+        throw new Error(`^splitlines@26258^ expected null, an object, a buffer or a list, got a ${type}`);
+    }
+    ctx = this.new_context(settings);
+    R = [];
+    for (i = 0, len = buffers.length; i < len; i++) {
+      buffer = buffers[i];
+      ref = this.walk_lines(ctx, buffer);
+      for (line of ref) {
+        R.push(line);
+      }
+    }
+    ref1 = this.flush(ctx);
+    for (line of ref1) {
+      R.push(line);
+    }
+    return R;
+  };
+
 }).call(this);
 
 //# sourceMappingURL=main.js.map

package.json

 {
   "name": "intertext-splitlines",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "split streaming buffers into neat, decoded lines of text",
@@ -5,0 +5,0 @@ "main": "lib/main.js",

README.md

@@ -10,2 +10,5 @@
 - [How to Use It](#how-to-use-it)
+  - [One-Off Call](#one-off-call)
+  - [Iterators](#iterators)
+  - [Settings](#settings)
 - [Revisions](#revisions)
@@ -21,5 +24,47 @@
 
-* import module as `SL = require 'intertext-splitlines'`
-* create context object as `ctx = SL.new_context settings`
-* where `settings` is an optional object with settings, see below
+### One-Off Call
+
+In case you have one or more buffers with textual content, the simplest way to use InterText SplitLines
+is to use the `splitlines()` method which will return a list of strings, each representing one line. To
+
+
+```coffee
+# For demonstration, let's assemble a number of buffers with lines
+# randomly spread all over the place:
+buffers = [
+  "helo"
+  " there!\nHere "
+  "come\na few lines\n"
+  "of text that are\nquite unevenly "
+  "spread over several\n"
+  "buffers.", ]
+buffers = ( Buffer.from d for d in buffers )
+
+
+# Now we can
+SL    = require 'intertext-splitlines'
+lines = SL.splitlines buffers
+# lines = SL.splitlines buffers... # can call with list or spread out, as seen fit
+# lines = SL.splitlines buffer_1, buffer_2, buffer_3
+
+# lines now contains:
+
+[ 'helo there!',
+  'Here come',
+  'a few lines',
+  'of text that are',
+  'quite unevenly spread over several',
+  'buffers.', ]
+```
+
+Observe that newline characters will be removed from the output so there's no way to determine whether
+the last line did or did not end with a newline; this should be the desired result most of the time. In
+the event that a trailing newline should be detectable, pass in an explicit setting:
+
+```coffee
+lines = SL.splitlines { skip_empty_last: false, }, buffers
+```
+
+### Iterators
+
 * whenever you receive a buffer from a stream or other source (such as a NodeJS stream's `data` event),
@@ -53,2 +98,11 @@ call `SL.walk_lines ctx, buffer` with that data; this returns an iterator over the decoded complete lines
 
+### Settings
+
+* **`?splitter <nonempty ( text | buffer )> = '\n'`**—the sequence of characters that mark linebreaks
+* **`?decode <boolean> = true`**—whether or not to decode buffers as UTF-8. NOTE to be replaced by
+  `encoding`.
+* **`?skip_empty_last <boolean> = true`**—whether to emit an emtpy string as last item when the source ended
+  in `splitter`.
+
+
 ## Revisions
@@ -58,3 +112,9 @@
 * [X] do not return lists but iterators
-* [X] publish v1.0.0
+* publish v1.0.0
+---------------------------------------------------------------------
+* [X] implement `splitlines()`
+* [X] implement setting `skip_empty_last`
+* publish v1.1.0
+---------------------------------------------------------------------
+* [ ] implement `encoding`
 
@@ -64,4 +124,1 @@
 
-
-
-

No alert changes

Improved metrics

Total package byte prevSize

21256

38.15%

Lines of code

132

48.31%

Number of lines in readme file

120

90.48%

No dependency changes