War3Net.CodeAnalysis

About

War3Net.CodeAnalysis is a library providing helper methods and extension methods for Pidgin parsers, along with utility classes for code generation. It simplifies the creation of complex recursive parsers for domain-specific languages and provides tools for generating properly formatted source code output. It is part of the War3Net modding library.

Key features

• Parse separated lists (e.g., comma-separated arguments) while preserving separator tokens
• Parse if/elseif/else/endif block structures with trivia preservation
• Parse block constructs with open/close tokens (e.g., loops, function bodies)
• Generate indented source code output with automatic indentation management
• Immutable data structures for representing parsed syntax lists

How to Use

Parse a comma-separated list

using Pidgin; using War3Net.CodeAnalysis; // Define your item and separator parsers Parser<char, Expression> expressionParser = /* your expression parser */; Parser<char, char> commaParser = Parser.Char(','); // Create a separated list parser Parser<char, SeparatedSyntaxList<Expression, char>> argumentListParser = expressionParser.SeparatedList(commaParser); // Parse input var result = argumentListParser.Parse("a, b, c"); SeparatedSyntaxList<Expression, char> arguments = result.Value; // Access items and separators foreach (var item in arguments.Items) { // Process each expression }

Parse block structures with UntilWithLeading

using Pidgin; using War3Net.CodeAnalysis; // Parse items between open and close tokens (e.g., loop/endloop) Parser<char, LoopStatement> loopParser = statementParser.UntilWithLeading( triviaParser, // Parser for leading whitespace/comments loopKeywordParser, // Open token parser endLoopKeywordParser, // Close token parser (trivia, stmt) => stmt.WithLeadingTrivia(trivia), (loopToken, statements, trivia, endLoopToken) => new LoopStatement(loopToken, statements, trivia, endLoopToken));

Build a separated syntax list manually

using War3Net.CodeAnalysis; // Create a builder with the first item var builder = SeparatedSyntaxList<string, char>.CreateBuilder("first"); // Add more items with separators builder.Add(',', "second"); builder.Add(',', "third"); // Build the immutable list SeparatedSyntaxList<string, char> list = builder.ToSeparatedSyntaxList();

Generate indented source code

using System.IO; using War3Net.CodeAnalysis; using var stringWriter = new StringWriter(); using var writer = new IndentedTextWriter(stringWriter); writer.WriteLine("function Main()"); writer.Indent(); writer.WriteLine("local x = 1"); writer.WriteLine("call DoSomething(x)"); writer.Unindent(); writer.WriteLine("endfunction"); string output = stringWriter.ToString(); // Output: // function Main() // local x = 1 // call DoSomething(x) // endfunction

Note: For rendering JASS code, avoid writing strings manually as shown above. Instead, use War3Net.CodeAnalysis.Jass.Extensions.IndentedTextWriterExtensions which provides convenience extension methods that handle indentation for you automatically. See the War3Net.CodeAnalysis.Jass package for details.

Main Types

The main types provided by this library are:

• War3Net.CodeAnalysis.ParserExtensions - Extension methods for Pidgin parsers (SeparatedList, IfThenElse, UntilWithLeading)
• War3Net.CodeAnalysis.SeparatedSyntaxList<TItem, TSeparator> - Immutable list of items with separators between them
• War3Net.CodeAnalysis.SeparatedSyntaxList<TItem, TSeparator>.Builder - Builder for incrementally constructing separated syntax lists
• War3Net.CodeAnalysis.IndentedTextWriter - TextWriter that automatically handles indentation

Related Packages

• War3Net.CodeAnalysis.Jass - Parse and render JASS source files
• War3Net.CodeAnalysis.Transpilers - Transpile JASS to C# or Lua
• War3Net.Build - Generate JASS map scripts and compile maps

Feedback and contributing

War3Net.CodeAnalysis is released as open source under the MIT license. Bug reports and contributions are welcome at the GitHub repository.

• File an issue
• Submit a pull request

Disclaimer

This README was generated with the assistance of AI and may contain inaccuracies. Please verify the information and consult the source code for authoritative details.