Roosl's Text Machine - User Guide
Roosl's Text Machine - User Guide
Introduction
Thank you for trying and purchasing Roosl's Text Machine! I'm certain you'll love this program, and support is just an e-mail away!
This utility program provides several text manipulation tools with an easy to use interface. It allows you to perform several operations on any text files.
Sort lines
Stream edit (Sed) - E.g: global string replacement
Pattern (string) Matching (Grep)
Extract delimited Fields (Cut)
Features:
Multiple Input files - Handles Huge I/O jobs
- Limited only by your system/available memory.
Preview an operation's input/output
View each operation input/result in split window.
- Allows you to cancel or proceed.
- Great for large jobs and multiple input files.
Toggle I/O views between normal and maximized display.
Set font and color individually for each display window:
- Input preview, Result preview, Result output
Automatic Pipeline
- Have the output of an operation become the input to the next,
providing a "pipeline" of search and edit operations.
Instructions...
This program is designed for manipulating plain text. You may use it for other types of files, but the results may not be what you expect. For example, word processing files contain special (hidden) characters for colors, fonts, formatting, etc. For best results with files created with Word and other formatting applications, you should save the file as text first (use the application's "File: Save as.." menu). For cutting and sorting fields from a spreadsheet or address book, save as a CSV (comma separated values) file.
Commands and Processes:
The detailed instructions describe the fields(edit boxes), options (checkboxes), and command buttons. The primary commands described below each have a description of their setup and options. These primary command buttons (Sort, Sed, Grep, Cut) are aligned on the right of the interface dialog along with the Help and Exit buttons.
Be certain to see the setup, trial period and agreement section below.
This image of the program interface is a context map to sections of the help text below. You may click an area (button, box, etc.) in the image to jump to help for that item. Your mouse pointer will indicate each help section as you move it over the image:
In the application itself, you may move among the fields, boxes and buttons with the TAB key and with Alt-keys as well as your mouse. The Alt-keys are underlined on the screen. For example, holding Alt and typing X is the same as clicking the Exit button.
The default button (if you just hit the "Enter" key) is the "Select Files" button, to prevent an accidental command from being issued.
A tutorial example of using the pipeline feature is provided below as well.
Free Trial Period and Licensing
You may try the program free for 30 days. Anytime during the trial period (and certainly when it expires), you may purchase a permanent license if you like the program and want to keep it.
During the trial period, when you start the program, a reminder box similar to this one will pop up which displays the number of days remaining in your trial period.
A license code can be entered into this box at any time during the trial period. If the 30 days have expired, this box will let you know, and the program will not run unless you enter a valid license code.
After you purchase a license (via PayPal) at my website, you will be sent a license code in an e-mail message. You simply paste this code into the box and press the "Accept" button. During the trial period, you may just press Cancel.
Once you have applied a valid license, all functionality is available (if any are disabled during the trial), and the reminder box will stop annoying you! You may download the newest version anytime without purchasing a new license, and you'll receive news regarding updates!
You may purchase your license anytime via the PayPal button displayed on the page where you downloaded the program. The "Register" button on the license prompt box will open your browser and direct you to the web page.
Initial Setup and Install Options
I suggest you check the download page (if you didn't just read it) for newest information regarding Vista UAC and other notes I may have added since this guide was updated.
The first time you run the program, the following screen appears:
You may keep the program where you have it, or have it installed elsewhere, such as the suggested location. Either way, you may also opt to have it automatically create a shortcut on your desktop. Once setup is complete, the program will restart from its installed location and be ready to go. The 30 day free trial period will then begin.
Everything the program needs is kept in the same folder. This includes the User Guide HTML file (and its images), supporting libraries (DLL), and setup and preferences data. Your data is initialized the first time, and updated with your other settings later. All other files bundled with the program are extracted into this folder whenever the program is run.
If you get an updated program later, you should copy it into the same folder (you may of course rename the existing one as a backup precaution). If the new copy contains other updates (to the User Guide for example), they will automatically be extracted again.
If you delete any of these files, the bundled files will re-appear the next time you run the program. If you delete your data file (.dat), you will lose all of your preferences and settings!
The first time you run the program, the following screen appears:
Review our agreement, and acknowledge by pressing "I Agree". If you do not accept the agreement, press Cancel and the program will exit. Once accepted, the agreement screen will no longer pop up, and you may proceed.
Usage Details
Here are the details of each command, options and setup, as well as certain handy features...
[Edit box]Files for Operation:
Enter the file(s) to be read (as input) for the command. You may enter more than one file name seperated by commas. For example: c:\temp\file1, file2, file3. Of course, the file(s) must exist, and may be located anywhere on your system.
[Button]Select Files:
Use this button to select the input files rather than typing their names into the box above (recommended).
Files for Operation are referred to as the "input".
Note: If you previously checked the box for "Auto Make Output next Input", it will become unchecked when you click the Select Files button.
[Primary Command Button] Sort
The Sort command will sort all the lines in the input and write the result to output.
Note: To sort more than one input file into one output file, select all the desired input files, and let each sort result go to the same output file. Then finally, sort that output file. This is the best setup for allowing preview, as well as removing duplicates, if desired.
[CheckBox]Sort: Remove duplicates:
Check this box to have the Sort command remove any duplicate lines.
[Primary Command Button] Sed (Stream editor)
The Sed command will replace every occurence of a string of characters (in the input) with another string (to the output). This is handy as a "global replace" function.
[Edit box]Sed > String to Edit:
In this box, type the string you want to change (example: apples).
[Edit box]Sed > Change String to:
In this box, type the new string you want the Sed command to replace the first string with (example: oranges). You may leave this field blank if what you want to do is delete the above string.
The output will contain all the input text, with string1 (apples) replaced by string2 (oranges).
[Primary Command Button] Grep (Search)
The Grep command finds patterns (strings) in the input and writes only the matching (or non-matching) lines to the output.
[Edit box]Grep > String to Find:
Enter the string you want to match (find) in the input text.
You may use special characters for pattern matching and restrictions as follows:
1. Use an asterisk (*) preceded by a backslash (\) to represent any number of characters. Example: "abc\*xyz" will match any string containing "abc" and "xyz" with any number of other characters in between.
2. Use a question mark (?) preceded by a backslash (\) to represent any one character. For example, "abc\?efg" will match any string containing "abc" and "efg" with any other single character in between.
3. Use a caret (^) preceded by a backslash (\) to match only lines that begin with the string. For example, "\^abc" will match only lines that begin with "abc", rather than lines with "abc" anywhere else in the line.
4. Use a dollar sign ($) preceded by a backslash (\) to match only lines that end with the string. For example, "xyz\$" will match only lines that end with "xyz", rather than lines with "xyz" anywhere else in the line.
The output will contain only the lines which contain the found strings, or lines which do NOT contain the strings, based on the CheckBox "Return Non-matching lines".
[CheckBox]Sed and Grep: Ignore case:
Check this box for the Sed and Grep commands to treat upper and lower case the same. Sed will replace either "APPLES" or "apples" with the new string. The new string will retain whatever upper/lower case as you entered. Note that when the wildcards (* or ?) are used with Grep, it will ignore case even if the box is not checked.
[CheckBox]Grep: Return Non-matching lines:
Check this box to have Grep output the lines which do NOT contain the matching string, rather than the lines which DO contain the string.
[Primary Command Button] Cut (Field extracton)
The Cut command will extract fields (columns) from the input text. Fields are delimited by any character you choose. You'll generally want to use Cut on text that is in a consistent format in the input, such as CSV (comma separated), as in an export file from an address book or spreadsheet.
[Edit box]Cut > Fields (1,2,3...):
Enter the field numbers you want to cut. Enter multiple fields separated by commas, for example: 1,3,5. These can be in any order.
Enter the field delimiter character. This can be any character in the input text. For example:
Where a file contains lines such as:
Apples|Oranges|Blueberry Pie|Coffee...
Set fields to "2,4" and delimiter to "|" to extract "Oranges Coffee". Set fields to "4,3" to extract "Coffee Blueberry Pie".
Check this box to preserve the delimiter character in the output. In the example above, the output would be "Oranges Coffee" (with a space). With the Preserve box checked, the output would be "Oranges|Coffee" with the vertical bar ("|") instead of a space. This would be useful for subsequent Cuts, and Sed may be used to replace the delimiter if needed.
The output will contain only the selected fields, from lines which contain the delimiter.
Output
[Edit box]Save Results in Output File:
Enter the name of the file you want the final output written to.
[Button]Select File:
Use this button to select an existing file rather than typing its name into the box above.
Notes about the output file:
Unless you want to the program to setup a pipeline (see "Auto Make Output next Input" below), note the following:
1. If the file already exists, it will be replaced unless you check the Append box (below).
2. Avoid having this file be the same one as an input file!
3. You may leave this blank, and a default will be used*.
*For Sort and Sed commands only: If you leave this blank, the input file will be backed up (copied to a file named "file.bak") and replaced with the sorted/edited output. This only applies when you select a single input file. This way you may quickly sort a file or perform a global string replacement in a file, rewriting it in one pass.
4. The last file name used will appear in this box as the default for the next command.
5. The file does not need to already exist, and may be located anywhere on your system.
6. Generally (and by default) the output (and temporary) is in C:\temp.
Output is also displayed in the window "Last Output Results" to the right of the command buttons. This will display the text "wrapped" to fit. This does not mean the output file has the text wrapped as it appears in the window. For memory purposes, if the output is very large, a button will appear below that box such as "Huge Output - Next Part". Use this button to view each buffer of the huge output. When the end is reached, the button will change to "Huge Output - Previous Part". A scroll bar appears when there is more to view than will fit in the window.
So, you may page and scroll forth and back all you want in the display. You may even edit the contents of the window if you want to use it for a copy (Ctrl-C) to your clipboard (Just a thought.. Changes made in the display (including font) are not saved to the output file). The preceding information also applies to both windows in the preview display.
[CheckBox]Append Existing File:
Check this box to have the output appended to an existing file, rather than have that file replaced (erased and rewritten).
[CheckBox]Auto Make Output next Input:
Checking this box will have the program setup a "pipeline" for you, where the output from one command automatically becomes the input file for the next.
You just need your input file name(s) for the first command. The program will set the output file automatically (you don't need to enter an output file, as it won't be used anyway). The output file will be entered for you as the input file for the next command. These will be sequentially named files in the C:\TEMP folder.
Tutorial example - Using the Pipeline feature:
Say we have an address book export file in CSV format, named addr.csv in C:\documents, which contains lines having values such as:
first name,last name,e-mail address,home phone,work phone,..
The list is in no particular order, and we know some people have more than one entry, because they have more than one e-mail address.
Let's make a list of people and their home phone numbers, sorted by last name...
Step 1. Enter (or use Select Files) "c:\documents\addr.csv" in the "Files for Operation" box.
Step 2. Check the "Auto Make Output next Input" box.
Step 3. Enter "2,1,4" in the "Cut > Fields" box, enter a comma (",") in the "Delimiter" box, and check the "Preserve" box.
Step 4. Click the "Cut" button.
Now we see the result in the "Last Output Results" window, the "Files for Operation" box has "C:\temp\Roosl Text0.txt", and the "Save Results in Output File" box is pre-loaded with the next output, "C:\temp\Roosl Text1.txt".
Step 5. Check the "Sort: Remove duplicates" box.
Step 6. Click the "Sort" button.
Now we see that result in the "Last Output Results" window, the "Files for Operation" box has "C:\temp\Roosl Text1.txt", and the "Save Results in Output File" box is pre-loaded with the next output, "C:\temp\Roosl Text2.txt".
A further option, let's now take the commas out of our phone list.
Step 7. Enter a comma (",") in the "Sed > String to Edit" box, and enter a space (" ") in the "Change String to" box.
Step 8. Click the "Sed" button.
We see that result in the "Last Output Results" window, and the file "C:\temp\Roosl Text2.txt" contains the result. Now we can rename, edit, print (or whatever) our phone list, currently in that last file, which is now set to be the next input file, if we decide to do yet another operation.
[Checkbox]Preview each Input/Result:
When a command (operation) runs, it reads each input file and puts the result from the command into a temporary file. This output is sent to the "Last Output Results" window and written to your output file. With the Preview box checked, you can view, in a split window display, the current input and command result before it is sent to the output.
In this window, you may click "Cancel Further Operation" or "Proceed". If you cancel, the operation is aborted. Proceed causes the operation to continue, and the current result is written to the output. If you are processing several input files, "Proceed" has a cumulative effect on the output, appending each result until all input is processed (or until you click cancel).
In the preview display, you may also toggle (maximize/restore) the window size, and set the font and font color for each window.
Click the Maximize button to render the display in full screen. Note that this is not the same as the standard "maximize" from the title bar. That will maximize the display, but the "Last Output Results" window won't change size. By using the button, the size of the window is adjusted to fit relative to the display according to your screen resolution.
This also applies in the Preview (split input/result) display.
When maximized, the button reads "Restore", which returns the display to its default size.
The Font button opens a standard font selection dialog. You may choose any available font, size, weight and color for the output results window. This is only for display/readability/preferences, and does not affect the output file content.
This also applies in the Preview (split input/result) display, where you may set different fonts and colors for each side.
Other Buttons:
[Button]Help: Displays this document in a browser window.
[Button]Exit: Closes the program, and saves all current settings (check boxes, etc.)
[Button]Logo: Displays the "About" box.
I hope you like this software, and come back often to the website. Please tell your friends!
Thanks, and Enjoy!
Support from the Author
If errors or problems occur, please let me know. A box should appear in the event of internal program errors which has a button to connect you with my website. I want to know of any problems you have, as well as suggestions! Several features have been added since the initial release based on feedback from folks like you! You may also e-mail me with the link (animated mailbox) at the end of this guide.
Copyright © 2008 Roosl's Graphic Design - All Rights Reserved
Software, Graphics and Website Design by Roosl's Graphic Design
