Project doesn't contain enough examples

[ArsenShnurkov]

there is no gh-pages orphan git branch, and it may help to figure out, how this library work.

Questions which I have:

1. where to read about red-green model?
2. how parsing is done (is it recursive descent?)?
3. how to use XPath expressions with this library?
4. is it ok to use list of microsoft errors source code from licensing point of view?
5. this looks like read-only model. Are there any plans to implement modification, node deletion? (i think no)

[KirillOsenkov]

This is a good suggestion. I certainly need to revisit this at some point.

Read about red-green trees here:

• https://blogs.msdn.microsoft.com/ericlippert/2012/06/08/persistence-facades-and-roslyns-red-green-trees/
• http://stackoverflow.com/questions/25963328/how-does-the-release-version-of-roslyn-implement-immutable-trees

Parser is a manually written top-down recursive descent. Unfortunately the parser isn't written really well, the scanner is not separate from the parser, so you can't just scan tokens easily without involving the parser. This is a limitation of how the Roslyn VB parser was written.

XPath is not supported at all and I haven't even been thinking about it at all. It may be easy to add, or it may be super difficult, I don't know. I have no plans to investigate XPath.

It is OK to use the list of error codes, it's under the Apache 2.0 license.

I want to implement modification/mutation/deletion, because it's a useful feature. XLinq has it really convenient.

However there's a design choice I'll have to make.

1. Retain full immutability and do tree-respining (just like Roslyn edits respine the tree by creating what really is a new tree that reuses most green nodes). The old tree remains unaffected.
2. Sacrifice immutability in favor of memory efficiency. The immutable approach unfortunately has the side effect of a lot of unneeded allocations. The benefit of immutability is you can be guaranteed that it's OK to observe the tree at any time from any thread and it won't be changed. However I feel that in the XML parser case such a strong guarantee is not usually needed. Locking the tree and/or cloning it should be enough in the unlikely case of parallel processing. I'm thinking that making the tree mutable and getting rid of red/green would be preferable and allow to handle larger XML/HTML files.

I'll think about it later.

[j-sauer]

Hi,

I want to modify the syntax tree. I've seen that there is already a SyntaxRewriter that I could use to "modify" the tree. Is there a reason why this class is internal? Or do you plan in the near future to implement any kind of modification mechanism as you described above?

Thx in advance

[KirillOsenkov]

Hi, first of all apologies that the modification story is not there yet. We just don't have the time to think through the modification story. We do hope to get to it eventually but this is a side project with low priority for us right now.

I guess the simplest thing you can do is based on a syntax tree prepare a list of text edits to modify the source and then just do a full reparse of the text. I know this is terrible from performance standpoint but you'll be guaranteed a fresh, clean and correct tree every time.

We've taken shortcuts to get things going with the current model and we're not sure the syntax rewriter will even work with the hacks we made (Start, FullWidth, Parent etc). You can of course fork the library and try making it public to see if it works, which I honestly doubt.

So for now the suggestion is: generate text edits and do full reparse for modification scenarios. We'll get to the proper modification support eventually, I just don't know when.

[Beautyod]

This project looks really nice, but I agree to the big disadvantage of missing documentation.
I did read the readme, looked to the sweet example and made tries in a test project.

My problems:

• As a C# programmer I have big problems to understand the F# code and therefore it's more difficult to understand the way of the parser usage.
• There are no published XML comments to describe all the members. (Please include the XML documentation file to the nuget package!) There are so many members and without help it's really tricky.
• I miss some basic code examples in the readme file. After installing the nuget package, I have not even known, which namespace and variable types I have to use. After long time I found out, it's XmlDocumentSyntax.
• I can't figure out, how to get the texts of the tags, etc. I found only ToFullString(), but this is not what I want.

After maybe 3 hours of experimenting I give up.

I "just" wanted to do do a simple thing, but I can't get it without more information.
My goal: A simple beautifyer for incomplete XML documents, which adds line breaks and indentions.
My way of implementation: A recursive method, which prints the opening tag, the closing tag and in between a call of itself for the children.
But without the knowledge about how to use XmlDocumentSyntax I can't do that.

It's very sad. This great library is hard to use for newcomers, because of missing documentation.
Please add more documentation.