Documentation

Configure tags

First of all you need to configure the tags you want to parse. This configuration can either be done programmatically or using an external configuration file in XML format.

To configure a tag programmatically, you need to create an object of the TagConfiguration class for each tag you want to use. To the constructor, there are two mandatory and two optional parameters. The first parameter contains the BBCode you want to configure. Please note that you do not need to specify the tag's square brackets.

The second parameter contains the text you want to replace the tag with. In codeparser.net, there are two types of tags: Single tags and paired tags. A single tag appears alone and does not have any content, a paired tag always consists of an opening and a closing tag. Since paired tags always have content between their opening and closing tag, codeparser.net is able to determine the tag type automatically.

If you want to use a single tag, just provide the replacement and everything is fine. This is useful for tags like smileys or other images where the tag only shall be replaced by a smiley or an image. However, if you want to use a paired tag, provide the expression {0} within the replacement. This is the placeholder for the content.

C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

using codeparser.net;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new tag configuration for the [flagEU] tag. Note
        // that [flagEU] is a single tag, since {0} is NOT provided
        // within the replacement.
        TagConfiguration tagConfigurationFlagEU =
            new TagConfiguration("flagEU", "<img src=\"flagEU.png\" />");

        // Create a new tag configuration for the [b] tag. Note
        // that [b] is a paired tag, since {0} is provided within
        // the replacement.
        TagConfiguration tagConfigurationBold =
            new TagConfiguration("b", "<strong>{0}</strong>");
    }
}
Moreover, sometimes there is the need for a paired tag whose content shall not be parsed any further. E.g., this might be useful for a [code] tag. That is what the third - optional - parameter is for: If you set it to false, the tag's content is not parsed. If you do not provide the parameter, it has the same effect as setting it to true: The tag's content will be parsed.
C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

using codeparser.net;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new tag configuration for the [flagEU] tag. Note
        // that [flagEU] is a single tag, since {0} is NOT provided
        // within the replacement.
        TagConfiguration tagConfigurationFlagEU =
            new TagConfiguration("flagEU", "<img src=\"flagEU.png\" />");

        // Create a new tag configuration for the [b] tag. Note
        // that [b] is a paired tag, since {0} is provided within
        // the replacement.
        TagConfiguration tagConfigurationBold =
            new TagConfiguration("b", "<strong>{0}</strong>");

        // Create a new tag configuration for the [code] tag. Note
        // that [code] is a paired tag whose content shall not be
        // parsed.
        TagConfiguration tagConfigurationCode =
            new TagConfiguration("code", "<div>{0}</div>", false);
    }
}
If you need to pass parameters to a tag you can use the expressions {1} for the first parameter, {2} for the second, ...
C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

using codeparser.net;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new tag configuration for the [flagEU] tag. Note
        // that [flagEU] is a single tag, since {0} is NOT provided
        // within the replacement.
        TagConfiguration tagConfigurationFlagEU =
            new TagConfiguration("flagEU", "<img src=\"flagEU.png\" />");

        // Create a new tag configuration for the [b] tag. Note
        // that [b] is a paired tag, since {0} is provided within
        // the replacement.
        TagConfiguration tagConfigurationBold =
            new TagConfiguration("b", "<strong>{0}</strong>");

        // Create a new tag configuration for the [code] tag. Note
        // that [code] is a paired tag whose content shall not be
        // parsed.
        TagConfiguration tagConfigurationCode =
            new TagConfiguration("code", "<div>{0}</div>", false);

        // Create a new tag configuration for the [url] tag. Note
        // that [url] is a paired tag with a parameter.
        TagConfiguration tagConfigurationUrl =
            new TagConfiguration("url", "<a href=\"{1}\">{0}</a>");
    }
}
Since version 1.1 codeparser.net additionally provides the possibility to perform syntax highlighting within [code] tags. To enable syntax highlighting, you need to specify the language for syntax highlighting as fourth parameter. The following languages are currently supported:

ASPX, C, Cobol, ColdFusion, C++, C#, CSS, Eiffel, Fortran, Haskell, Java, JavaScript, JScript, Mercury, MSIL, Pascal, Perl, PHP, Python, Ruby, SQL, Visual Basic, VBScript, XML

C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

using codeparser.net;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new tag configuration for the [flagEU] tag. Note
        // that [flagEU] is a single tag, since {0} is NOT provided
        // within the replacement.
        TagConfiguration tagConfigurationFlagEU =
            new TagConfiguration("flagEU", "<img src=\"flagEU.png\" />");

        // Create a new tag configuration for the [b] tag. Note
        // that [b] is a paired tag, since {0} is provided within
        // the replacement.
        TagConfiguration tagConfigurationBold =
            new TagConfiguration("b", "<strong>{0}</strong>");

        // Create a new tag configuration for the [code] tag. Note
        // that [code] is a paired tag whose content shall not be
        // parsed. Enable syntax highlighting for C#.
        TagConfiguration tagConfigurationCode =
            new TagConfiguration("code", "<div>{0}</div>", false, "C#");

        // Create a new tag configuration for the [url] tag. Note
        // that [url] is a paired tag with a parameter.
        TagConfiguration tagConfigurationUrl =
            new TagConfiguration("url", "<a href=\"{1}\">{0}</a>");
    }
}
Since configuring tags programmatically may be impractical in situations where you need to change tag configuration often and you do not want to recompile every time, there is the possibility to store the configuration within an XML file. Please note that you may need to mask some characters that have a special meaning within XML like <, >, & or ".
XML 
1
2
3
4
5
6
7
8
9
10

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <tags>
    <tag name="flagEU" replacement="&lt;img src=&quot;flagEU.png&quot; /&gt;" />
    <tag name="b" replacement="&lt;strong&gt;{0}&lt;/strong&gt;" />
    <tag name="code" replacement="&lt;div&gt;{0}&lt;/div&gt;"
      parseContent="False" contentHighlighter="C#" />
    <tag name="url" replacement="&lt;a href=&quot;{1}&quot;&gt;{0}&lt;/a&gt;" />
  </tags>
</configuration>
Since version 1.2 of codeparser.net it is possible to specify an alternative replacement for each tag that may be used to allow an alternative syntax for the tag. To use this function you need to specify the optional parameter alternativeReplacement that is used as fallback.
XML 
1
2
3
4
5
6
7
8
9
10
11

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <tags>
    <tag name="flagEU" replacement="&lt;img src=&quot;flagEU.png&quot; /&gt;" />
    <tag name="b" replacement="&lt;strong&gt;{0}&lt;/strong&gt;" />
    <tag name="code" replacement="&lt;div&gt;{0}&lt;/div&gt;"
      parseContent="False" contentHighlighter="C#" />
    <tag name="url" replacement="&lt;a href=&quot;{1}&quot;&gt;{0}&lt;/a&gt;"
      alternativeReplacement="&lt;a href=&quot;{0}&quot;&gt;{0}&lt;/a&gt;" />
  </tags>
</configuration>

Configure parser

After you have set up your tag configuration, you need to create a parser configuration that contains all tag configurations you want to use. This is neccessary for being able to specify different parser configurations for different contexts.

No matter how you have set up your tag configuration, first you need to create an object of the ParserConfiguration class. Since version 1.3 of codeparser.net you can declare that invalid tags get ignored by the parser. To do so, add the parameter throwExceptionOnInvalidTag to the constructor and set its value to false.

C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

using codeparser.net;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new tag configuration for the [flagEU] tag. Note
        // that [flagEU] is a single tag, since {0} is NOT provided
        // within the replacement.
        TagConfiguration tagConfigurationFlagEU =
            new TagConfiguration("flagEU", "<img src=\"flagEU.png\" />");

        // Create a new tag configuration for the [b] tag. Note
        // that [b] is a paired tag, since {0} is provided within
        // the replacement.
        TagConfiguration tagConfigurationBold =
            new TagConfiguration("b", "<strong>{0}</strong>");

        // Create a new tag configuration for the [code] tag. Note
        // that [code] is a paired tag whose content shall not be
        // parsed. Enable syntax highlighting for C#.
        TagConfiguration tagConfigurationCode =
            new TagConfiguration("code", "<div>{0}</div>", false, "C#");

        // Create a new tag configuration for the [url] tag. Note
        // that [url] is a paired tag with a parameter.
        TagConfiguration tagConfigurationUrl =
            new TagConfiguration("url", "<a href=\"{1}\">{0}</a>");

        // Create a new parser configuration.
        ParserConfiguration parserConfiguration =
            new ParserConfiguration();
    }
}
Now you are able to add the tag configurations to your parser configuration. If you have set up the tag configurations programmatically, you have to use the Add method of the parserConfiguration object's TagConfigurations property.
C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

using codeparser.net;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new tag configuration for the [flagEU] tag. Note
        // that [flagEU] is a single tag, since {0} is NOT provided
        // within the replacement.
        TagConfiguration tagConfigurationFlagEU =
            new TagConfiguration("flagEU", "<img src=\"flagEU.png\" />");

        // Create a new tag configuration for the [b] tag. Note
        // that [b] is a paired tag, since {0} is provided within
        // the replacement.
        TagConfiguration tagConfigurationBold =
            new TagConfiguration("b", "<strong>{0}</strong>");

        // Create a new tag configuration for the [code] tag. Note
        // that [code] is a paired tag whose content shall not be
        // parsed. Enable syntax highlighting for C#.
        TagConfiguration tagConfigurationCode =
            new TagConfiguration("code", "<div>{0}</div>", false, "C#");

        // Create a new tag configuration for the [url] tag. Note
        // that [url] is a paired tag with a parameter.
        TagConfiguration tagConfigurationUrl =
            new TagConfiguration("url", "<a href=\"{1}\">{0}</a>");

        // Create a new parser configuration.
        ParserConfiguration parserConfiguration =
            new ParserConfiguration();

        // Add the tag configurations to the parser configuration.
        parserConfiguration.TagConfigurations.Add(tagConfigurationFlagEU);
        parserConfiguration.TagConfigurations.Add(tagConfigurationBold);
        parserConfiguration.TagConfigurations.Add(tagConfigurationCode);
        parserConfiguration.TagConfigurations.Add(tagConfigurationUrl);
    }
}
Since version 1.4 codeparser.net supports so-called expression replacements. You can use them to replace arbitrary string by arbitrary replacements - at every occurence within the text, except the parts whose parseContent attribute is set to false.
C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

using codeparser.net;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new tag configuration for the [flagEU] tag. Note
        // that [flagEU] is a single tag, since {0} is NOT provided
        // within the replacement.
        TagConfiguration tagConfigurationFlagEU =
            new TagConfiguration("flagEU", "<img src=\"flagEU.png\" />");

        // Create a new tag configuration for the [b] tag. Note
        // that [b] is a paired tag, since {0} is provided within
        // the replacement.
        TagConfiguration tagConfigurationBold =
            new TagConfiguration("b", "<strong>{0}</strong>");

        // Create a new tag configuration for the [code] tag. Note
        // that [code] is a paired tag whose content shall not be
        // parsed. Enable syntax highlighting for C#.
        TagConfiguration tagConfigurationCode =
            new TagConfiguration("code", "<div>{0}</div>", false, "C#");

        // Create a new tag configuration for the [url] tag. Note
        // that [url] is a paired tag with a parameter.
        TagConfiguration tagConfigurationUrl =
            new TagConfiguration("url", "<a href=\"{1}\">{0}</a>");

        // Create a new parser configuration.
        ParserConfiguration parserConfiguration =
            new ParserConfiguration();

        // Add the tag configurations to the parser configuration.
        parserConfiguration.TagConfigurations.Add(tagConfigurationFlagEU);
        parserConfiguration.TagConfigurations.Add(tagConfigurationBold);
        parserConfiguration.TagConfigurations.Add(tagConfigurationCode);
        parserConfiguration.TagConfigurations.Add(tagConfigurationUrl);

        // Add the expression replacements.
        parserConfiguration.ExpressionReplacements.Add(
            new ExpressionReplacement("\n", "<br />"));
    }
}
If instead you have set up your tags using a configuration file, you have to use the parserConfiguration object's LoadConfigurationFromXml method. As single parameter you need to specify the configuration file you want to load.
C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

using codeparser.net;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new parser configuration.
        ParserConfiguration parserConfiguration =
            new ParserConfiguration();

        // Load the tag configuration from the specified file.
        parserConfiguration.LoadConfigurationFromXml("Configuration.xml");
    }
}
Please note that you may call the LoadConfigurationFromXml method more than one to load more than one configuration file. Especially if you are using our extensions this is an easy way to import only those extensions you want to.

Since version 1.3 of codeparser.net you are able to declare within the configuration file, too, that invalid tags get ignored by the parser. To do so, add an element parser, add a sub-element to this element called throwExceptionOnInvalidTag and set its value to False.

XML 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <parser>
    <throwExceptionOnInvalidTag value="False" />
    <expressionReplacements>
      <expressionReplacement expression="\n" replacement="&lt;br /&gt;" />
    </expressionReplacements>
  </parser>
  <tags>
    <tag name="flagEU" replacement="&lt;img src=&quot;flagEU.png&quot; /&gt;" />
    <tag name="b" replacement="&lt;strong&gt;{0}&lt;/strong&gt;" />
    <tag name="code" replacement="&lt;div&gt;{0}&lt;/div&gt;"
      parseContent="False" contentHighlighter="C#" />
    <tag name="url" replacement="&lt;a href=&quot;{1}&quot;&gt;{0}&lt;/a&gt;"
      alternativeReplacement="&lt;a href=&quot;{0}&quot;&gt;{0}&lt;/a&gt;" />
  </tags>
</configuration>

Parse code

Finally, you need to create an object of the Parser class and provide the parser configuration as parameter to the constructor.

C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

using codeparser.net;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new parser configuration.
        ParserConfiguration parserConfiguration =
            new ParserConfiguration();

        // Load the tag configuration from the specified file.
        parserConfiguration.LoadConfigurationFromXml("Configuration.xml");

        // Create a parser object and provide the parser configuration.
        Parser parser = new Parser(parserConfiguration);
    }
}
Now you are ready to parse texts for BBCode and replacing them by expressions you defined.
C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

using codeparser.net;

using System;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new parser configuration.
        ParserConfiguration parserConfiguration =
            new ParserConfiguration();

        // Load the tag configuration from the specified file.
        parserConfiguration.LoadConfigurationFromXml("Configuration.xml");

        // Create a parser object and provide the parser configuration.
        Parser parser = new Parser(parserConfiguration);

        // Parse a sample text;
        string text =
            "This is a [b]test[/b] with a [url=http://wwwcodeparser.net]link[/url].";
        string parsedText = parser.Parse(text);
        Console.WriteLine(parsedText);
        Console.ReadLine();
    }
}
Note that if you want to specify a left squared bracket you need to mask it by providing it twice. Otherwise codeparser.net would try to interpret it as the beginning of a tag.
C# 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

using codeparser.net;

using System;

/// <summary>
/// Contains the program.
/// </summary>
public class Program
{
    /// <summary>
    /// Executes when the application starts.
    /// </summary>
    public static void Main()
    {
        // Create a new parser configuration.
        ParserConfiguration parserConfiguration =
            new ParserConfiguration();

        // Load the tag configuration from the specified file.
        parserConfiguration.LoadConfigurationFromXml("Configuration.xml");

        // Create a parser object and provide the parser configuration.
        Parser parser = new Parser(parserConfiguration);

        // Parse a sample text;
        string text =
            "This is a [b]test[/b] with a left bracket: [[.";
        string parsedText = parser.Parse(text);
        Console.WriteLine(parsedText);
        Console.ReadLine();
    }
}