======================================== == TextAnalysisTool.NET Documentation == ======================================== ----------------------------- -- Section: Brief Tutorial -- ----------------------------- If you're not already viewing this document with TextAnalysisTool.NET, please do so by running the application and choosing the Help | Documentation menu item. Having done so, you should be seeing this documentation file displayed in the top part of the application's window along with a few handy filters in the bottom part of the window. To quickly see what section headings this document has, click the "Section:" filter to enable it - and while you're at it go ahead and enable the next filter down, too: "Marked by marker 1". Notice how all lines that don't match the filters you just enabled have been dimmed. Click anywhere in the line display to give it focus and then hit the Space bar a few times to cycle forward through all the matching lines (use Shift+Space to cycle backward). To take things a step further, hit Ctrl+H or choose the View | Show Only Filtered Lines menu option. Because you're now seeing only the lines you're interested in, it's easy to avoid getting bogged down by spurious details. Use the arrow keys to highlight the section on command-line parameters (it's near the bottom) and hit Ctrl+H again to view the selected line in the context of its surroundings. Explore the power of this interface by enabling and disabling some of the other sample filters, then read the rest of this document to find out how to take advantage of more neat features! ----------------------- -- Section: Overview -- ----------------------- The Problem: For those times when you have to analyze a large amount of textual data, picking out the relevant line(s) of interest can be quite difficult. Standard text editors usually provide a generic "find" function, but the limitations of that simple approach quickly become apparent (e.g., when it is necessary to compare two or more widely separated lines). Some more sophisticated editors do better by allowing you to "bookmark" lines of interest; this can be a big help, but is often not enough. The Solution: TextAnalysisTool.NET - a program designed from the start to excel at viewing, searching, and navigating large files quickly and efficiently. TextAnalysisTool.NET provides a view of the file that you can easily manipulate (through the use of various filters) to display exactly the information you need - as you need it. Filters: Before displaying the lines of a file, TextAnalysisTool.NET passes the lines of that file through a set of user-defined filters, dimming or hiding all lines that do not satisfy any of the filters. Filters can select only the lines that contain a sub-string, those that have been marked with a particular marker type, or those that match a regular expression. Text and background colors can be associated with each filter so that lines matching a particular filter stand out and lines matching different filters can be easily distinguished. In addition to the normal "including" filters that isolate lines of text you DO want to see, there are also "excluding" filters that can be used to suppress lines you do NOT want to see. Excluding filters are configured just like including filters but are processed afterward and remove all matching lines from the set. Excluding filters allow you to easily refine your search even further. Markers: Markers are another way that TextAnalysisTool.NET makes it easy to navigate a file; you can mark any line with one or more of eight different marker types. Once lines have been marked, you can quickly navigate between similarly marked lines - or add a "marked by" filter to view only those lines. Find: TextAnalysisTool.NET also provides a flexible "find" function that allows you to search for text anywhere within a file. This text can be a literal string or a regular expression, so it's easy to find a specific line. If you decide to turn a find string into a filter, the history feature of both dialogs makes it easy. Summary: TextAnalysisTool.NET was written with speed and ease of use in mind throughout. It saves you time by allowing you to save and load filter sets; it lets you import text by opening a file, dragging-and-dropping a file or text from another application, or by pasting text from the clipboard; and it allows you to share the results of your filters by copying lines to the clipboard or by saving the current lines to a file. TextAnalysisTool.NET supports files encoded with ANSI, UTF-8, Unicode, and big-endian Unicode and is designed to handle large files efficiently. --------------------------------- -- Section: The User Interface -- --------------------------------- Display ------- Line Display: The line display shows all of the lines with which you are currently working. Each line is shown with its original line number, an indication of which markers have been applied to it, and colored according to whether or not it matches any of the current filters (if a line matches more than one filter it will be colored by the topmost colored filter in the filter display). Any selected lines are highlighted; actions like toggling markers or copying to the clipboard affect all selected lines. Non-contiguous selections can be made in the usual manner with the Shift and Ctrl keys. Filter Display: The filter display shows the filters with which you are currently working. Filters can be enabled or disabled by clicking on the checkboxes next to them, they can be edited by double-clicking or pressing Enter, and they can be re-arranged through drag and drop. Further functionality is available from the Filters menu or from the context menu obtained by right- clicking on any filter. Lines matching any of the first twenty-six filters can be easily cycled through with the keyboard. Status Bar: The status bar at the bottom of the window contains information about the currently loaded file and some indicators about the current state of TextAnalysisTool.NET. Menus ----- File Open... Opens and displays a file Reload Reloads the current file from disk Save Current Lines... Saves the current lines to a new file Load Filters... Loads a filter file (*.tat) and replaces the current filters Save Filters Saves the current filters to a filter file (*.tat) Save Filters As... Saves the current filters to a new filter file (*.tat) Append to Existing Filters... Loads a filter file (*.tat) and appends the filters to the current filters Recent Files A list of the most recently loaded files Clear Recent Files List Clears the list of most recently loaded files Recent Filter Files A list of the most recently loaded filter files Clear Recent Filter Files List Clears the list of most recently loaded filter files Exit Exits the application Edit Copy Copies the currently selected line(s) to the clipboard Paste Displays all text currently on the clipboard Copy Filters Copies the selected filter or filters to the clipboard Paste Filters Adds any filters in the clipboard to the end of the filter list Select All Selects all lines Find... Finds the next match of a string or regular expression Find Previous Repeats the last find operation (searching up) Find Next Repeats the last find operation (searching down) Go To... Scrolls to the specified line number Preferences... Sets configuration options View Show Only Filtered Lines Toggles showing/hiding of lines that do not satisfy the currently active filters (note: the current line is preserved whenever possible; otherwise it is kept as near to its previous location as possible) Show Line Numbers Toggles showing/hiding of line numbers Show Filter Tool Tip Toggles showing/hiding a tool tip with the matching filters for each line Show Markers Always Always show the markers left of the text Never Never show the markers left of the text Only When In Use Show the markers only when markers are defined Zoom In Increases the font size Zoom Out Decreases the font size Reset Zoom Resets the font size to the default size Filter List Location Set the docking location for the filter list Encoding System Default Use the OS's default character encoding Windows-1252, UTF-8, GB18030 Commonly used encodings More encodings... Dialog to select an encoding supported by the current system Filters Previous Match Find a match for the current filter, searching up Next Match Find a match for the current filter, searching down Add New Filter... Adds a new filter of any type Edit Selected Filter... Edits the selected filter Remove Selected Filter Removes the selected filter Enable All Filters Enables all filters Disable All Filters Disables all filters Remove All Filters Removes all filters Help Documentation Loads the documentation file Installed plug-ins Displays information about installed plug-ins About Displays version information Line Display Keys ----------------- Space Scrolls to the next line that matches any filter Shift+Space Scrolls to the previous line that matches any filter 1-8 Scrolls to the next line marked by the associated marker Shift+1-8 Scrolls to the previous line marked by the associated marker Ctrl+1-8 Toggles the associated marker type for the selected line(s) A-Z Scrolls to the next line matched by the associated filter Shift+A-Z Scrolls to the previous line matched by the associated filter Ctrl+Shift+A-Z Toggles the associated filter Filter Display Keys ------------------- Space Toggles the selected filter on and off Enter Edits the selected filter (also accessible through double-click) Delete Removes the selected filter Ctrl+(Left, Right, Up, or Down) Set the docking location of the filter list Status Bar Indicators --------------------- Funnel Icon Indicates that the "Show Only Filtered Lines" menu option is currently selected Sel Indicates the number of lines selected in the line display Fil Indicates the number of filtered lines Total Indicates the total number of lines Zoom Percent Indicates the currently used zoom value for the font size ----------------------- -- Section: Plug-ins -- ----------------------- TextAnalysisTool.NET's support for plug-ins allows users to add in their own code that understands specialized file types. Every time a file is opened, each plug-in is given a chance to take responsibility for parsing that file. When a plug-in takes responsibility for parsing a file, it becomes that plug- in's job to produce a textual representation of the file for display in the usual line display. If no plug-in supports a particular file, then it gets opened using TextAnalysisTool.NET's default parser (which displays the file's contents directly). One example of what a plug-in could do is read a binary file format and produce meaningful textual output from it (e.g., if the file is compressed or encrypted). Another plug-in might add support for the .zip format and display a list of the files within the archive. A particularly ambitious plug-in might translate text files from one language to another. The possibilities are endless! Plug-ins are "installed" simply by copying the relevant implementation file ("TATPlugin_*.dll") to the same folder as the TextAnalysisTool.NET program file (TextAnalysisTool.NET.exe). Every time TextAnalysisTool.NET starts up, it searches its startup folder for plug-in files and attempts to load each of them. From then on, installed plug-ins are seamlessly integrated with the rest of the application. To see a list of active plug-ins, use the Help | Installed plug-ins menu item. ------------------------------------------------ -- Section: Differences from TextAnalysisTool -- ------------------------------------------------ TextAnalysisTool.NET represents a complete rewrite of TextAnalysisTool to produce a fully managed-code application built on top of the .NET Framework. Efforts were made during development of the user interface to maintain the default/recommended behavior in all cases - except where it was possible to make significant usability or performance gains by doing things differently. Consequently, though TextAnalysisTool.NET's features are a strict superset of TextAnalysisTool's; some of those features may be exposed in a slightly different manner. Apologies for the inconvenience to loyal users! ---------------------------------------- -- Section: Regular Expression Syntax -- ---------------------------------------- TextAnalysisTool.NET uses the standard .NET Framework regular expression class Regex, and therefore supports the same regular expression syntax used by the .NET Framework. For more details, please refer to the ".NET Framework Regular Expressions" page: . (Note that you can right-click the "Regular expression" checkbox from the relevant TextAnalysisTool.NET dialog boxes to automatically open this web page in your default browser.) -------------------------------------- -- Section: Command-Line Parameters -- -------------------------------------- TextAnalysisTool.NET.exe [InputFile] [/Filters:FilterFile] [/Config:ConfigFile] [/Line:LineNumber] [/Clipboard] InputFile - Name of the file to open and display FilterFile - Name of a .tat file containing a saved filter configuration ConfigFile - Name of an .xml file containing configuration options LineNumber - The line to display when the file is opened Clipboard - Load text from the clipboard Examples: TextAnalysisTool.NET.exe \Logs\MyLog.log /Filters:"\Saved Filters\MyFilters.tat" TextAnalysisTool.NET.exe \Logs\MyLog.log /Config:"\configs\MyConfig.xml" Note that several /Filters flags can be supplied on the command line. TextAnalysisTool.NET will append the filters from all supplied filter files. Configuration options loaded from the command line become active when TextAnalysisTool.NET starts and are saved to the registry when it is closed. If both InputFile and Clipboard are specified, the first one is used. --------------------------------- -- Section: Configuration File -- --------------------------------- You can customize certain aspects of the user interface through a configuration file that can be imported from the Preferences dialog ("Preferences..." in the Edit menu) with the "Import..." button. An initial version of the file can be generated by using the "Export..." button from the same "Preferences..." dialog. This will generate the configuration XML file with all the available options. Once generated, you can remove some of the configuration options from the file if you don't want to override the current application value for that option. ------------------------ -- Section: Encodings -- ------------------------ All text files are written with a certain character encoding [1]. This encoding determines how characters are translated to bytes when written to the file and how a reader should interpret those bytes. If a file is read with the wrong encoding the characters can look garbled or random. Using the correct encoding is critical for properly analysis. TextAnalysisTool.NET determines which encoding to use in the following order, from highest priority to lowest: 1) Byte order marks in a UTF file [2] 2) The current view's encoding chosen in the View / Encodings... menu 3) The "Default Encoding" setting in the Edit / Preferences... menu 4) The default character encoding of the current system Note that 2 will immediately impact the current view and not future files. 3 will only impact files opened after it is changed, not the current view. All text copied to the clipboard is UTF-8. [1] https://en.wikipedia.org/wiki/Character_encoding [2] https://en.wikipedia.org/wiki/Byte_order_mark -------------------------- -- Section: Bug Reports -- -------------------------- Please create an issue at https://github.com/TextAnalysisTool/Releases/issues with a detailed description of any problem you encounter. Whenever possible, please include a file demonstrating the problem. Thanks and enjoy!!!