⟦1c405ff7f⟧

TextFile

-- This package defines the syntax for software catalog Data Files.
--
-- Software catalog Data Files consist of text containing embedded
-- "annotations". Annotations are of two forms:
--
-- @SIMPLE_KEYWORD
--
-- @VALUED_KEYWORD=ARGUMENT_VALUE
--
-- Only one annotation can appear on a line. An annotation can
-- start in any column, and may have trailing blanks.
--
-- Annotations and arguments are explained in more detail in the
-- package "Annotations_Generic".
--
-- *****
--
-- Every software catalog file must start with three annotations:
--
-- @CATALOG=CATALOG_NAME
-- @LOCATION=SIMPLE_WORLD_NAME
-- @VERSION=SIMPLE_WORLD_NAME
--
-- Catalog names can be any string. Locations must be simple world
-- names which can be resolved to:
--
--     Catalog_Pathnames.Catalogs_Context & "." & <CATALOG LOCATION>
--
-- Versions must be simple world names which can be resolved to:
--
--     Catalog_Pathnames.Catalogs_Context & "." & <CATALOG LOCATION>
--         & ".VERSIONS." & <VERSION>
--
-- Following the @VERSION annotation there may be an arbitrary
-- amount of text.
--
-- Following the text, there may be an arbitrary number of "sections",
-- which are explained below:
--
-- *****
--
-- Every section must start with two annotations:
--
-- @SECTION=SECTION_NAME
-- @KIND=SECTION_KIND
--
-- Section names can be any string.
--
-- Section kinds are defined as follows:
--
--    "TEXT"   The section is composed only of text, and corresponds
--             to no physical object.
--
--    "ITEMS"  The section contains at least one "item" which corresponds
--             to a physical object (items are explained further down
--             in these comments).
--
-- If a section is of kind ITEMS, it must have a third annotation
-- immediately following the first two annotations, with syntax:
--
-- @LOCATION=SIMPLE_WORLD_NAME
--
-- Locations must be simple world names which can be resolved to:
--
--     Catalog_Pathnames.Catalogs_Context & "." & <CATALOG LOCATION>
--         & ".SECTIONS." & <SECTION LOCATION>
--
-- A section of kind ITEMS must contain at least one item.
-- A section of kind TEXT cannot contain any items.
--
-- *****
--
-- Each item must start with two annotations:
--
-- @ITEM=ITEM_NAME
-- @KIND=ITEM_KIND
--
-- Item names can be any string.
--
-- Item kinds are defined as follows:
--
--    "VISIBLE_UNITS"  The item is a subsystem with visible units in at least
--                     one load view (code-only views are permissible, provided
--                     at least one view is not code-only).
--
--    "CODE_ONLY"      The item is a subsystem with no visible units in any
--                     of its load views.
--
--    "FREE_FORM"      The item is some arbitrary library structure. This
--                     provides a way to escape the consistency invariants
--                     imposed on the first two kinds of items. This is
--                     sometimes useful, but it can also be DANGEROUS, so
--                     the use of free-form items should be restricted.
--
--    "ENVIRONMENT"    The item is delivered as part of the standard
--                     Environment, and is therefore not part of the
--                     Software Catalog tape.
--
-- (NOTE: The above descriptions of the structure of the various kinds of
-- items reflect how an item would look AFTER it was restored from the
-- Software Catalog tape by the Browser. The original item would probably
-- look different.)
--
-- *****
--
-- (NOTE: The text in this part of these comments does NOT apply to items of
--  kind "ENVIRONMENT".)
--
-- Following the @KIND annotation, there must be a third annotation:
--
-- @LOCATION=SIMPLE_WORLD_NAME
--
-- Locations must be simple world names which can be resolved to:
--
--     Catalog_Pathnames.Catalogs_Context & "." & <CATALOG LOCATION>
--         & ".SECTIONS." & <SECTION LOCATION> & "." & <ITEM LOCATION>
--
-- If the item is of kind VISIBLE_UNITS or CODE_DATABASE, then:
--
--   Following the @LOCATION annotation there may 0 to N of the following
--   annotations:
--
--   @IMPORT=FULLY_QUALIFIED_SPEC_VIEW_NAME
--
--   These annotations list the spec views which have been imported into
--   the current item.
--
--   Following the @LOCATION annotation (or the @IMPORT annotation if imports
--   were specified) there may be 0 to N of the following annotations:
--
--   @SPEC_VIEW=SIMPLE_SPEC_VIEW_NAME
--
--   These annotations list the spec views which should be placed on the
--   Software Catalog tape when building a release of the Catalog.
--
--   Following the last @SPEC_VIEW annotation (or the last @IMPORT annotation
--   if no spec views were specified (or the @LOCATION annotation if no
--   imports were specified)), there must be at least one of the following
--   annotations:
--
--   @LOAD_VIEW=SIMPLE_LOAD_VIEW_NAME
--
-- Following any and all other annotations for the current item, there must
-- be the following annotation:
--
-- @PROPRIETARY=BOOLEAN_VALUE
--
-- The value can only be TRUE or FALSE. If TRUE, this indicates that the
-- current item is proprietary. If FALSE, this indicates that the current
-- item is in the public domain.
--
-- Following the @PROPRIETARY annotation, there may be an arbitrary amount
-- of text.
--
-- *****
--
-- Following the last item, there must be at least one of the following
-- annotations:
--
-- @MODEL=FULLY_QUALIFIED_WORLD_NAME
--
-- The set of @MODEL annotations lists the models allowed in the current
-- catalog. There is no limit to how many models may be allowed (but
-- there must be at least one allowable model).
--
-- Following the last @MODEL annotation, there may be 0 to N of the following
-- annotations:
--
-- @LINK=FULLY_QUALIFIED_PATHNAME_OF_ADA_UNIT
--
-- The set of @LINK annotations lists the external links allowed in the current
-- catalog. There is no limit to how many links may be allowed, and different
-- links to different Ada units with the same simple name are permitted.
--
-- *****
--
-- Comments may appear anywhere in a catalog file (as long as they
-- obey the basic formatting rules for annotations). A comment begins with
-- an "@BEGIN_COMMENT" annotation, and ends with an "@END_COMMENT"
-- annotation. Everything between the beginning and ending of the comment
-- is ignored.
--
-- Comments may be nested.
--
-- *****
--
-- All parsing of annotations and their arguments is case-insensitive.
--
package Syntax is

    Annotation_Indicator : constant Character := '@'; -- Start of annotation.

    Argument_Delimiter : constant Character := '='; -- Start of argument.

    -- Simple annotation keywords:

    type Comment_Keywords is (Begin_Comment,  
                              End_Comment);

    -- Valued annotation keywords:

    type Valued_Keywords is (Catalog,  
                             Section,  
                             Item,  
                             Location,  
                             Version,  
                             Import,  
                             Spec_View,  
                             Load_View,  
                             Proprietary,  
                             Kind,  
                             Model,  
                             Link);

    -- Allowable arguments to @KIND annotations for @SECTIONs:

    type Section_Kinds is (Text, Items);

    -- Allowable arguments to @KIND annotations for @ITEMs:

    type Item_Kinds is (Visible_Units, Code_Only, Free_Form, Environment);

    -- Allowable arguments to @PROPRIETARY annotations for @ITEMs:

    type Booleans is (True, False);

end Syntax;
DataMuseum.dk

Rational R1000/400 Tapes

⟦1c405ff7f⟧ TextFile

Derivation

TextFile
