UTFCast Pro User Manual

Wildcard filter

A wildcard is a symbol used to represent one or more unknown characters in a file name. UTFCast Pro supports two wildcard symbols: the asterisk (*) for any number of unknown characters, and the question mark (?) for only one unknown character.

You can combine wildcard symbols by using the semicolon (;) separator. If a file name does not match any of the specified wildcard strings, it will be ignored.

Examples

To only pick file names that start with the letter 'W' and end with the '.TXT' extension, use the wildcard string:

w*.txt

To only pick file names that have two characters and the '.PHP' extension, use the wildcard string:

??.php

To only pick file names that have two or three characters and end with any extension, use the wildcard string:

??.*; ???.*

Regular expression filter

UTFCast Pro supports the ECMA Script (ECMA-262) regular expression format. For more information on the ECMA Script standard, please visit the ECMA website or download the specification document from http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf.

Example

To pick file names that are numeric and have a '.TXT' extension, use the following regular expression: '\d+.txt'

\d+\.txt

Default Settings

Changes to the following settings will affect the behavior of both the Instant Conversion and the default settings of the Custom Conversion.

Advanced Settings

GB18030 Support

GB18030 is a separate standard used in the People's Republic of China for encoding Chinese characters superseding GB2312. In GB18030, characters can be 1, 2, or 4 bytes. GB18030 support is turned on by default.

Supported Codepages

UTFCast Pro supports detecting and reading the below input codepages:

• US-ASCII
• Big5
• EUC-JP (EUC 20932 subset)
• EUC-KR
• EUC-TW
• GB18030
• GB2312
• HZ-GB2312
• IBM855
• IBM866
• ISO-2022-CN
• ISO-2022-JP / JIS
• ISO-2022-KR
• ISO-8859-2
• ISO-8859-5
• ISO-8859-7
• ISO-8859-8
• KOI8-R
• Shift-JIS
• UCS-4-2143
• UCS-4-3412
• UTF-16 Big Endian
• UTF-16 Little Endian
• UTF-32 Big Endian
• UTF-32 Little Endian
• UTF-8
• Windows-1250 / ISO-8859-1 / Latin-2
• Windows-1251
• Windows-1252 / ANSI / Latin-1
• Windows-1253
• Windows-1255
• Windows-874 / TIS 620
• MAC-Cyrillic / x-mac-cyrillic

Codepage Identifiers

A codepage identifier is a number for UTFCast Pro to identify which codepage you are referring to. It is usually used with the /cp command line switch. For example:

UTFCastPro.exe /in:"C:\My Files" /out:"D:\My Output" /cp:1252

The below table shows the complete list of supported codepage identifiers.

Supported output Return-Types (Also known as CR/LF Style)

• No change
• Force CRLF (Windows Style)
• Force CR Only (Macintosh Style)
• Force LF Only (Unix/Linux Style)

Command Line Modes

UTFCast Pro supports two command line modes, one is the Windows Application Command Line Mode, and the other one is the Console Command Line Mode.

The Windows Application Command Line Mode of UTFCast Pro supports two modes: GUI mode and Quiet mode. In GUI mode, the current status of a session is displayed and the user can interact with the interface to pause or stop the session. In Quiet mode, no interface is displayed and the program can work with a System Service in the background.

The Console Command Line Mode provides a text-only interface that runs in a console window, such as a System Command Line Prompt Window, or a Powershell Window.

Most features provided in both modes are the same, but they run in different contexts and may provide different conveniences in different situations.

Console Command Line Mode

UTFCast Pro's Console Command Line Mode is a separate application that can be found in UTFCast Pro's installation folder as UTFCastCon.exe.

To use this command line mode, you need to open a Windows Command Line Prompt Window or a Powershell Window and run UTFCastCon.exe inside that window. UTFCast Pro's installer automatically adds its installation folder to your system's PATH environment variable, so you do not need to type the full path to UTFCast Pro's install folder when running console command line mode. However, if UTFCast Pro's installation folder is not included in the PATH environment variable for any reason, it is recommended that you manually add it for convenience.

Command Line Syntax

The command line syntax for UTFCast Pro is:

UTFCastPro.exe /switch:argument /switch /switch:"argument contains space characters"

The command line syntax for UTFCast Console is:

UTFCastCon.exe /switch:argument /switch /switch:"argument contains space characters"

Switches And Arguments

The table below lists all switches and their corresponding available arguments. Both switches and arguments are case insensitive. If an argument contains at least one space character, the argument must be enclosed in a pair of double quotes.

Using Command Line File

Windows has a limit of 260 characters for the length of file paths, which means that you may not be able to access a file, directory, or run a command line if its total length exceeds 260 characters. UTFCast Pro provides various command line switches and arguments to control the command line mode, some of which may require a path to a file or a directory. If you combine multiple switches in the command line mode, it is possible that your command line will exceed the 260-character limit. Additionally, Windows does not allow you to pass a very long path as an argument to UTFCast Pro in command line mode.

To address this issue, UTFCast Pro introduced a Command Line File feature in version 2.8. This file is a simple text file containing the command line switches and arguments. As you can store very long text in a text file, UTFCast Pro can read the command line from the text file up to a maximum length of 32768 characters.

Using the Command Line File is easy. Simply store all of your command line switches and arguments in the first line of the text file and pass the /cmdfile switch with an argument pointing to the command line file. UTFCast Pro will take care of the rest. For example:

UTFCastPro.exe /cmdfile:"C:\My UTFCast Command Line.txt"

And now in your C:\My UTFCast Command Line.txt can contain a full command line in the first line like the below example (note that the keyword UTFCastPro.exe or UTFCastCon.exe must not be in the command line file):

/in:"C:\A Very Very Very Long Long Long Path That Causes The Command Line to Exceed 260 characters\Input.txt" /out:"C:\Another Very Very Very Long Long Long Path That Causes The Command Line to Exceed 260 characters\Output.txt" /mode:file /bom:yes /enc:utf8 /export:"D:\My UTFCast Logs\Today.log"

Command Line Examples

Here are some examples of how to use UTFCast Pro in command line mode:

Example 1: To convert every text file in C:\MyFolder (including files in subfolders but excluding hidden files and hidden folders) and save the converted files to D:\MyOutput as UTF-16BE without BOM encoding, the command line is:

UTFCastPro.exe /in:"C:\MyFolder" /out:"D:\MyOutput" /r /enc:utf16be /bom:no

Example 2: To convert the file C:\MyFile.txt to C:\MyConvertedFile.txt as UTF-8 with BOM encoding (skipping auto-detection) and manually specifying the Windows-1252 decoder to read the source file, the command line is:

UTFCastPro.exe /in:"C:\MyFile.txt" /out:"D:\MyConvertedFile.txt" /enc:utf8 /bom:yes /mode:file /cp:1252

Logging Example: To convert every text file in C:\MyFiles (including files in subfolders but excluding hidden files and hidden folders) and save the converted files to D:\MyConvertedFiles as UTF-8 with BOM encoding (skipping auto-detection) and manually specifying the Windows-1252 decoder to read the source file, while also logging the conversion process to a log file located at D:\UTFCastPro.log, the command line is:

UTFCastPro.exe /in:"C:\MyFiles" /out:"D:\MyConvertedFiles" /enc:utf8 /bom:yes /mode:file /cp:1252 /logfile:"D:\UTFCastPro.log"

Merging multiple tasks

Merging multiple tasks is a useful technique that can simplify repetitive tasks and reduce the number of commands required to accomplish them. In the given example, the task is to convert multiple files and folders to a different encoding format and save them in a new location. Without merging, this would require running the command line multiple times, once for each task.

UTFCastPro.exe /in:"D:\My Files" /out:"D:\My Output" /enc:utf8 /rt:crlf /bom:YES

However, by using Bachuite and wrapping the command lines to Bachuite XML, the tasks can be merged into a single command, allowing them to be executed with just one command. The XML elements in the Bachuite code correspond to the different tasks that need to be performed, and the attributes within each element correspond to the specific parameters needed for that task.

<dir in="D:\My Files" out="D:\My Output" enc="utf8" rt="crlf" bom="yes"/>

If you want to convert multiple sibling folders and some single files with the command line, you'll need to run the command line multiple times, one time for each task:

                
UTFCastPro.exe /in:"D:\My Files A" /out:"D:\My Output A" /enc:UTF8 /bom:YES /rt:CRLF
UTFCastPro.exe /in:"D:\My Files B" /out:"D:\My Output B" /enc:UTF8 /bom:NO /rt:CRLF
UTFCastPro.exe /in:"D:\Single File A.txt" /out:"D:\Single File Output A.txt" /enc:UTF16LE /mode:FILE /rt:CRLF /bom:YES
UTFCastPro.exe /in:"D:\Single File B.txt" /out:"D:\Single File Output B.txt" /enc:UTF16LE /mode:FILE /rt:CRLF /bom:NO
UTFCastPro.exe /in:"D:\Single File C.txt" /out:"D:\Single File Output C.txt" /enc:UTF16LE /mode:FILE /rt:CRLF /bom:YES
                
            

By merging tasks in this way, the overall process becomes more efficient:

                
<dir in="D:\My Files A" out="D:\My Output A" enc="utf8" bom="yes" rt="crlf"/>
<dir in="D:\My Files B" out="D:\My Output B" enc="utf8" bom="no" rt="crlf"/>
<file in="D:\Single File A.txt" out="D:\Single File Output A.txt" enc="utf16le" rt="crlf" bom="yes" />
<file in="D:\Single File B.txt" out="D:\Single File Output B.txt" enc="utf16le" rt="crlf" bom="no" />
<file in="D:\Single File C.txt" out="D:\Single File Output C.txt" enc="utf16le" rt="crlf" bom="yes" />
                
            

In fact, simple wrapping is just one of the options. Bachuite can do multiple tasks with ease by using Sets.

Using Sets

Sets allow you to define a group of attributes that can be inherited by child elements within the set. This makes it easy to apply a set of common attributes to multiple tasks without having to repeat the same attributes for each task.

                
<set rt="crlf" bom="yes" enc="utf8">
 
  <!-- The below tasks inherit rt, bom and enc from the parent set -->
  <dir in="D:\My Files A" out="D:\My Output A" />
  <dir in="D:\My Files B" out="D:\My Output B" bom="no" />
 
    <!-- A child set inherits properties too -->
    <set enc="utf16le">
      <file in="D:\Single File A.txt" out="D:\Single File Output A.txt" />
      <file in="D:\Single File B.txt" out="D:\Single File Output B.txt" bom="no"/>
      <file in="D:\Single File C.txt" out="D:\Single File Output C.txt" />
    </set>
 
</set>
                
            

In the above example, the parent set defines the rt, bom, and enc attributes, which are then inherited by the child elements within the set. The first two dir elements inherit all three attributes from the parent set, while the third file element inherits rt and bom but overrides enc with its own value.

This approach can simplify your XML code and make it easier to manage and maintain, especially when dealing with large sets of similar tasks.

Using Links

When a link element is used, the Bachuite processor will load the referenced file and include its contents in the current Bachuite document. This allows you to reuse common elements across multiple Bachuite files and keep your code more organized. Here's an example:ple:

                
<link src="D:\MyBachuite1.xml" />
<link src="MyBachuite2.xml" enc="utf32be" bom="no" />
                
            

The src attribute specifies the path to the file to be linked, which can be either an absolute path or a relative path to the current Bachuite file. Any attributes specified on the link element will override those of the linked file.

Becareful using links as the linked file must exist and be valid for the whole task to run.

Using Profiles

A profile is a set of predefined attributes that can be reused in other elements. A profile element is similar to a set element but has a name and cannot have children. When a profile is defined, it covers the scope of any sibling elements and their children, and only elements in the covered scope can access it. If an element is assigned an existing profile, it does not inherit any attribute from its parent; instead, it inherits the profile's parent attribute and clones all attributes from the profile. Bachuite applies all attributes of the profile to the element first and then applies explicitly presented attributes.

A profile can be assigned to another, so you can have a profile that includes another profile as well as specific attribute overrides.

Profiles can also be overridden by explicitly presented attributes. For example, if you have a profile with bom="yes" but then explicitly set bom="no" on an element, that element will have bom="no".

It's important to note that profiles have a scope. Any element outside of the scope of a profile cannot access it. In the below example given, the element on line 22 will result in an error because it is outside of the scope of the "with_bom" profile. Overall, profiles can be a powerful tool for organizing and reusing attributes in Bachuite.

Note that Bachuite profile elements are similar to the setting profile feature in the GUI but are designed for and work in different environments. It is not possible to load saved GUI setting profiles or Bachuite profiles in each other.

Here's an example of using profiles:

                
<set enc="utf8" in="D:\Text Files">
    <!-- A profile also inherits attributes from its parent, just like other elements. -->
    <!-- The below profiles also have the enc attribute set to "utf8" and the in attribute set to "D:\Text Files" even these attributes are not explicitly presented. -->
    <profile name="with_bom" bom="yes" rt="crlf" />
    <profile name="without_bom" bom="no" rt="crlf" />
 
    <!-- All elements below here and their children can use the two profiles defined above -->
    <dir out="D:\Output with bom" profile="with_bom" />
    <dir out="D:\Output without bom" profile="without_bom" />
 
    <!-- A profile can also be assigned to a set, a link, or even another profile -->
    <!-- Explicitly setting an attribute value (enc="utf16" in this example) overrides it -->
    <profile name="different_enc" enc="utf16" out="D:\Profile Out" profile="without_bom" />
 
    <set out="D:\New Output">
        <!-- Because a profile is assigned, this element does not inherit any attribute from its parent, the out attribute value "D:\Profile Out" which is copied from the profile is used -->
        <dir profile="different_enc" />
    </set>
</set>
<set enc="utf16le">
    <!-- ERROR, the below element is out of the "with_bom" profile's scope -->
    <dir in="D:\Text Files" out="D:\Output with bom" profile="with_bom" />
</set>
                
            

Resolving absolute and relative paths

Any path in an element can be an absolute path like C:\MyFile.txt, or a relative path like: MyFile.txt or ..\MyFile.txt. If a path is a relative one, it will be resolved to the relative location of the current Bachuite file. For example:

In C:\First.xml:

                
<link src="D:\Second.xml" />
<link src="Third.xml" />
<file in="MyFile.txt" out="SubDir\MyFileOutput.txt" />
                
            

When linking to Third.xml in C:\First.xml, the path of Third.xml is resolved to C:\Third.xml.

The same thing applies to paths in other elements. In C:\First.xml, MyFile.txt and MyFileOutput.txt are resolved to C:\MyFile.txt and C:\SubDir\MyFileOutput.txt.

Running Bachuite

The Bachuite XML must be saved as an XML file. Its content is nothing more than a normal XML file with the Bachuite root element and the Bachuite XML schema. For example, save the below XML to D:\MyBachuite.xml:

                
<?xml version="1.0" encoding="UTF-8"?>
<bachuite version="1.0">
 
  <!-- Your Bachuite XML goes here -->
 
</bachuite>
                
            

Run the Bachuite file using the below command line:

UTFCastPro.exe /in:"D:\MyBachuite.xml" /mode:bachuite

Bachuite Attributes

All available attributes are listed in the below table. Elements and Attributes are case sensitive, however, Attribute Values are case insensitive.