Shy Beginner (looking for a starting point)

SyntaxEditor for WPF Forum

Posted 3 years ago by Richard Langin
Version: 11.1.0543
Avatar

Good evening. I’ve been reading several pages from SyntaxEditor’s documentation, opened the Sample Browser, snooped into the only provided Visual Studio solution — the overwhelming Sample Browser’s source code — and I feel very frustrated, because, as far as my examination has gone, I can say there’s no real «getting started» example anywhere neither in the reference nor in the example code.


Even the so-called «getting started» section at the beginning of the manual is a lot of theory — necessary theory, no question about that — but there’s nothing like a simple but fully worked Visual Studio example project, from start to finish and, most of all, step by step. I was expecting some tutorial, like: 1) add the required references; 2) create and place the control; 3) use the Language Designer to build a new (simple) language; 4) register this language in the control; (… plus some application related to syntax recognition, completion list or even simpler stuff). I’m talking a «Syntax Editor for Dummies» tutorial before hitting the heavy details, just to let the user «feel» the path to follow, or just understand where’s the starting point and what are the first steps.


I thought that knowing the essential theory about C# and WPF were the only requirements for learning about this control but its documentation seems to assume much more, like… mastering Syntax Editor already! Every single piece of information is described in detail, but the help manual is a web of mutual cross-references and there’s no place — as far as I could see — where a complete picture of how those pieces can be glued together into a small, simple project is shown.


Is there anywhere in Actipro’s website or discussion forum anything like this kind of «getting started» material? Otherwise, I hope somebody — either in the staff or the expert users — will have the merciful patience to answer my upcoming «how can I..?» posts while I try to make my way through SyntaxEditor. Reading through this forum’s posts I can see it’s made up of 100% experts already confident with SyntaxEditor, hence I assume a very shy beginner like me can be invited to the party.


Thank you for your attention.

Comments (12)

Posted 3 years ago by Actipro Software Support - Cleveland, OH, USA
Avatar

Hi Richard,

Thank you for your comments.  We realize that as a product as complex as SyntaxEditor grows and grows in features and functionality, it can get difficult to make sure the documentation and samples are still approachable for new customers.  We are happy to work with you to adjust our documentation so that there is a better onboarding experience.

Our SyntaxEditor Getting Started series of samples (in the main samples project under /ProductSamples/SyntaxEditorSamples/QuickStart/GettingStartedXX) is intended to be a step-by-step introduction to building a feature-rich syntax language.  It starts off with basic syntax highlighting and adds features like parsing, code outlining, automated IntelliPrompt, etc. as each step progresses.

What enhancements to the documentation would help most to get you pointed to that Getting Started series of samples so that it's more clear on how to get going?  In the meantime, feel free to ask questions if you can't find related documentation or samples and we can answer them.


Actipro Software Support

Posted 3 years ago by Richard Langin
Avatar

Thank you very much for your reply.

Either by pure coincidence or by my «complaint» triggering something in my mind, few minutes after posting my message something «unlocked» and I succeeded in writing a very elementary project (bare-bone editor, «Simple» language loaded in it, completion list popping up when typing «this.», as instructed by your manual). This strongly feels like a beginning, after a long «frozen» time spent trying to find a thread to pull. Before posting my next question I’ll make sure it’s not already clearly (to me) answered in either your documentation or samples.

 Best regards. R.

Posted 3 years ago by Richard Langin
Avatar

Good evening.

 

Subject:

Connecting a TaggerBase<ISquiggleTag> object to an editor.

 

Preliminaries:


 

I have faithfully copied a snippet shown in SyntaxEditor’s manual ( Text/Parsing Framework - Tagging --> Taggers and Tagger Providers --> Sample: ITagger<ISquiggleTag> Implementation ), which I repeat here:

public class CustomSquiggleTagger : TaggerBase<ISquiggleTag>
    {

        public CustomSquiggleTagger(ICodeDocument document) : base("ActiProPatternBasedSquiggle", null, document, true) { }

        public override IEnumerable<TagSnapshotRange<ISquiggleTag>> GetTags(NormalizedTextSnapshotRangeCollection snapshotRanges, object parameter)
        {
            if (snapshotRanges != null)
            {
                foreach (TextSnapshotRange snapshotRange in snapshotRanges)
                {
                    string text = snapshotRange.Text;

                    MatchCollection matches = Regex.Matches(text, @"My Test Sentence", RegexOptions.IgnoreCase);

                    if (matches.Count > 0)
                    {

                        foreach (Match match in matches)
                        {
                            SquiggleTag tag = new SquiggleTag();
                            yield return new TagSnapshotRange<ISquiggleTag>
                                (TextSnapshotRange.FromSpan(snapshotRange.Snapshot, 
                                snapshotRange.StartOffset + match.Index, match.Length), tag);
                        }
                    
                    }
                }
            
            }
        }

    }

 I have replaced your test string @"\bActipro\b" with @"My Test Sentence".

 

My question:


 

How do I effectively «glue» (is «register» the correct name for this?) my editor (a SyntaxEditor control instance named myeditor on the WPF form) to this CustomSquiggleTagger object, so that typing «My Test Sentence» actually squiggles it?

 

Further information:


 

This is what happens in MainWindow.xaml.cs:

public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();

            // the method defined below is called
            InitEditor(myeditor);

        }

        static void InitEditor(SyntaxEditor myeditor)
        {

            SyntaxLanguageDefinitionSerializer serializer =
                new SyntaxLanguageDefinitionSerializer();               

            ISyntaxLanguage language =
                serializer.LoadFromFile("Simple-Basic.langdef");        

            myeditor.Document.Language = language;                      

            
            myeditor.DocumentTextChanged += Prompter;        /* Prompter(s, e) is a method I use
							     to show a completion list */
        
        }
}

 Thank you very much for your attention, kind regards.

[Modified 3 years ago]

Posted 3 years ago by Actipro Software Support - Cleveland, OH, USA
Avatar

Hello Richard,

Please check out the language class in the AdornmentsSquigglesIntro QuickStart in the samples.  That shows you how you can register a tagger like this with the language.  Then any SyntaxEditor that uses that language on its document will get the tagged used.


Actipro Software Support

Posted 3 years ago by Richard Langin
Avatar

I followed your advice and everything worked perfectly. I found inspiration in this line:

this.RegisterService(new CodeDocumentTaggerProvider<CustomSquiggleTagger>(typeof(CustomSquiggleTagger)));

 (courtesy of the CustomSyntaxLanguage.cs file included in the project AdornmentsSquigglesIntro you pointed out)

Hence in my MainWindow’s code I added:

language.RegisterService(new CodeDocumentTaggerProvider<CustomSquiggleTagger>(typeof(CustomSquiggleTagger)));

and now every occurrence of the string My Test Sentence gets squiggled as soon as it’s typed.

Thank you very much for two reasons: 1) your prompt and enlightening help in this specific issue; 2) the overall increasing confidence I’m gaining in what I can find in the already-made sample files, with my «sight» becoming clearer while I peruse them.


Gratefully, R.

Posted 3 years ago by Actipro Software Support - Cleveland, OH, USA
Avatar

Great, you got it exactly right.  We tried to design SyntaxEditor so everything is more or less done in syntax language services that are registered.  That way the syntax language is portable and can be used in multiple SyntaxEditors at the same time, bringing all the functionality with it.

We try to make a QuickStart for every feature area that focus specifically on some small-ish task in that area.  They can be very helpful starting points for various feature areas.


Actipro Software Support

Posted 6 months ago by Richard Langin
Avatar

Good evening. My question is about the «3b - Language Code Generation» sample code. I’ve perused those files but I cannot actually spot a simple detail, i.e. where the editor knows that its language is going to be the Simple Advanced Language. Whilst in the previous sample we can find

editor.Document.Language = SyntaxEditorHelper.LoadLanguageDefinitionFromResourceStream("Simple-Advanced.langdef");

  in MainControl.xaml.cs, in this sample this statement is omitted in the same file.  Unless I’m very blind, the only anwser I came up with is the following. MainControl.xaml.cs has the following property:

<editor:EditorDocument.Language>
   <sample:SimpleSyntaxLanguage />
</editor:EditorDocument.Language>

and, in the same namespace, the generated

public partial class SimpleSyntaxLanguage

can be found, and the editor automatically detects it. Is this correct?

Thank you very much for your attention.

Posted 6 months ago by Actipro Software Support - Cleveland, OH, USA
Avatar

Hi Richard,

Yes, that's it.  In the 3a QuickStart, we have the editor use the syntax langauge from the .langdef file.  In the 3b QuickStart, we had the Language Designer write out code-behind files instead of a .langdef file.  This allows us to have a type for our language (SimpleSyntaxLanguage) and to be able to reference it directly in XAML, which is handy.

The "sample" XML namespace is defined as:

xmlns:sample="clr-namespace:ActiproSoftware.ProductSamples.SyntaxEditorSamples.QuickStart.GettingStarted03b"

Which is the .NET namespace where that language is.


Actipro Software Support

Posted 6 months ago by Richard Langin
Avatar

Good evening, thank you very much for your previous answer.

My next question is related to this topic:

Language Designer Tool > AST Nodes Configuration Pane > AST Node Configuration > Adding AST Node.

There’s no practical example of a concrete entry, hence I don’t understand how, through this wizard, the created node’s properties relate to other elements in the current language’s grammar, such as classification types. After loading a predefined language (C# in my case) I tried to create AST Nodes with both arbitrary names and names from the classification types list, and the only properties I can set are ID, Key and Inherits. Either way, the «Properties on selected AST Node» pane remain blank.

In this topic:

Text/Parsing Framework > Parsing > AST Nodes > Type-Specific AST Nodes

an example of default AST node is shown, then, without showing the alternative type-specific node (just «ClassDeclaration»?), it is explained that it would be achieved by the following class:

​public class ClassDeclaration : AstNodeBase {
    public string Name { get; set; }
    }

But this «naked» example — which assumes some «ClassDeclaration», maybe as classification type — is another piece among missing pieces of information. In the same paragraph it is also stated that the Language Designer is supposed to take over this class developing job, thus it’d be interesting to see an «extended» version of the previous example, specifically how the AST Node generating this class would look like in the designer.

The issue I’m trying to highlight (which is, of course, also an issue about my understanding of AST Nodes) boils down to:

  1. Could you please give me an example (with any language, e.g. the Simple Language) of AST Node entry in the Language Designer?
  2. In order to increase my understanding of AST Nodes, could you also give me an example of inherited AST Node in the Language Designer?
  3. What exactly the «Properties on selected AST Node» pane is supposed to show?

Thank you very much for your attention and support.

Posted 6 months ago by Actipro Software Support - Cleveland, OH, USA
Avatar

Hi Richard,

First, classification types are related to tokens and help map how syntax highlighting should be applied.  Classification types don't really related to grammars.

When the top node declarations list is focused in the "AST Nodes" tab, the Properties tool window will show Id, Key, and Inherits for the selected nodes.  You generally leave Id blank.  You want Key to be the class name generated for the node.  And Inherits lets you have one AST node inherit another one.  To better clarify this, we will add this verbiage to the documentation topic section you referenced:

For instance, if you are building a set of expression-related AST nodes for a syntax language, you might start with adding an Expression base AST node. Then add other AST nodes with keys like LiteralExpression, ParenthesizedExpression, UnaryExpression, and so on and set each of their Inherits values to be the base Expression AST node. That way, any productions in your grammar that deal with general expressions can return an AST node of type Expression and any of the expression implementation AST node types can be returned since they inherit Expression.

For the "Type-Specific AST Nodes" section in that other topic, the "ClassDeclaration" is a type-specific AST node.  The Language Designer can generate classes like that "ClassDeclaration" based on what you enter on the "AST Nodes" tab.  Please see below for a reference to a full example.

Back on your questions...

1/2) There is a full example of AST Nodes with inheritance defined in this language project:  "SampleBrowser\ProductSamples\SyntaxEditorSamples\Languages\Projects\Simple-Advanced.langproj"  This language project is used to generate the AST nodes seen in the "Getting Started #4d" QuickStart.

3) You need to add properties that make sense to each AST node.  The "Properties on selected AST node" will be empty by default since you haven't defined anything yet.  

We are adding this to the documentation topic as well:

For instance, a ParenthesizedExpression AST node would likely need a property named ChildExpression added, which would be an AstNode property type, and its Type would be Expression.


Actipro Software Support

Posted 6 months ago by Richard Langin
Avatar

The greatest benefit from your kind answer is mainly understanding that:

  1. I have to study more (of course: that’s the required background for well-posed questions against wrong assumptions);
  2. I’m maybe seeing the light about one point (one more wrong assumption envolved): your Language Designer has nothing to do with the construction of a grammar and its productions, except for the AST Nodes, objects that a grammar may use.

Thank you very much for your patience and help.

Posted 6 months ago by Actipro Software Support - Cleveland, OH, USA
Avatar

Hi Richard,

Correct, the Language Designer helps code generate language services for lexers / syntax highlighting, and type-specific AST nodes that can be used with a grammar.  But it doesn't help code the grammar itself.  It does have a debugger that can load up a LL(*) Parser Framework grammar and can help debug problems with it though.


Actipro Software Support

The latest build of this product (v2019.1 build 0686) was released 1 month ago, which was after the last post in this thread.

Add Comment

Please log in to a validated account to post comments.