Added an examples solution and more documentation.

.github/actions/build/action.yml

@@ -0,0 +1,64 @@
+name: Build
+description: "Builds a C# solution."
+inputs:
+ name:
+ description: "Name of the solution."
+ required: true
+ directory:
+ description: "Directory containing the solution."
+ required: true
+ assembly-filter:
+ description: "Optional code coverage assembly filter."
+ required: false
+ default: "+*"
+
+runs:
+ using: composite
+
+ steps:
+ - name: Restore Dependencies
+ shell: bash
+ working-directory: ${{ inputs.directory }}
+ run: dotnet restore
+
+ - name: Build
+ shell: bash
+ working-directory: ${{ inputs.directory }}
+ run: dotnet build --no-restore --configuration Release
+
+ - name: Test
+ shell: bash
+ working-directory: ${{ inputs.directory }}
+ run: dotnet test --no-restore --no-build --configuration Release --logger "trx;LogFileName=test-results.trx" --collect:"XPlat Code Coverage"
+
+ - name: Test Report
+ uses: dorny/test-reporter@v1.6.0
+ if: success() || failure()
+ with:
+ name: ${{ inputs.name }} Test Results
+ path: "${{ inputs.directory }}/**/TestResults/test-results.trx"
+ reporter: dotnet-trx
+
+ - name: Aggregate Coverage Reports
+ shell: bash
+ working-directory: ${{ inputs.directory }}
+ run: |
+ dotnet new tool-manifest
+ dotnet tool install dotnet-reportgenerator-globaltool
+ dotnet tool run reportgenerator "-reports:**/TestResults/**/coverage.cobertura.xml" "-targetdir:." "-reportTypes:Cobertura" "-assemblyfilters:${{ inputs.assembly-filter }}"
+
+ - name: Generate Coverage Report
+ uses: irongut/CodeCoverageSummary@v1.3.0
+ with:
+ filename: ${{ inputs.directory }}/Cobertura.xml
+ format: markdown
+ indicators: true
+ output: file
+ thresholds: '95 100'
+
+ - name: Attach Coverage Report to Build
+ uses: dtinth/markdown-report-action@v1
+ with:
+ name: ${{ inputs.name }} Test Coverage
+ title: ${{ inputs.name }} Test Coverage
+ body-file: code-coverage-results.md

.github/actions/deploy-documentation/action.yml

@@ -0,0 +1,17 @@
+name: Documentation
+description: "Deploys the documentation."
+
+runs:
+ using: composite
+
+ steps:
+ - name: Setup Pages
+ uses: actions/configure-pages@v3
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v1
+ with:
+ path: './doc/_site'
+
+ - name: Deploy to GitHub Pages
+ uses: actions/deploy-pages@v2

.github/workflows/build.yml

@@ -4,6 +4,12 @@ on:
  push:
  pull_request:
 
+permissions:
+ checks: write
+ contents: write
+ id-token: write
+ pages: write
+
 jobs:
  Build:
  name: Build and Test
@@ -20,47 +26,25 @@ jobs:
  uses: actions/setup-dotnet@v3
  with:
  dotnet-version: 7.0.x
-
- - name: Restore Dependencies
- run: dotnet restore
-
- - name: Build
- run: dotnet build --no-restore --configuration Release
-
- - name: Test
- run: dotnet test --no-restore --no-build --configuration Release --logger "trx;LogFileName=test-results.trx" --collect:"XPlat Code Coverage"
-
- - name: Test Report
- uses: dorny/test-reporter@v1.6.0
- if: success() || failure()
+
+ - name: Build and Test MrKWatkins.Ast
+ uses: ./.github/actions/build
  with:
- name: Test Results
- path: "**/TestResults/test-results.trx"
- reporter: dotnet-trx
-
- - name: Aggregate Coverage Reports
- run: |
- dotnet new tool-manifest
- dotnet tool install dotnet-reportgenerator-globaltool
- dotnet tool run reportgenerator "-reports:**/TestResults/**/coverage.cobertura.xml" "-targetdir:." "-reportTypes:Cobertura"
-
- - name: Generate Coverage Report
- uses: irongut/CodeCoverageSummary@v1.3.0
- with:
- filename: src/Cobertura.xml
- format: markdown
- indicators: true
- output: file
- thresholds: '50 60'
-
- - name: Attach Coverage Report to Build
- uses: dtinth/markdown-report-action@v1
+ name: MrKWatkins.Ast
+ directory: ./src
+
+ - name: Build and Test Examples
+ uses: ./.github/actions/build
  with:
- name: Test Coverage
- title: Test Coverage
- body-file: code-coverage-results.md
-
+ name: Examples
+ directory: ./examples
+ assembly-filter: "+*;-MrKWatkins.Ast"
+  
  - name: Build Documentation
- uses: ./.github/actions/documentation
- with:
- deploy: false
+ shell: bash
+ working-directory: ./doc
+ run: ./build.sh
+
+ - name: Deploy Documentation
+ if: ${{ github.ref == 'refs/heads/main' }}
+ uses: ./.github/actions/deploy-documentation

.github/workflows/release.yml

@@ -7,11 +7,6 @@ on:
  description: 'Version Number'
  required: true
  type: string
-
-permissions:
- contents: write
- id-token: write
- pages: write
 
 jobs:
  Release:
@@ -36,9 +31,4 @@ jobs:
  run: dotnet nuget push ./packages/*.nupkg --source https://api.nuget.org/v3/index.json --api-key ${{ secrets.NUGET_API_KEY }} --skip-duplicate
 
  - name: Create Release
- run: gh release create v${{ inputs.version }} --generate-notes
-
- - name: Deploy Documentation
- uses: ./.github/actions/documentation
- with:
- deploy: true
+ run: gh release create v${{ inputs.version }} --generate-notes

doc/home.md

@@ -1,4 +1,4 @@
-# MrKWatkins.Ast
+# Home
 
 [![Build Status](https://github.com/MrKWatkins/Ast/actions/workflows/build.yml/badge.svg)](https://github.com/MrKWatkins/Ast/actions/workflows/build.yml)
 [![NuGet Version and Download Count](https://buildstats.info/nuget/MrKWatkins.Ast)](https://www.nuget.org/packages/MrKWatkins.Ast)
@@ -7,10 +7,9 @@
 
 ## Background
 
-As part of my [Oakley](https://www.mrkwatkins.co.uk/tag/oakley/) project to create a compiler and
-it's associated OakAsm project to create an assembler (details coming soon) I needed to represent
-[abstract syntax trees](https://en.wikipedia.org/wiki/Abstract_syntax_tree) in C#. This library
-was created so I could share the code between those two projects.
+As part of my [Oakley](https://www.mrkwatkins.co.uk/tag/oakley/) project to create a compiler and it's associated OakAsm project to create an assembler
+(details coming soon) I needed to represent [abstract syntax trees](https://en.wikipedia.org/wiki/Abstract_syntax_tree) in C#. This library was created
+so I could share the code between those two projects.
 
 ## Usage
 

doc/listeners.md

@@ -0,0 +1,37 @@
+# Listeners
+
+Listeners are an alternative lightweight method to [processing](processing.md) for visiting nodes in a tree and performing
+some functionality. Listeners walk all the nodes and a tree and have events that can be hooked into when nodes are reached.
+Processing is best for mutating a tree, listeners are more suitable for building something new from a tree.
+
+## Creating a Listener
+
+There are four base listener classes that can be inherited from to create a listener:
+
+* [Listener\<TNode\>](xref:MrKWatkins.Ast.Listening.Listener\`1) - Listens to all nodes in a tree.
+* [Listener\<TBaseNode, TNode\>](xref:MrKWatkins.Ast.Listening.Listener\`2) - Listens to all nodes of a specific type in a tree.
+* [ListenerWithContext\<TContext, TNode\>](xref:MrKWatkins.Ast.Listening.ListenerWithContext\`2) - Listens to all nodes in a tree with access to a context object.
+* [ListenerWithContext\<TContext, TBaseNode, TNode\>](xref:MrKWatkins.Ast.Listening.ListenerWithContext\`3) - Listens to all nodes of a specific type in a tree with access to a context object.
+
+The listeners have three methods that can be overridden to get access to the nodes:
+
+* [BeforeListenToNode](xref:MrKWatkins.Ast.Listening.Listener\`1.BeforeListenToNode(\`0)) - Called immediately before a node and its children are visited.
+* [ListenToNode](xref:MrKWatkins.Ast.Listening.Listener\`1.ListenToNode(\`0)) - Called when node is visited.
+* [AfterListenToNode](xref:MrKWatkins.Ast.Listening.Listener\`1.AfterListenToNode(\`0)) - Called immediately after a node and its children have been visited.
+
+To start the listening process call the [Listen](xref:MrKWatkins.Ast.Listening.Listener\`1.Listen(\`0)) method.
+
+## Composite Listeners
+
+Often you will want to visit a tree performing different actions for specific types of node in the tree. Rather than have all the code in one class with
+switch statements on the node type you can instead build a composite listener from multiple other listeners. A composite listener can be built using a fluent
+interface from the [Build](xref:MrKWatkins.Ast.Listening.CompositeListener\`1.Build) or [BuildWithContext](xref:MrKWatkins.Ast.Listening.CompositeListener\`1.BuildWithContext\`\`1)
+methods.
+
+Only one listener for a given type can be registered. However listeners can be registered for base types too, and the listener with the most specific type
+will be chosen to listen to a node. This is useful for fallback behaviour. Listeners can also have base classes to share implementation between different node
+types.
+
+## Example
+
+Find an example of using listeners to produce a string representation of a tree at <https://github.com/MrKWatkins/Ast/tree/main/examples/Listeners>.

doc/processing.md

@@ -0,0 +1,2 @@
+# Processing
+

doc/templates/singulinkfx/styles/discord.css

@@ -60,18 +60,11 @@ h1,h2,h3,h4,h5
  position: relative;
 }
 
-h1, h2
-{
- margin-block-start: 2em;
-}
-
 h3 
 {
- margin-block-start: 1em;
  font-weight: 300;
  font-size: 1.5em;
  color: var(--h3-color);
- margin-block-start: 3em;
 }
 
 h4 
@@ -85,8 +78,6 @@ h4
 
 
 h5 {
- margin-block-end: .8em;
- margin-block-start: 1em;
  font-size: .85em;
  font-weight: 500;
  color: var(--h5-color);

doc/templates/singulinkfx/styles/singulink.css

@@ -419,7 +419,7 @@ legend, pre {
  font-style: normal;
 }
 
-p .xref, code {
+code {
  background-color: var(--ref-bg-color);
  color: var(--ref-color);
  padding: 2px 3px;

doc/toc.yml

@@ -1,5 +1,11 @@
 - name: Home
  href: home.md
 
+- name: Processing
+ href: processing.md
+
+- name: Listeners
+ href: listeners.md
+
 - name: API
  href: api/