!ASIS Issue #028
!topic  Clarification of Function Lines
!reference  ASIS
!from  Sergey Rybin  97-01-12
!keywords  Lines
!discussion

The comment on this Lines function is appended to its definition.

------------------------------------------------------------------------------
-- Section 20.19  function Lines
------------------------------------------------------------------------------
    function Lines (Element  : in Asis.Element;
                    The_Span : in Span) return Line_List;

------------------------------------------------------------------------------
--  Element  - Specifies the element to query
--  The_Span - Specifies the textual span to return
--
-- Returns a list of lines covering the given span from the compilation
-- containing the given program element.
--
-- Returns a Nil_Line_List if not Is_Text_Available(Element).
--
-- This operation can be used to access lines from text outside the span of an
-- element, but still within the compilation.  For example, lines containing
-- preceding comments or lines between two elements.
--
-- Line lists can be indexed to obtain individual lines.  The bounds of each
-- list correspond to the lines with those same numbers in the compilation
-- text.
--
-- The first Line of the result contains text from the compilation starting at
-- line Span.First_Line and column Span.First_Column.  The last Line of the
-- result contains text from the compilation ending at line Span.Last_Line and
-- column Span.Last_Column.  Text before or after those limits is not
-- reflected in the returned list.
--
-- Raises Asis_Inappropriate_Line_Number if the Span defines a Nil_Span or a
-- line whose number is outside the range of text lines that can be accessed
-- through the element.

Comments:
========

1. What does "if the Span defines a Nil_Span" mean here?

   Nil_Span is defined as

    Nil_Span : constant Span := (First_Line   => 1,
                                 First_Column => 1,
                                 Last_Line    => 0,
                                 Last_Column  => 0);

   But the span like:

    My_Nil_Span : constant Span := (First_Line   => 100,
                                    First_Column => 100,
                                    Last_Line    =>  99,
                                    Last_Column  =>  99);

   is also nil, is not it?

!resolution  Accepted, with Modifications.
!date 97-05-28
!Notes

To answer the question posed above: Yes, it is.

No change has been made to the definition of the Nil_Span constant.

Commentary changes have been made to the newly renumbered Subclause
20.21 (version 2.0.N):

     Raises Asis_Inappropriate_Line_Number if Is_Nil (Span)
     or a line whose number is outside the range of text lines
     that can be accessed with the compilation unit.

A new function has been added:

     function Is_Nil (Right : Span) return boolean;

as a new section 20.15.  This takes into account all the "nil"
parameters.  The Nil_Span constant remains in the specification;
the remaining subclauses in Clause 20 were renumbered.

A modification has been made to the newly renumbered Subclause 20.21:
The argument First_Line is of type Line_Number_Positive.

However, no changes were needed for Subclause 20.8; First_Line_Number
returns a value of type Line_Number.

All these changes were made to ASIS version 2.0.M.