Macro commands

Manual of easyChem macrocommands using

This article provides an overview of all the macrocommand's features of the CharChem system and contains examples.
Macrocommands (or macros) are powerful tool to automate the description of similar components. Although they did not make any specific ways to describe chemical structures, but it can improve the efficiency of the entire instrument as a whole.
For a better understanding of the proposed examples desirable to get introduced to the procedure of describing the structural formulas.

Quick Reference / Contents

Cheatsheet contains all the basic syntax in summary form. And links to more detailed explanation.

Action	Example	The result of the post-processing
Simplest declaration	`@:MyMacro()...some text...@;`
Call the macros	`@MyMacro()`	...some text...
Simultaneous declaration and call the macro	`@MyMacro()...some text...@()`	...some text...
The use of positional parameters	`@:MyMacro(a,b)...&a...&b...@(First,Second)`	...First...Second...
Using named parameters	`@:MyMacro(a,b)...&a...&b...@(b:Second,a:First)`	...First...Second...
Default values	`@:MyMacro(a:First,b:Second)...&a...&b...@() @MyMacro(,Last)`	...First...Second... ...First...Last...
Recursive calls	`@:MyMacro(a,b)[&a...&b]@(@MyMacro(A,B),@MyMacro(C,D))`	[[A...B]...[C...D]]

Creating a simple macro and its call

Suppose you want to describe the reaction of acetic acid with alkali.

$C()H3C-C<//O>\O-H + NaOH -> $C()H3C-C<//O>\O-Na + H2O <=> H3C-C<//O>\O^- + Na^+ + H2O

One can see that there are three times repeated a big chunk of a molecule of acetic acid. Let's define it as a macro.
Details describing the macros are in bold.

@:Ac()$C()H3C-C<//O>\O@;
@Ac()-H + NaOH -> @Ac()-Na + H2O <=> @Ac()^- + Na^+ + H2O

Here we see that the macro is described by design @:Name(). . . @;
Invoked via @Name(). Name should be a word that begins with a letter.
Names are case sensitive. That is, ABC and Abc - different names.

Declared macro can be used later in the text. He is a global definition. For example, we can use it in another formula:

@Ac()-CH3

Simultaneous announcement and use macros

There is a way to both describe and use macros. To do this, at the end of the definition instead @; to use @().
Our previous example can be rewritten as:

@:Ac()$C()H3C-C<//O>\O@()-H + NaOH -> @Ac()-Na + H2O <=> @Ac()^- + Na^+ + H2O

Using parameters

The next step is the use of macro parameters. Example with acetic acid can be rewritten as:

@:Ac(x)$C()H3C-C<//O>\O&x@(-H) + NaOH -> @Ac(-Na) + H2O <=> @Ac(^-) + Na^+ + H2O

Here we see the parameter x. He declared in parentheses, and used with &x. Parameter name must be a word that starts with a letter, then may follow other letters or numbers.
However, in this example, there is little to gain from the using of parameter. But here is illustrates the redefining the macro. We have created a new macro with the same name. It replaced the old macro. Those calls that used without the parameter can not be applied after the declaration of the new macro.

Consider a more complicated example, where you need two parameters. Suppose we have to represent something like a crystal lattice, where the two elements are alternated in a checkerboard pattern. For more expressive color the items in red and blue. First, make a prototype, where the elements are sodium and chlorine:

{}_(x.8,H)$color(red)Na$color()_(x1.4,H)$color(blue)Cl$color()_(x.8,H)"";
""_(x.8,H)$color(blue)Cl$color()_(x1.4,H)$color(red)Na$color()_(x.8,H)"";
""|h#-8|h#-4|h"";""|h#-9|h#-5|h""

Description turned out not too simple. But the more reason to automate it for later use. Translate the prototype into a macro, replacing Na and Cl in the parameters. Call them a and b. And let the macro is called Cross.

@:Cross(a,b){}_(x.8,H)$color(red)&a$color()_(x1.4,H)$color(blue)&b$color()_(x.8,H)"";
""_(x.8,H)$color(blue)&b$color()_(x1.4,H)$color(red)&a$color()_(x.8,H)"";
""|h#-8|h#-4|h"";""|h#-9|h#-5|h""@;
{Cross demo:}_(x2,h,N0)""@Cross(Na,Cl)

But now we got a pretty strong design:

@Cross(K,Br) @Cross(Li,F) @Cross(Ga,As)

Positional and named parameters

Suppose we want to create a macro that defines the benzene derivatives. To do this, we place into nodes parameters with numbers corresponding to the nomenclature of IUPAC.

@:Ph(n1,n2,n3,n4,n5,n6)&n1\\&n2|&n3`//&n4`\&n5`||&n6/@()

Although we have announced as much as 6 parameters, but for the first demo, we did not use any. The result is a simple benzene. But now we can make this design of toluene, indicating in the first position of a methyl group.

@Ph(CH3|)

But this is only a small part of how we can use the resulting macro. Depict the ortho-, meta-, and para-cresol by connecting a hydroxyl group at position 2, 3, and 4, respectively:

@Ph(CH3|,</OH>) @Ph(CH3|,,<\OH>) @Ph(CH3|,,,<|OH>)

Here we used the positional substitution, skipping the nodes that do not need to fill out. But you can immediately specify the name of the parameter is needed:

The first parameter for the first three molecules is given by position. Because he was the first and so, why write too much? The second parameter is specified by name.
All parameters In the last molecule are named. In her 6th parameter is specified before the 2 nd. Because it does not matter in what order are the named parameters.

It should be clear that we have a certain feature in the description of the macro associated with the use of parameters. The first parameter is the beginning of the chain, and the other must be in the branch. Therefore, the < > are used for all parameters except the first. However, we can describe the pyridine, if you specify the nitrogen in the 4th parameter. In this case, the branch is not needed:

@Ph(n4:N)

The use of default values

Further improvement in the description of the macro is to use parameters with preset values (default values). This allows you to describe the rather complex structure with a convenient way to make small changes. For example, to perform the improvement described above macro Cross. We give the user the ability to influence the color of the items and the length of links. To do this, add the parameters colorA and colorB, which through a sign : set desired values red and blue. The length of the central bond is set by parameter len1:1.4, and lateral bond - len2:0.8.

@:Cross(a,b,colorA:red,colorB:blue,len1:1.4,len2:0.8)#
{}_(x&len2,H)$itemColor(&colorA)&a$itemColor()_(x&len1,H)$itemColor(&colorB)&b$itemColor()_(x&len2,H)"";
""_(x&len2,H)$itemColor(&colorB)&b$itemColor()_(x&len1,H)$itemColor(&colorA)&a$itemColor()_(x&len2,H)"";
""_(y&len2,H)#-8_(y&len1,H)#-4_(y&len2,H)"";
""_(y&len2,H)#-9_(H)#-5_(y&len2,H)""@;
@Cross(Na,Cl)

Please note that after the improvements remain possible to use a macro in the same way as before. This ensures that all the previous work which contains a reference to a macro not require alteration. But you can use the new features where you need it:

@Cross(K,Br,colorB:darkmagenta,len1:2,len2:1.5)
$color(blue)@Cross(Fe,Cl,len2:1,colorA:black,colorB:darkgreen)$color()
$color(#888)@Cross({[+]},{[-]},len2:0.1,colorA:,colorB:)$color()

The first structure shows enhanced using a macro with optional parameters.
The second structure uses an external description of the color line.
The third structure demonstrates the ability to cancel those default values that are set in the description of the macro. So, instead of $itemColor(red) will be used $itemColor(), which does not affect the color you have created.

Consider a simple but practical example. Let's say we are working on article on amino acids. This is where you show different reactions, including the formation of the peptide bond. It is desirable to provide a common style for displaying amino acids that the reader will pay attention to the important features, without wasting time on the details. It needs to develop a macro where it will be possible to determine the radical and if necessary, modify the amino depicted by the left and the carboxyl group with the right.

@:AminoAcid(r:{R},a:H-,c:OH,rcol:blue)&a$C()N<`|H&>-C<`|H><|$color(&rcol)&r$color()>-C<`||O>-&c@()

We have a powerful tool that can easily handle. (Except for proline, which does not fit into this scheme).
Draw a few amino acids: alanine, methionine and glutamine:

@AminoAcid(CH3) @AminoAcid(CH2|CH2|S|CH3) @AminoAcid(CH2|CH2|C`/O/\NH2)

Now picture for these molecules react with the formation of the peptide bond.

@AminoAcid(CH3) + @AminoAcid(CH2|CH2|S|CH3) + @AminoAcid(CH2|CH2|C`/O/\NH2) -> @AminoAcid(CH3,c:)@AminoAcid(CH2|CH2|S|CH3,a:,c:)@AminoAcid(CH2|CH2|C`/O/\NH2,a:) + 2H2O

Recursive call macros

From the last example shows that a good idea to introduce a separate description for amino acids, not to list every time their radicals in the parameters. We describe three macros for the above-mentioned amino acids.

@:Ala(a,c)@AminoAcid(CH3,&a,&c)@;
@:Met(a,c)@AminoAcid(CH2|CH2|S|CH3,&a,&c)@;
@:Gln(a,c)@AminoAcid(CH2|CH2|C`/O/\NH2,&a,&c)@;

Rewrite expression with the formation of the peptide bond

@Ala() + @Met() + @Gln() -> @Ala(c:# )@Met(# ,# )@Gln(a:# )

There had clearly pointed out that the ground connections amino and carboxyl group is set to an empty place. To do this, use #(space). This is a compromise associated with a particular way to declare a macro. To obtain @Ala, similar to the behavior of @AminoAcid, one would have to use a more complex record:

@:Ala(a:H-,c:OH)@AminoAcid(CH3,a:&a,c:&c)@;
@Ala() -> {R1}-@Ala(a:,c:){R2}

Here everything is in the hands of the author of the macro. He can choose where to apply which method.:

Try to combine the developed macros @AminoAcid and @Ph to describe the aromatic amino acids phenylalanine and tyrosine. Both methyl group is joined to node 1, and in the tyrosine hydroxyl group - to node 4.

@:Phe(a,c)@AminoAcid(@Ph(CH2|),&a,&c)@()
+ @:Tyr(a,c)@AminoAcid(@Ph(CH2|,n4:<|OH>),&a,&c)@() =
@Phe(c:# )@Tyr(a:# ) + H2O

Well, another example where we use nested call @ Cross to create a larger structure.

@:Cross1(a,b,colorA:red,colorB:blue)@Cross(&a,&b,colorA:&colorA,colorB:&colorB,len1:2,len2:1)@;
@:Cross2(a,b,colorA:red,colorB:blue)@Cross1(&a,&b,colorA:&colorA,colorB:&colorB)_(x1,y-3,N0)# @Cross1(&a,&b,colorA:&colorA,colorB:&colorB)@;
@:Cross4(a,b,colorA:red,colorB:blue)@Cross2(&a,&b,colorA:&colorA,colorB:&colorB)_(x-7,y1,N0)# @Cross2(&a,&b,colorA:&colorA,colorB:&colorB)@;
@Cross1(Na,Cl) -> @Cross2(Na,Cl,colorB:green) -> @Cross4(Na,Cl)

Conclusion

To sum up. The use of macros allows you to:

reduce the description for formulas with the same type of content;
reduce the complexity of the description by the decomposition;
avoid typing errors that appear in the duplication of information similar in composition;
undertake improvements in macro that will automatically apply to the rest of the text.

The downside is the additional time associated with the study of this topic. In addition, the description of the macro will require a bit more work and time than a description of the formula. The more universal functionality, the more it will take time for testing and debugging.