docs: update README

README.md

@@ -1,15 +1,27 @@
 # st-randomness-helpers
 
-To install dependencies:
+st-randomness-helpers is a extension for [SillyTavern](https://sillytavern.app/).
 
-```bash
-bun install
-```
+# Features
 
-To run:
+## WordLists
 
-```bash
-bun run index.ts
-```
+WordList are plaintext files containing one or more words per line. The name of the file is the name of the WordList.
 
-This project was created using `bun init` in bun v1.2.17. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+## Macros
+
+Register [macros](https://docs.sillytavern.app/usage/core-concepts/macros/) that are usually replaced with a value at save time.
+
+## Placeholders
+
+Placeholders are strings that are replaced with a value at generation time.
+
+## Services
+
+### RandomWord
+
+Get a random word from a WordList. can be used as a Macro or a Placeholder. Macro format: `{{RandomWord::WordListName}}`. Placeholder format: `%%RandomWord:WordListName%%`.
+
+### Shuffle
+
+Shuffle a list of values. can be used as Placeholder only. Placeholder format: `%%Shuffle::Value1::Value2::Value3;;separator%%`. Example: `%%Shuffle::Value1::Value2::Value3;;, %%` will return `Value3, Value1, Value2`.

src/placeholders/initializePlaceholders.ts

@@ -1,7 +1,9 @@
 import { setupRandomWordPlaceholders } from '@/services/randomWord'
+import { setupShufflePlaceholders } from '@/services/shuffle'
 
 const initializePlaceholders = () => {
   setupRandomWordPlaceholders()
+  setupShufflePlaceholders()
 }
 
 export default initializePlaceholders

src/services/shuffle.ts

@@ -0,0 +1,31 @@
+import type { generationData } from '@/types/SillyTavern'
+
+const fishersYatesShuffle = <Type>(arr: Type[]): Type[] => {
+  const shuffled = [...arr]
+  for (let index = shuffled.length - 1; index > 0; index--) {
+    const secondIndex = Math.floor(Math.random() * (index + 1))
+    // @ts-ignore We know index and secondIndex are valid
+    ;[shuffled[index], shuffled[secondIndex]] = [
+      shuffled[secondIndex],
+      shuffled[index]
+    ]
+  }
+  return shuffled
+}
+
+const shufflePlaceholderRegex = /%%shuffle::([\w\W]*?)(;;[\w\W]*?)?%%/g
+
+export const setupShufflePlaceholders = () => {
+  const { eventTypes, eventSource } = SillyTavern.getContext()
+  eventSource.on(eventTypes.GENERATE_AFTER_DATA, (chat: generationData) => {
+    chat.prompt = chat.prompt.replaceAll(
+      shufflePlaceholderRegex,
+      (_, toBeshuffleed: string, separator?: string) => {
+        const options = toBeshuffleed.split('::')
+        return fishersYatesShuffle(options).join(
+          separator !== undefined ? separator.substring(2) : ''
+        )
+      }
+    )
+  })
+}