TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Package Text

Package Text provides access to the text of compilation units. Text is associated with elements and is defined in terms of:

For more information, click on a topic:


Resources in Package Text

The subprograms in package Text fall into several functional groups, as shown below.

To see detailed referenced information, click on the name of a subprogram:
Determining the line numbers on which text for an element appears:
First_Line_Number
Last_Line_Number 
Obtaining spans:
Compilation_Span Element_Span
Compilation_Unit_Span
Obtaining lines or information about lines:
Is_Equal Is_Nil Lines
Is_Identical Length
Obtaining the text image of an element or line:
Comment_Image Image_Delimiter Non_Comment_Image
Image Is_Text_Available


Key Concepts for Package Text

Package Text makes extensive use of data types defined in package Asis. These are described in the "Data Definitions" section.

Because of variations in Ada library implementation, all ASIS implementations are not able to provide the full functionality described by the subprograms in package Text. These restrictions are described in the "Implementation Restrictions" section.

The subprograms for manipulating text are grouped into four categories. To see more information, click on a topic:

Data Definitions

Text comes from the one or more compilation units that make up a compilation (Ada83 LRM 10.1 , Ada95 LRM 10.1.1). Access to text is defined in terms of the following data types:
Data Type
Definition
Line
A private type that identifies a specific line of text, or a portion of a line of text, from a specific compilation unit. The applicable portion of a line of text is identified by a span.
Line_List
An array type indexed by Line_Number whose elements are each a line. The index values correspond to the line number of the corresponding line from the compilation.
Line_Number
A integer type that represents the line numbers in a compilation.
Span
A record that contains the textual bounds of an element. The span identifies the first and last columns and line numbers of an element.

The text images ASIS returns can be derived from:

Rational Apex accesses the original source file to obtain the text images. If the source file is updated or removed, the text images are no longer available.

Elements represent Ada program constructs that are created based on source code provided by a programmer. The origin of an element can be explicit or implicit. Elements whose origins are explicit occupy column positions and lines and have a text image. Elements whose origins are implicit have no positions, no image, and return a 0 or an appropriate Nil value. You can determine whether an element's origin is implicit with the Declarations.Is_Part_Of_Implicit function plus the Declarations.Is-_Part_Of_Instance function.

Implementation Restrictions

Because of variations in Ada library implementation, not all ASIS implementations are able to return line numbers, column positions, and code commentary.

If the Environment.Is_Span_Column_Position_Supported function returns False, the ASIS implementation cannot provide the column positions of elements. In this case, the spans returned by the Compilation_Span, Compilation_Unit_Span, and Element_Span functions always cover complete lines.

If the Environment.Is_Line_Number_Supported function returns False, the ASIS implementation cannot provide the line numbers where elements exist. In this case, the Environment.Is_Span-
_Column_Position_Supported
function also returns False and functions returning a line number return 0.

If the Environment.Is_Commentary_Supported function returns False, the ASIS implementation cannot provide code commentary. In this case, the Comment_Image function always returns Asis.Nil_Asis_String, and the Image function never includes any commentary.

File Descriptors

Efficient recovery of text images requires the use of multiple file descriptors. A file descriptor is a handle to a disk file; the file can contain source code, DIANA, or other needed information.

If too many file descriptors are used by ASIS, an operating system error can result; in this case, Asis_Failed is raised and Environment.Status returns Capacity_Error. Alternately, if too few descriptors are used, your application will run more slowly as ASIS opens and closes files so as not to exceed the specified limit.

You can specify the maximum number of file descriptors ASIS should use, to recover text images, when you call Environment.Initialize.

Obtaining Line Numbers

You can use the First_Line_Number and Last_Line_Number functions to obtain the range of line numbers for the text corresponding to an element.

Alternatively, you can use the Element_Span function to obtain the element's span (see "Processing Spans"). The First_Line and Last_Line components of the span are identical to the values returned by the First_Line_Number and Last_Line-_Number functions.

Processing Spans

A span is a record type that represents the first and last column positions and line numbers for the text corresponding to an element.

You can use the Element_Span, Compilation_Unit_Span, and Compilation_Span functions to obtain the span of an element, the span of the compilation unit containing an element, or the span of a compilation from which the element was derived.

You can use the Lines function with a span to obtain the line list corresponding to the span. The individual lines can then be provided to the Image functions (see "Processing Images") to obtain the source code, commentary, or both.

The span also contains First_Column and Last_Column components. These represent the first character position of the element in the first source line and the last character position of the element in the last source line. These values can be used as indexes into the text images to obtain the image portion applicable to the element.

A compilation may include multiple compilation units. Because the highest level of abstraction defined for an element is a library unit or a secondary unit, it is possible for the Compilation_Span function to return more text than can be represented by a single element. The only way to verify that multiple library units or secondary units are part of the same compilation is to verify that they come from the same source file and that their spans do not overlap.

Processing Lines

The Line type identifies a specific line of text, or a portion of a line of text, from a specific compilation unit.

Line values are returned in line lists. Line lists are obtained from the Lines functions. Line lists also indicate, by their subscript values, which line numbers are represented.

The Lines function is overloaded, allowing you to obtain the line list for an element, a range of line numbers, or the range of line numbers and column positions referenced by a span.

Each instance of the Lines function requires, at a minimum, that an element be specified. The element is used to determine which library the returned line list references.

If text is not available for the specified element, Asis.Nil_Line_List is returned. Asis.Nil_Line_List has a length of 0 elements. You can also use the Is_Nil function to determine whether a line list is empty.

The effect of the other parameters on the content of the returned line list is described in the following table:
Additional
Parameter(s)


Line-List Content

None
The returned line list references the range of line numbers and column positions on which the specified element has text
First_Line,
Last_Line

The returned line list references the range of line numbers bounded by the specified First_Line and Last_Line
Span
The returned line list references the range of line numbers and column positions identified by the specified Span

You can use the Is_Equal function to determine whether two lines have the same span and are from the same compilation. You can use the Is_Identical function to determine whether two lines are Is_Equal and come from the same library.

Processing Images

ASIS uses the term image to describe program text. An image may represent a single line of program text, the commentary from that line, the code from that line, or the text from a range of lines. The image might not look identical to the original program text but will be semantically equivalent. The kinds of changes that might be performed by a compiler before generation of the information used by ASIS include:

Rational Apex does not perform any of these optimizations.

The Image function, with a Line parameter, can be used to obtain the text image represented by that line. The Comment_Image function can be used to obtain the commentary from a line. The Non_Comment_Image function can be used to obtain the code from a line.

The Image function, with an Element parameter, can be used to obtain the lines of program text, including enclosed commentary, corresponding to the element. The returned text image can include multiple lines of program text. Multiple lines of text are separated by the value of the Image_Delimiter function. An Image_Delimiter string will not appear at the end of the text image.

Portions of the text images returned by the above functions may have had characters replaced by white space. In particular, the text image returned by Comment_Image has all leading non-comment text replaced by white space. According to the ASIS standard, white space can be composed of space characters (Ascii." "), horizontal tab characters (Ascii.Ht), or any combination. Rational ASIS always uses a space character; other ASIS implementations will operate differently. A portable ASIS application should handle any combination of either character.

You can determine whether an image is available for an element by calling the Is_Text_Available function. If Is_Text_Available returns True, the Non_Comment_Image function will return something other than Asis.Nil_Asis_String.

Whether a text image is available for predefined compilation units (see "Determining Compilation-Unit Kind") is implementation-defined. Rational ASIS can obtain text images of all predefined compilation units.

Examples

To achieve column alignment, space characters (Ascii." ") and horizontal tab characters (Ascii.Ht) are commonly used. If tab characters are used, printing or displaying a text image might place visible characters in column positions that differ from their offset in the image. For simplicity, we have used only space
characters.

Assume that the following variables exist
Variable Name
Represents
Package_Element 
The element representing
A_Package_Body_Declaration for package Buffer_Manager

Assign_Element
The element representing
An_Assignment_Statement on line numbers 11 and 12

Assign_Span
The span corresponding to the Assign_Element
Package_Line_List
The line list corresponding to the
Package_Element

:

Given the above package body fragment and variable definitions, you would obtain the results given in the following tables.

Implementations vary; some include preceding and/or following white space and/or comments in the span elements. Also, ASIS does not define whether any terminating semicolon (;) is included in the span of an element. Rational Apex does not include any white space or comments but does include the
semicolon.

For line numbers:
Function Call
Result
First_Line_Number
(Package_Element)

First_Line_Number
(Assign_Element)

Last_Line_Number
(Assign_Element)

Last_Line_Number
(Package_Element)

For spans:
Function Call
Result
Compilation_Unit_Span
(Package_Element)

Compilation_Unit_Span
(Assign_Element)

Compilation_Span
(Package_Element)

Compilation_Span
(Assign_Element)

Element_Span
(Package_Element)

Element_Span
(Assign_Element)

For lines:
Function Call
Result
Lines (Package_Element)

Lines
(Assign_Element)

Lines1
(Assign_Element,
First_Line => 10,
Last_Line => 15)

Lines2
(Package_Element,
Span => Assign_Span)

1 The specified element is used to determine which library is referenced by the lines in the returned line list. The specified line numbers are used to determine the subscripts of the returned line list.

2 The specified element is used to determine which library is referenced by the lines in the returned line list. The specified span is used to determine the subscripts of the returned line list.

For lengths of lines:
Function Call
Result
Length
(Package_Line_List (4))

Length
(Package_Line_List (10))

Length
(Package_Line_List (11))

Length
(Package_Line_List (15))

For images:
Function Call
Result
Comment_Image
(Package_Line_List (10))

Comment_Image
(Package_Line_List (11))

Non_Comment_Image (Package_Line_List (10))

Non_Comment_Image (Package_Line_List (11))

Image
(Package_Line_List (4))

Image
(Assign_Element)

1 To simplify the example, it is assumed that the Image_Delimiter function returns an Asis_String containing a single Asis_Character. An ASIS application designed to be portable should not make this assumption.


Function Comment_Image

Expanded Name Asis.Text.Comment_Image

Returns any comment text contained in the value of the line.

Description

If the line does not contain a comment, Asis.Nil_Asis_String is returned.

The lower bound of the returned image is 1.

The returned image includes leading hyphens (--).

The comment text begins at the same offset, from the start of the line, in the returned image that it occupied in the source code. In Rational ASIS, all characters that precede the hyphens are changed to spaces in the returned image.

If the returned image contains tab characters, printing or displaying the image might place visible characters in column positions that differ from their offsets in the returned image.

Parameters

Specifies the line for which the comment text should be returned.

Returns the comment contained in the value of the specified line.

Errors

Asis_Inappropriate_Element is raised and Environment.Status is
set to Value_Error if a parameter references a Library variable that is no longer open.

Asis_Inappropriate_Line is raised and Environment.Status is set to Value_Error if a Line parameter references a Library variable that is no longer open.

Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

Examples

Cross-References

Related subprograms:

Related concept:


Function Compilation_Span

Expanded Name Asis.Text.Compilation_Span

Returns the span of the text composing the compilation (Ada83 LRM 10.1 , Ada95 LRM 10.1.1) to which the specified element belongs.

Description

If text is not available for the specified element, Asis.Nil_Span is returned.

The returned span includes all library units and secondary units in the compilation that contained the specified element. The span includes all leading and trailing blank and comment lines.

You can use the Compilation_Units.Enclosing_Compilation_Unit function to obtain a handle for the compilation unit containing the specified element. By providing the handle to the Compilation-_Units.Text_File_Name function, you can obtain the name of the file from which the element was derived.

Parameters

Specifies the element for which the compilation span should be returned.

Returns the span of the compilation that includes the specified element.

Errors

Asis_Inappropriate_Element is raised and Environment.Status is
set to Value_Error if a parameter references a Library variable that is no longer open.

Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

Examples

Cross-References

Related subprograms:

Related concepts:


Function Compilation_Unit_Span

Expanded Name Asis.Text.Compilation_Unit_Span

Returns the span of the text composing the compilation unit (Ada83 LRM 10.1 , Ada95 LRM 10.1.1) to which the specified element belongs.

Description

If text is not available for the specified element, Asis.Nil_Span is returned.

The compilation-unit span encompasses the single library unit or secondary unit that contained the specified element.

Rational Apex allows multiple library and secondary units per compilation. It is not yet defined whether commentary existing outside a unit is returned with the unit that precedes the commentary or the unit that follows the commentary.

You can use the Compilation_Units.Enclosing_Compilation_Unit function to obtain a handle for the compilation unit containing the specified element. By providing the handle to the Compilation-_Units.Text_File_Name function, you can obtain the name of the file from which the element was derived.

Parameters

Specifies the element for which the compilation-unit span should be returned.

Returns the span of the compilation unit that includes the specified element.

Errors

Asis_Inappropriate_Element is raised and Environment.Status is
set to Value_Error if a parameter references a Library variable that is no longer open.

Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

Examples

Cross-References

Related subprograms:

Related concepts:


Function Debug_Image

Expanded Name Asis.Text.Debug_Image

Returns an implementation-defined string representing the specified line value.

Description

Parameters

Specifies the line for which the debug information is desired.

Rational ASIS returns a single line of text. The content depends on whether the line is nil, invalid, or valid:

  • A valid line returns:

    Where the syntactic categories are defined as follows:
    Syntactic Category
    Definition
    column_position
    The first and last column numbers of the element associated with the line.
    element
    The Elements.Debug_Image of the element associated with the line.
    line_number
    The first and last line numbers containing the element associated with the line.

    Errors

    Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

    Examples

    Cross-References

    Related subprograms and types:

    Related subprogram:


    Function Element_Span

    Expanded Name Asis.Text.Element_Span

    Returns the text span of the specified element.

    Description

    If text is not available for the specified element, Asis.Nil_Span is returned.

    You can use the Compilation_Units.Enclosing_Compilation_Unit function to obtain a handle for the compilation unit containing the specified element. By providing the handle to the Compilation-_Units.Text_File_Name function, you can obtain the name of the file from which the element was derived.

    Parameters

    Specifies the element for which the span should be returned.

    Returns the span of the specified element.

    Errors

    Asis_Inappropriate_Element is raised and Environment.Status is
    set to Value_Error if a parameter references a Library variable that is no longer open.

    Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function First_Line_Number

    Expanded Name Asis.Text.First_Line_Number

    Returns the first line number containing text associated with the specified element.

    Description

    If a line number is not available for the specified element, a 0 is returned.

    The line number will not exceed Asis.Maximum_Line_Number.

    Parameters

    Specifies the element for which the line number should be returned

    Returns the first line number containing text associated with the specified element.

    Errors

    Asis_Inappropriate_Element is raised and Environment.Status is
    set to Value_Error if a parameter references a Library variable that is no longer open.

    Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function Image

    Expanded Name Asis.Text.Image

    Returns the text image for the specified element or line value.

    Description

    If an element is specified:

    Description (continued)

    If a line is specified:

    The lower bound of the returned image is 1.

    If the returned image contains tab characters, printing or displaying the image might place visible characters in column positions that differ from their offsets in the returned image.

    Parameters

    Specifies the element for which the image should be returned.

    Specifies the line for which the image should be returned.

    Returns the image of the specified element or line value.

    Errors

    Asis_Inappropriate_Element is raised and Environment.Status is
    set to Value_Error if a parameter references a Library variable that is no longer open.

    Asis_Failed is raised and Environment.Status is set to Capacity_Error if an element has a span that exceeds the size of Asis-_String.

    Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

    Examples

    Cross-References

    Related subprograms:

    Related concepts:


    Function Image_Delimiter

    Expanded Name Asis.Text.Image_Delimiter

    Returns the Asis_String used as a delimiter to separate individual lines in the image of an element.

    Description

    Rational uses Ascii.Lf as the image delimiter.

    A portable ASIS application should not depend on the existence of a particular value or a value of a particular length.

    Text returned by the Image functions are not terminated with an image delimiter.

    Parameters

    Returns the Asis_String used as a delimiter to separate individual lines in the image of an element.

    Errors

    None.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function Is_Equal

    Expanded Name Asis.Text.Is_Equal

    Returns a Boolean value indicating whether the specified lines have the same span and are from the same compilation.

    Description

    The two lines need not have been obtained from the same library variable.

    Parameters

    Specifies the first line.

    Specifies the second line.

    Returns True if the specified lines have the same span and are from the same compilation.

    Errors

    None.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function Is_Identical

    Expanded Name Asis.Text.Is_Identical

    Returns a Boolean value indicating whether the specified lines have the same span, are from the same compilation, and come from the same library variable.

    Description

    Use the Is_Equal function to determine whether two lines have the same span and are from the same compilation exclusive of the originating library variable.

    Parameters

    Specifies the first line.

    Specifies the second line.

    Returns True if the specified lines have the same span, are from the same compilation, and are from the same library.

    Errors

    None.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function Is_Nil

    Expanded Name Asis.Text.Is_Nil

    Returns a Boolean value indicating whether the specified line list is empty or the specified line is Asis.Nil_Line.

    Description

    A line is nil if its value is Asis.Nil_Line.

    A line list is nil if the value of its 'Length attribute is 0.

    Parameters

    Specifies the line list that should be checked to determine whether it is empty.

    Specifies the line that should be checked to determine whether it is Asis.Nil_Line.

    Returns True if the specified line list contains no elements or the specified line is Asis.Nil_Line.

    Errors

    None.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function Is_Text_Available

    Expanded Name Asis.Text.Is_Text_Available

    Returns a Boolean value indicating whether text is available for the specified element.

    Description

    If Asis.Nil_Element is specified, False is returned.

    If an element that returns True from either the Declarations.Is-_Part_Of_Implicit or the Declarations.Is_Part_Of_Instance function is specified, False is returned. Implicit and generic instance elements have no textual representation.

    Because Rational Apex maintains library information separate from the source file, the text of an element will still be available even after the source file has been removed or renamed.

    Parameters

    Specifies the element for which the availability of text should be determined.

    Returns True if the specified element represents actual text in the source code.

    Errors

    None.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function Last_Line_Number

    Expanded Name Asis.Text.Last_Line_Number

    Returns the last line number containing text associated with the specified element.

    Description

    If a line number is not available for the specified element, a 0 is returned.

    The line number will not exceed Asis.Maximum_Line_Number.

    Parameters

    Specifies the element for which the line number should be returned.

    Returns the last line number containing text associated with the specified element.

    Errors

    Asis_Inappropriate_Element is raised and Environment.Status is
    set to Value_Error if a parameter references a Library variable that is no longer open.

    Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function Length

    Expanded Name Asis.Text.Length

    Returns the image length of the specified line.

    Description

    The length includes the program text and any commentary contained by the line. The returned value is identical to the length of the Asis_String returned by the Image function for the same line.

    The result will not exceed Asis.Maximum_Line_Length.

    Parameters

    Specifies the line for which the length should be returned.

    Returns the length of the specified line.

    Errors

    Asis_Inappropriate_Line is raised and Environment.Status is set to Value_Error if a Line parameter references a Library variable that is no longer open.

    Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function Lines

    Expanded Name Asis.Text.Lines

    Returns a list of the lines containing the span of the specified element, the list spanning the specified first and last line numbers, or the list encompassing the span from the file containing the specified element.

    Description

    If text is not available for the specified element, Asis.Nil_Line_List is returned.

    The returned line list can be indexed to obtain an individual line. The index is a line number. The indexes of the returned list correspond to the range of line numbers associated with the specified parameters. Each line can be provided to the Image, Non_Comment_Image, and Comment_Image functions to obtain the image from that line.

    If only an element is specified, the returned line list corresponds to the span of that element.

    If line numbers are specified, the returned line list corresponds to the complete text of the line-number range specified. The span associated with each line in the line list references the entire line.

    If a span is specified, the index range of the returned line list corresponds to the First_Line and Last_Line components of the span. In addition, the First_Column of the span associated with the first line will be the First_Column of the specified span, and the Last_Column of the last line will be the Last_Column of the specified span.

    The second and third versions of this function allow lines outside the range of the specified element, but still within the compilation unit from which the element was derived, to be returned.

    Parameters

    Specifies an Element which indicates the compilation unit from which the lines should be returned. In the first Lines function, the returned list represents the Span of the Element. In the second and third Lines functions the returned list content is determined by the other parameters.

    Specifies the first line number to be returned.

    Specifies the last line number to be returned.

    Specifies the Span of text to be returned.

    Returns a list of the lines identified by the other parameters.

    Errors

    Asis_Inappropriate_Element is raised and Environment.Status is
    set to Value_Error if a parameter references a Library variable that is no longer open.

    Asis_Inappropriate_Line_Number is raised and Environment-.Status is set to Value_Error if the specified line numbers are outside the range of text that can be accessed through the specified element.

    Asis_Inappropriate_Line_Number is raised and Environment-.Status is set to Value_Error if the span is Asis.Nil_Span or contains a line number outside of the range of text that can be accessed through the specified element.

    Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Function Non_Comment_Image

    Expanded Name Asis.Text.Non_Comment_Image

    Returns the text of the specified line up to, but not including, any comment contained in the line.

    Description

    If the line is empty or contains a comment that begins in column 1, Asis.Nil_Asis_String is returned.

    The lower bound of the returned image is one 1.

    The value returned is the same as that returned by the Image function, except that any hyphens (--) that start a comment, and any characters that follow those hyphens, are not returned.

    The noncomment text begins at the same character position in the returned image that it occupied in the source code.

    If the returned image contains tab characters, printing or displaying the image might place visible characters in column positions that differ from their offsets in the returned image.

    Parameters

    Specifies the line for which the program text should be returned.

    Returns the text of the specified line up to, but not including, any comment that appears in the line.

    Errors

    Asis_Inappropriate_Line is raised and Environment.Status is set to Value_Error if a Line parameter references a Library variable that is no longer open.

    Asis_Failed is raised and Environment.Status is set to Capacity_Error if the operating system denies an ASIS request for an additional file descriptor.

    Examples

    Cross-References

    Related subprograms:

    Related concept:


    Package Operations

    Expanded Name Asis.Text.Operations

    Package Operations provides a simple way to obtain visibility to operators for types used in package Text. The package typically is referenced in a use clause by an application.

    Cross-References

    Related subprograms and types:

    Related topics:


  • Rational Software Corporation  http://www.rational.com
    support@rational.com
    techpubs@rational.com
    Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
    TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS