!../../wiki/easy-ide-book/common/images/prev_page.gif! !../../wiki/easy-ide-book/common/images/toc.gif! !../../wiki/easy-ide-book/common/images/next_page.gif!

<font color="navy">Structure of the Program that Reads Data from a File</font>

First, let’s consider how we can read the data that is written into a file. There are actually four steps involved in reading such data. These are as follows:

• Step 1: Specifying the location of the file

• Step 2: Opening the file

• Step 3: Reading the data

• Step 4: Closing the file

Let’s start by taking a look at the program’s source code.

1. Specifying the location of the file (Step 1)

let loc:Url = {url data.txt}

In the first step we need to specify the location of the file we will be reading. The location of the file is specified with a variable called a <font color="purple">Url</font>. In the <font color="purple">url</font> procedure, we set a character string value that specifies the path to the file.

2. Declaring TextInputStream

let input: #TextInputStream

To read a text file, we use <font color="purple">TextInputStream</font>. In this example, an initial value is not set for the variable declaration. In this case, we preceed <font color="purple">TextInputStream</font> with a # so that the default value (null) will be legal.

3. Declaring the character string array that is used to store the read data

let data-array:StringArray = {StringArray}

Here, data is read from the file line-by-line and then saved into a <font color="purple">StringArray</font>. <font color="purple">StringArray</font> is an abbreviation for {Array-of String}.

4. Creating the variables that are used for display

let list:DropdownList = {DropdownList width = 5cm}

We declare the list variable as a <font color="purple">DropdownList</font> that is used to display the read-in data.

5. Exception processing

{try
    ... (code here) ...
    
 catch e:IOException do
    {popup-message Error reading file}
    {output e.message}
    
 finally
    ... (code here) ...
} 

If the file cannot be opened or read, the Curl RTE detects that the operatio cannot be completed normally. This is known as an exception. If an exception occurs, this program performs exception processing to prevent an error with the applet.

In our example, when the file at the specified URL is opened, an exception may occur when data is read from the file.

To handle an exception, we use the <font color="purple">try</font> expression. That location at which an exception may occur is enclosed in the <font color="purple">try</font> expression. Also, we define a <font color="purple">catch</font> clause that handles exceptions that may occur.

For every <font color="purple">try</font> expression, we can define multiple <font color="purple">catch</font> clauses. Each <font color="purple">catch</font> clause is used to define a specific exception to be handled. In our example, we specify an <font color="purple">IOException</font> because we are dealing with input/output operations. It is also possible to catch all exceptions by specifying <font color="purple">Exception</font> for the type of the exception processed by each <font color="purple">catch</font> phrase.

At the end, we use the <font color="purple">finally</font> clause to describe processing that must be performed regardless of whether an exception has occurred.

-

<font color="#006968">Exception Processing</font>

{try
    body 
    [catch-clauses] 
    [finally-clause]
} 

    where    

• body is one or more Curl language expressions (this is the code that throws the exception).

• catch-clauses is zero or more optional catch clauses.

• finally-clause  is an optional finally clause.

</font>            

-

6. Opening a file (Step 2)

set input = {read-open loc}

<font color="purple">TextInputStream</font> is opened from the file URL; this is the second step. Using the <font color="purple">read-open</font> procedure, we specify the URL as the argument and the file is opened as a <font color="purple">TextInputStream</font>.

7. Opening a file (Step 3)

{until input.end-of-stream? do
    {if-non-null line = {input.read-line} then
        {data-array.append {line.to-String}}
    }
}

After the file is opened as a <font color="purple">TextInputStream</font>, the data is read using the <font color="purple">until</font> expression. In this case, the code block is processed repeatedly until the specified boolean expression becomes true.

There are three types looping expressions in Curl: until, while, and for. Let's look at the until and while expressions now (we'll cover the <font color="purple">for</font> expression later). These two expressions have a body that is repeatedly executed until a specified expression becomes either true or false.

-

<font color="#006968">until expression</font>

{until conditional_expression do
    
}

    <font color="purple">until</font> processing is repeated until the condition is true.</font>            

-

-

<font color="#006968">while expression</font>

{while conditional_expression do
    
}

    <font color="purple">while</font> processing is repeated until the condition is false.</font>            

-

Now, let’s take a look at our example.

{until input.end-of-stream? do
    
}

In the example, the input.end-of-stream? expression indicates the condition. When the <font color="purple">TextInputStream</font> reaches the end of the stream, the expression returns a value of true, so, the <font color="purple">until</font> expression is repeatedly processed until it reaches the end of the stream.

-

<font color="navy">Streams</font>

            Streams are sequences of data that your applets can either read from or write to. They create a generic interface for exchanging data with resources.            

-

The next expression in our example is <font color="purple">if-non-null</font>. This expression is very similar to the <font color="purple">if</font>, but the <font color="purple">if-non-null</font> expression branches based on whether the value is of the expression is <font color="purple">null</font> or not (rather than true or false). Therefore, when the value of the expression is non-null, the the specified code block is executed.

-

<font color="#006968">if-non-null</font>

{if-non-null [var-name[:type] = ] expr
 then if-body
    [elseif cond then elseif-body] 
    [else else-body]
}

• When the expression is not null, processing is performed

• The elseif and else phrases can be omitted.

</font>            

-

Let’s take a look at the example.

{if-non-null line = {input.read-line} then
    {data-array.append {line.to-String}
    }
}

The input.read-line method lets us read data from the <font color="purple">TextInputStream</font> line by line. In our example, whenever the value is non-null, one line of data has been read. The text of each line read will be appended to an array. In addition to read-line, there are several methods for reading data.

Finally, let’s take a look at the processing following the if-non-null expression. data-array is a <font color="purple">String</font> array, as described above. Using the append method, we can add an element to an array. The following table describes other methods that can be used to manipulate array contents.

Table 5-1: Methods used to manipulate an array

The input.read-line method returns the data that has been read from a file. This value is returned as a <font color="purple">StringBuf</font>. Since elements of this array are of <font color="purple">String</font> type,  we use the to-String method to convert from <font color="purple">StringBuf</font> to <font color="purple">String</font>.  The value is then added to the array.

In summary, the processing performed involves reading all the stream data line-by-line and provided that data is non-null, converting the data to a <font color="purple">String</font> and adding it to the array.

8. Closing the file (Step 4)

{if-non-null input then
    {input.close}
}

The file is closed after the data is read from the file. A close must always be performed, regardless of whether an exception has occurred, so it is performed in the finally clause. In our example, we use if-non-null to check whether the file was ever opened. If the file is open, the close method is used to close the file.

9. Adding elements to the drop-down list

{for s:String in data-array do
    {list.append s}
}

Since the data that is read from a file is stored in the array named data-array, we can access each element as input for our dropdown list. The data is taken, in order, and then added to a <font color="purple">DropdownList</font> control named list. The body of the <font color="purple">for</font> expression is executed repeatedly, each time adding another element to the <font color="purple">DropdownList</font>.

Curl supports two variations of the <font color="purple">for</font> expression. The first is used to specify a range and executes the body for each value in the range, while the second executes the body for each value in a collection of elements, such as an array.

-

<font color="navy">What is a Collection?</font>

            A “collection” is a group of elements, all of which are of the same data type. Arrays and hash tables are both typical examples of collections.            

-

-

<font color="#006968">for expression, executed repeatedly within a given range</font>

{for repeat variable:int = initial_value to final_value step step_size do
    body
}

</font>            

-

If we omit step step_size, the variable value is increased (or decreased), by 1 each.

Instead of to,  we can also specify below, downto,  or above.

• to …        Variable value is increased in increments of the step_size. Processing is repeated while the variable value is less than or equal to the final value.

• below …         Variable value is increased in increments of the step_size. Processing is repeated while the variable value is less than the final value.

• downto …        Variable value is decreased in increments of the step_size. Processing is repeated while the variable value is greater than or equal to the final value.

• above …         Variable value is decreased in increments of the step_size. Processing is repeated while the variable value is greater than the final value.

Let’s execute the following two pieces of source code and see how the results differ. When we use to, the results should be 0 2 4 6 8.  When we use below, it should return 0 2 4 6.

• When we use to

{value
    let message:HBox = {HBox}
    {for x:int = 0 to 8 step 2 do
        {message.add x}
    }
    message
}

• When we use below

{value
    let message:HBox = {HBox}
    {for x:int = 0 below 8 step 2 do
        {message.add x}
    }
    message
}

The <font color="purple">for</font> expression that takes its values from the elements of a collection, will be as follows:

-

<font color="#006968">for expression</font>

{for element _variable[:element_type] key key_variable[:key_type] in collection_name do
    processing
}

</font>            

-

In our example, we use the for expression which repeats only the values among the elements of an array. The data is extracted from the element values in the array, and then added as items to be shown in the dropdown list.

10. Adding an event handler

{list.add-event-handler
    {on ValueChanged at lb:DropdownList do
        {popup-message lb.value &  was selected}
    }
}

Curl supports a method for adding an event handler, as mentioned in Try 2. We can use this method to specify that, when a value is selected from the dropdown list, it is displayed in a pop-up window.

10. Specifying the layout

{VBox
    Select a US state,
    list
}

We specify the screen display layout at the end of value. Character strings and the dropdown list are arranged vertically.

!../../wiki/easy-ide-book/common/images/next_page.gif!