![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Package Text Package Text provides access to the text of compilation units. Text is associated with elements and is defined in terms of:
- Line numbers
- Spans
- Text lines
- Text images
For more information, click on a topic:
Resources in Package TextThe 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 TextPackage 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:
The text images ASIS returns can be derived from:
- The original source file, whether in text or some intermediate form
- A copy of the original source file made by the compilation system
- Nontextual or textual information obtained from a compiler's library
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:
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:
- Constant folding
- Call argument defaulting
- Unfolding multiname declarations
- Optimizations:
- Dead-code elimination
- Common subexpression elimination
- Loop unrolling
- Expression simplification
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
Line_Number | | Column Number 2 3 4 v 1234567890123456789012345678901234567890123456789 1 -- This package assists in the generation of 2 -- examples for package Text. 3 -- 4 package body Buffer_Manager is 5 6 procedure Adjust_Buffer (Root : in out Buffer_Ptr; 7 Old_Buffer : Buffer_Ptr) is 8 Last_Buffer : Buffer_Ptr := Root; 9 begin 10 11 Root := -- Update list root 12 Old_Buffer.Next; -- to compensate 13 end Adjust_Buffer; 14 15 end Buffer_Manager; 1234567890123456789012345678901234567890123456789 Column Number 2 3 4To 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
:
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.
Function Call Result
First_Line_Number
(Package_Element)
First_Line_Number
(Assign_Element)
Last_Line_Number
(Assign_Element)
Last_Line_Number
(Package_Element)
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)
Function Call Result
Lines (Package_Element)
Lines
(Assign_Element)
Lines1
(Assign_Element,
First_Line => 10,
Last_Line => 15)
Lines2
(Package_Element,
Span => Assign_Span)
Function Call Result
Length
(Package_Line_List (4))
Length
(Package_Line_List (10))
Length
(Package_Line_List (11))
Length
(Package_Line_List (15))
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 .. 71) => " Root :=" & (14 .. 25 => ' ') & "-- Update list root" & Image_Delimiter1 & (46 .. 55 => ' ') & "Old_Buffer.Next"
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
function Comment_Image (Line : in Asis.Line) return Asis.Asis_String;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
Line : in Asis.Line;Specifies the line for which the comment text should be returned.
return Asis.Asis_String;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
- function Image
- function Image_Delimiter
- function Lines
- function Non_Comment_Image
- function Environment.Is_Commentary_Supported
Function Compilation_Span
function Compilation_Span (Element : in Asis.Element) return Asis.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
Element : in Asis.Element;Specifies the element for which the compilation span should be returned.
return Asis.Span;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
- function Compilation_Unit_Span
- function Element_Span
- function Is_Text_Available
- function Compilation_Units.Enclosing_Compilation_Unit
- function Compilation_Units.Text_File_Name
- function Environment.Is_Line_Number_Supported
- function Environment.Is_Span_Column_Position_Supported
- "Processing Spans"
- Ada83 LRM 10.1 , Ada95 LRM 10.1.1
Function Compilation_Unit_Span
function Compilation_Unit_Span (Element : in Asis.Element) return Asis.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
Element : in Asis.Element;Specifies the element for which the compilation-unit span should be returned.
return Asis.Span;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
- function Compilation_Span
- function Element_Span
- function Is_Text_Available
- function Compilation_Units.Enclosing_Compilation_Unit
- function Compilation_Units.Text_File_Name
- function Environment.Is_Line_Number_Supported
- function Environment.Is_Span_Column_Position_Supported
- "Processing Spans"
- Ada83 LRM 10.1 , Ada95 LRM 10.1.1
Function Debug_Image
function Debug_Image (Line : in Asis.Line) return Asis.Asis_String;Expanded Name Asis.Text.Debug_Image
Returns an implementation-defined string representing the specified line value.
Description
Parameters
Line : in Asis.Line;Specifies the line for which the debug information is desired.
return Asis.Asis_String;Rational ASIS returns a single line of text. The content depends on whether the line is nil, invalid, or valid:
- A nil line tests as Is_Nil and returns:
<Nil_Line>
- An invalid line is one where the associated library is closed. An invalid line returns:
<Invalid Line; Library closed>
return Asis.Asis_String; (continued)A valid line returns:
<First_Line => line_number, Last_Line => line_number, First_Column => character_position, Last_Column => character_position, Element => element_data>
Where the syntactic categories are defined as follows:
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:
- subtype Asis.Line_Number
- subtype Asis.Column_Position
- function Elements.Debug_Image
Function Element_Span
function Element_Span (Element : in Asis.Element) return Asis.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
Element : in Asis.Element;Specifies the element for which the span should be returned.
return Asis.Span;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
- function Compilation_Span
- function Compilation_Unit_Span
- function Is_Text_Available
- function Compilation_Units.Enclosing_Compilation_Unit
- function Compilation_Units.Text_File_Name
- function Environment.Is_Line_Number_Supported
- function Environment.Is_Span_Column_Position_Supported
Function First_Line_Number
function First_Line_Number (Element : in Asis.Element) return Asis.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
Element : in Asis.Element;Specifies the element for which the line number should be returned
return Asis.Line_Number;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
Function Image
function Image (Element : in Asis.Element) return Asis.Asis_String;function Image (Line : in Asis.Line) return Asis.Asis_String;Expanded Name Asis.Text.Image
Returns the text image for the specified element or line value.
Description
- The returned image contains the text of the full span of the element and can contain multiple lines of code and commentary. If the returned image contains multiple lines, they are separated with the value returned by the Image_Delimiter function. The returned image is not terminated with an Image_Delimiter string.
- The returned image begins with a series of spaces whose length is equal to the First_Column component of the element's span.
- If text is not available for the specified element, Asis.Nil_Asis-_String is returned. If text is available, the bounds of the returned image are 1 .. Length (Line).
- The image might exceed the range of Asis_String. In this case, Asis_Failed is raised and Environment.Status is set to Capacity_Error. If this occurs, the Lines function can be used to obtain individual lines for the element.
Description (continued)
- The image contains the program text and commentary contained in the line.
- Each line has an associated span that identifies the column positions that should be returned. Characters before the First_Column of the span are returned as spaces. Characters after the Last_Column of the span are not returned.
- The bounds of the returned image are 1 .. Last_Column.
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
Element : in Asis.Element;Specifies the element for which the image should be returned.
Line : in Asis.Line;Specifies the line for which the image should be returned.
return Asis.Asis_String;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
- function Comment_Image
- function Image_Delimiter
- function Is_Text_Available
- function Lines
- function Non_Comment_Image
- function Environment.Is_Commentary_Supported
- "Processing Images"
- Ada83 LRM 2.7 , Ada95 LRM 2.7
Function Image_Delimiter
function Image_Delimiter return Asis.Asis_String;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
return Asis.Asis_String;Returns the Asis_String used as a delimiter to separate individual lines in the image of an element.
Errors
Examples
Cross-References
Function Is_Equal
function Is_Equal (Left : in Asis.Line; Right : in Asis.Line) return Boolean;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
Left : in Asis.Line;
Right : in Asis.Line;
return Boolean;Returns True if the specified lines have the same span and are from the same compilation.
Errors
Examples
Cross-References
Function Is_Identical
function Is_Identical (Left : in Asis.Line; Right : in Asis.Line) return Boolean;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
Left : in Asis.Line;
Right : in Asis.Line;
return Boolean;Returns True if the specified lines have the same span, are from the same compilation, and are from the same library.
Errors
Examples
Cross-References
Function Is_Nil
function Is_Nil (Right : in Asis.Line) return Boolean;
function Is_Nil (Right : in Asis.Line_List) return Boolean;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
Right : in Asis.Line_List;Specifies the line list that should be checked to determine whether it is empty.
Right : in Asis.Line;Specifies the line that should be checked to determine whether it is Asis.Nil_Line.
return Boolean;Returns True if the specified line list contains no elements or the specified line is Asis.Nil_Line.
Errors
Examples
Cross-References
Function Is_Text_Available
function Is_Text_Available (Element : in Asis.Element) return Boolean;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
Element : in Asis.Element;Specifies the element for which the availability of text should be determined.
return Boolean;Returns True if the specified element represents actual text in the source code.
Errors
Examples
Cross-References
Function Last_Line_Number
function Last_Line_Number (Element : in Asis.Element) return Asis.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
Element : in Asis.Element;Specifies the element for which the line number should be returned.
return Asis.Line_Number;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
Function Length
function Length (Line : in Asis.Line) return Asis.Character_Position;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
Line : in Asis.Line;Specifies the line for which the length should be returned.
return Asis.Character_Position;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
Function Lines
function Lines (Element : in Asis.Element) return Asis.Line_List;
function Lines (Element : in Asis.Element; First_Line : in Asis.Line_Number; Last_Line : in Asis.Line_Number) return Asis.Line_List;
function Lines (Element : in Asis.Element; Span : in Asis.Span) return Asis.Line_List;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
Element : in Asis.Element;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.
First_Line : in Asis.Line_Number;Specifies the first line number to be returned.
Last_Line : in Asis.Line_Number;Specifies the last line number to be returned.
Span : in Asis.Span;Specifies the Span of text to be returned.
return Asis.Line_List;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
- function Comment_Image
- function Image
- function Is_Equal
- function Is_Identical
- function Is_Nil
- function Length
- function Non_Comment_Image
Function Non_Comment_Image
function Non_Comment_Image (Line : in Asis.Line) return Asis.Asis_String;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
Line : in Asis.Line;Specifies the line for which the program text should be returned.
return Asis.Asis_String;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
- function Comment_Image
- function Image
- function Image_Delimiter
- function Is_Text_Available
- function Lines
Package Operations
package Operations is -- For Asis.Lines and Asis.Line_List function "&" (Left : Asis.Line_List; Right : Asis.Line_List) return Asis.Line_List; function "&" (Left : Asis.Line_List; Right : Asis.Line) return Asis.Line_List; function "&" (Left : Asis.Line; Right : Asis.Line) return Asis.Line_List; function "&" (Left : Asis.Line; Right : Asis.Line_List) return Asis.Line_List; function Is_Nil (Right : Asis.Line) ... function Is_Nil (Right : Asis.Line_List) ... function Is_Equal (Left, Right : Asis.Line) ... function Is_Identical (Left, Right : Asis.Line) ...end 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
Rational Software Corporation
http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |