1------------------------------------------------------------------------------ 2-- -- 3-- ASIS-for-GNAT INTERFACE COMPONENTS -- 4-- -- 5-- A S I S . T E X T -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 1995-2012, Free Software Foundation, Inc. -- 10-- -- 11-- This specification is derived from the Ada Semantic Interface -- 12-- Specification Standard (ISO/IEC 15291) for use with GNAT. The copyright -- 13-- notice above, and the license provisions that follow apply solely to the -- 14-- contents of the part following the private keyword. -- 15-- -- 16-- ASIS-for-GNAT is free software; you can redistribute it and/or modify it -- 17-- under terms of the GNU General Public License as published by the Free -- 18-- Software Foundation; either version 2, or (at your option) any later -- 19-- version. ASIS-for-GNAT is distributed in the hope that it will be use- -- 20-- ful, but WITHOUT ANY WARRANTY; without even the implied warranty of MER- -- 21-- CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General -- 22-- Public License for more details. You should have received a copy of the -- 23-- GNU General Public License distributed with ASIS-for-GNAT; see file -- 24-- COPYING. If not, write to the Free Software Foundation, 51 Franklin -- 25-- Street, Fifth Floor, Boston, MA 02110-1301, USA. -- 26-- -- 27-- -- 28-- -- 29-- -- 30-- -- 31-- -- 32-- -- 33-- -- 34-- ASIS-for-GNAT was originally developed by the ASIS-for-GNAT team at the -- 35-- Software Engineering Laboratory of the Swiss Federal Institute of -- 36-- Technology (LGL-EPFL) in Lausanne, Switzerland, in cooperation with the -- 37-- Scientific Research Computer Center of Moscow State University (SRCC -- 38-- MSU), Russia, with funding partially provided by grants from the Swiss -- 39-- National Science Foundation and the Swiss Academy of Engineering -- 40-- Sciences. ASIS-for-GNAT is now maintained by AdaCore -- 41-- (http://www.adacore.com). -- 42-- -- 43------------------------------------------------------------------------------ 44 45pragma Ada_2012; 46 47------------------------------------------------------------------------------ 48-- 20 package Asis.Text 49------------------------------------------------------------------------------ 50------------------------------------------------------------------------------ 51package Asis.Text is 52------------------------------------------------------------------------------ 53------------------------------------------------------------------------------ 54-- Asis.Text 55-- 56-- This package encapsulates a set of operations to access the text of ASIS 57-- Elements. It assumes no knowledge of the existence, location, or form of 58-- the program text. 59-- 60-- The text of a program consists of the texts of one or more compilations. 61-- The text of each compilation is a sequence of separate lexical elements. 62-- Each lexical element is either a delimiter, an identifier (which can be a 63-- reserved word), a numeric literal, a character literal, a string literal, 64-- blank space, or a comment. 65-- 66-- Each ASIS Element has a text image whose value is the series of characters 67-- contained by the text span of the Element. The text span covers all the 68-- characters from the first character of the Element through the last 69-- character of the Element over some range of lines. 70-- 71-- General Usage Rules: 72-- 73-- Line lists can be indexed to obtain individual lines. The bounds of each 74-- list correspond to the lines with those same numbers from the compilation 75-- text. 76-- 77-- Any Asis.Text query may raise ASIS_Failed with a Status of Text_Error if 78-- the program text cannot be located or retrieved for any reason such as 79-- renaming, deletion, corruption, or moving of the text. 80------------------------------------------------------------------------------ 81------------------------------------------------------------------------------ 82-- 20.1 type Line 83------------------------------------------------------------------------------ 84-- An Ada text line abstraction (a private type). 85-- 86-- Used to represent text fragments from a compilation. 87-- ASIS Lines are representations of the compilation text. 88-- This shall be supported by all ASIS implementations. 89------------------------------------------------------------------------------ 90 91 type Line is private; 92 Nil_Line : constant Line; 93 94 function "=" (Left : Line; Right : Line) return Boolean is abstract; 95 96-- Nil_Line is the value of an uninitialized Line object. 97-- 98------------------------------------------------------------------------------ 99-- 20.2 type Line_Number 100------------------------------------------------------------------------------ 101-- Line_Number 102-- 103-- A numeric subtype that allows each ASIS implementation to place constraints 104-- on the upper bound for Line_List elements and compilation unit size. 105-- 106-- The upper bound of Line_Number (Maximum_Line_Number) is the only 107-- allowed variation for these declarations. 108-- 109-- Line_Number = 0 is reserved to act as an "invalid" Line_Number value. No 110-- unit text line will ever have a Line_Number of zero. 111------------------------------------------------------------------------------ 112-- Line shall be an undiscriminated private type, or, shall be derived from an 113-- undiscriminated private type. It can be declared as a new type or as a 114-- subtype of an existing type. 115------------------------------------------------------------------------------ 116 117 Maximum_Line_Number : constant ASIS_Natural := 118 Implementation_Defined_Integer_Constant; 119 120 subtype Line_Number is ASIS_Natural range 0 .. Maximum_Line_Number; 121 122------------------------------------------------------------------------------ 123-- 20.3 type Line_Number_Positive 124------------------------------------------------------------------------------ 125 126 subtype Line_Number_Positive is Line_Number range 1 .. Maximum_Line_Number; 127 128------------------------------------------------------------------------------ 129-- 20.4 type Line_List 130------------------------------------------------------------------------------ 131 132 type Line_List is array (Line_Number_Positive range <>) of Line; 133 Nil_Line_List : constant Line_List; 134 135------------------------------------------------------------------------------ 136-- 20.5 type Character_Position 137------------------------------------------------------------------------------ 138-- Character_Position 139-- 140-- A numeric subtype that allows each ASIS implementation to place constraints 141-- on the upper bound for Character_Position and for compilation unit line 142-- lengths. 143-- 144-- The upper bound of Character_Position (Maximum_Line_Length) is the 145-- only allowed variation for these declarations. 146-- 147-- Character_Position = 0 is reserved to act as an "invalid" 148-- Character_Position value. No unit text line will ever have a character in 149-- position zero. 150------------------------------------------------------------------------------ 151 152 Maximum_Line_Length : constant ASIS_Natural := 153 Implementation_Defined_Integer_Constant; 154 155 subtype Character_Position is ASIS_Natural range 0 .. Maximum_Line_Length; 156 157------------------------------------------------------------------------------ 158-- 20.6 type Character_Position_Positive 159------------------------------------------------------------------------------ 160 161 subtype Character_Position_Positive is 162 Character_Position range 1 .. Maximum_Line_Length; 163 164------------------------------------------------------------------------------ 165-- 20.7 type Span 166------------------------------------------------------------------------------ 167-- Span 168-- 169-- A single text position is identified by a line number and a column number, 170-- that represent the text's position within the compilation unit. 171-- 172-- The text of an element can span one or more lines. The textual Span of an 173-- element identifies the lower and upper bound of a span of text positions. 174-- 175-- Spans and positions give client tools the option of accessing compilation 176-- unit text through the queries provided by this package, or, to access 177-- the text directly through the original compilation unit text file. Type 178-- span 179-- facilitates the capture of comments before or after an element. 180-- 181-- Note: The original compilation unit text may or may not have existed in a 182-- "file", and any such file may or may not still exist. Reference Manual 10.1 183-- specifies that the text of a compilation unit is submitted to a compiler. 184-- It does not specify that the text is stored in a "file", nor does it 185-- specify that the text of a compilation unit has any particular lifetime. 186------------------------------------------------------------------------------ 187 188 type Span is -- Default is Nil_Span 189 record 190 First_Line : Line_Number_Positive := 1; -- 1..0 - empty 191 First_Column : Character_Position_Positive := 1; -- 1..0 - empty 192 Last_Line : Line_Number := 0; 193 Last_Column : Character_Position := 0; 194 end record; 195 196 Nil_Span : constant Span := (First_Line => 1, 197 First_Column => 1, 198 Last_Line => 0, 199 Last_Column => 0); 200 201------------------------------------------------------------------------------ 202-- 20.8 function First_Line_Number 203------------------------------------------------------------------------------ 204 205 function First_Line_Number (Element : Asis.Element) return Line_Number; 206 207------------------------------------------------------------------------------ 208-- Element - Specifies the element to query 209-- 210-- Returns the first line number on which the text of the element resides. 211-- 212-- Returns 0 if not Is_Text_Available(Element). 213-- 214-- --|AN Application Note: 215-- --|AN 216-- --|AN The line number recorded for a particular element may or may not 217-- --|AN match the "true" line number of the program text for that element if 218-- --|AN the Ada environment and the local text editors do not agree on the 219-- --|AN definition of "line". For example, the Reference Manual states that 220-- --|AN any occurrence of an ASCII.Cr character is to be treated as one or 221-- --|AN more end-of-line occurrences. On most Unix systems, the editors do 222-- --|AN not treat a carriage return as being an end-of-line character. 223-- --|AN 224-- --|AN Ada treats all of the following as end-of-line characters: ASCII.Cr, 225-- --|AN ASCII.Lf, ASCII.Ff, ASCII.Vt. It is up to the compilation system to 226-- --|AN determine whether sequences of these characters causes one, or more, 227-- --|AN end-of-line occurrences. Be warned, if the Ada environment and the 228-- --|AN system editor (or any other line-counting program) do not use the 229-- --|AN same end-of-line conventions, then the line numbers reported by ASIS 230-- --|AN may not match those reported by those other programs. 231-- 232------------------------------------------------------------------------------ 233-- 20.9 function Last_Line_Number 234------------------------------------------------------------------------------ 235 236 function Last_Line_Number (Element : Asis.Element) return Line_Number; 237 238------------------------------------------------------------------------------ 239-- Element - Specifies the element to query 240-- 241-- Returns the last line number on which the text of the element resides. 242-- 243-- Returns 0 if not Is_Text_Available(Element). 244-- 245------------------------------------------------------------------------------ 246-- 20.10 function Element_Span 247------------------------------------------------------------------------------ 248 249 function Element_Span (Element : Asis.Element) return Span; 250 251------------------------------------------------------------------------------ 252-- Element - Specifies the element to query 253-- 254-- Returns the span of the given element. 255-- 256-- Returns a Nil_Span if the text of a Compilation_Unit (Compilation) cannot 257-- be located for any reason. 258-- --|AN 259-- --|AN For this query, Element is only a means to access the 260-- --|AN Compilation_Unit (Compilation), the availability of the text of this 261-- --|AN Element itself is irrelevant to the result of the query. 262-- 263------------------------------------------------------------------------------ 264-- 20.11 function Compilation_Unit_Span 265------------------------------------------------------------------------------ 266 267 function Compilation_Unit_Span (Element : Asis.Element) return Span; 268 269------------------------------------------------------------------------------ 270-- Element - Specifies the element to query 271-- 272-- Returns the span of the text comprising the enclosing compilation unit of 273-- the given element. 274-- 275-- Returns a Nil_Span if the text of a Compilation_Unit (Compilation) cannot 276-- be located for any reason. 277-- --|AN 278-- --|AN For this query, Element is only a means to access the 279-- --|AN Compilation_Unit (Compilation), the availability of the text of this 280-- --|AN Element itself is irrelevant to the result of the query. 281-- 282------------------------------------------------------------------------------ 283-- 20.12 function Compilation_Span 284------------------------------------------------------------------------------ 285 286 function Compilation_Span (Element : Asis.Element) return Span; 287 288------------------------------------------------------------------------------ 289-- Element - Specifies the element to query 290-- 291-- Returns the span of the text comprising the compilation to which the 292-- element belongs. The text span may include one or more compilation units. 293-- 294-- Returns a Nil_Span if not Is_Text_Available(Element). 295-- 296------------------------------------------------------------------------------ 297-- 20.13 function Is_Nil 298------------------------------------------------------------------------------ 299 300 function Is_Nil (Right : Line) return Boolean; 301 302------------------------------------------------------------------------------ 303-- Right - Specifies the line to check 304-- 305-- Returns True if the argument is the Nil_Line. 306-- 307-- A Line from a Line_List obtained from any of the Lines functions 308-- will not be Is_Nil even if it has a length of zero. 309-- 310------------------------------------------------------------------------------ 311-- 20.14 function Is_Nil 312------------------------------------------------------------------------------ 313 314 function Is_Nil (Right : Line_List) return Boolean; 315 316------------------------------------------------------------------------------ 317-- Right - Specifies the line list to check 318-- 319-- Returns True if the argument has a 'Length of zero. 320-- 321 322------------------------------------------------------------------------------ 323-- 20.15 function Is_Nil 324------------------------------------------------------------------------------ 325 326 function Is_Nil (Right : Span) return Boolean; 327 328------------------------------------------------------------------------------ 329-- Right - Specifies the Span to check 330-- 331-- Returns True if the argument has a Nil_Span. 332-- 333------------------------------------------------------------------------------ 334-- 20.16 function Is_Equal 335------------------------------------------------------------------------------ 336 337 function Is_Equal (Left : Line; Right : Line) return Boolean; 338 339------------------------------------------------------------------------------ 340-- Left - Specifies the first of the two lines 341-- Right - Specifies the second of the two lines 342-- 343-- Returns True if the two lines encompass the same text (have the same Span 344-- and are from the same compilation). 345-- 346------------------------------------------------------------------------------ 347-- 20.17 function Is_Identical 348------------------------------------------------------------------------------ 349 350 function Is_Identical (Left : Line; Right : Line) return Boolean; 351 352------------------------------------------------------------------------------ 353-- Left - Specifies the first of the two lines 354-- Right - Specifies the second of the two lines 355-- 356-- Returns True if the two lines encompass the same text (have the same Span 357-- and are from the same compilation) and are from the same Context. 358-- 359------------------------------------------------------------------------------ 360-- 20.18 function Length 361------------------------------------------------------------------------------ 362 363 function Length (The_Line : Line) return Character_Position; 364 365------------------------------------------------------------------------------ 366-- The_Line - Specifies the line to query 367-- 368-- Returns the length of the line. 369-- 370-- Raises ASIS_Inappropriate_Line if Is_Nil (The_Line). 371-- 372------------------------------------------------------------------------------ 373-- 20.19 function Lines 374------------------------------------------------------------------------------ 375 376 function Lines (Element : Asis.Element) return Line_List; 377 378------------------------------------------------------------------------------ 379-- Element - Specifies the element to query 380-- 381-- Returns a list of lines covering the span of the given program element. 382-- 383-- Returns a Nil_Span if the text of a Compilation containing a given 384-- Element cannot be located for any reason. 385-- 386-- Line lists can be indexed to obtain individual lines. The bounds of each 387-- list correspond to the lines with those same numbers in the compilation 388-- text. 389-- 390-- The first Line of the result contains text from the compilation starting at 391-- the First_Line/First_Column of Element's Span. The last Line of the result 392-- contains text from the compilation ending at the Last_Line/Last_Column of 393-- the Element's Span. Text before or after those limits is not reflected 394-- in the returned list. 395-- --|AN 396-- --|AN For this query, Element is only a means to access the 397-- --|AN Compilation_Unit (Compilation), the availability of the text of this 398-- --|AN Element itself is irrelevant to the result of the query. 399-- 400------------------------------------------------------------------------------ 401-- 20.20 function Lines 402------------------------------------------------------------------------------ 403 404 function Lines 405 (Element : Asis.Element; 406 The_Span : Span) 407 return Line_List; 408 409------------------------------------------------------------------------------ 410-- Element - Specifies the element to query 411-- The_Span - Specifies the textual span to return 412-- 413-- Returns a list of lines covering the given span from the compilation 414-- containing the given program element. 415-- 416-- Returns a Nil_Span if the text of a Compilation containing a given 417-- Element cannot be located for any reason. 418-- 419-- This operation can be used to access lines from text outside the span of an 420-- element, but still within the compilation. For example, lines containing 421-- preceding comments or lines between two elements. 422-- 423-- Line lists can be indexed to obtain individual lines. The bounds of each 424-- list correspond to the lines with those same numbers in the compilation 425-- text. 426-- 427-- The first Line of the result contains text from the compilation starting at 428-- line Span.First_Line and column Span.First_Column. The last Line of the 429-- result contains text from the compilation ending at line Span.Last_Line and 430-- column Span.Last_Column. Text before or after those limits is not 431-- reflected in the returned list. 432-- 433-- Raises ASIS_Inappropriate_Line_Number if Is_Nil (The_Span). If 434-- The_Span defines a line whose number is outside the range of text lines 435-- that can be accessed through the Element, the implementation is encouraged, 436-- but not required to raise ASIS_Inappropriate_Line_Number. 437-- --|AN 438-- --|AN For this query, Element is only a means to access the 439-- --|AN Compilation_Unit (Compilation), the availability of the text of this 440-- --|AN Element itself is irrelevant to the result of the query. 441-- 442------------------------------------------------------------------------------ 443-- 20.21 function Lines 444------------------------------------------------------------------------------ 445 446 function Lines 447 (Element : Asis.Element; 448 First_Line : Line_Number_Positive; 449 Last_Line : Line_Number) 450 return Line_List; 451 452------------------------------------------------------------------------------ 453-- Element - Specifies the element to query 454-- First_Line - Specifies the first line to return 455-- Last_Line - Specifies the last line to return 456-- 457-- Returns a list of Lines covering the full text for each of the indicated 458-- lines from the compilation containing the given element. This operation 459-- can be used to access lines from text outside the span of an element, but 460-- still within the compilation. 461-- 462-- Returns a Nil_Span if the text of a Compilation containing a given 463-- Element cannot be located for any reason. 464-- 465-- Line lists can be indexed to obtain individual lines. The bounds of each 466-- list correspond to the lines with those same numbers in the compilation 467-- text. 468-- 469-- Raises ASIS_Inappropriate_Line_Number if the span is nil. If the span 470-- defines a line whose number is outside the range of text lines that can be 471-- accessed through the Element, the implementation is encouraged, but not 472-- required to raise ASIS_Inappropriate_Line_Number. 473-- --|AN 474-- --|AN For this query, Element is only a means to access the 475-- --|AN Compilation_Unit (Compilation), the availability of the text of this 476-- --|AN Element itself is irrelevant to the result of the query. 477-- 478------------------------------------------------------------------------------ 479-- 20.22 function Delimiter_Image 480------------------------------------------------------------------------------ 481 482 function Delimiter_Image return Wide_String; 483 484------------------------------------------------------------------------------ 485-- Returns the string used as the delimiter separating individual lines of 486-- text within the program text image of an element. It is also used as the 487-- delimiter separating individual lines of strings returned by Debug_Image. 488-- 489------------------------------------------------------------------------------ 490-- 20.23 function Element_Image 491------------------------------------------------------------------------------ 492 493 function Element_Image (Element : Asis.Element) return Program_Text; 494 495------------------------------------------------------------------------------ 496-- Element - Specifies the element to query 497-- 498-- Returns a program text image of the element. The image of an element can 499-- span more than one line, in which case the program text returned by the 500-- function Delimiter_Image separates the individual lines. The bounds on 501-- the returned program text value are 1..N, N is as large as necessary. 502-- 503-- Returns a null string if not Is_Text_Available(Element). 504-- 505-- If an Element's Span begins at column position P, the returned program text 506-- will be padded at the beginning with P-1 white space characters (ASCII.' ' 507-- or ASCII.Ht). The first character of the Element's image will thus begin 508-- at character P of the returned program text. Due to the possible presence 509-- of ASCII.Ht characters, the "column" position of characters within the 510-- image might not be the same as their print-column positions when the image 511-- is displayed on a screen or printed. 512-- 513-- NOTE: The image of a large element can exceed the range of Program_Text. 514-- In this case, the exception ASIS_Failed is raised with a Status of 515-- Capacity_Error. Use the Lines function to operate on the image of large 516-- elements. 517-- 518------------------------------------------------------------------------------ 519-- 20.24 function Line_Image 520------------------------------------------------------------------------------ 521 522 function Line_Image (The_Line : Line) return Program_Text; 523 524------------------------------------------------------------------------------ 525-- The_Line - Specifies the line to query 526-- 527-- Returns a program text image of the line. The image of a single lexical 528-- element can be sliced from the returned value using the first and last 529-- column character positions from the Span of the Element. The bounds on the 530-- returned program text are 1 .. Length(Line). 531-- 532-- If the Line is the first line from the Lines result for an Element, it can 533-- represent only a portion of a line from the original compilation. If the 534-- span began at character position P, the first Line of it's Lines 535-- result is padded at the beginning with P-1 white space characters 536-- (ASCII.' ' or ASCII.Ht). The first character of the image will 537-- thus begin at character P of the program text for the first Line. Due to 538-- the possible presence of ASCII.Ht characters, the "column" position of 539-- characters within the image may not be the same as their print-column 540-- positions when the image is displayed or printed. 541-- 542-- Similarly, if the Line is the last line from the Lines result for an 543-- Element, it may represent only a portion of a line from the original 544-- compilation. The program text image of such a Line is shorter than the 545-- line from compilation and will contain only the initial portion of 546-- that line. 547-- 548-- Raises ASIS_Inappropriate_Line if Is_Nil (The_Line). 549-- 550------------------------------------------------------------------------------ 551-- 20.25 function Non_Comment_Image 552------------------------------------------------------------------------------ 553 554 function Non_Comment_Image (The_Line : Line) return Program_Text; 555 556------------------------------------------------------------------------------ 557-- The_Line - Specifies the line to query 558-- 559-- Returns a program text image of a Line up to, but excluding, any comment 560-- appearing in that Line. 561-- 562-- The value returned is the same as that returned by the Image function, 563-- except that any hyphens ("--") that start a comment, and any characters 564-- that follow those hyphens, are dropped. 565-- 566-- The bounds on the returned program text are 1..N, where N is one less than 567-- the column of any hyphens ("--") that start a comment on the line. 568-- 569-- Raises ASIS_Inappropriate_Line if Is_Nil (The_Line). 570-- 571------------------------------------------------------------------------------ 572-- 20.26 function Comment_Image 573------------------------------------------------------------------------------ 574 575 function Comment_Image (The_Line : Line) return Program_Text; 576 577------------------------------------------------------------------------------ 578-- The_Line - Specifies the line to query 579-- 580-- Returns a program text image of any comment on that line, excluding any 581-- lexical elements preceding the comment. 582-- 583-- The value returned is the same as that returned by the Image function, 584-- except that any program text prior to the two adjacent hyphens ("--") which 585-- start a comment is replaced by an equal number of spaces. If the hyphens 586-- began in column P of the Line, they will also begin in character position 587-- P of the returned program text. 588-- 589-- A null string is returned if the line has no comment. 590-- 591-- The bounds of the program text are 1..N, where N is as large as necessary. 592-- 593-- Raises ASIS_Inappropriate_Line if Is_Nil (The_Line). 594-- 595------------------------------------------------------------------------------ 596-- 20.27 function Is_Text_Available 597------------------------------------------------------------------------------ 598 599 function Is_Text_Available (Element : Asis.Element) return Boolean; 600 601------------------------------------------------------------------------------ 602-- Element - Specifies the element to query 603-- 604-- Returns True if the implementation can return a valid text image for the 605-- given element. 606-- 607-- Returns False for any Element that Is_Nil, Is_Part_Of_Implicit, or 608-- Is_Part_Of_Instance. 609-- 610-- Returns False if the text of the element cannot be located for any reason 611-- such as renaming, deletion, or moving of text. 612-- 613-- --|IR Implementation Requirements: 614-- --|IR 615-- --|IR An implementation shall make text available for all explicit 616-- --|IR elements. 617-- 618------------------------------------------------------------------------------ 619-- 20.28 function Debug_Image 620------------------------------------------------------------------------------ 621 622 function Debug_Image (The_Line : Line) return Wide_String; 623 624------------------------------------------------------------------------------ 625-- The_Line - Specifies the line to convert 626-- 627-- Returns a string value containing implementation-defined debug 628-- information associated with the line. 629-- 630-- The return value uses Asis.Text.Delimiter_Image to separate the lines 631-- of multi-line results. The return value does not end with 632-- Asis.Text.Delimiter_Image. 633-- 634-- These values are intended for two purposes. They are suitable for 635-- inclusion in problem reports sent to the ASIS implementor. They can 636-- be presumed to contain information useful when debugging the 637-- implementation itself. They are also suitable for use by the ASIS 638-- application when printing simple application debugging messages during 639-- application development. They are intended to be, to some worthwhile 640-- degree, intelligible to the user. 641-- 642------------------------------------------------------------------------------ 643 644private 645 646 -- The content of this private part is specific for the ASIS 647 -- implementation for GNAT 648 649------------------------------------------------------------------------------ 650 651 type Line is 652 record 653 Sloc : Source_Ptr := No_Location; 654 Comment_Sloc : Source_Ptr := No_Location; 655 Length : Character_Position := 0; 656 Rel_Sloc : Source_Ptr := No_Location; 657 Enclosing_Unit : Unit_Id := Nil_Unit; 658 Enclosing_Context : Context_Id := Non_Associated; 659 Enclosing_Tree : Tree_Id := Nil_Tree; 660 Obtained : ASIS_OS_Time := Nil_ASIS_OS_Time; 661 end record; 662 663 Nil_Line : constant Line := (Sloc => No_Location, 664 Comment_Sloc => No_Location, 665 Length => 0, 666 Rel_Sloc => No_Location, 667 Enclosing_Unit => Nil_Unit, 668 Enclosing_Context => Non_Associated, 669 Enclosing_Tree => Nil_Tree, 670 Obtained => Nil_ASIS_OS_Time); 671 672 -- Note, that Line does not have the predefined "=" operation (it is 673 -- overridden by an abstract "=". The predefined "=" is explicitly 674 -- simulated in the implementation of Is_Nil query, so, if the full 675 -- declaration for Line is changed, the body of Is_Nil should be revised. 676 677 ----------------------------- 678 -- Fields in the Line type -- 679 ----------------------------- 680 681 -- Sloc : Source_Ptr := No_Location; 682 -- indicates the beginning of the corresponding line in the Source 683 -- Buffer. If a given Line is the first line covering the Image of 684 -- some Element, the position in the Source Buffer pointed by Sloc 685 -- may or may not correspond to the beginning of the source text 686 -- line 687 -- 688 -- Comment_Sloc - represents the starting Sloc position of a comment 689 -- that is a part of the line. Set to 0 if the line does not contain a 690 -- a comment. Note, that we assume that in the comment text the bracket 691 -- encoding can not be used for wide characters 692 -- 693 -- Length : Character_Position := 0; 694 -- represents the length of the Line, excluding any character 695 -- signifying end of line (RM95, 2.2(2)) 696 -- Note, that in the compiler lines of the source code are represented 697 -- using the String type, and if the line contains a wide character that 698 -- requires more than one one-byte character for its representation, the 699 -- length of one-byte character string used to represent wide-character 700 -- string from the source code may be bigger then the length of the 701 -- original source line (length here is the number of characters). In the 702 -- Line type we keep the lenth of the source line counted in source 703 -- characters, but not the length of the internal representation in 704 -- one-byte characters. Note that this length does not depend on the 705 -- encoding method. 706 -- 707 -- Rel_Sloc : Source_Ptr := No_Location; 708 -- needed to compare string representing elements of the same 709 -- compilation units, but probably obtained from different trees 710 -- containing this unit. Obtained in the same way as for Elements - 711 -- by subtracting from Sloc field the source location of the 712 -- N_Compilation_Unit node 713 -- 714 -- Enclosing_Unit : Unit_Id := Nil_Unit; 715 -- Enclosing_Context : Context_Id := Non_Associated; 716 -- These fields represent the Context in which and the Compilation 717 -- Unit from which the given line was obtained, they are needed 718 -- for comparing Lines and for tree swapping when obtaining 719 -- Line_Image 720 -- 721 -- Enclosing_Tree : Tree_Id := Nil_Tree; 722 -- Sloc field may be used for obtaining the image of a Line only in 723 -- the tree from which it was obtained. So the Line has to keep 724 -- the reference to the tree for tree swapping 725 -- 726 -- Obtained : ASIS_OS_Time := Nil_ASIS_OS_Time; 727 -- Lines, as well as Elements, cannot be used after closing the 728 -- Context from which they were obtained. We use time comparing 729 -- to check the validity of a Line 730 731 -- In the current implementation, ASIS Lines are mapped onto logical 732 -- GNAT lines, as defined in the Sinput package. 733 734 -- The child package Asis.Text.Set_Get defines operations for 735 -- accessing and updating fields of Lines, for checking the validity 736 -- of a Line and for creating the new value of the Line type. 737 -- (This package is similar to the Asis.Set_Get package, which 738 -- defines similar things for other ASIS abstractions - Element, 739 -- Context, Compilation_Unit.) 740 741 Nil_Line_List : constant Line_List (1 .. 0) := (1 .. 0 => Nil_Line); 742 743------------------------------------------------------------------------------ 744 745end Asis.Text; 746