Add support for variable operator syntax

docs/syntax/substitutions.md

@@ -3,6 +3,7 @@ sub:
   frontmatter_key: "Front Matter Value"
   a-key-with-dashes: "A key with dashes"
   version: 7.17.0
+  hello-world: "Hello world!"
 ---
 
 # Substitutions
@@ -26,7 +27,7 @@ Doing so will result in a build error.
 
 To use the variables in your files, surround them in curly brackets (`{{variable}}`).
 
-## Example
+### Example
 
 Here are some variable substitutions:
 
@@ -36,6 +37,97 @@ Here are some variable substitutions:
 | {{a-key-with-dashes}} | Front Matter |
 | {{a-global-variable}} | `docset.yml` |
 
+## Mutations
+
+Substitutions can be mutated using a chain of operators seperated by a pipe (`|`).
+
+````markdown
+`{{hello-world | trim | lc | tc}}`
+````
+
+Will trim, lowercase and finally titlecase the contents of the 'hello-world' variable.
+
+### Operators
+
+
+| Operator | Purpose                                            |
+|----------|----------------------------------------------------|
+| `lc`     | LowerCase,                                         |
+| `uc`     | UpperCase,                                         |
+| `tc`     | TitleCase, capitalizes all words,                  |
+| `c`      | Capitalize the first letter,                       |
+| `kc`     | Convert to KebabCase,                              |
+| `sc`     | Convert to SnakeCase,                              |
+| `cc`     | Convert to CamelCase,                              |
+| `pc`     | Convert to PascalCase,                             |
+| `trim`   | Trim common non word characters from start and end |
+
+For variables declaring a semantic version or `Major.Minor` the following operations are also exposed
+
+| Operator | Purpose                                  |
+|----------|------------------------------------------|
+| `M`      | Display only the major component         |
+| `M.x`    | Display major component followed by '.x' |
+| `M.M`    | Display only the major and the minor     |
+| `M+1`    | The next major version                   |
+| `M.M+1`  | The next minor version                   |
+
+### Example
+
+Given the following frontmatter:
+
+```yaml
+---
+sub:
+  hello-world: "Hello world!"
+---
+```
+
+::::{tab-set}
+
+:::{tab-item} Output
+
+* Lowercase: {{hello-world | lc}}
+* Uppercase: {{hello-world | uc}}
+* TitleCase: {{hello-world | tc}}
+* kebab-case: {{hello-world | kc}}
+* camelCase: {{hello-world | tc | cc}}
+* PascalCase: {{hello-world | pc}}
+* SnakeCase: {{hello-world | sc}}
+* CapitalCase (chained): {{hello-world | lc | c}}
+* Trim: {{hello-world | trim}}
+* M.x: {{version.stack | M.x }}
+* M.M: {{version.stack | M.M }}
+* M: {{version.stack | M }}
+* M+1: {{version.stack | M+1 }}
+* M+1 | M.M: {{version.stack | M+1 | M.M }}
+* M.M+1: {{version.stack | M.M+1 }}
+
+:::
+
+:::{tab-item} Markdown
+
+````markdown
+* Lowercase: {{hello-world | lc}}
+* Uppercase: {{hello-world | uc}}
+* TitleCase: {{hello-world | tc}}
+* kebab-case: {{hello-world | kc}}
+* camelCase: {{hello-world | tc | cc}}
+* PascalCase: {{hello-world | pc}}
+* SnakeCase: {{hello-world | sc}}
+* CapitalCase (chained): {{hello-world | lc | c}}
+* Trim: {{hello-world | trim}}
+* M.x: {{version.stack | M.x }}
+* M.M: {{version.stack | M.M }}
+* M: {{version.stack | M }}
+* M+1: {{version.stack | M+1 }}
+* M+1 | M.M: {{version.stack | M+1 | M.M }}
+* M.M+1: {{version.stack | M.M+1 }}
+````
+:::
+
+::::
+
 ## Code blocks
 
 Substitutions are supported in code blocks but are disabled by default. Enable substitutions by adding `subs=true` to the code block.

docs/syntax/version-variables.md

@@ -10,14 +10,21 @@ Besides the current version, the following suffixes are available:
 
 | Version substitution                 | result                            | purpose                                 |
 |--------------------------------------|-----------------------------------|-----------------------------------------| 
-| `{{versions.stack}}`                 | {{version.stack}}                 | Current version                         |
-| `{{versions.stack.major_minor}}`     | {{version.stack.major_minor}}     | Current `MAJOR.MINOR`                   |
-| `{{versions.stack.major_x}}`         | {{version.stack.major_x}}         | Current `MAJOR.X`                       |
-| `{{versions.stack.major_component}}` | {{version.stack.major_component}} | Current major component                 |
-| `{{versions.stack.next_major}}`      | {{version.stack.next_major}}      | The next major version                  |
-| `{{versions.stack.next_minor}}`      | {{version.stack.next_minor}}      | The next minor version                  |
-| `{{versions.stack.base}}`            | {{version.stack.base}}            | The first version on the new doc system |
+| `{{version.stack}}`                 | {{version.stack}}                 | Current version                         |
+| `{{version.stack.base}}`            | {{version.stack.base}}            | The first version on the new doc system |
 
+## Formatting
+
+Using specialized [mutation operators](substitutions.md#mutations) versions 
+can be printed in any kind of ways.
+
+
+| Version substitution   | result    |
+|------------------------|-----------|
+| `{{version.stack| M.M}}`    |  {{version.stack|M.M}} |
+| `{{version.stack.base | M }}`     | {{version.stack.base | M }} |
+| `{{version.stack | M+1       | M }}` | {{version.stack | M+1 | M }} |
+| `{{version.stack.base | M.M+1 }}` | {{version.stack.base | M.M+1 }} |
 
 ## Available versioning schemes.
 

src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs

@@ -163,27 +163,11 @@ public ConfigurationFile(IDocumentationContext context, VersionsConfiguration ve
 			foreach (var (id, system) in versionsConfig.VersioningSystems)
 			{
 				var name = id.ToStringFast(true);
-				var current = system.Current;
 				var key = $"version.{name}";
 				_substitutions[key] = system.Current;
 
 				key = $"version.{name}.base";
 				_substitutions[key] = system.Base;
-
-				key = $"version.{name}.major_minor";
-				_substitutions[key] = $"{current.Major:N0}.{current.Minor:N0}";
-
-				key = $"version.{name}.major_x";
-				_substitutions[key] = $"{current.Major:N0}.x";
-
-				key = $"version.{name}.major_component";
-				_substitutions[key] = $"{current.Major:N0}";
-
-				key = $"version.{name}.next_minor";
-				_substitutions[key] = new SemVersion(current.Major, current.Minor + 1, current.Patch, current.Prerelease, current.Metadata);
-
-				key = $"version.{name}.next_major";
-				_substitutions[key] = new SemVersion(current.Major + 1, current.Minor, current.Patch, current.Prerelease, current.Metadata);
 			}
 
 			var toc = new TableOfContentsConfiguration(this, sourceFile, ScopeDirectory, _context, 0, "");

src/Elastic.Markdown/DocumentationGenerator.cs

@@ -180,7 +180,13 @@ private void HintUnusedSubstitutionKeys()
 	{
 		var definedKeys = new HashSet<string>(Context.Configuration.Substitutions.Keys.ToArray());
 		var inUse = new HashSet<string>(Context.Collector.InUseSubstitutionKeys.Keys);
-		var keysNotInUse = definedKeys.Except(inUse).ToArray();
+		var keysNotInUse = definedKeys.Except(inUse)
+				// versions keys are injected
+				.Where(key => !key.StartsWith("version."))
+				// reserving context namespace
+				.Where(key => !key.StartsWith("context."))
+				.ToArray();
+
 		// If we have less than 20 unused keys, emit them separately,
 		// Otherwise emit one hint with all of them for brevity
 		if (keysNotInUse.Length >= 20)

src/Elastic.Markdown/Myst/InlineParsers/Substitution/SubstitutionParser.cs

@@ -3,35 +3,130 @@
 // See the LICENSE file in the project root for more information
 
 using System.Buffers;
+using System.ComponentModel.DataAnnotations;
 using System.Diagnostics;
+using System.Globalization;
+using System.Text;
+using System.Text.Json;
+using Elastic.Documentation;
 using Elastic.Markdown.Diagnostics;
 using Markdig.Helpers;
 using Markdig.Parsers;
 using Markdig.Renderers;
 using Markdig.Renderers.Html;
 using Markdig.Syntax;
 using Markdig.Syntax.Inlines;
+using NetEscapades.EnumGenerators;
 
 namespace Elastic.Markdown.Myst.InlineParsers.Substitution;
 
 [DebuggerDisplay("{GetType().Name} Line: {Line}, Found: {Found}, Replacement: {Replacement}")]
-public class SubstitutionLeaf(string content, bool found, string replacement) : CodeInline(content)
+public class SubstitutionLeaf(string content, bool found, string replacement)
+	: CodeInline(content)
 {
 	public bool Found { get; } = found;
 	public string Replacement { get; } = replacement;
+	public IReadOnlyCollection<SubstitutionMutation>? Mutations { get; set; }
+}
+
+[EnumExtensions]
+public enum SubstitutionMutation
+{
+	[Display(Name = "M")] MajorComponent,
+	[Display(Name = "M.x")] MajorX,
+	[Display(Name = "M.M")] MajorMinor,
+	[Display(Name = "M+1")] IncreaseMajor,
+	[Display(Name = "M.M+1")] IncreaseMinor,
+	[Display(Name = "lc")] LowerCase,
+	[Display(Name = "uc")] UpperCase,
+	[Display(Name = "tc")] TitleCase,
+	[Display(Name = "c")] Capitalize,
+	[Display(Name = "kc")] KebabCase,
+	[Display(Name = "sc")] SnakeCase,
+	[Display(Name = "cc")] CamelCase,
+	[Display(Name = "pc")] PascalCase,
+	[Display(Name = "trim")] Trim
 }
 
 public class SubstitutionRenderer : HtmlObjectRenderer<SubstitutionLeaf>
 {
-	protected override void Write(HtmlRenderer renderer, SubstitutionLeaf obj) =>
-		renderer.Write(obj.Found ? obj.Replacement : obj.Content);
+	protected override void Write(HtmlRenderer renderer, SubstitutionLeaf leaf)
+	{
+		if (!leaf.Found)
+		{
+			_ = renderer.Write(leaf.Content);
+			return;
+		}
+
+		var replacement = leaf.Replacement;
+		if (leaf.Mutations is null or { Count: 0 })
+		{
+			_ = renderer.Write(replacement);
+			return;
+		}
+
+		foreach (var mutation in leaf.Mutations)
+		{
+			var (success, update) = mutation switch
+			{
+				SubstitutionMutation.MajorComponent => TryGetVersion(replacement, v => $"{v.Major}"),
+				SubstitutionMutation.MajorX => TryGetVersion(replacement, v => $"{v.Major}.x"),
+				SubstitutionMutation.MajorMinor => TryGetVersion(replacement, v => $"{v.Major}.{v.Minor}"),
+				SubstitutionMutation.IncreaseMajor => TryGetVersion(replacement, v => $"{v.Major + 1}.0.0"),
+				SubstitutionMutation.IncreaseMinor => TryGetVersion(replacement, v => $"{v.Major}.{v.Minor + 1}.0"),
+				SubstitutionMutation.LowerCase => (true, replacement.ToLowerInvariant()),
+				SubstitutionMutation.UpperCase => (true, replacement.ToUpperInvariant()),
+				SubstitutionMutation.Capitalize => (true, Capitalize(replacement)),
+				SubstitutionMutation.KebabCase => (true, ToKebabCase(replacement)),
+				SubstitutionMutation.CamelCase => (true, ToCamelCase(replacement)),
+				SubstitutionMutation.PascalCase => (true, ToPascalCase(replacement)),
+				SubstitutionMutation.SnakeCase => (true, ToSnakeCase(replacement)),
+				SubstitutionMutation.TitleCase => (true, TitleCase(replacement)),
+				SubstitutionMutation.Trim => (true, Trim(replacement)),
+				_ => throw new Exception($"encountered an unknown mutation '{mutation.ToStringFast(true)}'")
+			};
+			if (!success)
+			{
+				_ = renderer.Write(leaf.Content);
+				return;
+			}
+			replacement = update;
+		}
+		_ = renderer.Write(replacement);
+	}
+
+	private static string ToCamelCase(string str) => JsonNamingPolicy.CamelCase.ConvertName(str.Replace(" ", string.Empty));
+	private static string ToSnakeCase(string str) => JsonNamingPolicy.SnakeCaseLower.ConvertName(str).Replace(" ", string.Empty);
+	private static string ToKebabCase(string str) => JsonNamingPolicy.KebabCaseLower.ConvertName(str).Replace(" ", string.Empty);
+	private static string ToPascalCase(string str) => TitleCase(str).Replace(" ", string.Empty);
+
+	private static string TitleCase(string str) => CultureInfo.InvariantCulture.TextInfo.ToTitleCase(str);
+
+	private static string Trim(string str) =>
+		str.AsSpan().Trim(['!', ' ', '\t', '\r', '\n', '.', ',', ')', '(', ':', ';', '<', '>', '[', ']']).ToString();
+
+	private static string Capitalize(string input) =>
+		input switch
+		{
+			null => string.Empty,
+			"" => string.Empty,
+			_ => string.Concat(input[0].ToString().ToUpper(), input.AsSpan(1))
+		};
+
+	private (bool, string) TryGetVersion(string version, Func<SemVersion, string> mutate)
+	{
+		if (!SemVersion.TryParse(version, out var v) && !SemVersion.TryParse(version + ".0", out v))
+			return (false, string.Empty);
+
+		return (true, mutate(v));
+	}
 }
 
 public class SubstitutionParser : InlineParser
 {
 	public SubstitutionParser() => OpeningCharacters = ['{'];
 
-	private readonly SearchValues<char> _values = SearchValues.Create(['\r', '\n', ' ', '\t', '}']);
+	private readonly SearchValues<char> _values = SearchValues.Create(['\r', '\n', '\t', '}']);
 
 	public override bool Match(InlineProcessor processor, ref StringSlice slice)
 	{
@@ -81,9 +176,13 @@ public override bool Match(InlineProcessor processor, ref StringSlice slice)
 		startPosition -= openSticks;
 		startPosition = Math.Max(startPosition, 0);
 
-		var key = content.ToString().Trim(['{', '}']).ToLowerInvariant();
+		var key = content.ToString().Trim(['{', '}']).Trim().ToLowerInvariant();
 		var found = false;
 		var replacement = string.Empty;
+		var components = key.Split('|');
+		if (components.Length > 1)
+			key = components[0].Trim(['{', '}']).Trim().ToLowerInvariant();
+
 		if (context.Substitutions.TryGetValue(key, out var value))
 		{
 			found = true;
@@ -100,7 +199,6 @@ public override bool Match(InlineProcessor processor, ref StringSlice slice)
 		var start = processor.GetSourcePosition(startPosition, out var line, out var column);
 		var end = processor.GetSourcePosition(slice.Start);
 		var sourceSpan = new SourceSpan(start, end);
-
 		var substitutionLeaf = new SubstitutionLeaf(content.ToString(), found, replacement)
 		{
 			Delimiter = '{',
@@ -109,8 +207,31 @@ public override bool Match(InlineProcessor processor, ref StringSlice slice)
 			Column = column,
 			DelimiterCount = openSticks
 		};
+
 		if (!found)
 			processor.EmitError(line + 1, column + 3, substitutionLeaf.Span.Length - 3, $"Substitution key {{{key}}} is undefined");
+		else
+		{
+			List<SubstitutionMutation>? mutations = null;
+			if (components.Length >= 10)
+				processor.EmitError(line + 1, column + 3, substitutionLeaf.Span.Length - 3, $"Substitution key {{{key}}} defines too many mutations, none will be applied");
+			else if (components.Length > 1)
+			{
+				foreach (var c in components[1..])
+				{
+					if (SubstitutionMutationExtensions.TryParse(c.Trim(), out var mutation, true, true))
+					{
+						mutations ??= [];
+						mutations.Add(mutation);
+					}
+					else
+						processor.EmitError(line + 1, column + 3, substitutionLeaf.Span.Length - 3, $"Mutation '{c}' on {{{key}}} is undefined");
+				}
+			}
+
+			substitutionLeaf.Mutations = mutations;
+		}
+
 
 		if (processor.TrackTrivia)
 		{