rantjs 1.0.9 → 2.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2014-2026 Sven Anders Robbestad
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,158 +1,144 @@
 # Rantjs
 
-Rantjs is a procedural text generator. The goal is to augment human creativity with the boundless potential of randomness. Inspired by [Rant][1].
+Procedural text for JavaScript. Write a pattern, get a sentence.
 
-<img src="http://res.cloudinary.com/sven-anders-robbestad/image/upload/c_scale,w_350/v1418975366/rantjs_0.8.4.png">
+Inspired by [Rant](https://github.com/TheBerkin/rant3). This is the Rantjs dialect (`<noun>`, `[rep:3]{...}`), not a Rant 4 VM.
 
-The project is available via npm (do _npm install rantjs_). 
+```js
+import { rant } from "rantjs";
 
+const sentence = rant(
+  "<firstname male> likes to <verb-transitive> <noun.plural> with <pron poss male> pet <noun-animal> on <timenoun dayofweek plural>.",
+);
 
-## Demo and more information
-
-Interactive demo available [here][5]
-
-Click [here][4] for a writeup on my blog
-
-
-## Usage
-
-    # When using the npm module
-
-    var rant = require("rantjs");
-    var sentence=rant('<firstname male> likes to <verb-transitive> <noun.plural> with <pron poss male> pet <noun-animal> on <timenoun dayofweek plural>.');
-
-    console.log(sentence); // 'Sean likes to chop parrots with his pet cat on Saturdays.'
-
-For implementation details, please visit the [npmjs page][3]
-
-    # When using the CDN version at https://cdnjs.com/libraries/rantjs
-
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/rantjs/1.0.6/rant.min.js">
-    <script type="text/javascript">
-        var sentence=rant('<firstname male> likes to <verb-transitive> <noun.plural> with <pron poss male> pet <noun-animal> on <timenoun dayofweek plural>.');
-        console.log(sentence); // 'Sean likes to chop parrots with his pet cat on Saturdays.'
-        document.querySelector('#app').textContent=sentence;
-    </script>
-
-## Install
+console.log(sentence);
+// 'Sean likes to chop parrots with his pet cat on Saturdays.'
+```
 
 ```bash
-git clone https://github.com/svenanders/rantjs && cd rantjs
-npm i
-gulp serve
+npm install rantjs
+npx rantjs --seed 42 '<firstname male> found [a] <noun-animal>.'
 ```
-Then open http://localhost:8000
-
-
-## Development Plan
-
-Easy way to choose alternative dictionaries
-
-Indefinite article (a/an) automation
-
-Overwriting (targets)
 
-~~Capitalisation~~
+## Patterns
 
-~~Looping (repeaters)~~
+**Queries** pull a random dictionary entry. Filters and inflections can be separated with a space, dash, or dot:
 
-Conditionals
-
-## Contributions
-
-Contributions are welcome. Feel free to submit an issue/pull request. The following areas are
-of particular interest:
+```
+<firstname male>
+<noun-animal plural>
+<verb.ed>
+<pron poss male>
+<yn yes>
+```
 
-Documentation (wiki/code)
+**Blocks** choose an alternative. A block with no repeater runs once. `|` splits options. Nested braces work.
 
-Fixing bugs
+```
+{heads|tails}
+{Example text}
+[rep:3][sep:\s]{click|clack}
+```
 
-Optimization
+**Tags**
 
-Functions in the development plan
+| Tag | Effect |
+| --- | --- |
+| `[case:none\|default\|first\|word\|title\|upper\|lower\|sentence]` | Casing for the finished string |
+| `[rep:n]` | Repeat the next block `n` times |
+| `[sep:\s\|\n\|literal]` | Join those repetitions |
+| `[a]` | Insert *a* or *an* before the next word |
+| `[if:name]{then}{else}` | Branch on whether carrier `name` is set |
 
-New language features
+**Carriers** remember a result so a character stays the same person:
 
-Testing. Currently, this is the result of the coverage report:
+```
+<firstname male :: hero> saw <::hero> in the <place>.
+```
 
-    Statements   : 96.44% ( 461/478 )
-    Branches     : 67.65% ( 46/68 )
-    Functions    : 100% ( 18/18 )
-    Lines        : 97.24% ( 458/471 )
+**Escapes:** `\C` is a random A–Z letter.
 
-Ideally, it should be 100% on everything
+NSFW entries are omitted unless the query asks (`<noun nsfw>`) or you pass `{ nsfw: true }`.
 
-## New in version 1.0.0
+## API
 
-  Added option for custom dictionaries. Note that this replaces the built-in dictionary.
-  
-    var yourCustomDic = {}
-    ...
-    rant('your text', yourCustomDic);
-     
-A sample dictionary file can be found in the ./src folder. Also take a look at the built-in english dicionary in the same folder for reference.
+```ts
+import { rant, createRant, enUS } from "rantjs";
 
-## New in version 0.9.x
+rant(pattern);
+rant(pattern, { seed: 42 });
+rant(pattern, { seed: "chapter-1", nsfw: false, dictionary: enUS });
+rant(pattern, customDictionary); // 1.x-compatible second argument
 
-  0.9.7 - Added nonsense verbs from Rantionary
-  
-  0.9.5 - Added verbs for success and defeat
-  
-  0.9.4 - Added Death (<verb death>)
-  
-  0.9.3 - Added climb (<verb climb up|down>)
+const r = createRant({ seed: 42 });
+r.run(pattern);
+r.run(pattern, { seed: 99 });
+```
 
-## New in version 0.9.1
+Custom dictionary shape:
+
+```ts
+const pets = {
+  tables: {
+    pet: {
+      name: "pet",
+      subs: ["default", "plural"],
+      entries: [{ forms: ["capybara", "capybaras"], classes: ["animal"] }],
+    },
+  },
+};
+```
 
-  Rewrote Rantjs for CommonJS. 
-  
-  Removed several gulp tasks (concat, minify)
- 
-  Refactored the tests
- 
-  Renamed the app internally
- 
-  New usage syntax (not compatible with 0.8.x)
- 
-  You can now call Rantjs directly from require:
-  
-    var sentence=require("rantjs")("<firstname male> likes to <verb-transitive> 
-    <noun.plural> with <pron poss male> pet <noun-animal> on <timenoun dayofweek plural>.");
- 
-  Added randomization:
-  
-    require("rantjs")("A random string: [rep:8][sep:\N]{\C}");
-    //A random string: XUACJGOGN
+## Browser
 
-## New in version 0.8.6
+ESM:
 
-  Added support for [rep:x]
+```html
+<script type="module">
+  import { rant } from "https://cdn.jsdelivr.net/npm/rantjs@2.0.0/+esm";
+  document.body.textContent = rant("<greet> <firstname>.");
+</script>
+```
 
-  Usage:
+Script tag (cdnjs / jsDelivr):
 
-    [case:title][sep:\n][rep:3]{I like <noun animal plural> but not <noun animal plural>}
+```html
+<script src="https://cdn.jsdelivr.net/npm/rantjs@2.0.0/dist/rant.min.js"></script>
+<script>
+  document.body.textContent = rant("<greet> <firstname>.");
+</script>
+```
 
-    // I Like Ogres but not Turtles
-    // I Like Bulls but not Horses
-    // I Like Poodles but not Owls
+The IIFE build assigns `rant` on `globalThis`. The Node/ESM build does not touch `window`.
 
-   Note: [sep:\n] dictates newlines. Alternatively, you can specify \s for space.
+## CLI
 
-## New in version 0.8.5
+```bash
+rantjs '<pattern>'
+rantjs --seed 7 -f story.rant
+rantjs --nsfw '<adj nsfw> <noun>'
+```
 
-  Added support for [case]-tag.
+## Development
 
-  Usage:
+```bash
+npm install
+npm test
+npm run demo          # playground at http://localhost:5173
+```
 
-    [case:upper]<firstname male>
+Dictionary sources live in `vocab/` (Rantionary plus a few custom tables). `npm run build:dict` compiles them into `src/dictionaries/en-US.ts`.
 
-  Variants:
+The playground is `npm run demo`. After GitHub Pages is enabled it will live at `https://robbestad.github.io/Rantjs/`.
 
-    [case:none|default|word|upper|lower|case|sentence]
+## Migrating from 1.x
 
+- Node 18+.
+- `import { rant } from "rantjs"` (or `require("rantjs").rant`).
+- `window.rant` is only set by the IIFE browser file, not by `require("rantjs")`.
+- `String.prototype` is no longer patched.
+- Some dictionary words changed; the query syntax did not.
 
+## License
 
-[1]: https://github.com/TheBerkin/Rant
-[3]: https://www.npmjs.com/package/rantjs
-[4]: http://www.robbestad.com/blog/procedurally-generated-text-with-rantjs
-[5]: http://rantjs.surge.sh/
+ISC