AutoCode Walkthrough
In this Walkthrough, you will learn different features of AutoCode command templates that will help you understand the potential of AutoCode code generation. The major steps for this walkthrough are as follows: - Hello World Example - to understand a simple command
- Using Arguments - to generate parameterized code
- Specifying Where to Insert Code - beginning of current method, end of the class, etc.
- Multiple Code Insertion in Different Positions - for code surround and more
- Cursor Positioning - after the code is generated
- Code Formatting - to maintain document well formated
Hello World Example The following is a simple command that generates "Hello World!" in the current edition position. <?xml version="1.0"?>
<Commands xmlns="http://schemas.devprojects.net/AutoCode/v3.0">
<Command name="HelloWorld">
<CommandBehavior>
<CommandLine shortcut="hw" />
</CommandBehavior>
<CommandCode language="csharp">
<Codes>
<Code>
Console.WriteLine( "Hello World!" );
</Code>
</Codes>
</CommandCode>
</Command>
</Commands>
The key elements of this command are:
<Command name="HelloWorld">
The name of the command as will be show in the AutoCode Catalog.
<CommandLine shortcut="hw" />
The shortcut to invoke the command.
<Code>
Console.WriteLine( “Hello World!” );
</Code>
The literal code that will be generated.
Using Arguments
To make this command more useful lets parameterize the code changing the literal “Hello World!” to an input parameter.
<Code> <![CDATA[
Console.WriteLine( “Hello <%=args[0]%>!” );
]]>
</Code>
Note that we escaped the Code with <![CDATA[]]> because of the ‘<’ and ‘>’ characters.
Now, if we press Ctrl+Enter and then write “Summer hw” we generate this.
Console.WriteLine(“Hello Summer!”);
Invoking an AutoCode command is similar to invoking an application from a command prompt, although in AutoCode the shortcut usually goes at the end of the line like in the following example:
arg0 arg1 arg2 argN shortcut
Shortcut Position
By default, shortcut goes at the end of the command line. The reason for this is not to mess up with Intellisense and let it suggest the correct key words. If the shortcut were the first word, intellisense won’t be able to help us.
Anyway, if we want the shortcut to go first, we still can declare the command as follows.
<CommandLine shortcut="hw" shortcutPosition="First" />
And now we can invoke our command as “hw Summer” instead.
Arguments Delimiter
By default, arguments are separated by a space character.
This is the preferred for most of the commands, but there are some cases were we want to change this.
For example, in our HelloWorld command we may want to use spaces inside the argument but that will be interpreted as different arguments. To instruct our command to use the literal as a single argument we can specify a different argument delimiter as follows.
<CommandLine shortcut="hw" shortcutPosition="First" delimiter="#" />
Now, we can write:
Summer, how are you hw <Ctrl+Enter>
And will generate:
Console.WriteLine(“Hello Summer, how are you!”);
Note that we still can use more that one argument using ‘#’ as the argument delimiter.
Specifying Where Insert the Code
By default, generated code is inserted in the current position.
To insert the code in, for example, the beginning of the document, we can specify the following:
<Codes>
<Code codeElement="Document" codePoint="StartOfDocument">
<![CDATA[using <%=args[0]%>;]]>
</Code>
</Codes>
This will generate a using statement at the beginning of the document, while the edit position will remain in the current position.
The codeElement attribute specify which element (Document, Class, Method, etc.) while the codePoint specify where in the element to insert the code (StartofDocument, StartOfBody, EndOfElement, etc.);
Here are some other combinations.
Beginning of the class code
<Code codeElement="Class" codePoint="StartOfBody">
Before the Property declaration, just in the attributes decoration
<Code codeElement="Property" codePoint=" StartOfAttributes">
Beginning of the Selected text (the default)
<Code codeElement="Selection" codePoint="StartOfSelection">
End of the Selected text (usefull for code surround)
<Code codeElement="Selection" codePoint="EndOfSelection">
Multiple Code Insertions in Different Positions
We can generate different piece of code and insert it in different positions.
For example, to surround the current selection we will want to insert code at the beginning of the selected text and at the end of the selected text.
The following example surrounds the selected code with an IF THEN sentence in VB.NET.
<Code codeElement="Selection" codePoint="StartOfElement">
If Then
</Code>
<Code codeElement="Selection" codePoint="EndOfElement">
End If
</Code>
Referencing Generated Code
Sometimes we will want to reference generated code position, for example, to set the cursor position at the beginning of the generated code or even to insert more code at the end.
The ID attribute of the <Code> element identify the code. For example:
<Code id=”BeginIF”>
If Then
</Code>
<Code id=”EndIF”>
End If
</Code>
Now we can reference “BeginIF” or “EndIF” as codeElements. For example:
<Code codeElement="BeginIF" codePoint="EndOfElement">
‘ This will be inserted between “IF Then” and “End If”
</Code>
Also we can reference “BeginIF” or “EndIF” to position the cursor after the code insertion as described below.
Cursor Positioning
To position the cursor in a specific location after the code generation we can use the <Selection> tag.
The <Selection> tag uses the codeElement and codePoint attributes in a similar way as the <Code> tag.
For example, to position the cursor at the beginning of the “BeginIF” code:
<Selection codeElement="BeginIF" codePoint="StartOfElement" />
If we want to move the cursor inside the generated code we can use the <SelectText> attribute as follows:
<Selection codeElement="BeginIF" codePoint="StartOfElement">
<SelectText>Then</SelectText>
</Selection>
This will select the word “Then” of the generated code. Actually, we are instructing AutoCode to position the cursor at the beginning of the “BeginIF” and search for the word “Then” and select it.
The trick to position the cursor exactly where we want is to generate a mark word and select that mark. For example:
<Code id=”BeginIF”>
If SELECT_THIS Then
</Code>
<Selection codeElement="BeginIF" codePoint="StartOfElement">
<SelectText>SELECT_THIS</SelectText>
</Selection>
Finally, to hide our trick we can clear the selection with the clearSelection attribute so our mask SELECT_THIS won’t show.
<Selection codeElement="BeginIF" codePoint="StartOfElement" clearSelection="true">
<SelectText>SELECT_THIS</SelectText>
</Selection>
Formatting Code
When using multiple code insertions the generated code may appear unformatted. To avoid this the <SmartFormat> element can be used.
The following example will format the code from the beginning of the generated code identify as “BeginIF” to the end of the generated code “EndIF”.
<SmartFormat>
<Start codeElement="BeginIF" codePoint="StartOfElement" />
<End codeElement="EndIF" codePoint="EndOfElement" />
</SmartFormat>
If the code is inserted in different parts of the current function or class we can always specify the whole function or class:
<SmartFormat>
<Start codeElement="Class" codePoint="StartOfElement" />
<End codeElement="Class" codePoint="EndOfElement" />
</SmartFormat>
This will format the whole Class after the code generation.
Next Steps
After this Walkthrough you may be interested in creating your own commands and test different concepts explained here.
The fastest way to create your custom command is using the Command Generation Wizard.
The Command Generation Wizard is just a built in command (AX) that can be invoked as usual pressing Ctrl+Enter and specifying the name and shortcut of the command. For example:
- Press Ctrl+Enter
- Input “HelloWorld hw AX” in the input box
- Press enter
For more information see Creating a Custom Command.
|