TextConverter

References

With the help of references, content from the text or the file to be processed as well as content from any other text files can be used in the text fields of most actions and functions of the TextConverter. For example, this content can be characters, words, lines, CSV cells, inner XML texts, XML attribute values or an entire file. In this tutorial, we would like to explain how you can use these references in the TextConverter and how you can optionally edit the referenced content before inserting based on explanations and many examples. The tutorial is divided into the following sections:

Basics of using References

References are a special type of placeholders, with which you can use single as well as multiple characters, words or lines, the content of cells from CSV data, components from an XML structure such as inner texts and attribute values or entire files as well as combinations of these components in the functions and actions of the TextConverter as if you would write the respective text directly into the corresponding fields.

In order to be able to use references, the following option must first be activated in the Text Converter:

Actions > Options > References

All placeholders for references are starting with "%ref:" and ending with "%". In between, single references as well as an arbitrary number of references and functional placeholders can be used in any order combined with a ">". For example, the placeholder

%ref:line=1%

stands for the first line of the current file or the current text and the placeholder

%ref:file=E:\File.txt%

stands for the entire content of the file "E:\File.txt". We can combine these two references with the character ">" to the following placeholder:

%ref:file=E:\File.txt>line=1%.

Accordingly, this combined placeholder then stands for the first line of the file "E:\File.txt". If we use %ref:line=1% alone instead, the placeholder stands for the first line of the text that is being edited. As long as there is no reference to another file in a placeholder, all placeholders presented in this tutorial always refer to the text or file that is being processed.

When combining references, there is no limit for nesting. For example, you could also create the following placeholder, which contains four different references that relate to each other:

%ref:file=E:\File.txt>line=2>word=3>char=1%

This placeholder then stands for the first character of the third word of the second line of the file "E:\File.txt".

In addition, the placeholders for references can also be combined with functional placeholders with which the text can be changed or edited before inserting. One example would be the following placeholder:

%ref:line=1>trim=whitespace>chars=1-3>write=uppercase%

When this placeholder is dissolved, first, the text from the first line is read out via a line reference. After that, all whitespace characters (such as spaces or tabs) are removed from the front and rear using the functional placeholder for trimming text. Then, the first three characters are extracted via a character reference and converted into capital letters using the functional placeholder for changing the writing. As you can see, the functional placeholders can be inserted at any place and always edit the text at hand up to this point. You can find out more about this topic in the sections about functional placeholders as well as in the overview over all available functional placeholders.

As already mentioned, you can use the references both alone and in combination with any other characters, letters or placeholders in the supported functions. So you could, for example, write into the field "Replace with" of the replacement function of the TextConverter both, only "%ref:line=1%" or also something like "The first line of the file %filename% is: %ref:line=1%" in order to replace an arbitrary text either only with the text from the first line or with the sentence mentioned, in which the file name and the content from the first line is inserted instead of the respective placeholders.

You can find out more about the different types of references in the sections after the next section of this tutorial as well as in the overview over all available placeholders for references at the end of this tutorial. The combination of several placeholders is discussed in the section about combining different references.

Supported Functions

In the current version of the TextConverter, you can use references in the following actions and functions from the categories Text Actions, Line Actions, CSV Actions, XML Actions and Action Lists as well as in the Storage Options.

In all actions mentioned, you can use the placeholders for references in the text fields both alone and together with any other characters, any other references, any functional placeholders as well as any other placeholders.

References to Characters

With the three placeholders %ref:char=x% as well as %ref:chars=x-y% and %ref:chars=x,y% you can reference individual respectively multiple characters.

If you want to reference individual characters, you can use the placeholder %ref:char=x% for that. The x stands for the position of the character that is to be taken over. With positive values for x, the character position is counted from the front beginning with 1. If you want to count the character positions from behind, you can use negative values for x. Let's look at a few examples for those cases:

PlaceholderMeaning
%ref:char=1%stands for the first character from the front
%ref:char=10%stands for the tenth character from the front
%ref:char=-1%stands for the last character or the first character from behind
%ref:char=-2%stands for the penultimate character or the second character from behind

If you want to reference several characters in a row, you can use one of the two placeholders %ref:chars=x-y% or %ref:chars=x,y%. In both of these placeholders, the x stands for the first character position from which characters are to be taken. The y has a different meaning depending on the placeholder. In %ref:chars=x-y%, the y stands for the last character position that is taken over. That means, the characters from the character positions x to y are referenced with this placeholder. On the other hand, in %ref:chars=x,y%, the y stands for the number of characters that are to be read out. For example, if you substitute y with "3", three characters are referenced: the character at character position x and the two characters that follow.

Again, the characters can alternatively be counted from the end by inserting a negative value for x in the %ref:chars=x,y% placeholder, whereby y characters from the character position x counted from the back are taken over. In the other placeholder %ref:chars=x-y% a negative value can only be used for y. This negative value means in this case that the characters are taken from character position x (counted from the beginning) to character position y (counted from the end).

Let's look at some examples to clarify the cases mentioned:

PlaceholderMeaning
%ref:chars=1-3% stands for the first 3 characters
%ref:chars=1,3% also stands for the first 3 characters
%ref:chars=10-17%stands for the characters 10 to 17
%ref:chars=10,8%also stands for the characters 10 to 17
%ref:chars=-1,1%stands for the last character
%ref:chars=-2,2%stands for the last two characters
%ref:chars=-10,3%stands for the three characters beginning with the tenth character from behind
%ref:chars=1--1%stands for the first to the last character (all characters)
%ref:chars=2--2%stands for the second to penultimate character (all characters except the first and last character)
%ref:chars=3--1%stands for the third to the last character (all characters except the first two characters)
%ref:chars=1--3%stands for the first to the third last character (all characters except the last two characters)

The placeholders %ref:char=x%, %ref:chars=x-y% and %ref:chars=x,y% can be combined with all other placeholders for references as well as with all placeholders for text processing, for example to reference characters from another file, characters within a word, characters from a CSV cell or characters from within a line. To do this, the placeholders for characters can simply be combined with the other placeholders in the following way:

PlaceholderMeaning
%ref:word=1>char=2%stands for the second character of the first word
%ref:line=3>chars=10-20%stands for the characters 10 to 20 from the third line
%ref:word=2>chars=-3,3%>write=uppercase%stands for the last three characters of the second word converted into capital letters regardless of the original writing of the word, implemented with the functional placeholder for changing the writing
%ref:file=D:\data.csv>cell=1:2>char=1%stands for the first character from the second line of the first column of the CSV file "data.csv"

You can find more information about combining the character references with other references in the section about the combination of different references.

References to Words

The three placeholders %ref:word=x%, %ref:words=x-y% as well as %ref:words=x,y% work the same way like the three references to characters presented in the last section. The only difference is that with these placeholders, instead of the characters, individual or several words can be referenced.

One single word at word position x can be referenced with the placeholder %ref:word=x%. If you want to reference multiple words at once, you can use the placeholders %ref:words=x-y% and %ref:words=x,y%. The first of these two placeholders references the words from word position x to y, the second placeholder references a number of y words starting at word position x.

Again, the word position can alternatively be specified with negative values for x in the placeholders %ref:word=x% and %ref:words=x,y% to indicate a word counting from the end, while in the placeholder %ref:words=x-y% negative values for y can be used to count the word position of the last accepted word from the back.

Let's take a look at some examples for that:

PlaceholderMeaning
%ref:word=1%stands for the first word from the front
%ref:word=3%stands for the third word from the front
%ref:word=-1%stands for the last word respectively the first word from behind
%ref:word=-2%stands for the penultimate word respectively the second word from behind
%ref:words=1-7%stands for the first 7 words
%ref:words=3-6%stands for the third, fourth, fifth and sixth word
%ref:words=3,4%also stands for the third, fourth, fifth and sixth word (4 words from the third word)
%ref:words=1--1%stands for the first to the last word (all words)
%ref:words=2--2%stands for the second to penultimate word (all words except the first and last word)
%ref:words=2--1%stands for the second to the last word (all words except the first word)
%ref:words=1--2%stands for the first to penultimate word (all words except the last word)

For all of these three placeholders, words are defined by the definition that a word is a collection of characters that is separated from other parts of the text either by a space or a line break. When counting the words, double whitespace, such as several spaces in a row, is not taken into account.

This way of extracting words from the text means that punctuation marks such as periods, commas, question marks or exclamation marks are also considered as part of a "word" unless they are separated by spaces or line breaks. So, the last "word" of the last sentence of this paragraph would be "break." with an attached period. If you don't want this, you can for example use one of the functional placeholders like delete_chars or trim_chars to remove the punctuation marks from the words. For example, the word reference could be expanded like this:

PlaceholderMeaning
%ref:word=1>delete_chars=.,!?%removes all periods, commas, exclamation marks and question marks from the word, regardless of their position
%ref:word=1>trim_chars=.,!?%removes all periods, commas, exclamation marks and question marks from the beginning and from the end of the word

The difference between these two placeholders is whether punctuation marks are also to be removed from within the word or not. As an example, let's look at a sentence that ends with a filename. With %ref:word-1% alone, the last word would be "file.txt.", for example. In conjunction with the "remove_chars" example, all dots would be removed and we would get "filetxt". With "trim_chars" the points would only be removed from the sides and left in the middle, the result would be "file.txt" instead.

Like the references to characters, also the references to words can be combined with all other placeholders including functional placeholders. Here are some examples of possible combinations:

PlaceholderMeaning
%ref:word=1>chars=1-2%stands for the first two characters of the first word
%ref:word=1>write=lowercase%stands for the first word, written in lower case letters, converted with the functional placeholder write
%ref:word=2>rpad=10,.%stands for the second word enlarged to a length of 10 characters with using the functional placeholder rpad by filling up the word with the character "."
%ref:line=1>words=2-6%stands for the second to sixth word from the first line
%ref:line=1>word=2>char=3%stands for the third character of the second word of the first line
%ref:file=E:\data.xml>xml=#a%>word=1%stands for the first word of the inner text of the element with the ID "a" from the XML file "data.xml"

For more information on combining word placeholders with other references and placeholders, see the section about combining different references.

References to Lines

Also the placeholders %ref:line=x% as well as %ref:lines=x-y% and %ref:lines=x,y% for single or multiple lines follow the same principle as the placeholders for characters and words introduced in the last two sections.

Individual lines can be referenced with the placeholder %ref:line=x%, where x stands for the line number and can also be negative for counting from the back. Multiple lines can be referenced using the placeholders %ref:lines=x-y% and %ref:lines=x,y%, where %ref:lines=x-y% stands for the lines with the line numbers x to y and %ref:lines=x,y% stands for y lines starting with the line that has the line number x. To count the line numbers from the back, negative values for x can be used in the placeholder %ref:lines=x,y% and negative values for y can be used in the placeholder %ref:lines=x-y%.

Here are some examples for all of those 3 types of placeholders for line references:

PlaceholderMeaning
%ref:line=1%stands for the first line from the front
%ref:line=2%stands for the second line from the front
%ref:line=-1%stands for the last line respectively the first line from behind
%ref:line=-3%stands for the third line from behind
%ref:lines=1-3%stands for the first three lines
%ref:lines=3-5%stands for the third, fourth and fifth line
%ref:lines=4,2%stands for the fourth and fifth line (2 lines beginning with line number 4)
%ref:lines=-3,3%stands for the last three lines
%ref:lines=1--1%stands for the first to the last line (all lines)
%ref:lines=2--2%stands for the second to penultimate line (all lines except the first and last line)
%ref:lines=10--1%stands for the tenth to the last line (all lines except the first nine lines)
%ref:lines=1--10%stands for the first to the tenth last line (all lines except the last nine lines)

Of course, also the placeholders for single or multiple lines can be combined with the other placeholders for references or with the functional placeholders. We would like to look at some examples for this as well:

PlaceholderMeaning
%ref:line=1>word=3%stands for the third word from the first line
%ref:line=2>trim=whitespace%stands for the second line without possible spaces at the beginning or at the end
%ref:lines=1,3>rewrite=remove_tags%stands for the first three lines without possible HTML tags, implemented with the rewrite function placeholder
%ref:line=2>insert=abc,3%stands for the second line, in which the text "abc" is inserted at character position 3, implemented with the functional placeholder for insertions
%ref:lines=1-10>find_lines=abc%stands for those of the first 10 lines in which the text "abc" occurs, implemented with a placeholder for filtering lines
%ref:lines=1-10>find_lines=[0-9],r%stands for those of the first 10 lines in which an arbitrary number occurs, implemented with the find_lines function in combination with regular expressions
%ref:lines=1-10>delete_lines=[0-9],r%stands for those of the first 10 lines in which no number occurs, implemented with the delete_lines function in combination with regular expressions
%ref:file=E:\file.txt>line=-1%stands for the last line of the file "file.txt"
%ref:file=E:\file.txt>line=3>char=2%stands for the second character from the third line of the file "file.txt"
%ref:file=E:\web.html>xml=h2>line=3%stands for the text of the third h2 heading from the file "web.html"

If you want to learn more about combining the line references with other placeholders for references, you can see the section about combining various references.

References to Cells from CSV Data

The content of fields from CSV data or CSV files can be referenced with the placeholder %ref:cell=x:y%. The x in this placeholder stands for the number of the column, the y stands for the row number. As an example, the following four uses of this placeholder would reference the listed fields within the first two columns and the first two rows:

PlaceholderMeaning
%ref:cell=1:1%Content of the CSV field, first column, first row
%ref:cell=1:2%Content of the CSV field, first column, second row
%ref:cell=2:1%Content of the CSV field, second column, first row
%ref:cell=2:2%Content of the CSV field, second column, second row

Crucial for the interpretation of texts as CSV data and thus for this reference to CSV fields are the settings in the TextConverter under "Actions > CSV > Import Format" as well as under "Actions > Files > Line Break Type". In these settings you can specify which user-defined characters, code points or fixed character lengths should be used for the field separation, the field delimitation and the line end or whether the TextConverter should automatically recognize them from the text (which is the default). You can learn more about this topic in the tutorial about CSV Editing with the TextConverter.

Like all other placeholders, also this placeholder can of course be combined with any other placeholder for references or functional placeholder. Here you can see some examples for this:

PlaceholderMeaning
%ref:cell=2:3>char=4%stands for the fourth character of the CSV field from the third line of the second column
%ref:cell=2:4>chars=1,3%stands for the first three characters from the CSV field from the fourth line of the second column
%ref:cell=1:3>write=uppercase_words%stands for the content of the CSV field in the third row of the first column with capitalized word beginnings, implemented with the write function
%ref:cell=1:2>lpad=5,0%stands for the content of the CSV field in the second row of the first column with leading zeros, padded to 5 characters, implemented with the lpad function
%ref:file=D:\data.csv>cell=1:2>word=1%stands for the first word from the second line of the first column of the CSV file "data.csv"

In the section about the combination of placeholders you can learn more about these combinations and what there is to consider when using them.

References to Texts from an XML Structure

If you want to reference texts from an XML structure, you can use the placeholder %ref:xml=x%. The x in this placeholder stands for a CSS selector that can be used to address the elements within the XML structure. All common CSS selectors such as type selectors, ID selectors, class selectors, position selectors, and so on are supported.

Reading out all Texts of an XML Example File

For clarification, we would like to take a look at the placeholders we can use to extract the text of the following HTML page as an example.

<!DOCTYPE HTML>
<html>
<head>
  <title>Title of the Page</title>
</head>
<body>
  <h1>Headline of the Page</h1>
  <p class="a">Text of the first Paragraph.</p>
  <p class="b">Text of the second Paragraph.</p>
  <p>Text of the third Paragraph.</p>
  <div id="footer" class="b">Text in the Footer</div>
</body>

With the following placeholders we can read out the title of the page, the heading of the page, the texts of the first two paragraphs as well as the text from the footer of the page for further use:

PlaceholderMeaning
%ref:xml=title%stands here for "Title of the Page"
%ref:xml=h1%stands here for "Headline of the Page"
%ref:xml=.a%stands here for "Text of the first Paragraph."
%ref:xml=p.b%stands here for "Text of the second Paragraph."
%ref:xml=#footer%stands here for "Text in the Footer."

As you can see, we use the type selectors "title" and "h1" with which we can address the elements of the title tag and the heading directly via their tag name. We then address the two paragraphs via their class. The first paragraph only via its class name "a" with the CSS class selector ".a", the second paragraph via its type and its class using the CSS selector "p.b". In this case, we use "p.b" because neither the tag name "p" nor the class "b" would lead to a unique result, since both occur multiple times in the HTML page. Finally, we address the footer via its ID "footer" with the CSS ID selector "#footer".

Selectors with multiple Hits

You've probably wondered what happens when using a selector that matches more than one element of our XML structure. In our example HTML page, these would be, for example, the CSS selectors "p" or ".b", which would return three respectively two matches. If we would use such a selector, we would get all the inner texts of all elements that match the selector, separated from each other by a line break, each match in a new line.

So, if we use the CSS selectors "p" or ".b" as a reference, the result for our HTML example page would be as follows:

%ref:xml=p%stands here for"Text of the first Paragraph.
Text of the second Paragraph.
Text of the third Paragraph."
%ref:xml=.b%stands here for"Text of the second Paragraph.
Text in the Footer."

But what can we do if we only need a certain text from the multitude of hits from a CSS selector? For example, we can just combine our XML reference with a line reference and thus get the opportunity to specifically address a certain hit via its number or to select several of the hits:

%ref:xml=p>line=1%stands here for"Text of the first Paragraph."
%ref:xml=p>line=2%stands here for"Text of the second Paragraph."
%ref:xml=p>line=3%stands here for"Text of the third Paragraph."
%ref:xml=p>lines=1-2%stands here for"Text of the first Paragraph.
Text of the second Paragraph."
%ref:xml=.b>line=1%stands here for"Text of the second Paragraph."
%ref:xml=.b>line=2%stands here for"Text in the Footer."

Alternatively, if we don't want to select the hits by their number, we can also use one of the line filters to limit the hits based on their content:

%ref:xml=p>find_lines=c%stands here for"Text of the second Paragraph."
%ref:xml=.b>find_lines=Paragraph%stands here for"Text of the second Paragraph."
%ref:xml=.b>delete_lines=Paragraph%stands here for"Text in the Footer."

In these three examples, we use the line filters find_lines and delete_lines. In the first two examples we are looking for all hits that contain the text "c" respectively "paragraph", in the third example we remove all lines from the search result that contain the word "paragraph".

Combinations of the XML Reference with other Placeholders

Combinations are of course not only limited to line references or line filters. The XML reference can also be combined with any other placeholder for references as well as with functional placeholders, as the small selection of the following examples demonstrates:

PlaceholderMeaning
%ref:xml=h2%stands for the text of all h2 headings
%ref:xml=h2>line=3>word=4%stands for the fourth word of the third h2 heading
%ref:xml=h1,h2,h3%stands for the text of all h1, h2 and h3 headings
%ref:xml=*%stands for all inner texts
%ref:xml=[style]%stands for all inner texts of all elements with a style attribute
%ref:xml=[data-id=3]>line=1%stands for the inner text of the first element which data-id attribute has the value "3"
%ref:xml=*>replace=abc,def%stands for all inner texts in which the string "abc" is replaced by the string "def", implemented with the functional placeholder for replacements
%ref:xml=#a>trim=whitespace%stands for the inner text of the element with the ID "a" without whitespace at the beginning or at the end, implemented with the functional placeholder for trimming text
%ref:xml=ul>>li>line=1%stands for the content of the first li element below a ul element
%ref:file=D:\page.html>xml=title%stands for the title of the HTML file "D:\page.html" if the file contains a title tag

You can see a specialty in the example using the CSS selector "ul>li", which stands for a li list element below a ul element. Since the character ">" required for this selector serves as a separator between multiple combined placeholders, we have to double this character in cases it is not used in its function of a separator. You can read more about this, and about combining placeholders in general, in the section about combining references.

References to Attributes from an XML Structure

If you want to reference the values of attributes from an XML structure, you can add the placeholder for attributes ">attribute=name" to the placeholder %ref:xml=x% introduced in the last section. The resulting placeholder %ref:xml=x>attribute=y% accordingly stands for the value of the attribute with the name "y" of the element within an XML structure to which the CSS selector "x" applies. The XML part respectively the selection of the XML nodes from which the attribute values are to be read can be used in exactly the same way as described in the last section and only needs to be supplemented with the attribute part in order to be able to access the attribute values.

Reading out all Attribute Values from an XML Example File

To demonstrate this reference type, let's look at a small sample file again.

<?xml version="1.0"?>
<audios year="2023">
  <audio id="sample1" genre="Pop">
    <title en="The Pilot's Dance" de="Der Pilotentanz">
  </audio>
  <audio id="sample2" genre="Rock">
    <title en="Hard Way to Jupiter" de="Beschwerlicher Weg zum Jupiter">
  </audio>
  <audio id="sample3" genre="Dance">
    <title en="Ringle Man" de="Ringelmann">
  </audio>
  <audio id="sample4" genre="Hardstyle">
    <title en="The Exit" de="Der Ausgang">
  </audio>
</audios>

Now we would like to read out every single type of attribute value that occurs in this file.

This is easiest for attributes of elements that are unique or appear only once in the XML file. In the example file, this applies, for example, to the element "audios" with the attribute "year" or the "genre" attributes, which we can address uniquely via the ID of the "audio" element:

%ref:xml=audios>attribute=year%stands here for"2023"
%ref:xml=#sample1>attribute=genre%stands here for"Pop"
%ref:xml=#sample2>attribute=genre%stands here for"Rock"

As you can see, we can select the elements in the same way via CSS selectors as described in the last section for referencing inner texts with just appending the name of our desired attribute of the respective element using ">attribute=attributename".

If we use a selector that matches multiple elements of our XML structure, we get all matching attribute values of these elements line by line. An example of this is the "audio" selector in combination with the ID attribute. The "audio" selector matches a total of 4 elements of our example file and each of these elements contains its own ID attribute. So we get 4 lines and each of these lines contains one of the 4 attribute values:

%ref:xml=audio>attribute=id%stands here for"sample1
sample2
sample3
sample4"

If we don't need all of those rows, we can combine our placeholder with a line reference or a line filter in order to selectively read out only certain of the matching rows. The procedure is the same as for referencing individual inner texts demonstrated in the last section and can be used both for reading out individual lines as well as for reading out several lines:

%ref:xml=audio>attribute=id>line=1%stands here for"sample1"
%ref:xml=audio>attribute=id>line=3%stands here for"sample3"
%ref:xml=audio>attribute=id>lines=1-2%stands here for"sample1
sample2"
%ref:xml=audio>attribute=id>delete_lines=3%stands here for"sample1
sample2
sample4"

Using the same method, also either all or a selection of the "genre" attributes can be read out from the sample file. In the following examples, we filter the attribute values both by their number and by their content:

%ref:xml=audio>attribute=genre%stands here for"Pop
Rock
Dance
Hardstyle"
%ref:xml=audio>attribute=genre>line=3%stands here forr"Dance"
%ref:xml=audio>attribute=genre>line=4%stands here for"Hardstyle"
%ref:xml=audio>attribute=genre>lines=1-2%stands here for"Pop
Rock"
%ref:xml=audio>attribute=genre>find_lines=e%stands here for"Dance
Hardstyle"

It gets interesting again when coming to reading out the attributes "en" and "de" because these are located one level below the elements with an ID and do not have their own ID but are all structured the same way. If we only use "title" as a selector and want to read out the attributes "en" or "de", we get all 4 attribute values at once. If we only want to read one of these attribute values and want to go via the ID of the parent element, we can use the selector "#sample3>title" (title element below the element with the ID "sample3" where we have to double the ">" character). Alternatively, we could of course also work with the line reference again, as in the last example. Here are examples of all of these cases:

%ref:xml=title>attribute=en%stands here for"The Pilot's Dance
Hard Way to Jupiter
Ringle Man
The Exit"
%ref:xml=#sample3>>title>attribute=de%stands here for"Ringelmann"
%ref:xml=#sample4>>title>attribute=en%stands here for"The Exit"
%ref:xml=title>attribute=en>line=4%stands here for"The Exit"

With this, we have read out all available attribute types of the sample file.

Reading out Properties of HTML Documents

Among other things, the attribute reference can also be used to read out certain properties from HTML files. Here are some examples that show how to read the language, the author, the keywords or the meta description of HTML documents (you can find an example of reading out the title attribute in the last section, since no attribute references are required to read the title attribute):

PlaceholderMeaning
%ref:xml=html>attribute=lang%stands for the language of an HTML page provided the language is specified using <html lang="en">
%ref:xml=meta[name=content-language]>attribute=content%stands for the language of an HTML page provided the language is specified using <meta name="content-language" content="en">
%ref:xml=meta[name=author]>attribute=content%stands for the author of an HTML page provided the author is specified using <meta name="author" content="name of the author">
%ref:xml=meta[name=keywords]>attribute=content%stands for the keywords of an HTML page provided the keywords are specified using <meta name="keywords" content="list of keywords">
%ref:file=D:\page.html>xml=meta[name=description]> attribute=content%stands for the meta description of the HTML file "D:\page.html" provided the file contains a meta description (<meta name="description" content="text of the meta description">)

Combination of the Attribute Reference with other Placeholders

Of course, the placeholder for attribute values can also be combined with any other placeholder or placeholder function. Some examples for this can be found in the following table:

PlaceholderMeaning
%ref:xml=div>attribute=style>line=2>word=1%stands for the first word / the first property of the style attribute of the second div container
%ref:xml=meta[name=keywords]> attribute=content>words=1-3>delete=,%stands for the first three keywords of an HTML page without commas, removed by the delete function
%ref:xml=*>attribute=style%stands for the values of all style attributes of an entire HTML document
%ref:xml=#a>attribute=style>find_text=width:([0-9]+)px%stands for the width of the element with the ID "a" provided that the width is specified via the style attribute in the form "width:...px", implemented with the find_text function
%ref:xml=a>attribute=href%stands for all links of an HTML document
%ref:xml=a>attribute=href>find_lines=^http,r% stands for all outgoing links of an HTML document, as long as internal links are not linked with "http://..." or "https://..."
%ref:xml=a>attribute=href>delete_lines=^/,r%stands for all outgoing links of an HTML document, as long as internal links are linked with href="/..."
%ref:xml=a>attribute=href>find_lines=^/,r%stands for all internal links of an HTML document, as long as internal links are linked with href="/..."
%ref:xml=a>attribute=href>delete_lines=^https?://,r%stands for all internal links of an HTML document, as long as internal links are not linked with "http://..." or "https://..."

The placeholders for reading out the internal and external links were implemented using the FindLines and DeleteLines functions in combination with regular expressions. You can learn more about combining placeholders in the sections about combined placeholders and the use of placeholder functions.

References to Files

While all other placeholders presented so far in this tutorial used on its own always refer to the current text or the current file that is being edited, with the placeholder %ref:file=filename% you can reference also any other text files respectively the content of these files. Instead of "filename" you can insert any file name respectively a path to a file into the placeholder. So for example:

%ref:file=C:\Folder\File.txt%

When you use this placeholder exactly like this, it represents the entire content of the file "C:\Folder\File.txt". For example, if you write this placeholder in the text field of an insert function of the TextConverter, the entire content of the specified file is inserted at the desired location.

If you want to reference the own file, that is the file that is currently being edited, you can also use the word "self" instead of the exact file path. Accordingly, the placeholder %ref:file=self% stands for the entire content of the file that is currently being edited. The referencing with "self" works not only for file editing but also for unsaved texts: Also if you edit an unsaved text, you can reference this text in its entire length with %ref:file=self%.

Tip: If you don't want to manually write an entire file path into the placeholder and the file you want to reference is in the TextConverter's file list, you can simply right-click on the corresponding file and select "Copy File Path to the Clipboard" from the context menu in order to be able to easily paste the file path via the clipboard.

Of course, the content of the file can be edited, adjusted and modified with the functional placeholders before its usage. As you can see in the following examples, multiple functional placeholders can be written one after the other in order to implement several processing steps as well:

PlaceholderMeaning
%ref:file=F:\test.txt>trim=whitespace%stands for the content of the file "test.txt" without whitespace at the beginning or at the end, implemented with the trim function
%ref:file=F:\test.txt>delete=abc%stands for the content of the file "test.txt" without the text "abc", implemented with the delete function
%ref:file=F:\test.txt>write=uppercase%stands for the contents of the file "test.txt" with all text converted to uppercase letters regardless of its original case, implemented with the write function
%ref:file=F:\test.xml>rewrite=remove_tags%stands for the content of the file "test.xml" without XML tags, that means only the pure text is extracted from the XML structure, implemented with the rewrite function
%ref:file=F:\test.xml>rewrite=remove_tags>rewrite= remove_double_whitespace%stands for the content of the file "test.xml" without XML tags and without double whitespace (several line breaks or spaces in a row), implemented with the rewrite function
%ref:file=self>find_text=[0-9]+%stands for all numbers occurring in the entire current file, implemented with the findtext filter
%ref:file=self>find_text=[0-9]+>line=3%stands for the third number occurring in the current file, implemented using the findtext function and a line reference
%ref:file=self>find_lines=1%stands for all lines of the current file in which the number "1" occurs, implemented with the findlines filter
%ref:file=self>find_lines=[0-9],r%stands for all lines of the current file in which an arbitrary number occurs, implemented with a line filter in combination with regular expressions

If you do not put a file reference at the first position of a chain of combined placeholders or if you write multiple file references in a row, the contents of the files are attached to the previous text of the reference. So for example:

PlaceholderMeaning
%ref:lines=1-3>file=D:\file.txt%initially reads the first 3 lines of the file that is currently being processed and then appends the content of the file "file.txt"
%ref:file=D:\file1.txt>file=D:\file2.txt%stands for the content of the files "file1.txt" and "file2.txt" one after the other
%ref:file=D:\1.txt>file=D:\2.txt>file=D:\3.txt%stands for the content of the files "1.txt", "2.txt" and "3.txt" one after the other
%ref:file=D:\1.txt>append=\l>file=D:\2.txt%stands for the content of the files "1.txt" and "2.txt" separated by a line break, implemented with the append function (in the functional placeholders "\l" corresponds to the system line break, see here)
%ref:file=D:\1.txt>trim=whitespace>file=D:\2.txt> trim=whitespace%initially reads the file "1.txt", then removes the whitespace from the front and the back with the trim function, then reads the file "2.txt", appends the content of this file and again removes the front and back whitespace

For concatenating multiple files, alternatively, you can of course also use the function "Actions > Files > Join Files" in the TextConverter, which is described in the tutorial about the concatenation of text files. Whether it makes more sense to work with this function or with references depends on the respective use case. While references offer more flexible integration, the "Join Files" function is quicker to use to simply connect some text files without further editing (all you have to do is to tick a checkbox for doing so).

If you do not want to insert the entire content of an file, but only parts of this content, such as individual letters, words or lines, you can simply combine the file reference placeholder with any other reference. Some examples of this would be:

PlaceholderMeaning
%ref:file=D:\File.txt>word=1%stands for the first word of the file
%ref:file=D:\File.txt>chars=1-10%stands for the first 10 characters of the file
%ref:file=D:\File.txt>line=2%stands for the second line of the file
%ref:file=D:\File.txt>lines=1-4%stands for the first four lines of the file
%ref:file=D:\File.txt>line=7>write=lowercase%stands for the seventh line of the file, written in lower case letters
%ref:file=D:\File.txt>line=-1%>char=3%stands for the third character of the last line of the file
%ref:file=D:\File.csv>cell=2:3%stands for the content of the field in the third line of the second column of the CSV file
%ref:file=D:\File.html>xml=p%stands for the entire text of all p paragraphs from the HTML file
%ref:file=D:\File.html>xml=p>line=1%stands for the text of the first p paragraph of the HTML file
%ref:file=D:\File.html>xml=title%stands for the title of the HTML file
%ref:file=D:\File.xml>xml=#a>attribute=b%stands for the value of the attribute named "b" in the element with the ID "a" from the XML file

As you can see, the individual placeholders for references can be written one after the other as often as you like and combined with each other as well as with functional placeholders. You will learn more about the functional placeholders in the next section and more about the combination of references in the section after the next section.

Functional Placeholders

The TextConverter provides you with some functional placeholders for replacing, deleting, trimming, prepending, appending, inserting, filtering, rewriting and padding the text read out via references.

For a tabular overview over all available functional placeholders, please refer to the overview over all functional placeholders for references at the end of this tutorial. A description of all functional placeholders can be found after this introduction within this section.

Functional placeholders can be used and combined with other placeholders in the same way as any other placeholder for references. The only difference is that the functional placeholders do not create a reference to a piece of text or a file, but can edit the text read out up to the occurrence of the functional placeholder within the placeholder. For this reason, the functional placeholders only make sense at a position beginning with the second position or higher of the placeholder chain, since they only work with the text that has been read out up to that point and they cannot read any text themselves (even if functional placeholders can generally occur at any position in the placeholder and the occurrence of a functional placeholder at the first position in the chain would not generate an error but would only "process" the currently empty string of the reference at this point).

Let us first have a look at a placeholder that contains a chain of different references and functions for manipulating the extracted text as an example of using functional placeholders:

%ref:line=1>trim=whitespace_left>chars=1-3>replace,a,b>write=lowercase%

This placeholder represents the first 3 non-space characters of the first line, in which the letter "a" has been replaced with the letter "b", written in lower case letters.

The individual chain links of this placeholder are connected with the character ">". You can learn more about linking references and functions in the next section. But first, let's look at the explanations and some examples for each of the available functional placeholders:

Placeholders for Replacing Text

There are three different versions of functional placeholders for replacing text: replace=x,y, replace=x,y,z and replace_regex=x,y. With the basic version replace=x,y the text x is replaced by the text y. Thus, the x stands for an arbitrary search text and y for an arbitrary replacement. In the extended version replace=x,y,z options can be passed via the additional parameter z and replace_regex=x,y can be used for replacements with the help of regular expressions. Below we would like to look at examples for each of these variants.

Our first example demonstrates the simplest use of the functional placeholder for replacements:

%ref:line=1>replace=abc,def%

This placeholder stands for the content of the first line in which the text "abc" has been replaced with the text "def".

If we want to use a comma in our search text and/or in our replacement, we need to enclose the respective text in quotes to make clear which comma should be treated as part of the text and which comma separates the parameters:

%ref:line=1>replace="1,0","1,1"%

Another special case is the use of line breaks and tabs in the search text or in the replacement. Line breaks can be written as "\l", tabs as "\t", as in our next example:

%ref:file=E:\File.txt>replace=\t,\l%

Accordingly, this placeholder stands for the content of the file "Ffile.txt" in which all tabs have been replaced with line breaks. You can learn more about this topic in the section about using line breaks and tabs in functional placeholders.

If we use the replace function placeholder in the way we've seen it in our previous examples, the replacement is carried out case-insensitive. This means "replace=a,b" not only replaces all lowercase "a" with "b" but also all uppercase "A" with "b". If we don't want this, we can express this wish as an option via the optional third parameter of the replace function replace=x,y,z:

%ref:line=1>replace=a,b,c>replace=A,B,c%

This placeholder stands for the content of the first line with all lowercase "a" replaced with "b" and all uppercase "A" replaced with "B". As third parameter, we have passed "c" (case sensitive). This means that the search text is interpreted case-sensitive. If we omit the "c", there is no difference between a search for "a" and a search for "A". At the same time, this placeholder is an example of how we can perform multiple replacements within one placeholder by simply hanging several functional placeholders one after the other.

Another option we can pass with the third parameter is "r". If we do this, x and y in replace=x,y,z will be interpreted as regular expressions. So for example:

%ref:line=1>replace=[1-9],0,r%

This placeholder stands for the content of the first line in which all digits from 1 to 9 have been replaced with "0". We specified the regular expression [1-9] as the search text and passed "r" as parameter, which tells the TextConverter that the input is to be interpreted as a regular expression.

Incidentally, we get the same result also with the following placeholder:

%ref:line=1>replace_regex=[1-9],0%

The functional placeholder replace_regex=x,y is a short form for replace=x,y,r in which we do not have to write the third parameter.

Of course, "c" and "r" can be used not only alone but also together:

%ref:file=self>replace=([A-Z]),_$1,cr%

This placeholder stands for the content of the entire text (file=self) currently being edited, in which all uppercase letters from A to Z have been preceded by the character "_". We passed "cr" as third parameter, because on the one hand we want to work with regular expressions and on the other hand we are only interested in uppercase letters. This time, we specified a regular expression for both the search text and the replacement, since we reference the found letter with $1. We can't work with replace_regex at this point because we need the "c" option and replace_regex is always case-insensitive.

Placeholders for Deleting Text

The functional placeholders delete=x as well as delete_regex=x for deleting text are working similarly to the functional placeholders for text replacements described in the last section. The only difference is that it is always replaced with an empty text - the search text is not replaced in the classic sense but it is deleted. Added to those two placeholders there is delete_chars=x as a third functional placeholder for deleting individual characters. In the following we would like to look again at examples for all three types.

To delete an arbitrary text, we can use the functional placeholder delete=x in its pure form:

%ref:line=1>delete=abc%

This placeholder stands for the content of the first line in which the text "abc" has been deleted. The deletion is carried out case-insensitive. This means "a" not only deletes "a" but also "A". To delete a text case-sensitively, you can use the replace function placeholder. This is to be used in the form replace=x,,c to delete the text x taking into account its upper and lower case writing.

If you don't want to delete a specific text but all text fragments matching a regular expression, you can use delete_regex=x, where x is to be replaced with the regular expression:

%ref:line=1>delete_regex=[0-9]%

This placeholder stands for the content of the first line from which all numbers have been removed. This placeholder can also be expressed using the replace function placeholder: the equivalent for "delete_regex=[0-9]" is "replace=[0-9],,r". Like "delete=x", also "delete_regex=x" is working case-insensitively. In order to delete text fragments with the help of regular expressions taking into account the uppercase and lowercase writing, it is necessary to use the replace function placeholder again. In this case, the form "replace=x,,cr" is required to delete all text fragments that match the case-sensitive regular expression x.

If you want to delete multiple individual characters, you could construct the following placeholder with combining several individual delete functions:

%ref:line=1>delete=a>delete=b>delete=c%

This placeholder stands for the content of the first line from which the letter "a" was deleted first, followed by the letter "b" and finally by the letter "c". However, there is a short form for deleting individual letters that makes our work easier:

%ref:line=1>delete_chars=abc%

This placeholder also stands for the content of the first line from which the letters "a", "b" and "c" have been deleted. These letters do not have to appear in a row as "abc" to be deleted: instead, like in the example above, they are all deleted individually and independently of each another. That means, all text that we pass to delete_chars=x is broken down into its individual characters and causes a single deletion for each of those characters. Incidentally, this example could also easily be implemented with regular expressions: the placeholder "delete_regex=[a-c]" would also lead to the same result.

If we want to delete line breaks or tabs, we can use the placeholders \l, \r, \n and \t in our search text. You can learn more about this topic in the section about using line breaks and tabs in functional placeholders.

Placeholders for Trimming Text

The functional placeholder trim=x can be used to remove certain characters from the beginning and/or the end of the current text. Depending on which parameter is used for x, these can be different characters: For example, whitespace characters, a certain number of characters, certain freely definable characters or all characters up to a certain text can be removed. All of these types are available in variants for double-side removal (front and back), as well as for left-side only (front, left) or right-side only (back, right) removal of characters.

To remove whitespace such as spaces, line breaks or tabs, trim=x can be called with "whitespace", "whitespace_left" or "whitespace_right". For example, the following placeholder stands for the first line whose content has been stripped of whitespace on both sides:

%ref:line=1>trim=whitespace%

If we would write "trim=whitespace_left" or "trim=whitespace_right" instead, the whitespace would not be removed on both sides but only from the front or only from the back.

If you want to remove a certain number of characters from the beginning and/or the end of the text, regardless of what characters these are, you can use the parameters "number_of_chars:y", "number_of_chars_left:y" and "number_of_chars_right:y" for x in trim=x where y is the number of characters to remove. An example of this is the following placeholder, which represents the content of the second line from which the first 3 characters have been truncated from the front:

%ref:line=2>trim=number_of_chars_left:3%

The parameters "number_of_chars:y" and "number_of_chars_right:y" can be used analogously for cutting of an arbitrary number of characters on both sides respectively from the end.

If you want to decide for yourself which characters are to be removed from the beginning and/or the end of the text, you can use the parameters "chars:y", "chars_left:y" and "chars_right:y" for x in trim=x to remove all characters defined in y. Let's also look at an example for that:

%ref:file=E:\file.txt>trim=chars:0123456789 .!?%

This placeholder stands for the content of the file "file.txt" from which numbers, spaces, periods, exclamation marks and question marks have been removed from the front and rear. The character selection is arbitrary and it does not matter in which order the characters are specified. Analogously, the parameters "chars_left:y" as well as "chars_right:y" can be used to remove characters only on the left side or only on the right side. An example of this is the following placeholder that combines "chars_left:y" and "chars_right:y":

%ref:line=3>trim=chars_left:123>trim=chars_right:abc%

This placeholder stands for the content of the third line with all digits from 1 to 3 removed from the front and all letters from a to c removed from the end. So, as you can see, you can also use the trim function placeholder to remove characters from the front and from the back in different ways. For example, it would be equally possible to only remove whitespace at the front and to only remove a certain number of characters at the end within the same placeholder.

In addition to removing specific characters or removing a specific number of characters, you can also remove all characters before and/or after a specific text. To do this, you can use one of the parameters "till_text:y,z", "till_text_left:y,z" or "till_text_right:y,z" for x in trim=x. In these parameters, y stands for the text from or up to which all characters should be removed and via z optional options can be passed. Available are the options "c" (case sensitive), "r" (interpret as regular expression) and/or "i" (include text).

The following example demonstrates all of these options:

%ref:line=4>trim=till_text_left:[0-9],ri>trim=till_text_right="a,b",c%

This reference stands for the content of the fourth line, from which characters have been cut off up to a certain text according to different criteria for the beginning and for the end:

Again, the parameter "till_text:y,z" can be used analogously to this example if the characters should be removed from both sides instead of only from one specific side.

Placeholders for Inserting and Attaching Text

With the two functional placeholders insert=x,y as well as append=x you can insert or append an arbitrary text. While text is always appended at the end, you can use the insert function to determine the character position for the text like you want.

As an example, the following placeholder represents the content of the first line with the text "abc" inserted at character position 3:

%ref:line=1>insert=3,abc%

If the first line consists of the text "12345", you will get "12abc345" with using this placeholder. Thus, in "insert=x,y" the x stands for the insertion position and the y for the text that is inserted.

In contrast, the functional placeholder "append=x" only knows one parameter. The x represents the text that will be appended at the end of the existing text. Accordingly, the following placeholder stands for the first 3 characters to which the 3 further characters "abc" have been appended:

%ref:chars=1-3>append=abc%

If the first 3 characters are "123", this placeholder results in "123abc".

Incidentally, a separate "prepend" function for attaching text to the beginning of a text is not necessary, since the "append" placeholder function can also be placed in front and thus fulfills the same function:

%ref:append=->word=1%

This placeholder stands for the first word preceded by the character "-". We could also achieve the same result with the insert function if we use "1" as the insert position:

%ref:word=1>insert,1,-%

However, in this case, neither the "append" nor the "insert" function would be required, since we would get the same result if instead of "%ref:append=->word=1%" or "%ref:word =1>insert,1,-%" we simply write "-%ref:word=1%". In other words, we can just remove the hyphen from within the placeholder entirely in this case and instead write it directly as text into the function in which we want to use the reference.

Of course, the same applies not only to texts that we want to put at the beginning, but also to texts that we want to append to the end. Since the "append" function placeholder only appends texts to the end, the most sensible place to use this placeholder is in combined placeholders as an intermediate link. But even this application in many cases can also be replaced by just using two individual instead of one combined placeholder.

Even if we have only used letters and hyphens as text in the previous examples, of course also line breaks and tabs can be used in both the insert and the append functions. How this works is explained in the section about using line breaks and tabs in functional placeholders.

Placeholders for Filtering Text

The functional placeholder respectively text filter find_text=x works like a search function. In this placeholder, x stands for a regular expression and all text fragments that match this regular expression are found.

In the following example we use find_text to extract all numbers from the first line:

%ref:line=1>find_text=[0-9]+%

With the regular expression [0-9]+ we match all numbers, regardless of whether a number consists of one or more digits. Accordingly, combined with that line reference, this placeholder stands for all numbers from the first line.

If we don't want to get the entire text that the used regular expression matches, we can use parentheses inside the regular expression to limit the search to only those included characters. This will only adopt the characters that are inside the brackets, while of course the whole regular expression will still be used for the search. An example of this is the following placeholder:

%ref:file=self>find_text= (a[a-t]+) %

This placeholder matches all words from the entire text (file=self) that begins with the letter "a" and consists of the characters a to t. We have defined a word within this regular expression in such a way that there must be a space before the first "a" and the word ends with another space. However, we do not want to find these two spaces again in our found text, which is why we are using brackets and write the spaces outside of these brackets and thus exclude them.

If the used regular expression matches multiple text fragments, we get each of these hits in a separate line with find_text. This allows us to suffix a line reference to select a specific one of those matches if we don't want to have all matches. An example of this is the following placeholder:

%ref:file=self>find_text=[0-9]+>line=1%

This placeholder stands for the first number that appears in the text being edited. First, the entire text of the own file or text is selected with "file=self". Then all numbers are extracted from this text with "find_text=[0-9]+" (each of these numbers in one line). Finally, after using the line reference "line=1", only the first line from the selection remains, that is the line in which the first number found is written. So, this placeholder stands for the first number of the text.

This way, any hit can be specifically addressed via its number. Of course, it is also possible to select several hits at the same time:

%ref:file=self>find_text=[0-9]+>lines=3-7%

Here, we do not use "line=x" to select a specific hit via its exact number, but several at once with "lines=x-y". Accordingly, this placeholder stands for the third, fourth, fifth, sixth and seventh number that occurs in the current text.

If we don't want to have the individual hits listed line by line, we can use the replace function placeholder to replace the line breaks with another character or text:

%ref:file=self>find_text=[0-9]+>lines=3-7>replace=\l,", "%

In this example, we replace the line breaks (\l) that are separating the individual lines with the text ", " and thus do not get our 5 numbers one below the other in several lines, but comma-separated one after the other.

In addition, for some purposes, also the line filter, which is introduced in the next section, is suitable. This filter allows you to filter the hits not by their number but by their content.

Placeholders for Filtering Lines

The functional placeholders respectively line filters find_lines=x and find_lines=x,y as well as delete_lines=x and delete_lines=x,y can be used to filter lines. With find_lines=x, only those lines that contain the text x are kept. On the other hand, with delete_lines=x, all lines that contain the text x are sorted out and only those lines that do not contain the text x are kept. Both functional placeholders can optionally be extended with the parameter y, with which options can be passed, for example to be able to use the filters with regular expressions.

A simple example of using the line filter is the following placeholder:

%ref:file=self>find_lines=abc%

This placeholder stands for all lines of the current text (file=self) that contain the text "abc".

The opposite of this placeholder is the following placeholder, which stands for all lines of the current text that do not contain the text "abc":

%ref:file=self>delete_lines=abc%

Accordingly, the functional placeholder delete_lines produces an inverse result to the result of find_lines, otherwise it works exactly like find_lines and can also be used with the same parameters.

Of course, the results of find_lines or delete_lines can still contain multiple lines that are all matching the chosen criterion. If we want to narrow down this result even further, we can do so, for example, using line references:

%ref:file=self>find_lines=abc>line=1%

This placeholder, for example, stands for the first line of the entire text that contains the text "abc". The line reference "line=1" keeps only the first line of all possible matches and discards all others. In the next example, on the other hand, we don't want to keep only one line, but three lines starting from the second line:

%ref:file=self>find_lines=abc>lines=2,3%

In our examples so far, we have searched for a specific text that has to be part of a line regardless of its uppercase and lowercase writing. However, instead of searching case-insensitively, we can also search case-sensitively. Instead of searching a specific text, we can also search using regular expressions. And instead of that it is enough that the search text only has to appear in a line to produce a match, we can also search in a way that the entire line must match the search text completely to produce a match. All of these different cases can be controlled via the optional parameter y, which we have already mentioned at the beginning of this section.

In the functional placeholders find_lines=x,y and delete_lines=x,y, x stands for the search text respectively for the regular expression and y for the parameters. If y contains the letter "r", x is interpreted as a regular expression (otherwise as text). If y contains the letter "c", x is searched for in a case-sensitive manner (otherwise a search for "a" will find both "a" and "A"). And if y contains the letter "a", the whole line must match x to produce a hit (otherwise only parts of it will suffice).

As an example, the following placeholder stands for all lines that only contain numbers respectively digits and no other characters:

%ref:file=self>find_lines=[0-9]+,ra%

As parameters, we have passed "ra". Accordingly, our search text "[0-9]+" should be interpreted as a regular expression (r) and the entire line content must match this regular expression (a). If we had omitted the "a" parameter, instead, the criterion would be that there must occur at least one digit in a line to match regardless of any other line content, so lines containing other characters beside one or more digits would also be found.

An example for the "c" parameter is the following placeholder:

%ref:file=self>delete_lines=These are,c%

This placeholder stands for all lines in which the text "These are" does not occur. Without the "c", those lines that only contain the text "these are" would also be sorted out. However, since we use "c" to indicate that we attach importance to observing upper and lower case letters, all letters must appear in exactly this case in order to match this placeholder. If we would have taken "ca" as a parameter, only those lines would match that contain exactly the text "These are", without any different writing and without any other character.

If our search text contains a comma, we have to enclose the search text in quotation marks so that it is clear that after the comma there is not the second parameter beginning. For example, the following placeholder finds all lines containing the text "a,b" taking into account the parameter"c":

%ref:file=self>find_lines="a,b",c%

The line filter placeholder can of course be used at any place of a chain of combined placeholders and therefore does not always have to refer to the entire text, as we have done in the previous examples with "file=self". As an example, the following placeholder stands for those of the first 20 lines that contain the number "1" (all lines beginning with the 21st line are ignored accordingly):

%ref:lines=1-20>find_lines=1%

Additionally, the line filters can also be used to limit search results:

%ref:xml=h2>find_lines=abc%

This placeholder, for example, stands for all h2 headings that contains the text "abc". With the XML reference "xml=h2", first all inner texts of all h2 elements are read out. Then find_lines is used to filter this list. Of course, the same also works for all other search results of references or functional placeholders, such as for the results of references to attribute values within XML files or for the hit lists of the text filter.

Placeholders for Rewriting Text

With the two functional placeholders write=x and rewrite=x we can rewrite a text or change its writing. The placeholder write=x only changes the case of the text, while rewrite=x can also be used to perform more detailed paraphrasing and text changes. What exactly is to be changed can be controlled via the parameter x in both placeholders.

In the case of write=x, x can take one of the values "lowercase", "uppercase", "uppercase_words", "uppercase_first" or "randomcase" and thus change the uppercase and lowercase writing of the text. We can see an example for this here:

%ref:word=3>write=uppercase%

This placeholder stands for the third word written in uppercase letters. When this placeholder is resolved, first, the third word is read out via the used word reference and then all letters of the read text are converted to upper case letters with "write=uppercase".

In the next example, we combine two different changes of the writing:

%ref:line=7>write=lowercase>write=uppercase_first%

This placeholder stands for the seventh line, which is completely written in lowercase letters except for the first letter. To achieve this, the functional placeholders write=lowercase (all letters lowercase) and write=uppercase_first (first letter uppercase) are used one after the other. First, the content of the line is converted to lower case letters, then the first character of the line is converted to an upper case letter.

The other values for x have the following meanings: "uppercase_words" (all words should start with a capital letter) and "randomcase" (the upper and lower case writing of all letters should be random).

In the case of the functional placeholder write=x, x accepts one of the following values: "remove_double_spaces", "remove_double_tabs", "remove_double_linebreaks", "remove_double_whitespace", "replace_diacritics", "remove_diacritics", "separate_camelcase", "encode_url", "decode_url", "encode_htmlentities", "decode_htmlentities", "encode_xmlchars", "decode_xmlchars", "insert_linebreaks_after_breaking_html_tags", "remove_tags", "link_websites" or "link_emails".

Again, we can simply replace the "x" in "write=x" with one of these parameters to apply the function. The following example represents the content of the XML file "file.xml" with all tags removed:

%ref:file=E:\file.xml>rewrite=remove_tags%

The next example stands for the content of the file "file.txt" with all double line breaks, spaces and tabs (more than one of these whitespace characters in a row) removed:

%ref:file=E:\file.txt>rewrite=remove_double_whitespace%

If we only want to remove double linebreaks (and not double spaces or tabs), we could use "rewrite=remove_double_linebreaks". Analogously, the parameters "rewrite=remove_double_spaces" and "rewrite=remove_double_tabs" work for removing double spaces or double tabs only.

With "rewrite=replace_diacritics", umlauts can be converted into their alternative (ä to ae), with "rewrite=remove_diacritics" accents can be removed from the characters (äá to aa), "separate_camelcase" separates words connected with uppercase and lowercase writing changes ("AbcDef " to "Abc Def") and the rest of the parameters should be self-explanatory.

Placeholders for Padding Text

With the two functional placeholders lpad=x,y and rpad=x,y a text can be filled up on the left (lpad) or on the right (rpad) with any text to a desired length. Within the placeholders, x is the desired length and y is the text or character that is used for the padding.

In the following example we use the functional placeholder lpad to bring the content of the CSV field of the second row from the first column to a total length of three characters using leading zeros:

%ref:cell=1:2>lpad=3,0%

Accordingly, in lpad=3,0 the first number (3) is the desired length while the second number (0) is interpreted as text. For example, if the CSV field has the original content "1", using this placeholder ensures that the text returned is "001" instead of "1".

In the next example, we want to pad the content from the first line on the other side, that is on the right side, to a total length of 10 characters:

%ref:line=1>rpad=10, -%

This time we don't use a single character for the padding, but the text " -", so it is filled up alternately with spaces and hyphens. If the line has the content "abcdef" as an example, using this placeholder we get the result "abcdef - -".

Placeholders for Adjusting Numbers

The functional placeholder inc=x can be used to increase all numbers within the text of your reference by the value x. If you use a negative number for x, all numbers within the text are reduced by the value x instead.

As an example for this functional placeholder, we would like to have a look at a line reference. The first line of the text that we can extract with the reference %ref:line=1% contains the text "1 abc 2 def 3 ghi 10 jkl". Subsequently, we add the functional placeholder inc=x to this reference to increase all numbers within this line by 1 or 2 as well as decrease them by 1. The placeholders required for this as well as the result when using these placeholders are shown in the following table:

PlaceholderResult
%ref:line=1%1 abc 2 def 3 ghi 10 jkl
%ref:line=1>inc=1%2 abc 3 def 4 ghi 11 jkl
%ref:line=1>inc=2%3 abc 4 def 5 ghi 12 jkl
%ref:line=1>inc=-1%0 abc 1 def 2 ghi 9 jkl

If you don't want to edit each of the numbers within the text of the reference, you can add another parameter to the functional placeholder: With inc=x,y you can only increase or decrease the number by x that is located at position y within the text of your reference. With positive numbers for y you count the position from the front, with negative numbers for y you count the position from the back. The first number within the text of your reference corresponds to position 1, the second number corresponds to position 2 and so on.

We would like to look at an example for this as well. Again we use the same line reference that we have also used in our first examples:

PlaceholderResult
%ref:line=1%1 abc 2 def 3 ghi 10 jkl
%ref:line=1>inc=1,1%2 abc 2 def 3 ghi 10 jkl
%ref:line=1>inc=2,2%1 abc 4 def 3 ghi 10 jkl
%ref:line=1>inc=-3,4%1 abc 2 def 3 ghi 7 jkl
%ref:line=1>inc=-3,-1%1 abc 2 def 3 ghi 7 jkl

In the table, next to the unedited line, you can see four different edits created with the functional placeholder inc=x,y. In the first example, we use inc=1,1 to increase the first number by 1. In the second example, we use inc=2,2 to increase the second number by 2. Although we use different parameters in the last two examples, both examples lead to the same result. In the first case we count the positions of the numbers from the front and reduce the number at the fourth position by 3 with inc=-3,4. In the second case we count the positions of the numbers from the back and we use inc=-3,-1 to reduce the number at the last position (the first position counted from the back) also by 3. Since the first position from the back corresponds to the fourth position from the front, both examples lead to the same result.

How to use Line Breaks and Tabs in Functional Placeholders

If you want to use line breaks or tabs in the functional placeholders "replace=x,y", "replace=x,y,z", "replace_regex=x,y", "delete=x", "delete_regex=x", "delete_chars=x", "append=x", "insert=x,y", "find_text=x", "find_lines=x", "find_lines=x,y", "delete_lines=x" or "delete_lines=x,y", you can use the wildcards \l, \r, \n and \t for them. In doing so, "\l" stands for the line break type of the system, "\t" for a tab and "\r" and "\n" for the code points U+000D and U+000A, with which it is possible to emulate line break types of different systems. In the following we would like to look at examples for all of these wildcard types.

%ref:line=1>replace=\t, %

This placeholder stands for the first line in which all tabs have been replaced with spaces using the replace function placeholder. While the space is inserted as such in that functional placeholder, for the tab the wildcard "\t" is used.

%ref:file=E:\file1.txt>append=\l\l>=E:\file2.txt%

This placeholder stands for the contents of the files "file1.txt" and "file2.txt", between which two line breaks are written using the append function. Because the wildcard "\l" (system line break type) is used here, the result depends on which system this placeholder is used on. On Windows systems, a line break is expressed by the two characters 0D and 0A one after the other, so that on Windows systems "\l" stands for "0D 0A" and these two characters are written twice between the file contents, provided the placeholder is used on a Windows system .

In contrast to Windows, macOS only uses the character 0A for a line break. Accordingly, on a Mac, the "\l" wildcard would represent "0A". If you try to open a file that was saved on a Mac on a Windows system, this can lead to an incorrect display in some programs. This leads us to the \r and \n wildcards, where \r stands for 0D and \n for 0A. In other words, regardless of the "\l" wildcard, we can emulate macOS line breaks with \n and Windows line breaks with \r\n. Both variants appear in the next reference:

%ref:file=D:\macfile.txt>replace=\n,\r\n%

This placeholder references the content of the file "macfile.txt" in which all macOS line breaks (\n) have been replaced with Windows line breaks (\r\n) using the functional placeholder for replacements. This placeholder can be used, for example, if you want to paste the content of files saved on a Mac into Windows text files without having to fix the mix of different line break types later.

So far we have used the wildcards for line breaks and tabs only alone. Of course, a combination with any other characters is also possible. For example, the following placeholder appends the three additional lines "abc", "def" and "ghi" to the first three lines:

%ref:lines=1-3>append=\labc\ldef\lghi%

Last, we want to look at one final example demonstrating what we can do if we want to use "\r", "n", "\l" or "\t" as text without it being interpreted as a line break or a tab. In this case we can just write another "\" in front of the wildcard in order to escape the placeholder with that character:

%ref:line=1>replace=\\r\\n,\\l%

This placeholder stands for the first line in which the text "\r\n" has been replaced by "\l".

How to use the Character ">" in Functional Placeholders

The character ">" has a special meaning within placeholders for references. It serves as a separator with which several individual references can be combined with each other as well as with functional placeholders. For this reason, this character cannot simply be used as such within functional placeholders, since otherwise it would be unclear whether the character should be interpreted as text or as the beginning of a new chain link within several linked placeholders. Instead, the character must be written twice if it is to be interpreted as text.

An example for both cases is the following placeholder, which contains the character ">" in both of its two forms of use:

%ref:lines=1-10>find_lines=>>%

The single ">" stands between the two elements of the placeholder and thus separates the line reference "lines=1-10" from "find_lines=>>". The double ">>" is used in the functional placeholder "find_lines" and stands for the text ">". Accordingly, this placeholder stands for those of the first 10 lines that contain the character ">" . A simple ">" within the lines is sufficient for a hit, even if a line containing ">>" would of course also match this line filter. The following example also illustrates this type of interpretation:

%ref:line=1>replace=a>>b,a<b%

This placeholder stands for the first line in which the text "a>b" is replaced by the text "a<b".

Combination of various References and Functional Placeholders

As you may have already seen in the numerous examples of this tutorial, placeholders for references and functional placeholders can be combined with each other and under each other as desired. In this section, we would like to briefly address this topic and show what needs to be considered when concatenating the placeholders.

Structure of combined Placeholder

The first thing to note is that each reference placeholder starts with "%ref:" and ends with "%". In between there can either be a single reference...

%ref: ... %

...or also any number of references and functions, which are then separated from each other with a ">":

%ref: ... > ... > ... %

It is not without reason that the character ">" indicates an arrow that points from the first part of the placeholder across all elements of the chain to the last part of the placeholder, because this is exactly the way the TextConverter interprets a placeholder: The TextConverter starts with an empty string, which is then set, delimited or edited across the individual parts of the placeholder.

Example for the Interpretation of a combined Placeholder

Let's take a step-by-step look at this procedure on the basis of the following placeholder:

%ref:file=E:\text.txt>trim=whitespace>line=1>word=2>chars=1-3>rewrite=uppercase%

When interpreting this placeholder, the TextConverter will proceed as follows:

With this our reference ends, which at this point consists of 3 uppercase letters that originally came from the file "E:\text.txt" and that may have been written in lowercase letters first. With these 3 letters the TextConverter will work now at the place where you have inserted this reference.

Special Cases and Restrictions

Basically, there are no restrictions regarding the number of combined placeholders or the position of the individual components. In principle, you can use any placeholder and any function at any point within the chain. Nevertheless, some specialties should not remain unmentioned:

Beyond that, there are no further restrictions regarding the use of combined references and functional placeholders.

References in Action Lists

References can not only be used in the text fields of actions, but also in action lists. Also in this case, the placeholders can just be written into the actions and can also be combined with other characters or placeholders.

This way, placeholders for references can for example be used as a sole parameter in the actions of an action list as in the following example, which replaces the character "~" with the text from the first line:

REPLACE ~ %line=1%

Of course, it is also possible to use placeholders for references in both parameters, as in the following example, which replaces the text from the first line with the text from the second line with the help of line references in lines 3 to 10:

REPLACE_IN_LINES 3-10 %line=1% %line=2%

Also functional placeholders can be used in the parameters of action lists without any problems. In the following example, we use the action APPEND within an action list to attach the text from the first line, which is processed before attaching with the trim function within the placeholder before inserting:

APPEND %line=1>trim=whitespace%

Another example that combines the use of functions with the double use of placeholders is the following action of an action list that replaces the entire content of a text by those lines of the same text that contain the text "abc" with the help of the find_lines function:

REPLACE %ref:file=self% %ref:file=self>find_lines=abc%

In addition, it is of course also possible to combine the placeholders for references with other characters and placeholders, as the following action list shows:

REPLACE -- -%chars=1-3%-
REPLACE " %word=2-4% " " %word=2% %date% %word=4% "
DELETE " %word=3% "

As in any other case in which text is used as a parameter for actions of an action list, also when using placeholders for referecens in parameters, it must be taken care to put the parameters in quotation marks if they contain any spaces. If the parameters do not contain spaces, as in the action written in the first line of the last example, no quotation marks are necessary. Additionally, the example in the second line shows that, of course, also non-referencing placeholders such as here the placeholder for the current date (%date%) can be combined with other characters and placeholders for references as desired.

References in File Names

In the TextConverter, references can also be used to generate file names or storage locations from parts of the files' content for storing the corresponding converted files. For this, the placeholders for references introduced in this tutorial can be used and combined with any other characters and placeholders in the fields "Folder", "Name" and "File Extension" of the TextConverter's storage options.

For example, if you specify "%folder%\%ref:word=1%" as the folder for storage, a new folder which name corresponds to the first word of the file (%ref:word=1%) will be created in the folder where the original file is located (%folder%) to store the converted file. If you specify "%ref:line=1%" as the name for storage, the first line of the file will be used as the file name for the converted file. And if you specify "%name% (%chars=1-10%)" as the name, the first 10 characters of the file enclosed in brackets will be appended to the existing name of the file (%name%).

In contrast to the references within the actions, it is not necessary to activate the option "Actions > Options > References" to be able to use references in file names: references are always active within the storage options and will therefore automatically be replaced. This corresponds to the behavior of the other placeholders, which are also always active in the storage options.

Of course, the referenced texts could also contain characters such as ":", "\", "<" or ">", which are not allowed in file names. With the option "Settings > General > File Name > Replacement for disallowed Characters in File Names" you can specify a text that is used instead of these illegal characters, i.e. that replaces the illegal characters. As default, the character "_" is used, but you can also enter a space or any other character or text. If you leave the field completely empty, the disallowed characters will just be deleted and not replaced by another character or text.

Within the file list, the preview for file names that contain references is disabled for performance reasons. However, you can select individual files from the file list and thus display a preview of the file name below the preview text of the file.

References in Scripts

Also if you control the TextConverter via a script, the use of references must be activated for the placeholders for references in the actions to be replaced. Otherwise, the placeholders are treated as normal text. So, the behavior in case of a script control of the TextConverter is the same as in the case of controling the program via the graphical user interface (more about enabling and disabling the reference placeholders in the section about the basics of using references).

You can activate references both via settings files as well as via the parameter "ref=1". If you use settings files, just make sure to check the option "Actions > Options > References" before saving the settings file. If you don't use settings files, for example if you define actions or action lists directly via parameters, simply additionally pass the parameter "ref=1", as shown in the following example, which replaces the character "~" by the content of the first line in the file "test.txt":

TextConverter.exe -cl C:\test.txt "a=REPLACE ~ %%ref:line=1%%" ref=1

You can read more about this topic in the tutorial about script controlling the TextConverter in the section about parameters for enabling placeholders and references.

Overview over all Placeholders for References

In the following table you can see an overview over all uncombined placeholders for references that you can use in the text fields of the TextConverter. The placeholders are listed in the first column, while in the next columns you will find a short description and a link to the section of this tutorial, in which the respective placeholder is explained in detail and in which you will also find some examples for using the placeholder.

PlaceholderShort DescriptionDescription
%ref:char=x%Character at Position xDescription
%ref:chars=x-y%Characters from Position x to yDescription
%ref:chars=x,y%y Characters from Position xDescription
%ref:word=x%Word at Position xDescription
%ref:words=x-y%Words from Position x to yDescription
%ref:words=x,y%y Words from Position xDescription
%ref:line=x%Line with Line Number xDescription
%ref:lines=x-y%Lines from Line Number x to yDescription
%ref:lines=x,y%y Lines from Line Number xDescription
%ref:cell=x:y%Content of the Field in Column x and Line y from CSV DataDescription
%ref:xml=x%Inner Text of all Elements of an XML Structure to which the Selector x appliesDescription
%ref:xml=x>line=y%Inner Text of the Element Number y of an XML Structure to which the Selector x appliesDescription
%ref:xml=x>attribute=y%Values of all Attributes with the Attribute Name y of Elements from an XML Structure to which the Selector x appliesDescription
%ref:xml=x>attribute=y>line=z%Values of the Attribute Number z with the Attribute Name y of Elements from an XML Structure to which the Selector x appliesDescription
%ref:file=x%Content of the File with the File Path x or total Content of the Text to be processed for "file=self"Description

All of the listed placeholders can be combined with each other as well as with the functional placeholders listed in the next section. With this, the referenced text can be processed before inserting or you can, for example, only adopt certain characters or words from lines or files. You can find out more about that in the section about the combination of placeholders.

Overview over all Functional Placeholders for References

In the following table you can see an overview over all functional placeholders available in the TextConverter, which you can combine with the placeholders for references from the last section. The placeholders are listed in the first column, while in the second column you can find their description. In the third column there is a link to the section of this tutorial, in which the corresponding placeholder function is explained in more detail and presented with some examples.

PlaceholderDescriptionExamples
>replace=x,yReplaces Text x by Text y. This placeholder is working case-insensitively. To search the text for the replacement case-sensitively, you can use the placeholder replace=x,y,z in the form replace=x,y,c to replace the text x with the text y. You can find out how to use line breaks and tabs in this placeholder here.Examples
>replace=x,y,zReplaces Text x by Text y using the Options z. If z contains the character "c", the search is case-sensitive, that means it takes into account upper and lower case letters. If z contains the character "r", x and y are interpreted as regular expressions. Possible values of z are, for example, "c", "r" or "cr". You can find out how to use line breaks and tabs in this placeholder here.Examples
>replace_regex=x,yReplaces the Regular Expression x by the Regular Expression y. This placeholder is a short form of the placeholder replace=x,y,r and is therefore working case-insensitively. To work case-sensitively, please use the placeholder replace=x,y,cr instead where x and y are the regular expressions and x is replaced by y. You can find out how to use line breaks and tabs in this placeholder here.Examples
>delete=xDeletes Text x. This placeholder is working case-insensitively. To delete a text case-sensitively, you can use the placeholder replace=x,y,z in the form replace=x,,c to delete the text x. You can find out how to use line breaks and tabs in this placeholder here.Examples
>delete_regex=xDeletes all Characters matching the Regular Expression x. This placeholder is working case-insensitively. To delete a text using a case-sensitive regular expression, you can use the placeholder replace=x,y,z in the form replace=x,,cr to delete text with the help of the regular expression x. You can find out how to use line breaks and tabs in this placeholder here.Examples
>delete_chars=xyzRemoves all individual Characters x, y and z. The specification of any number of characters is possible. You can find out how to use line breaks and tabs in this placeholder here.Examples
>trim=xRemove Characters from the Front, from the Back or from both Sides. Possible values for x are "whitespace", "whitespace_left" and "whitespace_right" to remove whitespace, "number_of_chars:y", "number_of_chars_left:y" and "number_of_chars_right:y" to remove a number of y characters as well as "chars:y", "chars_left:y" and "chars_right:y" to remove all characters defined in y. In addition, the values "till_text:y,z", "till_text_left:y,z" and "till_text_right:y,z" can be used for x to truncate the characters till and/or from a text. In this variant, "y" is the text and "z" is a selection composed from the parameters "c" (case sensitive), "r" (interpret as regular expression) and/or "i" (include text).Examples
>append=xAttach Text. The text x is attached at the end. You can find out how to use line breaks and tabs in this placeholder here.Examples
>insert=x,yInsert Text. The text y is inserted at the character position x. You can find out how to use line breaks and tabs in this placeholder here.Examples
>find_text=xText Filter. Finds all fragments from the text that match the regular expression x. If you use parentheses inside the regular expression, only the text inside the parentheses will be taken. This placeholder can be combined with line references or line filters to select only certain from several hits.Examples
>find_lines=x
>find_lines=x,y
Line Filter. Finds all lines that contain or match the text or regular expression x. Parameters can be passed with the optional parameter y. If y contains the letter "r", x is interpreted as a regular expression (otherwise as text). If y contains the letter "c" x is searched case sensitively. If y contains the letter "a", the whole line must correspond to x to match (otherwise only parts of it). This placeholder can be combined with line references or more line filters to select only certain from several hits.Examples
>delete_lines=x
>delete_lines=x,y
Inverse Line Filter. Deletes all lines that contain the text or match the regular expression x. This function works the same way like find_lines, but produces the opposite result. Optionally, for y, the same parameters like for find_lines can be used.Examples
>write=xChanges the Writing. Possible values for x are "lowercase", "uppercase", "uppercase_words", "uppercase_first" and "randomcase".Examples
>rewrite=xRewrites the Textes. Possible values for x are "remove_double_spaces", "remove_double_tabs", "remove_double_linebreaks", "remove_double_whitespace", "replace_diacritics", "remove_diacritics", "separate_camelcase", "encode_url", "decode_url", "encode_htmlentities", "decode_htmlentities", "encode_xmlchars", "decode_xmlchars", "insert_linebreaks_after_breaking_html_tags", "remove_tags", "link_websites" as well as "link_emails".Examples
>lpad=x,yPads Text on the left Side. The text is enlarged to a length of x characters, for which the text y is prepended at the beginning of the text in the required length.Examples
>rpad=x,yPads Text on the right Side. The text is enlarged to a length of x characters, for which the text y is appended to the end of the text in the required length.Examples
>inc=x
>inc=x,y
Increase or Decrease Numbers. Increases the numbers in the text by x, if x is positive. If x is negative, the numbers are reduced by x. If no y is specified, all numbers are processed. If y is specified, only the number at position y is processed. Positive values of y count the position from the front, negative values of y count the position from the back.
Example

If you insert one or more of these functional placeholders behind a placeholder for references, the text of the reference is processed according to the function for which the functional placeholders stands for. For example, the combined placeholder %ref:line=1>write=uppercase% stands for the text from the first line converted into capital letters. Several functional placeholders can also be applied at the same time by simply writing them in a row. You can find out more about this topic in the sections about functional placeholders and the combination of placeholders.