Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sebastienros/shortcodes
Shortcodes processor for .NET
https://github.com/sebastienros/shortcodes
Last synced: 3 days ago
JSON representation
Shortcodes processor for .NET
- Host: GitHub
- URL: https://github.com/sebastienros/shortcodes
- Owner: sebastienros
- License: mit
- Created: 2020-05-19T02:50:38.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-01-13T02:46:58.000Z (11 days ago)
- Last Synced: 2025-01-14T21:09:18.148Z (10 days ago)
- Language: C#
- Size: 81.1 KB
- Stars: 72
- Watchers: 7
- Forks: 10
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
## Basic Overview
Shortcodes processor for .NET with focus on performance and simplicity.
## Features
- Parses and renders shortcodes.
- Supports **async** shortcode to execute database queries and async operations more efficiently under load.
- Named and positioned arguments.
## Contents
- [Sample usage](#sample-usage)
- [Used by](#used-by)
## Sample usage
Don't forget to include the __using__ statement:
```c#
using Shortcodes;
```
### Predefined shortcodes
```c#
var processor = new ShortcodesProcessor(new NamedShortcodeProvider
{
["hello"] = (args, content, ctx) => new ValueTask("Hello world!")
});
Console.WriteLine(await processor.EvaluateAsync("This is an [hello]"));
```
Which results in
```
This is an Hello world!
```
### Named arguments
Arguments can contain any character, but need to be quoted either with `'` or `"` if they contain spaces.
Strings can use standard string escape sequences like `\u03A9` and `\n`.
```c#
var processor = new ShortcodesProcessor(new NamedShortcodeProvider
{
["bold"] = (args, content, ctx) =>
{
var text = args.Named("text");
return new ValueTask($"{text}");
}
});
Console.WriteLine(await processor.EvaluateAsync("[bold text='bold text' 1234]"));
```
### Content arguments
Shortcodes using opening and closing tags can access their inner content.
```c#
var processor = new ShortcodesProcessor(new NamedShortcodeProvider
{
["bold"] = (args, content, ctx) =>
{
return new ValueTask($"{content}");
}
});
Console.WriteLine(await processor.EvaluateAsync("[bold]bold text[/bold]"));
```
For single tags, the content is `null`. It means that you can detect if a shortcode was
used with a closing tag, even if the inner content is empty.
### Positional arguments
If an argument doesn't have a name, an default index can be used.
```c#
var processor = new ShortcodesProcessor(new NamedShortcodeProvider
{
["bold"] = (args, content, ctx) =>
{
var text = args.NamedOrDefault("text");
return new ValueTask($"{text}");
}
});
Console.WriteLine(await processor.EvaluateAsync("[bold 'bold text']"));
```
```
bold text
```
Named and positional arguments can be mixed together. Each time an argument doesn't
have a name, the index is incremented.
```c#
var processor = new ShortcodesProcessor(new NamedShortcodeProvider
{
["bold"] = (args, content, ctx) =>
{
var text = args.At(0);
return new ValueTask($"{text}");
}
});
Console.WriteLine(await processor.EvaluateAsync("[bold id='a' 'some text']"));
```
```
some text
```
### Escaping tags
In case you want to render a shortcode instead of evaluating it, you can double the
opening and closing braces.
```
[[bold] some text to show [/bold]]
```
Will then be rendered as
```
[bold] some text to show [/bold]
```
And for single tags:
```
[[bold 'text']]
```
Will be rendered as
```
[bold 'text']
```
In case several braces are used, and they are balanced, a single one will be escaped.
```
[[[bold 'text']]]
```
Will be rendered as:
```
[[bold 'text']]
```
Not that unbalanced braces won't be escaped.
```
[[[[bold 'text']]
```
Will be rendered as
```
[[[[bold 'text']]
```
### Context object
A __Context__ object can be passed when evaluating a template. This object
is shared across all shortcodes
A common usage is to pass custom data that might be used by some shortcodes, like
the current `HttpContext` if a template is running in a web application and needs
to access the current request.
Another usage is to use it as a bag of values that can be shared across shortcodes.
```c#
// From a Startup.cs class
var processor = new ShortcodesProcessor(new NamedShortcodeProvider
{
["username"] = (args, content, ctx) =>
{
var httpContext = (HttpContext)ctx["HttpContext"];
return new ValueTask(httpContext.User.Identity.Name);
}
});
app.Run((httpContext) =>
{
var context = new Context(){ ["HttpContext"] = httpContext };
var result = await processor.EvaluateAsync("The current user is [username]", context);
return context.Response.WriteAsync(result);
});
```
```
The current user is admin
```