• Chapter 1: Getting Started with Stylus Studio
• Chapter 2: Editing and Querying XML
• Chapter 3: Converting Non-XML Files to XML
  • Overview
  • Choosing an Input File
  • The Convert to XML Editor
  • Parts of an Input File
  • Working with Regions
    • Converting the Region Type
    • Adjusting Fixed-Width Regions
    • Defining and Joining Regions
    • Controlling Region Output
  • Working with Fields
  • Controlling XML Output
  • Creating a Convert to XML Converter
  • Using Converters in Stylus Studio
  • Invoking an Adapter Programmatically
  • Properties Reference
• Chapter 4: Working with XSLT
• Chapter 5: Creating XSLT Using the XSLT Mapper
• Chapter 6: Debugging Stylesheets
• Chapter 7: Defining XML Schemas
• Chapter 8: Defining Document Type Definitions
• Chapter 9: Writing XPath Expressions
• Chapter 10: Working with XQuery in Stylus Studio
• Chapter 11: Composing Web Service Calls
• Chapter 12: Accessing Relational Data as XML
• Chapter 13: Extending Stylus Studio
• Chapter 14: Stylus Studio GUI Reference

Home > Online Product Documentation > Table of Contents > Working with Regions

Working with Regions

This section describes some of the features you can use to work with input file regions. It covers the following topics:

Converting the Region Type

The Region Type field in the Properties window displays information about the type of region Stylus Studio inferred when the file was first read. Its value is either Fixed-Width, Line-Oriented, or Unknown.

Stylus Studio's Convert to XML interprets regions with CR/LF control characters as line-oriented regions. There might be occasions, however, when you want to change the region type from line-oriented to fixed-width, or vice versa. This section describes the tools you can use to change a region from one type to another.

Consider the following file fixed-width file:

Make        Model    Year    Mileage
               
BMW         R1150RS  2004    14274  
               
Kawasaki    GPz1100  1996    60234  
               
Ducati      ST2      1997    24000  
               
MotoGuzzi   LeMans   2001    12393  
               
BMW         R1150R   2002    17439  
               
Ducati      Monster  2000    15682  
               
Aprilia     Futura   2001    17320 
               

            

It is a simple .txt file with fields ( Make, Model, and so on) that have been created using spaces. Each new row was created using the Enter key in the text editor, resulting in CR/LF control characters at the end of each line that cause Convert to XML to interpret the file as a single line-oriented region, like this:

Figure 164. Fields are Aligned by Default

For display purposes, we can remove the spaces Stylus Studio has inserted for readability (the cells with the light blue shading) by clicking the Align Fields ( ) button. This results in a display that resembles the source ( Figure 165), but Stylus Studio still considers the region to be line-oriented.

Figure 165. Turning Off Align Fields Can Aid Readability

When you convert a line-oriented region to a fixed-width region, Convert to XML removes spaces it added for readability and depicts only the spaces in the original input file used to create the fields and the field values themselves, as show in Figure 166.

Figure 166. Line-Oriented Regions Converted to Fixed-Width

By default, Stylus Studio displays fixed-width files using an 80-character row. This accounts for the input files appearance when it is first displayed as a fixed-width file - if you scan the document, you can see that all of the file's original information, including the CR/LF control characters has been retained, but that the formatting differs - the original input file had eight rows; now it has four rows of 80 characters.

How to Convert a Region Type

To convert a region type:

2. Click the Convert to Fixed-Width Region ( ) or Convert to Line-Oriented Region ( ) button. These actions are also accessible from the ConvertToXML menu and the shortcut menu in the Convert to XML Editor.

Adjusting Fixed-Width Regions

Stylus Studio uses a default row length of 80 characters for fixed-width files. You might need to adjust the row length of a region if your input file uses a different row length, or when converting a line-oriented region, like the one shown in Figure 167, to fixed-width.

Figure 167. Line-Oriented Region

There are three ways to specify the row length for a fixed-width region:

Example

After converting the line-oriented region shown in Figure 167 to fixed-width, it looks like this:

Figure 168. Line-Oriented Region Converted to Fixed-WIdth

Figure 167 shows the same fixed-width file after it has been resized by dragging the document grid.

Figure 169. Resized Fixed-Width Region

Defining and Joining Regions

An input file can contain any number of regions; fixed-width and line-oriented regions can exist in the same file. The Convert to XML Editor provides tools that allow you to define new regions and join existing ones.

This section covers the following topics:

Defining a Region

When you define a region in an input file, Stylus Studio splits the region at the current cursor location. The new region starts with the character on which the cursor resided when the region was defined, but it can be of either type - fixed-width or line-oriented - regardless of the type of the original region.

Consider the following input file:

# Bike Inventory Overview 2004-10-01 09:00:07EDT
               
Make,Model,Year,Mileage
               
BMW,R1150RS,2004,14274
               
Kawasaki,GPz1100,1996,60234
               
Ducati,ST2,1997,24000
               
Moto Guzzi,LeMans,2001,12393
               
BMW,R1150R,2002,17439
               
Ducati,Monster,2000,15682
               
Aprilia,Futura,2001,17320
               

            

By default, Stylus Studio reads this as a file with a single region. You might decide you want your XML to distinguish headers from actual records and treat the two accordingly (not generating headers as XML, for example).

When you define a new region, the Convert to XML Editor renumbers all the rows, using a region:row number format. In addition, each region is displayed with its own field name row, which is displayed in light green with the default field element name, field, as shown in Figure 170.

Figure 170. Regions Are Numbered and Colored Differently

Field and row values are independent across regions. For example, the <row> element might be <reg1>, <reg2>, and so on for each of the regions in an input file.

To define a region:

2. Click the Start New Line-Oriented Region Here ( ) or Start New Fixed-Width Region Here ( ) button. These actions are also accessible from the ConvertToXML menu and the shortcut menu in the Convert to XML Editor.

Stylus Studio defines the new region and renumbers existing regions accordingly.

Joining Regions

You can join regions that you define as well as regions that Stylus Studio interpreted when it first read the input file. You can join the current region to either adjacent region - the previous region, or the next region.

The region type after the join operation depends on whether you are joining with the previous region or the next region.The region you are joining assumes the type of the region to which it is being joined.

To join a region:

2. Click the Join with Previous Region ( ) or Join with Next Region ( ) button. These actions are also accessible from the ConvertToXML menu and the shortcut menu in the Convert to XML Editor.

Stylus Studio joins the region you specified in step 1with the adjacent region.

Controlling Region Output

By default, Stylus Studio generates output for all fixed-width and line-oriented regions. Unknown regions are never converted to XML. In addition to pattern matching, which controls whether or not individual rows in a region are output based on a pattern you define, you can omit entire regions from output by selecting Yes from the Omit from Output drop-down list in the Region Type section of the Properties window.