-- 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 & "." & -- -- Versions must be simple world names which can be resolved to: -- -- Catalog_Pathnames.Catalogs_Context & "." & -- & ".VERSIONS." & -- -- 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 & "." & -- & ".SECTIONS." &
-- -- 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 & "." & -- & ".SECTIONS." &
& "." & -- -- 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;