diff --git a/apps/website/content/docs/plugins/plugin-discord/parsers/embed.mdx b/apps/website/content/docs/plugins/plugin-discord/parsers/embed.mdx index d37bcb69..f6b2a143 100644 --- a/apps/website/content/docs/plugins/plugin-discord/parsers/embed.mdx +++ b/apps/website/content/docs/plugins/plugin-discord/parsers/embed.mdx @@ -1,3 +1,115 @@ --- title: EmbedParser --- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tabs } from 'fumadocs-ui/components/tabs'; + +The embed tag creates Discord embeds that can be sent along with messages. +There are two ways to use the embed tag: either by using properly formatted embed JSON or by manually inputting the accepted embed properties. + +## Usage + + + ```ts showLineNumbers tab="ESM" + import { Interpreter } from 'tagscript'; + import { EmbedParser } from '@tagscript/plugin-discord'; + const ts = new Interpreter(new EmbedParser()); + ``` + ```js showLineNumbers tab="CommonJs" + const { Interpreter } = require('tagscript'); + const { EmbedParser } = require('@tagscript/plugin-discord'); + const ts = new Interpreter(new EmbedParser()); + ``` + + +## API + +Check [EmbedParser](../../../typedoc-api/@tagscript/plugin-discord/classes/EmbedParser) for the API documentation. + +## For End Users + + +### Syntax + +**Using JSON:** +```yaml +{embed:json} +``` + +**Using properties:** +```yaml +{embed(property):value} +``` + +### Examples + +**JSON Format:** +```yaml +{embed:{"title": "Hello!", "description": "This is a test embed."}} +``` + +```yaml +{embed:{ + "title": "Here's a random duck!", + "image": {"url": "https://random-d.uk/api/randomimg"}, + "color": 15194415 +}} +``` + +**Property Format:** +```yaml +{embed(color):0x37b2cb} +{embed(title):Rules} +{embed(description):Follow these rules to ensure a good experience in our server!} +{embed(field):Rule 1|Respect everyone you speak to.|false} +``` + +```yaml +{embed(author):Author Name} +{embed(thumbnail):https://example.com/image.png} +{embed(footer):Footer text} +{embed(timestamp):true} +``` + +### Available Properties + +- `title` - The embed title +- `description` - The embed description +- `color` - The embed color (hex code or number) +- `author` - The embed author name +- `thumbnail` - URL for the thumbnail image +- `image` - URL for the main image +- `footer` - The footer text +- `timestamp` - Set to `true` to add current timestamp +- `field` - Add a field with format: `name|value|inline` + +### Field Format + +Fields use the format: `{embed(field):name|value|inline}` +- `name` - The field name +- `value` - The field value +- `inline` - `true` or `false` for inline display + +### Notes + +- Multiple embed tags in the same TagScript will merge properties +- Color values can be hex codes (0x37b2cb) or decimal numbers +- JSON format allows for more complex embed structures +- Developers need to construct the embed builder with the parser output + + + +## Developer Example + +```ts showLineNumbers +import { Interpreter } from 'tagscript'; +import { EmbedParser } from '@tagscript/plugin-discord'; +import { EmbedBuilder } from 'discord.js'; + +const ts = new Interpreter(new EmbedParser()); +const result = await ts.run('{embed:{"title": "Hello!", "description": "This is a test embed."}}'); + +// You might need to modify the embed object before passing to EmbedBuilder +const embed = new EmbedBuilder(result.actions.embed); +``` diff --git a/apps/website/content/docs/plugins/plugin-discord/parsers/index.mdx b/apps/website/content/docs/plugins/plugin-discord/parsers/index.mdx index 0287ae00..08128bb2 100644 --- a/apps/website/content/docs/plugins/plugin-discord/parsers/index.mdx +++ b/apps/website/content/docs/plugins/plugin-discord/parsers/index.mdx @@ -7,4 +7,4 @@ description: Tagscript parsers are used to parse a tag and return a value based Discord Plugin provides the following parsers which you can use to parse tags. -- [EmbedParser](/plugins/plugin-discord/parsers) +- [EmbedParser](/plugins/plugin-discord/parsers/embed) diff --git a/apps/website/content/docs/tagscript/parsers/fifty-fifty.mdx b/apps/website/content/docs/tagscript/parsers/fifty-fifty.mdx new file mode 100644 index 00000000..e64ed130 --- /dev/null +++ b/apps/website/content/docs/tagscript/parsers/fifty-fifty.mdx @@ -0,0 +1,62 @@ +--- +title: FiftyFiftyParser +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tabs } from 'fumadocs-ui/components/tabs'; + +The fifty-fifty tag has a 50% chance of returning the payload, and a 50% chance of returning an empty string. +This parser is useful for creating random events or decisions with equal probability. + +## Usage + + + ```ts showLineNumbers tab="ESM" + import { Interpreter, FiftyFiftyParser } from 'tagscript'; + const ts = new Interpreter(new FiftyFiftyParser()); + ``` + ```js showLineNumbers tab="CommonJs" + const { Interpreter, FiftyFiftyParser } = require('tagscript'); + const ts = new Interpreter(new FiftyFiftyParser()); + ``` + + +## API + +Check [FiftyFiftyParser](../../typedoc-api/tagscript/classes/FiftyFiftyParser) for the API documentation. + +## For End Users + + +### Syntax +```yaml +{5050:message} +{50:message} +{?:message} +``` + +### Examples + +```yaml +{5050:You got lucky!} +# 50% chance: You got lucky! +# 50% chance: (empty string) +``` + +```yaml +I pick {if({5050:.}!=):heads|tails} +# 50% chance: I pick heads +# 50% chance: I pick tails +``` + +```yaml +{?:Rare event occurred!} Welcome to the server! +# 50% chance: Rare event occurred! Welcome to the server! +# 50% chance: Welcome to the server! +``` + +### Aliases + +`5050`, `50`, `?` + + \ No newline at end of file diff --git a/apps/website/content/docs/tagscript/parsers/index.mdx b/apps/website/content/docs/tagscript/parsers/index.mdx index f7e0ed91..520f80a5 100644 --- a/apps/website/content/docs/tagscript/parsers/index.mdx +++ b/apps/website/content/docs/tagscript/parsers/index.mdx @@ -28,9 +28,15 @@ Parsers are used to parse a tag and return a value based on the tag. You can use Following is the list of builtin parsers: - [BreakParser](/tagscript/parsers/break) +- [FiftyFiftyParser](/tagscript/parsers/fifty-fifty) - [IfStatementParser](/tagscript/parsers/if-statement) -- [UnionStatementParser](/tagscript/parsers/union-statement) - [IntersectionStatementParser](/tagscript/parsers/intersection-statement) +- [RandomParser](/tagscript/parsers/random) +- [RangeParser](/tagscript/parsers/range) +- [ReplaceParser](/tagscript/parsers/replace) +- [SliceParser](/tagscript/parsers/slice) +- [StopParser](/tagscript/parsers/stop) +- [UnionStatementParser](/tagscript/parsers/union-statement) ## Custom Parser diff --git a/apps/website/content/docs/tagscript/parsers/meta.json b/apps/website/content/docs/tagscript/parsers/meta.json index 2c6ce156..ec1d9556 100644 --- a/apps/website/content/docs/tagscript/parsers/meta.json +++ b/apps/website/content/docs/tagscript/parsers/meta.json @@ -1,6 +1,12 @@ { "break": "Break Parser", + "fifty-fifty": "FiftyFifty Parser", "if-statement": "If Statement Parser", "intersection-statement": "Intersection Statement Parser", + "random": "Random Parser", + "range": "Range Parser", + "replace": "Replace Parser", + "slice": "Slice Parser", + "stop": "Stop Parser", "union-statement": "Union Statement Parser" } diff --git a/apps/website/content/docs/tagscript/parsers/random.mdx b/apps/website/content/docs/tagscript/parsers/random.mdx new file mode 100644 index 00000000..a9b4fa18 --- /dev/null +++ b/apps/website/content/docs/tagscript/parsers/random.mdx @@ -0,0 +1,65 @@ +--- +title: RandomParser +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tabs } from 'fumadocs-ui/components/tabs'; + +The random tag picks a random item from a list of strings, split by either `~` or `,`. +This parser is useful for selecting random messages, responses, or values from a predefined list. + +## Usage + + + ```ts showLineNumbers tab="ESM" + import { Interpreter, RandomParser } from 'tagscript'; + const ts = new Interpreter(new RandomParser()); + ``` + ```js showLineNumbers tab="CommonJs" + const { Interpreter, RandomParser } = require('tagscript'); + const ts = new Interpreter(new RandomParser()); + ``` + + +## API + +Check [RandomParser](../../typedoc-api/tagscript/classes/RandomParser) for the API documentation. + +## For End Users + + +### Syntax +```yaml +{random:item1,item2,item3} +{random:item1~item2~item3} +``` + +### Examples + +```yaml +{random:foo, bar, baz} +# foo +# bar +# baz +``` + +```yaml +{random:Hello, Hi, Hey} there! +# Hello there! +# Hi there! +# Hey there! +``` + +```yaml +{random:apple~banana~cherry~date} +# apple +# banana +# cherry +# date +``` + +### Aliases + +`rand` + + \ No newline at end of file diff --git a/apps/website/content/docs/tagscript/parsers/range.mdx b/apps/website/content/docs/tagscript/parsers/range.mdx new file mode 100644 index 00000000..a648dee7 --- /dev/null +++ b/apps/website/content/docs/tagscript/parsers/range.mdx @@ -0,0 +1,69 @@ +--- +title: RangeParser +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tabs } from 'fumadocs-ui/components/tabs'; + +The range tag picks a random number from a range of numbers separated by `-` or `,`. +The number range is inclusive, so it can pick the starting/ending number as well. +Using the `rangef` tag will pick a number to the tenth decimal place for floating-point values. + +## Usage + + + ```ts showLineNumbers tab="ESM" + import { Interpreter, RangeParser } from 'tagscript'; + const ts = new Interpreter(new RangeParser()); + ``` + ```js showLineNumbers tab="CommonJs" + const { Interpreter, RangeParser } = require('tagscript'); + const ts = new Interpreter(new RangeParser()); + ``` + + +## API + +Check [RangeParser](../../typedoc-api/tagscript/classes/RangeParser) for the API documentation. + +## For End Users + + +### Syntax +```yaml +{range:min-max} +{range:min,max} +{rangef:min-max} +{rangef:min,max} +``` + +### Examples + +```yaml +{range:1-10} +# 1, 2, 3, 4, 5, 6, 7, 8, 9, or 10 +``` + +```yaml +Your lucky number is {range:10-30}! +# Your lucky number is 14! +# Your lucky number is 25! +``` + +```yaml +{rangef:5.0-7.0} +I am guessing your height is {rangef:5-7}ft. +# I am guessing your height is 5.3ft. +# I am guessing your height is 6.8ft. +``` + +```yaml +Dice roll: {range:1,6} +# Dice roll: 4 +``` + +### Aliases + +`rangef` (for floating-point numbers) + + \ No newline at end of file diff --git a/apps/website/content/docs/tagscript/parsers/replace.mdx b/apps/website/content/docs/tagscript/parsers/replace.mdx new file mode 100644 index 00000000..b286b085 --- /dev/null +++ b/apps/website/content/docs/tagscript/parsers/replace.mdx @@ -0,0 +1,70 @@ +--- +title: ReplaceParser +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tabs } from 'fumadocs-ui/components/tabs'; + +The replace tag replaces specific characters or substrings in a string with new values. +The parameter should be split by a comma (`,`), containing the characters/text to find before the comma and the replacement text after. + +## Usage + + + ```ts showLineNumbers tab="ESM" + import { Interpreter, ReplaceParser } from 'tagscript'; + const ts = new Interpreter(new ReplaceParser()); + ``` + ```js showLineNumbers tab="CommonJs" + const { Interpreter, ReplaceParser } = require('tagscript'); + const ts = new Interpreter(new ReplaceParser()); + ``` + + +## API + +Check [ReplaceParser](../../typedoc-api/tagscript/classes/ReplaceParser) for the API documentation. + +## For End Users + + +### Syntax +```yaml +{replace(find,replacement):text} +``` + +### Examples + +```yaml +{replace(o,i):welcome to the server} +# welcime ti the server +``` + +```yaml +{replace(1,6):1637812} +# 6637862 +``` + +```yaml +{replace(, ):Test} +# T e s t +``` + +```yaml +{replace(old,new):This is the old way of doing things} +# This is the new way of doing things +``` + +```yaml +{replace(@,at):user@example.com} +# useratexample.com +``` + +### Notes + +- All occurrences of the search text will be replaced +- The replacement is case-sensitive +- If you need to include a comma in the search or replacement text, it should be the last comma in the parameter +- Empty strings are valid for both search and replacement values + + \ No newline at end of file diff --git a/apps/website/content/docs/tagscript/parsers/slice.mdx b/apps/website/content/docs/tagscript/parsers/slice.mdx new file mode 100644 index 00000000..62515f6e --- /dev/null +++ b/apps/website/content/docs/tagscript/parsers/slice.mdx @@ -0,0 +1,76 @@ +--- +title: SliceParser +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tabs } from 'fumadocs-ui/components/tabs'; + +The slice tag takes a string and returns a substring of it based on the provided start and end indices. +This parser is useful for extracting portions of text or limiting string length. + +## Usage + + + ```ts showLineNumbers tab="ESM" + import { Interpreter, SliceParser } from 'tagscript'; + const ts = new Interpreter(new SliceParser()); + ``` + ```js showLineNumbers tab="CommonJs" + const { Interpreter, SliceParser } = require('tagscript'); + const ts = new Interpreter(new SliceParser()); + ``` + + +## API + +Check [SliceParser](../../typedoc-api/tagscript/classes/SliceParser) for the API documentation. + +## For End Users + + +### Syntax +```yaml +{slice(start):text} +{slice(start-end):text} +{slice(start,end):text} +``` + +### Examples + +```yaml +{slice(3):Hello World} +# lo World +``` + +```yaml +{slice(0-5):Hello World} +# Hello +``` + +```yaml +{slice(6,11):Hello World} +# World +``` + +```yaml +{slice(0-3):Welcome to our server!} +# Wel +``` + +```yaml +{slice(-5):Hello World} +# World +``` + +### Aliases + +`substr`, `substring` + +### Notes + +- Start index is inclusive, end index is exclusive +- Negative indices count from the end of the string +- If only start index is provided, slices from that position to the end +- Uses JavaScript's `String.slice()` method internally + + \ No newline at end of file diff --git a/apps/website/content/docs/tagscript/parsers/stop.mdx b/apps/website/content/docs/tagscript/parsers/stop.mdx new file mode 100644 index 00000000..5ba3dbba --- /dev/null +++ b/apps/website/content/docs/tagscript/parsers/stop.mdx @@ -0,0 +1,55 @@ +--- +title: StopParser +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tabs } from 'fumadocs-ui/components/tabs'; + +The stop tag stops tag processing if the given parameter evaluates to true. +If a message is passed to the payload, it will return that message instead of an empty string. +This tag throws an error to halt all further processing, unlike the [BreakParser](/tagscript/parsers/break) which only affects the current tag output. + +## Usage + + + ```ts showLineNumbers tab="ESM" + import { Interpreter, StopParser } from 'tagscript'; + const ts = new Interpreter(new StopParser()); + ``` + ```js showLineNumbers tab="CommonJs" + const { Interpreter, StopParser } = require('tagscript'); + const ts = new Interpreter(new StopParser()); + ``` + + +## API + +Check [StopParser](../../typedoc-api/tagscript/classes/StopParser) for the API documentation. + +## For End Users + + +### Syntax +```yaml +{stop(expression):message} +``` + +### Examples + +```yaml +{stop({args}!=10):You didn't provide valid input.} +# if {args} is not 10 +You didn't provide valid input. +# if {args} is 10 +# Processing continues normally +``` + +```yaml +{stop({user.id}==12345):Access denied for this user.} +``` + +### Aliases + +`halt`, `stop`, `error` + + \ No newline at end of file diff --git a/apps/website/content/docs/tagscript/transformers/index.mdx b/apps/website/content/docs/tagscript/transformers/index.mdx index 9543a960..9b0b7446 100644 --- a/apps/website/content/docs/tagscript/transformers/index.mdx +++ b/apps/website/content/docs/tagscript/transformers/index.mdx @@ -32,7 +32,8 @@ Transformers are used to transform a value based on the tag at runtime. You can Following is the list of builtin transformers: -{/* - [BreakParser](/tagscript/parsers/break) */} +- [IntegerTransformer](/tagscript/transformers/integer) +- [StringTransformer](/tagscript/transformers/string) ## Custom Transformer diff --git a/apps/website/content/docs/tagscript/transformers/integer.mdx b/apps/website/content/docs/tagscript/transformers/integer.mdx new file mode 100644 index 00000000..6a24ee71 --- /dev/null +++ b/apps/website/content/docs/tagscript/transformers/integer.mdx @@ -0,0 +1,80 @@ +--- +title: IntegerTransformer +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tabs } from 'fumadocs-ui/components/tabs'; + +Integer transformer transforms an integer based on the given parameters. + +If no parameters are given, the integer will be returned as is. +If `++` parameter is given, the integer will be incremented. +If `--` parameter is given, the integer will be decremented. + +## Usage + + + ```ts showLineNumbers tab="ESM" + import { Interpreter, IntegerTransformer, StrictVarsParser } from 'tagscript'; + const ts = new Interpreter(new StrictVarsParser()); + ``` + ```js showLineNumbers tab="CommonJs" + const { Interpreter, IntegerTransformer, StrictVarsParser } = require('tagscript'); + const ts = new Interpreter(new StrictVarsParser()); + ``` + + +## API + +Check [IntegerTransformer](../../typedoc-api/tagscript/classes/IntegerTransformer) for the API documentation. + +## For End Users + + +### Syntax +```yaml +{variable} +{variable(++)} +{variable(--)} +``` + +### Examples + +```yaml +# Basic usage - returns the integer as string +{count} +# 5 +``` + +```yaml +# Increment the integer +{count(++)} +# 6 (if count was initially 5) +``` + +```yaml +# Decrement the integer +{count(--)} +# 4 (if count was initially 5) +``` + +```yaml +# Practical example with counter +Current count: {counter} +Incremented: {counter(++)} +Decremented: {counter(--)} +# Current count: 10 +# Incremented: 11 +# Decremented: 10 +``` + +### Notes + +- The transformer modifies the internal integer value when using `++` or `--` +- Multiple calls to `{variable(++)}` will continue incrementing the value +- The integer value persists for the lifetime of the transformer instance +- Input must be a valid integer string or number + + + +You need to use `StrictVarsParser` parser to use this transformer. \ No newline at end of file diff --git a/apps/website/content/docs/tagscript/transformers/meta.json b/apps/website/content/docs/tagscript/transformers/meta.json index 5f7e5360..1014eaa5 100644 --- a/apps/website/content/docs/tagscript/transformers/meta.json +++ b/apps/website/content/docs/tagscript/transformers/meta.json @@ -1,3 +1,4 @@ { + "integer": "Integer Transformer", "string": "String Transformer" } diff --git a/apps/website/content/docs/tagscript/transformers/string.mdx b/apps/website/content/docs/tagscript/transformers/string.mdx index a201290b..e70e1e73 100644 --- a/apps/website/content/docs/tagscript/transformers/string.mdx +++ b/apps/website/content/docs/tagscript/transformers/string.mdx @@ -3,16 +3,99 @@ title: StringTransformer --- import { Callout } from 'fumadocs-ui/components/callout'; +import { Tabs } from 'fumadocs-ui/components/tabs'; String transformer transforms a string based on the given parameters. If no parameters are given, the string will be returned as is. -If an integer parameter is given, the string will be splitted into an array of strings using payload or space as a separator. -And will return the element at the given index (integer parameter). +If an integer parameter is given, the string will be split into an array of strings using payload or space as a separator, +and will return the element at the given index (integer parameter). Use a `+` before the index to reference every element up to and including the index value. Use a `+` after the index to reference the index value and every element after it. -a + +## Usage + + + ```ts showLineNumbers tab="ESM" + import { Interpreter, StringTransformer, StrictVarsParser } from 'tagscript'; + const ts = new Interpreter(new StrictVarsParser()); + ``` + ```js showLineNumbers tab="CommonJs" + const { Interpreter, StringTransformer, StrictVarsParser } = require('tagscript'); + const ts = new Interpreter(new StrictVarsParser()); + ``` + + +## API + +Check [StringTransformer](../../typedoc-api/tagscript/classes/StringTransformer) for the API documentation. + +## For End Users + + +### Syntax +```yaml +{variable} +{variable(index)} +{variable(+index)} +{variable(index+)} +{variable.index:separator} +``` + +### Examples + +```yaml +# Basic usage +{args} +# Hi, How are you? +``` + +```yaml +# Get specific index (1-based) +{args(1)} +# Hi, + +{args(2)} +# How +``` + +```yaml +# Get everything up to and including index +{args(+2)} +# Hi, How + +{args(+3)} +# Hi, How are +``` + +```yaml +# Get everything from index onwards +{args(2+)} +# How are you? + +{args(3+)} +# are you? +``` + +```yaml +# Using custom separator +{args.1:|} +# If args contains "apple|banana|cherry" +# apple + +{args.2+:|} +# banana|cherry +``` + +### Notes + +- Index is 1-based (first element is index 1) +- Default separator is space when splitting +- You can specify custom separators using the payload syntax +- Returns the original string if index is out of bounds + + You need to use `StrictVarsParser` parser to use this transformer.