Script Control of the TextConverter
All actions and functions for the processing and the conversion of text files that can be used via the graphical user interface of the TextConverter can also be controlled via the command line. With this, it is possible to control the TextConverter via scripts and automate tasks of text conversion.
In this tutorial, we show you how you can control the TextConverter via parameters and which parameters are available to convert files and the content of folders. In addition, you can also have a look at the tutorial about the script control of the TextEncoder for the TextConverter. The TextEncoder tutorial places a greater focus on reading and changing the encoding and line break type of text files, while this tutorial is more focused on actions to change the content of the files. All parameters presented in the TextEncoder tutorial can also be used with the TextConverter. For the functions presented in this tutorial, you need the TextConverter in the version TextConverter Pro CL.
The tutorial is divided into the following sections:
- Basics of the Script Control of the TextConverter
- Apply single Actions
- Apply Action Lists
- Apply Settings Files
- Parameters for the Storage Location and the File Name
- Parameters for the Encoding and the Type of Line Break
- Parameters for the File Date
- Parameters for activating Placeholders and References
- Combined Application of Actions, Action Lists, Settings Files and Parameters
- Convert single and multiple Files
- Convert Files from Folders
- Show Information about Files
- Overview of all available Parameters
- Script Control of the old Program Version
Basics of the Script Control of the TextConverter
To put the TextConverter into batch mode, we use the parameter -cl. This parameter stands for "command line mode" and is always passed as the first parameter in all of the following examples. If we do not pass this parameter, the TextConverter will start with graphical user interface and there will be no automatic conversion of the files that are passed. Instead, files that are handed over as parameters will be displayed in the file list after the start of the program. In the same way, it behaves with passed folders, which content will be loaded into the file list of the TextConverter. Of course, this function can also be useful if you want to start the TextConverter with certain files.
Basically, we have 3 different ways to tell the TextConverter which conversions should be carried out: We can pass individual actions as parameters, we can pass action lists in the form of files that can contain multiple actions or we can pass settings files that in addition to the actions can also contain other settings such as storage settings, for example. Additionaly, there are some parameters available for the storage options, the encoding, the type of line break and for searching files in passed folders.
Let's have a look at some simple examples before we go into detail in the following sections. The most simple example is to let the TextConverter execute a single action. We can pass actions with the parameter "a=action":
TextConverter.exe -cl C:\test.txt "a=REPLACE a b"
This replaces the letters "a" by "b" in the file "test.txt". If we want to apply multiple actions, we can pass them with the help of the parameters a1, a2, a3 and so on in a row:
TextConverter.exe -cl C:\test.txt "a1=DELETE a" "a2=DELETE b"
This deletes all occurrences of "a" and "b" in the file "test.txt" file. You can find out more about that in the section about the application of individual actions.
If you want to apply multiple actions, you do not necessarily have to write them in a row. Instead, you can also summarize several actions in a action list (text file with one action per line) and only pass this action list:
TextConverter.exe -cl C:\test.txt al=C:\actionlist.tcal
Multiple action lists can be passed with the parameters al1, al2, al3 and so on and are then processed in turn by the TextConverter. You can find out more about action lists in the section on the application of action lists.
The third way is to hand over settings files. Settings files are the files in which theTextConverter stores its settings. These files always have the file extension TCS (Text Converter Settings) and can be passed as follows:
TextConverter.exe -cl C:\test.txt C:\settings.tcs
This converts the file "test.txt" according to the settings that are stored in the settings file "settings.tcs". You can find out more about the creation and the use of settings files in the section about the use of settings files.
In all of our previous examples, we have not influenced the storage location of the converted file (unless there are corresponding settings in the settings file). If there is no statement about a different storage location, the original file is overwritten. If we want to save the edited file to a location other than the original file, there are some parameters available, for example:
TextConverter.exe -cl C:\test.txt "a=WRITE LOWERCASE" save=C:\lowercase.txt
TextConverter.exe -cl C:\test.txt "a=WRITE UPPERCASE" save-folder=C:\uppercase
Both lines change the writing of the text in the file "test.txt". The first line converts all letters of the file into lowercase letters and stores the result as a new file in the file C:\lowercase.txt. In the second line, instead of a complete file path, only one folder for storage is specified. This means that the name of the file is retained and the result (all letters uppercase) in this case is saved as a new file under C:\uppercase\test.txt. You can find out more about the storage options in the section about the parameters for the storage.
In addition to the parameters for the storage, there are also some parameters available for the encoding and the line break type used for reading and saving the files. You can see an example here:
TextConverter.exe -cl C:\test.txt "a=SWAP_LINES 1 2" save=C:\swapped.txt enc=utf8 bom=0 lb=crlf
In this example we edit the file "test.txt" again. This time we exchange the first and the second line of the text in the file and we save the result in the file C:\swapped.txt with the encoding UTF-8 and the line break type CRLF (Windows). In addition, with "bom=0" we state that no byte order mark should be written into the file. If we omit the parameters for the encoding and the line break type, an attempt is made to determine the encoding and the type of line break of the original file automatically in order to use it again for the storage. You can find out more about this topic in the section about the parameters for the encoding and the line break type. There you can also find out how you can force the Text Converter to read files with a certain type of line break or a certain type of encoding. In addition, you can find a list of all encodings and line break types supported by the TextConverter in the overview of all supported formats of the TextConverter.
Of course, all parameters presented so far can also be combined with each other. In which order the parameters and actions are processed and executed, especially if several competing settings are passed, can be found in the section about the combined use of actions, action lists, settings files and parameters.
Up to now, we have only worked on one file at the same time. However, it is also possible to edit several files at once. For example by handing over multiple files or a whole folder:
TextConverter.exe -cl C:\test1.xml C:\test2.xml "a=DELETE_ATTRIBUTES ALL"
TextConverter.exe -cl C:\folder filter-ext=csv "a=CALC_IN_CELLS ALL ADD 1"
With the first line we delete all attributes from the XML files "test1.xml" and "test2.xml". The second line processes all CSV files in the folder "C:\folder" and adds the value 1 in every cell of the CSV table. You can learn more about this topic and other filter options for folders in the sections about the processing of individual or multiple files and the processing of folder content.
Apply single Actions
If you only want to make one or a few changes to files, you can pass individual actions directly via parameters without having to create an action list or a settings file. You can see an example of this here:
TextConverter.exe -cl C:\test.txt "a=REPLACE a b"
With this call we replace the letter "a" with "b" in the file "test.txt". First we put the TextConverter into the batch mode with the parameter "-cl". Then we hand over the file we want to edit. With the parameter "a" we can define an action (in this case "REPLACE a b"), which the TextConverter then executes.
If we want the TextConverter to apply several actions, we can use a1, a2, a3 and so on. Here is an example:
TextConverter.exe -cl C:\folder "a1=REWRITE REMOVE_DOUBLE_SPACES" "a2=DELETE_LINES 1-5"
With this call we edit all files from the folder "C:\folder". First we remove all double spaces, then we remove the first five lines from each file. Multiple actions are always carried out in the order of the parameters. Even if you write "a2" in front of "a1", the first parameter (here "a2") is always carried out first.
If you do not know which actions are available and what the syntax of the actions looks like, you can start the TextConverter and create your desired actions by using "Action Lists > New Action" via the graphical user interface. If you switch from the list view into the text view of the action list, you will see the syntax and you can copy and use the action directly. For more information, see the introduction to the use of action lists in the TextConverter.
Apply Action Lists
Action lists are text files that can contain one or more actions. This means that action lists offer the opportunity to summarize several actions and use them in a bundling. Within an action list, each action is written in a new line. So, for example:
REPLACE Hello "Good Day"
DELETE_IN_LINES 10-20 [0-9] -r
SORT_LINES 4-7 DOWN
WRITE UPPERCASE_WORDS
This action list initially replaces "Hello" with "Good Day". Then all numbers from lines 10 to 20 are deleted using regular expressions (-r), then the lines 4 to 7 are sorted in descending order and finally the first letter of all words of the entire text is capitalized.
If we save this text respectively this action list, for example, under the file name "C:\actionlist.tcal" (the file extension TCAL stands for "Text Converter Action List"), we can use it as follows:
TextConverter.exe -cl C:\test.txt al=C:\actionlist.tcal
First, we put the TextConverter into the batch mode using the parameter "-cl". We pass the file "test.txt" and use the parameter "al=" to hand over our action list. This means that the TextConverter will apply all actions from our action list "actionlist.tcal" to the file "test.txt". Since we have not given any information about a different storage location, the original file "test.txt" will be overwritten with the changed file.
Several action lists can also be passed and applied at the same time within one call:
TextConverter.exe -cl C:\test.txt al1=C:\actionlist1.tcal al2=C:\actionlist2.tcal
With the parameters al1, al2, al3 and so on, several action list files can be passed in a row. Regardless of whether you are using al1, al2, al or al10 as the first parameter, the TextConverter will always process the first passed action list first. When this action list is finished, the next passed action list will be processed and so on.
If you do not want to create your action lists manually, you can also use the graphical user interface of the TextConverter to do so. In all areas that are named "Action Lists" you will find the button "New Action List". If you click on this button, you will get to an editor with which you can conveniently create actions and add them to your action list. You can either copy and save the result from the editor manually or you can leave the management and storage of the action lists to the TextConverter. The action lists stored by the TextConverter can be found in the folder "actionlists" located in the program folder.
Apply Settings Files
In addition to passing individual actions or action lists as parameters, settings files can also be used for the conversion of files via script control. Settings files always have the file extension TCS (Text Converter Settings) and can contain all settings of the TextConverter. So they can not only contain individual actions such as the action lists, but also, for example, storage options. You can find out more about settings files in the article about loading and saving settings.
Settings files can be conveniently created via the graphical user interface of the TextConverter. First, just set all actions, options and storage settings in the TextConverter as if you want to convert files via the graphical user interface. Then go to the menu "Settings > Save and Load Settings" and click on the the button "Save as File". You will receive a file that contains all current settings of the TextConverter. You can pass this file directly to the TextConverter:
TextConverter.exe -cl C:\test.txt C:\settings.tcs
In this example, the file "test.txt" is converted according to the settings that you have saved in the file "settings.tcs". These can be actions as well as storage options or conversions of the encoding or the line break type used in the file.
If you hand over multiple settings files as parameters, they are loaded in turn and always overwrite the settings already loaded from the other setting files. If you mix settings, action lists or other parameters in the parameters, the settings files are always loaded first and, if necessary, overwritten by the parameters (more about this here).
If you save settings files with the TextConverter, these files contain a lot more information than we need for our script control. For example, the settings files can also contain information about the window size, the window position or the columns of your file list. The TextConverter uses this information when loading the graphic user interface. If the TextConverter is launched in batch mode, this information not needed is simply ignored. So it is not necessary to "clean up" the settings files manually, they can simply be used as they are saved by the TextConverter.
Nevertheless, there can be situations in which it makes sense to adapt the settings files manually. You can open and edit the settings files with any text editor. For example, to create a settings file that contains only certain actions or only the storage options. You can then combine these "part" settings files as a parameter with other settings files or parameters, which can be in certain situations more effective than creating your own settings file for each combination of settings.
Parameters for the Storage Location and the File Name
If we do not explicitly tell the TextConverter where and under which name converted files should be saved, the original file is overwritten by default. An example of this would be the following call:
TextConverter.exe -cl C:\test.txt "a=MOVE_LINES 1 -1"
With this call, the TextConverter will first read the file "C:\test.txt", then move the first line of the file to the end of the file and then save the result under "C:\test.txt". In other words, this will overwrite the original file because we have not specified a different location.
In the event that we do not want to overwrite the original file, the parameters save, save-folder, save-name and save-ext are available. In the following we look at examples of each of these parameters.
TextConverter.exe -cl C:\test.txt "a=REPLACE a b" save=C:\folder\new.dat
Wit the parameter "save", a whole path can be specified for storage. In this example, the file "C:\test.txt" is first read out, then the letter "a" is replaced by "b" and then the result is saved in the file "C:\folder\new.dat". The original file is preserved.
The same result can also be achieved with using the parameters save-folder, save-name and save-ext:
TextConverter.exe -cl C:\test.txt "a=REPLACE a b" save-folder=C:\folder save-name=new save-ext=dat
The result of this call is identical to the example before. Again, the result of the conversion is saved in the file "C:\folder\new.dat". While "save" expects a whole path, we can use the 3 parameters save-folder, save-name and save-ext to set all components of the path individually. The use of the 3 individual parameters is particularly useful if we do not want to set each of these parameters. For example:
TextConverter.exe -cl C:\test.txt "a=REPLACE a b" save-folder=C:\new
In this example, we only set the parameter "save-folder". Since the TextConverter always uses the previous name as a default value, this call leads to the situation that the name and the file extension are taken over from the original file. The converted file is therefore saved under the name "C:\new\test.txt". This parameter can be particularly useful if we want to convert several files or all files from a folder and we want to save the results in a new folder.
TextConverter.exe -cl C:\test.txt "a=REPLACE a b" save-name=new
TextConverter.exe -cl C:\test.txt "a=REPLACE a b" save-ext=dat
TextConverter.exe -cl C:\test.txt "a=REPLACE a b" save-folder=C:\new save-ext=dat
Analogous to the last example are the results of these 3 calls. The first line only changes the name of the file, so it is saved as "C:\new.txt" maintaining the folder and the file extension. The second line leads to the file "C:\test.dat" and in the third line we change the folder and the file extension while the name of the file is taken over by the original file, so the result is "C:\new\test.dat ".
In addition to the use of these parameters, there is another way to influence the location and the file name of the converted file. This is to use settings files. However, the principle is the same, since the parameters mentioned here, are also included within the settings files. The only difference is that the parameters do not have to be specified individually, but only the path to the relevant settings file has to be passed as a parameter. You can find out how you can create and use settings files in the section on setting files.
Parameters for the Encoding and the Type of Line Break
Other parameters are available to control the encoding and the type of line break used for reading and writing the files. For reading, these are the parameters lb-read (line break read) and enc-read (encoding read), for writing we can use the parameters lb (line break), enc (encoding) and bom (byte order mark). If we give the TextConverter no instructions, the TextConverter tries to automatically detect the line break type and the encoding of the original file during reading, and when writing, the determined line break type and the encoding of the original file is adopted.
Let's have a look at three examples that illustrate this.
TextConverter.exe -cl C:\test.txt enc=utf16le bom=1
This call changes the encoding of the file "test.txt" to UTF-16 Little Endian (utf16le), regardless of the encoding the file had before. The additive "bom=1" ensures that a Byte Order Mark is written into the file. Since we have neither specified parameters for the line break type nor for a location for the new file, the line break type of the original file is taken over and the original file is overwritten. Since we have also not specified in which encoding the original file has to be read, an attempt is made to automatically determine the encoding for reading.
TextConverter.exe -cl C:\test.txt enc-read=win-1251 enc=utf8 bom=0 lb=crlf save=C:\new.txt
In this call, we state that the original file has the Windows Codepage 1251 (Cyrillic) and the TextConverter should interpret the bytes of the original file in the sense of this code page. This is important for this encoding, especially if you are using the TextConverter on a Windows system with a different language, since the ANSI code pages cannot be distinguished due to the bytes and are a matter of interpretation. After the file has been read, the TextConverter changes the encoding of the file to UTF-8 without Byte Order Mark and uses the line break type CRLF (Windows), regardless of which type of line break was used in the original file. The converted file is saved under "C:\new.txt", the original file is kept.
TextConverter.exe -cl C:\test.txt a="INSERT test 10" lb-read=fixedlength-20 lb=system
In the first two examples, we have only changed the encoding and the type of line break of the original file without changing the content of the file. In this call we also perform an action that changes the file content: We would like to insert the word "test" at character position 10 in the file. Furthermore, we only want to switch the type of line break from a fixed line length of 20 characters to the system line break. The encoding of the original file should be preserved. The system line break type corresponds to the standard line break of the system on which the TextConverter is currently executed (for example CR LF on Windows systems).
The parameters for actions, action lists or settings files can be written at every position within the row of parameters. In our example, first we have defined the action, then "lb-read" and then "lb". However, we could also use any other order to get the same result.
You can see what values you can use for the different encodings and line break types in the overview of all available parameters. You can find more examples in the tutorial for the TextEncoder. All parameters and parameter values for the TextEncoder explained there can also be used with the TextConverter. In particular, the sections about custom characters for line breaks, line breaks at multiple characters and the conversion of files with a fixed line length go beyond the examples explained here.
Like the parameters for the storage location and the file name, also the parameters for the encoding and the line break type can be alternatively handed over via setting files. The procedure is as follows: Encoding and line break type can be configured via the graphical user interface of the TextConverter, these settings are saved as a settings file and this settings file is then passed to the TextConverter instead of specifying the individual parameters. In order to make it work, the actions "Encoding" and/or "Line Break Type" must be active. So it is not sufficient to just change the values under "Read as" and "Save as" in the graphic user interface, the hooks must also be set for "Encoding" and/or "Line Break Type". If this is not the case, the default value "auto" is used for reading and the default value "keep" is used for writing. If a settings file is passed, which contains instructions for the encoding and/or the line break type, and you are additionally passing parameters such as "enc" or "lb", the parameters will overwrite the values from the settings file. You can find out more about the creation and the use of settings files in the section on setting files.
Parameters for the File Date
When converting files with the TextConverter, we can either overwrite the original files with the converted files or save the converted files as new files by specifying a different storage location or name than the original file.
If the result of the conversion is saved as a completely new file, this file automatically carries the timestamp on which the conversion took place after it has been saved. This affects both the creation date as well as the last modification date of the file. If we overwrite the original file instead, the original creation date will remain the same, but the file modification date will change to the time of conversion.
If you don't wish this automatic file date change, we can pass the parameter "date=keep":
TextConverter.exe -cl C:\test1.txt "a=REPLACE a b" save=C:\test1.txt date=keep
TextConverter.exe -cl C:\test2.txt "a=REPLACE c d" save=C:\new.txt date=keep
The parameter "date=keep" has the affect that the date of the original file is adopted for the converted file. This affects both the creation date as well as the modification date and the date of the last access and can be used both for overwriting and for saving converted files as new files, as the example shows.
This parameter corresponds to the option "Keep Date of Original file" from the storage options from the graphical user interface of the TextConverter. Accordingly, this option can also be used by passing settings files that contains the appropriate settings.
Parameters for activating Placeholders and References
By default, the replacement of placeholders and references is disabled in the TextConverter. If you want to use placeholders or references when controlling the TextConverter via a script, you must therefore activate the corresponding options, otherwise the placeholders concerned will not be replaced. You have several opportunities to do that.
If you use settings files, you can enable one or both of the options via the graphical user interface of the TextConverter before saving your settings file. You can find both options in the section "Actions > Options".
If you do not use settings files, for example because you are working with individual actions or action lists, or if you want to overwrite the configuration from settings files passed, you can use the parameters "ph" and "ref" to control the use of placeholders and references. With "ph=1" you can activate placeholders, with "ref=1" you can activate references. If you use a "0" instead of a "1", the corresponding options will be disabled.
An example of using the parameter "ref" is the following call of the TextConverter, which sets the content of field A1 (1:1) to the content of the field B2 (2:2) in the CSV file "C:\data.csv" with the help of a reference:
TextConverter.exe -cl C:\data.csv "a=REPLACE_CELLS 2:2 %%ref:cell=1:1%%" ref=1
We use the action "REPLACE_CELLS Field NewContent". So that the contained cell reference %ref:cell=1:1% is interpreted as such, we pass the parameter "ref=1". When calling this script call on Windows, we also have to double the "%" character so that it is recognized as such.
An example of using the parameter "ph" is the following call of the TextConverter, which replaces an arbitrary date in the file "C:\test.txt" with the current date:
TextConverter.exe -cl C:\test.txt "a=REPLACE [0-9]+-[0-9]+-[0-9]+ %%date%% -r" ph=1
For this, we use the REPLACE function (REPLACE Find Replace -Parameters), which is passed as a single action here. This action searches for any date in the format "number-number-number" with the help of the regular expression "[0-9]+-[0-9]+-[0-9]+" (-r) and replaces it with the date placeholder "%date%", which stands for the current date. Again, we double the character "%" so that it is recognized as such. As the last parameter, we pass "ph=1" and thus ensure that the placeholder is also interpreted as such.
Even if only one of the two options was activated in each of the two examples, you can of course also pass both parameters at the same time within one call and accordingly, use them independently of one another.
In the parameters for the storage location and the file name "save", "save-folder", "save-name" as well as "save-ext", placeholders are always replaced. Accordingly, the activation of the placeholder option is only necessary if you use placeholders within your actions. An activation is not required for using placeholders in file names.
Combined Application of Actions, Action Lists, Settings Files and Parameters
Individual actions, files with action lists, settings files and all other parameters such as the parameters for the storage location, the encoding or the line break type can also be passed combined to the TextConverter. In this context, the question arises, which interaction the different parameters can develop and in which order the TextConverter processes the individual settings and actions. This question is particularly important in case if individual configurations complement or even contradict.
Generally, the TextConverter processes the passed parameters in the following order:
- First, the TextConverter sets all settings and parameters to their default. The default settings mean an automatic detection of the encoding and the line break type as well as keeping encoding, line break type and storage location (overwriting the original file). In addition, in the default settings, all actions are deactivated. Further information on the default settings can also be found in the overview of all parameters in the column "Default".
- Subsequently it is continued with the evaluation of the parameters. In the first step, all settings files are loaded regardless of their position in the parameters. The TextConverter recognizes them from the file extension TCS (Text Converter Settings). If multiple settings files are specified in the parameters, the first specified settings file is loaded first. After that, all further settings files are loaded in order and overwrite the previously loaded settings.
- In the next step, all parameters regarding the storage location (save, save-folder, save-name, save-ext), the encoding (enc, enc-read, bom) and the line break type (lb, lb-read) are loaded in their order of appearance. Regardless of whether these parameters occur in the parameters before or after a possible settings file, the parameters always overwrite the configurations from the settings files.
- Now all settings are loaded and the TextConverter comes to the conversion of the files. First, the actions that are defined in the settings files are applied. After that, individual actions and action lists are applied combined. The order of the application always corresponds to the order of the parameters regardless of the parameters used.
Let's take a look at some examples of the combined application of actions, action lists, settings files and parameters that illustrate the priority and the order of the application:
TextConverter.exe -cl C:\test.txt a2="DELETE a" al=C:\actionlist.tcal a1="DELETE b"
In this example, the action a2 is applied first, after that the action list is executed and then the action a1 is applied. So, the TextConverter strictly follows the order of the parameters, regardless of whether individual actions or action lists are passed and regardless of which parameter number you give the actions and action lists.
TextConverter.exe -cl C:\test.txt a="DELETE a" C:\settings.tcs al=C:\actionlist.tcal
In this example a settings file is added to the actions and action lists. Settings files are always processed first, regardless of which position they are defined in the parameters. So, first the settings file is applied, then the single action and finally the action list.
TextConverter.exe -cl C:\test.txt save-folder=C:\new save-ext=dat C:\settings.tcs
In this example, again, the settings file is loaded first. The parameters save-folder and save-ext then overwrite possible storage options from the settings file. Regardless of which storage options are defined in the settings file, it is saved in the folder "C:\new" with the file extension "dat". Since we have not specified a parameter for the name of the file, this setting is not overwritten and the name that is configured in the settings file will be used for storage (if there are no settings for the name in the settings file, the name from the original file will be used). In this case, the order of the parameters does not matter, we will get the same result, regardless of in which order we arrange the given parameters.
Convert single and multiple Files
To process a single file with the TextConverter via the command line, you can simply pass the path to the file, as we have already seen in many other examples in this tutorial:
TextConverter.exe -cl C:\test.txt "a=REPLACE a b"
With this call we replace the letter "a" with "b" in the file "test.txt". In this case, the original file is overwritten, as we do not give any different instructions for storing.
If we do not want to overwrite the original file, we can specify a different path for storage via the parameter "save":
TextConverter.exe -cl C:\test.txt "a=REPLACE a b" save=C:\new.txt
With this call, the original file "C:\test.txt" remains and we save our result in the file "C:\new.txt".
If you want to process multiple files at the same time in the same way, it is not necessary to call the TextConverter for several times. You can also simply hand over several file paths in a row:
TextConverter.exe -cl C:\test1.txt C:\test2.txt C:\test3.txt "a=REPLACE a b"
With this call we replace the letter "a" with "b" in the files "test1.txt", "test2.txt" and "test3.txt". Also in this example, the 3 original files are overwritten. If you would like to keep the original files, you can simply specify a different location or a different name for the new files via the parameters save-folder, save-name and save-ext (specifying a single file path for storage via the parameter "save", makes no sense at this point, since we have more than one file). So for example:
TextConverter.exe -cl C:\test1.txt C:\test2.txt "a=REPLACE a b" save-folder=C:\new
With this call we edit the files "C:\test1.txt" and "C:\test2.txt" and save the result in the folder "C:\new". Since we only specify a new folder and do not make a statement about the file name, the file name of the original file is taken over. The result of our conversion is therefore saved in the files "C:\new\test1.txt" and "C:\new\test2.txt". Of course, we can also change the name or the file extension for the new file. For example:
TextConverter.exe -cl C:\test1.txt C:\test2.txt "a=REPLACE a b" save-name=%%name%%_%%date%% save-ext=dat
In this example, we only keep the folder of the original files. On the other hand, we change the name and the file extension via the parameters "save-name" and "save-ext". As a new name, we would like to attach the current date to the old name. For this, we use the placeholders %name% for the old name and %date% for the current date (we have to double the percent sign so that the operating system does not interpret the variables in its sense). As a new file extension, we would like to use the file extension "dat". You can find out more on this topic in the section about the parameters for storage.
If you want to convert multiple files, you do not necessarily have to specify the path for each individual file. Instead, you can also pass one or more folders in order to convert their content. In the next section, you will find out how this works and how you can use filters to not convert all files stored in the folders handed over.
Convert Files from Folders
If you want to process a lot of files, it can be laborious to hand over each file individually to the TextConverter. In this case you can also work with folders. In order to convert all files from a folder, we can simply pass the path to the relevant folder. The syntax is the same as we have already seen from passing files:
TextConverter.exe -cl C:\folder "a=REPLACE a b"
With this call, all files that are stored in the folder "C:\folder" are converted (the letter "a" is replaced in the files by the letter "b"). Since we have not specified a different storage location, the original files are overwritten in the folder. If we would like to keep the original files, we can use the parameters for storage to influence the location and the new file name. For example:
TextConverter.exe -cl C:\folder "a=REPLACE a b" save-folder=C:\new
With this call, all files from the folder "C:\folder" are converted and the result is saved in the folder "C:\new". The original files from "C:\folder" are preserved and after the conversion, you can find all converted files in the folder "C:\new". Since we have not given any different instructions regarding the file name (for example via the parameter "save-name"), the file names of the original files are adopted.
Multiple folders can also be processed at the same time:
TextConverter.exe -cl C:\folder1 C:\folder2 "a=REPLACE a b" save-folder=%%folder%%\new
With this example, we process all files from the folders "C:\folder1" and "C:\folder2". We do not want to mix the converted files, so we want to save them in 2 different folders. Therefore, we work with the parameter "save-folder" and the variable %folder% that stands for the old folder (we have to double the percent sign so that the operating system does not interpret the variables in its sense). This call thus means that the converted files from "C:\folder1" are saved in "C:\folder1\new" and the converted files from "C:\folder2" are saved in "C:\folder2\new". If we would omit the paramater "save-folder" in this example, all original files in both folders would be overwritten by the converted files.
Of course we can also hand over files and folders mixed together:
TextConverter.exe -cl C:\test.txt C:\folder "a=REPLACE a b"
On the one hand, this call converts the individual file "C:\test.txt" and on the other hand all files from the folder "C:\folder".
In our previous examples, we have always processed all files from the passed folders. However, we can also use filters to only edit the files stored in the passed folders that matches the passed filter:
TextConverter.exe -cl C:\folder "a=REPLACE a b" filter-ext=txt
TextConverter.exe -cl C:\folder "a=REPLACE a b" filter-ext=htm/html
These two examples show the filter "filter-ext" for the file extension. With the first line we only process the files with the file extension "txt" from the folder "C:\folder": Several file endings can be separated with a slash. With the second line we edit all files that either have the file extension "htm" or "html".
TextConverter.exe -cl C:\folder "a=REPLACE a b" filter-name=[a-f]
TextConverter.exe -cl C:\folder "a=REPLACE a b" filter-name=[a-f] filter-name-regex=1
TextConverter.exe -cl C:\folder "a=REPLACE a b" filter-name=a/b/c filter-ext=txt
These 3 examples show the filter "filter-name" for the file name. With the first line we process all files that contain the string "[a-f]" in their name. So, for example "[a-f].txt" or "ab[a-f]cd.txt". In the second line we use regular expressions. With the parameter "filter-name-regex=1", we tell the TextConverter that "filter-name" is to be interpreted as a regular expression (if we omit "filter-name-regex", it is not interpreted as a regular expression by default). So this time we are not looking for files that contain the string "[a-f]", but for files that contain one of the letters from a to f. So, for example "a.txt", "xb.txt" or "abc.txt" but not files such as "gh.txt" or "p.txt". The third example combines "filter-name" with "filter-ext" and demonstrates that we can define multiple independent searches with a slash. We only want to edit files that contain the letter "a", "b" or "c" in their file name and have a "txt" file extension. For example, "a.txt", "abc.txt" but not "d.txt", "a.dat" or "b.dat".
Other filters are "filter-name-matchcase" (case sensitiveness: should the uppercase and lowercase writing be taken into account in filtering?), "filter-name-matchall" (should the entire file name match the search term?), "filter-hiddenfiles" (should also invisible files be included?) or "filter-onlytextfiles" (should only text files be processed?). Further explanations of the filters can be found in the list of all available parameters.
In addition to the filters for the file name and the file extension, also the handling of subfolders can be controlled via parameters. For that, the parameters "search-subdirs" and "keep-subdirs" are available.
With the parameter "search-subdirs", we can determine which files from within a folder should be processed: only the files that are stored directly in the folder (without considering sub folders), or also the files that are stored below the folder in subfolders (considering sub folders). We have 3 options:
TextConverter.exe -cl C:\folder "a=REPLACE a b" search-subdirs=0
TextConverter.exe -cl C:\folder "a=REPLACE a b" search-subdirs=1
TextConverter.exe -cl C:\folder "a=REPLACE a b"
In each of these examples, files from the folder "C:\folder" should be processed. In the first line we state with "search-subdirs=0" that no files should be processed that are stored in a subfolder of "C:\folder". So only files that are located directly in "C:\folder" are processed, for example "C:\folder\test.txt" but not files such as "C:\folder\folder\test.txt" or "C:\folder\1\2\3\test.txt". The effect of the second line is different. With "search-subdirs=1" we explicitly state that all files from subfolders should also be processed. With this call, all 3 files "C:\folder\test.txt", "C:\folder\folder\test.txt" and "C:\folder\1\2\3\test.txt" would be converted. In the third line we leave out the "search-subdirs" parameter. In this case, the default value "1" is used for "search-subdirs". So, if we omit the parameter, again, all files directly from the folder as well as all files from subfolders will be processed. Therefore, lines 2 and 3 lead to the same result.
With the parameter "keep-subdirs", we can regulate whether the folder structure of the subfolders should be kept or not. "keep-subdirs" can have the values 0 or 1:
TextConverter.exe -cl C:\folder "a=REPLACE a b" save-folder=C:\new search-subdirs=1 keep-subdirs=0
TextConverter.exe -cl C:\folder "a=REPLACE a b" save-folder=C:\new search-subdirs=1 keep-subdirs=1
In these two examples we would like to convert the files from the folder "C:\folder" and save the result in the new folder "C:\new". In both lines we state with "search-subdirs=1" that we would like to process not only the files directly stored in the folder but also all files from sub directories. However, once we write "keep-subdirs=0" and once we use "keep-subdirs=1". In the first line with "keep-subdirs=0" we signal the TextConverter that the subfolders should not be preserved. So, all converted files are stored directly in the folder "C:\new", regardless of whether the files were located directly in "C:\folder" or in any subfolder. The situation is different in the second line with "keep-subdirs=1". Here we tell the TextConverter that the subfolder structure should be maintained. Accordingly, the original file "C:\folder\test1.txt" is saved in "C:\new\test1.txt" and the original file "C:\folder\folder\test2.txt" in "C:\new\folder\test2.txt". With "keep-subdirs=0" the files would be saved under "C:\new\test1.txt" and "C:\new\test2.txt". If we leave out the parameter "keep-subdirs", this corresponds to "keep-subdirs=0" and all files would be saved directly in the output folder without subfolders.
Show Information about Files
In addition to the conversion and editing of text files via script control, the TextConverter also offers the option to output file properties and other information about text files in the command line or a script. Among other things, it is possible to issue general file information such as the file size or textfile-specific information such as the encoding, the line break type or the number of words, lines or characters of text files.
In the tutorial about the output of file informations and textfile-specific properties via the command line or by script, you will find explanations, example calls and overview tables of the possible parameters regarding this topic.
Overview of all available Parameters
The following table lists all available parameters that you can use in the batch mode of the TextConverter. You can find the name of the parameter in the column "Parameter". In the column "Values", all values that the respective parameter can take are listed. If the TextConverter is called without specifying a specific parameter, its value from the column "Default" is used. Most of the parameters can also be found in the examples within this tutorial.
Parameter | Values | Default | Description |
[Files] | any file path(s) | - | Path to the file to be converted. You can specify multiple files in sequence to convert multiple files at the same time. More information and examples in the section about the conversion of files. |
[Folders] | any folder path(s) | - | Path to a folder which contents should be converted. To avoid converting all files from the folder, you can use the parameters search-subdirs, filter-ext, filter-name, filter-name-matchcase, filter-name-matchall, filter-name-regex, filter-hiddenfiles and filter-onlytextfiles to narrow your search. Multiple folders can be specified consecutively to simultaneously convert the contents of multiple folders. More information and examples in the section about the conversion of folder content. |
[TCS-Files] | settings files with the file extension *.tcs | - | Path to a settings file with the file extension TCS (Text Converter Settings) that can contain all settings of the TextConverter such as actions or storage options. Settings files can be combined and overwritten with all other parameters. Multiple settings files can be specified in a row, which are then loaded consecutively. More about the use and the creation of settings files can be found in the section about the application of settings files. |
a, a1, a2, a3,... | single action | - | With the parameters a, a1, a2, a3 and so on, a single action can be passed to the TextConverter, which the TextConverter will then apply. The syntax is a=action, so for example "a=REPLACE a b" or "a1=DELETE x". If you only want to pass one action as a parameter, you can use "a". If you want to pass multiple actions as parameters, you can use "a1" for the first action, "a2" for the second action, "a3" for the third action and so on. However, you are not tied to a correct numbering. So, you can also start with "a7" and skip "a1" to "a6". Application examples and more information about this parameter can be found in the section about the use of individual actions. |
al, al1, al2, al3,... | any file path to a action list stored in a text file | - | With the parameters al, al1, al2, al3 and so on, the path to an action list can be passed to the TextConverter, which the TextConverter then will apply. The syntax is al=path, so for example "al=C:\actionlist.tcal" or "al1=C:\actions.txt". The passed file can be any text file that contains an action per line. The typical file extension for action lists for the TextConverter is TCAL (Text Converter Action List). However, the passed files can also have any other file extension such as TXT. If you only want to pass one action list as a parameter, you can use "al". If you want to pass multiple action lists as parameters, you can use "al1" for the first action list, "al2" for the second action list, "al3" for the third action list and so on. You are not tied to a correct numbering. So, you can also start with "al7" and skip "al1" to "al6". Application examples, an example of an action list and more information about this parameter can be found in the section about the application of action lists. In this section you will also find out how you can create action lists directly with the TextConverter via the graphical user interface. |
ph | 1 or 0 | - | Enables (ph=1) or disables (ph=0) placeholders. More about the background and use of this parameter in this section. |
ref | 1 or 0 | - | Enables (ref=1) or disables (ref=0) references. More about the background and use of this parameter in this section. |
save | path of any file | - | With this parameter you can save the converted file explicitly under a freely selectable file name. For example, you can specify save=C:\Folder\File.txt to save the converted file as C:\Folder\File.txt. If you only want to save the converted file in a different folder while keeping the file name and the file extension, please use the save-folder parameter and omit the save parameter. In addition, the parameters save-name for the name and save-ext for the file extension can be used in the same way and combined with each other. If you do not specify any of the save, save-folder, save-name, or save-ext parameters, the original file will be overwritten. More information about this parameter and examples of its use can be found in the section about the parameters for storage. |
save-folder | keep or any text | keep | Folder in which the converted file is saved. If you do not specify this parameter or if you call this parameter with the value "keep", the file is saved in the folder in which the original file is located. This parameter can be combined with the parameters save-name and save-ext. Each of these parameters is optional, allowing you to independently define the folder, name and extension. If you want to save the converted file under an explicit file name with path, name and extension, please use the parameter save. If you do not specify any of the save, save-folder, save-name, or save-ext parameters, the original file will be overwritten. With the parameter keep-subdirs you can control how to deal with subfolders within the folder. More information about this parameter and examples of its use can be found in the section about the parameters for storage. |
save-name | keep or any text | keep | Name without folder and file extension, with which the converted file is saved. If you do not specify this parameter or if you use this parameter with the value "keep", the file is given the same name as the original file. This parameter can be combined with the parameters save-folder and save-ext. Each of these parameters is optional, allowing you to independently define the folder, name and extension. If you want to save the converted file under an explicit file name with path, name and extension, please use the parameter save. If you do not specify any of the save, save-folder, save-name, or save-ext parameters, the original file will be overwritten. More information about this parameter and examples of its use can be found in the section about the parameters for storage. |
save-ext | keep or any text | keep | File extension with which the converted file is saved. If you do not specify this parameter or if you use this parameter with the value "keep", the converted file receives the file extension that also had the original file. This parameter can be combined with the parameters save-folder and save-name. Each of these parameters is optional, allowing you to independently define the folder, name and extension. If you want to save the converted file under an explicit file name with path, name and extension, please use the parameter save. If you do not specify any of the save, save-folder, save-name, or save-ext parameters, the original file will be overwritten. More information about this parameter and examples of its use can be found in the section about the parameters for storage. |
enc | keep, ascii, latin1, latin2, win-ansi, win-1250, win-1251, win-1252, win-1253, cp437, utf7, utf8, utf16le, utf16be, utf32le or utf32be | keep | Encoding for the converted file. With "keep" the encoding of the original file is used for storing the converted file, otherwise the specified encoding is used for the storage. The encoding "win-ansi" depends on the localization of your Windows version. The Windows code page that matches your language version of Windows will be used. An overview of all available encodings can be found here. More information about this parameter and examples of its use can be found in the section about the parameters for the encoding. |
enc-read | auto, ascii, latin1, latin2, win-ansi, win-1250, win-1251, win-1252, win-1253, cp437, utf7, utf8, utf16le, utf16be, utf32le or utf32be | auto | Encoding with which the file is read. If this parameter is not specified, an attempt is made to automatically detect the coding. The encoding "win-ansi" depends on the localization of your Windows version. The Windows code page that matches your language version of Windows will be used. More information about this parameter and examples of its use can be found in the section about the parameters for the encoding. |
bom | 0, 1 or keep | keep | Should a byte order mark be written into the file? 0 for never, 1 for always, "keep" for as in the original file. More information about this parameter and examples of its use can be found in the section about the parameters for the encoding. |
lb | keep, system, crlf, lf, cr, nl, rnl, lf_ebcdic, eol, gs, rs, us, ff, nel, ls, ps, vt, tab, nochar, customstr-x, customcp-x | keep | Linebreak type for the converted file. The value "keep" keeps the line break type of the original file, otherwise the specified type. The value "system" corresponds to the standard line break type of the operating system on which the TextConverter is currently running. So for example crlf for Windows. The constant nochar stands for no character. You can use it to remove all line break characters from a file. With customstr- and customcp-, custom characters can be defined as line break characters via text or code points (the x stands for the user-defined text or codepoint). An explanation and examples for the usage and application of custom line breaks can be found here and here (the last link refers to the TextEncoder, but can also be used for the TextConverter). You can find more information about this parameter and examples of its use in the overview of the various line break types that can be used with the TextConverter, as well as in the section about the parameters for the line break. |
lb-read | auto, system, crlf, lf, cr, nl, rnl, lf_ebcdic, eol, gs, rs, us, ff, nel, ls, ps, vt, tab, fixedlength-x, customstr-x, customstrs-x, customcp-x, customcps-x | auto | Line break with which the file is read. If this parameter is not specified or "auto" is specified, an attempt is made to automatically detect the line break. The value "system" corresponds to the standard line break type of the operating system on which the TextConverter is currently running. So for example crlf for Windows. With fixedlength-, a text with fixed line length can be read in (for example fixedlength-70 for 70 characters per line). An explanation and examples can be found here and here. With customstr- and customcp-, custom characters for a line break can be defined via text or code poioints for reading (the x stands for the user-defined text or codepoint). An explanation and examples can be found here and here. If you have files with different mixed line break types, you can use customstrs- and customcps-. This allows you to define multiple comma-separated custom line breaks via text or code points, for example customcps-13,10. An explanation and examples of the application can be found here and here. You can find more information about this parameter and examples of its use in the overview of the various line break types that can be used with the TextConverter, as well as in the section about the parameters for the line break. Some of the pages for explanations and examples linked here lead to the tutorial about the script control of the TextEncoder. The examples and explanations shown there also apply to the TextConverter. |
date | auto or keep | auto | With date=keep, every date of the original file is used for the changed or the newly stored file. If you omit this parameter or if you use date=auto, the changement date of the file depends on the time of processing and the creation date remains at the first creation time of the file. |
filter-ext | any text | - | If you only want to edit files with a specific extension, you can enter this extension(s) here. For example, filter-ext=txt to edit only files with the extension TXT. Multiple endings can be separated with a slash. For example, filter-ext=php/htm/html to edit only files with the extensions PHP, HTM or HTML. If you omit this parameter or leave it empty, files with all endings will be considered. |
filter-name | any text | - | If you only want to edit files with a specific name, you can enter a name here. All files containing the characters in their name specified with "filter-name" are processed. With filter-name=ab, for example, files like abc.txt or xab.txt. Multiple search terms can be defined separated by a slash (for example filter-name=abc/def to find all files whose names contain either "abc" or "def"). If you omit this parameter or leave it empty, files with all names are taken into account. |
filter-name-matchcase | 0 or 1 | 0 | Should the text or regular expression specified with the parameter "filter-name" be interpreted according to its uppercase and lowercase writing? 0 for no, 1 for yes. If 1, the text/regex in the file name must be the same in the same case. If 0 it is searched case-insensitive. |
filter-name-matchall | 0 or 1 | 0 | Should the text or regular expression specified with the parameter "filter-name" match the entire file name? 0 for no, 1 for yes. If 1, the entire file name must fully correspond to the search term. If 0, it is sufficient if the search term only appears somewhere in the file name. |
filter-name-regex | 0 or 1 | 0 | If the search filter specified with "filter-name" is to be interpreted as a regular expression, use 1. If you just want to search for the specified text, 0. |
filter-hiddenfiles | 0 or 1 | 0 | Do you want to edit hidden files when converting a folder? 0 for no, 1 for yes. A value of 0 leaves all hidden files untouched, a value of 1 also handles the hidden files. |
filter-onlytextfiles | 0 or 1 | 1 | Do you want to edit only text files when editing a folder? 0 for no, 1 for yes. If yes, each file is checked before being converted to see if it is a binary file and the processing is not carried out if so. |
search-subdirs | 0 or 1 | 1 | Should files from subfolders be edited when editing a folder? 0 for no, 1 for yes. With the value 0, only the files that are stored directly in the folder are processed. With the value 1, both the files that are stored directly in the folder as well as all files that are stored in a subfolder below the folder are processed. Examples and further explanations for this parameter can be found in the section "Convert Files from Folders". |
keep-subdirs | 0 oder 1 | 0 | This parameter controls whether the folder structure from an original folder should be maintained in a new folder or not. Example of Usage: A folder is passed, its contents should be converted. Within this folder there are one or more subfolders with an arbitrary number of levels. In addition, the files should be stored in a new or other folder (defined via the parameter save-folder). With keep-subdirs=1, the files are stored in the new folder in the same folder structure, as they were stored within the original folder. With keep-subdirs=0, the folder structure from the original folder is ignored and all files are stored directly in the folder defined for storage. Examples and further explanations for this parameter can be found in the section "Convert Files from Folders". |
openfile | 0 or 1 | 0 | Should the converted file be opened after editing? openfile=1 will open the newly created file. |
delfile | 0 or 1 | 0 | Should the original file be deleted after the conversion? delfile=1 deletes the original file. This option is only useful if the converted files are to be saved under a different name or in a different location than the original file and the original files should not be kept. |
info | %enc%, %bom%, %encbom%, %lb%, %lines%, %chars%, %words%, placeholders for the file name and folder, placeholders for the file size, placeholders for the date and arbitrary text freely combinable | - | With the parameter "info", you can output information about the passed files and the files from passed folders in the console. As a value, you can use the placeholders %enc% (encoding of the file), %bom% (is there a byte order mark?), %encbom% (encoding and byte order mark), %lb% (line break type), %lines% (number of lines), %chars% (number of characters) and %words% (number of words) and any arbitrary text. In addition, the placeholders for the file name, the folder, the file size and the date can be used. So, for example "info=%enc%" to display only the encoding, "info=%encbom% %lb%" to display encoding, byte order mark and line break type or "info=The file %filename% has %lines% lines, %chars% characters and %words% words." to output this sentence for a file. A detailed explanation as well as further examples can be found in the tutorial about the output of file information via script. |
In principle, all listed parameters can be combined and used together within one call of the TextConverter. You can find out what role the order of the parameters plays and how the different parameters interact - especially in the case, if individual parameters contradict each other - in the section about the combined use of actions, action lists, settings files and parameters. If the TextConverter is called without defining a certain parameter, the value from the column "Default" is used for this parameter. If the value "-" is specified as default value of a parameter, this means that the parameter in question is empty by default.
Script Control of the old Program Version
The old program version of the TextConverter did not yet know any actions or action lists. There were also many of today's parameters such as the parameters for the encoding and the line break type used for reading and saving as well as the parameters for the storage options not available. Instead, almost all settings had to be passed via settings files with the file extension TKG at the time.
If you would like to find out about the old possibilities or if you still use the old version of the TextConverter, you will find the introduction to the batch functionality of the old TextConverter Pro CL here.