{"diffoscope-json-version": 1, "source1": "/srv/reproducible-results/rbuild-debian/r-b-build.y4BwfSJo/b1/libgnatcoll-db_23.0.0-5_amd64.changes", "source2": "/srv/reproducible-results/rbuild-debian/r-b-build.y4BwfSJo/b2/libgnatcoll-db_23.0.0-5_amd64.changes", "unified_diff": null, "details": [{"source1": "Files", "source2": "Files", "unified_diff": "@@ -1,11 +1,11 @@\n \n 7f4a19a0efc9f51a76b27e72330bed54 397664 debug optional libgnatcoll-db-bin-dbgsym_23.0.0-5_amd64.deb\n cf8b8bbe594f8163d39d282cf7167192 218604 devel optional libgnatcoll-db-bin_23.0.0-5_amd64.deb\n- bc6acb05bd3ef960718075b9a4ac305e 493304 doc optional libgnatcoll-db-doc_23.0.0-5_all.deb\n+ 72790e9362aa9338fc191032b30f8922 493220 doc optional libgnatcoll-db-doc_23.0.0-5_all.deb\n c60ec6e164ff4c143807f7d86ed5022f 167904 libdevel optional libgnatcoll-postgres-dev_23.0.0-5_amd64.deb\n 36df005e85a2a7f7c43d319b8173263f 231436 debug optional libgnatcoll-postgres2-dbgsym_23.0.0-5_amd64.deb\n a1db4246cd2ff7246465500291bdb1e8 150240 libs optional libgnatcoll-postgres2_23.0.0-5_amd64.deb\n eb02e72b6dca3daf79d087918017c5e0 1262308 libdevel optional libgnatcoll-sql-dev_23.0.0-5_amd64.deb\n 9ac0ff06a99f31e5521afb357a290d5f 2047236 debug optional libgnatcoll-sql4-dbgsym_23.0.0-5_amd64.deb\n ca41e20e8f49e85c02b0238ab25906bf 1115100 libs optional libgnatcoll-sql4_23.0.0-5_amd64.deb\n 6fe8891e594ad756b559ab598fe53b64 74012 libdevel optional libgnatcoll-sqlite-dev_23.0.0-5_amd64.deb\n"}, {"source1": "libgnatcoll-db-doc_23.0.0-5_all.deb", "source2": "libgnatcoll-db-doc_23.0.0-5_all.deb", "unified_diff": null, "details": [{"source1": "file list", "source2": "file list", "unified_diff": "@@ -1,3 +1,3 @@\n -rw-r--r-- 0 0 0 4 2023-12-26 19:02:15.000000 debian-binary\n--rw-r--r-- 0 0 0 1688 2023-12-26 19:02:15.000000 control.tar.xz\n--rw-r--r-- 0 0 0 491424 2023-12-26 19:02:15.000000 data.tar.xz\n+-rw-r--r-- 0 0 0 1692 2023-12-26 19:02:15.000000 control.tar.xz\n+-rw-r--r-- 0 0 0 491336 2023-12-26 19:02:15.000000 data.tar.xz\n"}, {"source1": "control.tar.xz", "source2": "control.tar.xz", "unified_diff": null, "details": [{"source1": "control.tar", "source2": "control.tar", "unified_diff": null, "details": [{"source1": "./md5sums", "source2": "./md5sums", "unified_diff": null, "details": [{"source1": "./md5sums", "source2": "./md5sums", "comments": ["Files differ"], "unified_diff": null}]}]}]}, {"source1": "data.tar.xz", "source2": "data.tar.xz", "unified_diff": null, "details": [{"source1": "data.tar", "source2": "data.tar", "unified_diff": null, "details": [{"source1": "file list", "source2": "file list", "unified_diff": "@@ -11,15 +11,15 @@\n -rw-r--r-- 0 root (0) root (0) 1321 2022-09-22 17:07:33.000000 ./usr/share/doc/libgnatcoll-db-doc/examples/library/dbschema.txt\n -rw-r--r-- 0 root (0) root (0) 463 2022-09-22 17:07:33.000000 ./usr/share/doc/libgnatcoll-db-doc/examples/library/default.gpr\n -rw-r--r-- 0 root (0) root (0) 812 2022-09-22 17:07:33.000000 ./usr/share/doc/libgnatcoll-db-doc/examples/library/fixture.txt\n -rwxr-xr-x 0 root (0) root (0) 124 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/examples/library/generate.sh\n drwxr-xr-x 0 root (0) root (0) 0 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/examples/library/generated/\n drwxr-xr-x 0 root (0) root (0) 0 2022-09-22 17:07:33.000000 ./usr/share/doc/libgnatcoll-db-doc/examples/library/src/\n -rw-r--r-- 0 root (0) root (0) 7115 2022-09-22 17:07:33.000000 ./usr/share/doc/libgnatcoll-db-doc/examples/library/src/library.adb\n--rw-r--r-- 0 root (0) root (0) 344246 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/gnatcoll-db.pdf.gz\n+-rw-r--r-- 0 root (0) root (0) 344490 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/gnatcoll-db.pdf.gz\n drwxr-xr-x 0 root (0) root (0) 0 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/\n drwxr-xr-x 0 root (0) root (0) 0 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/_images/\n -rw-r--r-- 0 root (0) root (0) 1447 2022-09-22 17:07:33.000000 ./usr/share/doc/libgnatcoll-db-doc/html/_images/important.png\n -rw-r--r-- 0 root (0) root (0) 2247 2022-09-22 17:07:33.000000 ./usr/share/doc/libgnatcoll-db-doc/html/_images/note.png\n -rw-r--r-- 0 root (0) root (0) 2143 2022-09-22 17:07:33.000000 ./usr/share/doc/libgnatcoll-db-doc/html/_images/tip.png\n drwxr-xr-x 0 root (0) root (0) 0 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/_sources/\n -rw-r--r-- 0 root (0) root (0) 413 2022-09-22 17:07:33.000000 ./usr/share/doc/libgnatcoll-db-doc/html/_sources/index.rst.txt\n@@ -36,16 +36,16 @@\n -rw-r--r-- 0 root (0) root (0) 90 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/_static/minus.png\n -rw-r--r-- 0 root (0) root (0) 90 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/_static/plus.png\n -rw-r--r-- 0 root (0) root (0) 4902 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/_static/pygments.css\n -rw-r--r-- 0 root (0) root (0) 4080 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/genindex.html\n -rw-r--r-- 0 root (0) root (0) 7739 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/index.html\n -rw-r--r-- 0 root (0) root (0) 607 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/objects.inv\n -rw-r--r-- 0 root (0) root (0) 3889 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/search.html\n--rw-r--r-- 0 root (0) root (0) 23062 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/searchindex.js\n--rw-r--r-- 0 root (0) root (0) 186762 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/sql.html\n+-rw-r--r-- 0 root (0) root (0) 23059 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/searchindex.js\n+-rw-r--r-- 0 root (0) root (0) 186904 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/sql.html\n -rw-r--r-- 0 root (0) root (0) 34267 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/html/xref.html\n drwxr-xr-x 0 root (0) root (0) 0 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/text/\n drwxr-xr-x 0 root (0) root (0) 0 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/text/_static/\n -rw-r--r-- 0 root (0) root (0) 4289 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/text/_static/_sphinx_javascript_frameworks_compat.js\n -rw-r--r-- 0 root (0) root (0) 89037 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/text/_static/jquery.js\n -rw-r--r-- 0 root (0) root (0) 1169 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/text/index.txt\n -rw-r--r-- 0 root (0) root (0) 31506 2023-12-26 19:02:15.000000 ./usr/share/doc/libgnatcoll-db-doc/text/sql.txt.gz\n"}, {"source1": "./usr/share/doc/libgnatcoll-db-doc/gnatcoll-db.pdf.gz", "source2": "./usr/share/doc/libgnatcoll-db-doc/gnatcoll-db.pdf.gz", "unified_diff": null, "details": [{"source1": "gnatcoll-db.pdf", "source2": "gnatcoll-db.pdf", "unified_diff": null, "details": [{"source1": "pdftotext {} -", "source2": "pdftotext {} -", "unified_diff": "@@ -16,15 +16,15 @@\n 1.3 Database schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.4 The gnatcoll_db2ada tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.4.1\n Default output of gnatcoll_db2ada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.4.2\n database introspection in Ada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.4.3\n-Back to the library example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n+Back to the library example... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.5 Connecting to the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.6 Loading initial data in the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.7 Writing queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.8 Executing queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.9 Prepared queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.10 Getting results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n 1.11 Creating your own SQL types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .\n@@ -102,25 +102,25 @@\n two systems. For instance, development could be done using a local sqlite DBMS, and then deployed (after\n testing, of course!) on a PostgreSQL system.\n The code in GNATColl is such that adding support for a new DBMS should be relatively easy.\n \u2022 A place where an application stores its data. The term database in this document refers to this meaning. In a\n relational database, this place is organized into tables, each of which contains a number of fields. A row in a\n table represents one object. The set of tables and their fields is called the schema of the database.\n Traditionally, writing the SQL queries is done inline: special markers are inserted into your code to delimit sections\n-that contain SQL code (as opposed to Ada code), and these are then preprocessed to generate actual code. This isn\u2019t\n+that contain SQL code (as opposed to Ada code), and these are then preprocessed to generate actual code. This isn't\n the approach chosen in GNATColl: there are several drawbacks, in particular your code is no longer Ada and various\n tools will choke on it.\n The other usual approach is to write the queries as strings, which are passed, via a DBMS-specific API, to the DBMS\n server. This approach is very fragile:\n \u2022 The string might not contain well-formed SQL. This will unfortunately only be detected at run time when the\n DBMS complains.\n \u2022 This is not type safe. You might be comparing a text field with an integer, for instance. In some cases, the DBMS\n-will accept that (sqlite for instance), but in some other cases it won\u2019t (PostgreSQL). The result might then either\n+will accept that (sqlite for instance), but in some other cases it won't (PostgreSQL). The result might then either\n raise an error, or return an empty list.\n-\u2022 There is a risk of SQL injection. Assuming the string is constructed dynamically (using Ada\u2019s & operator), it\n+\u2022 There is a risk of SQL injection. Assuming the string is constructed dynamically (using Ada's & operator), it\n might be easy for a user to pass a string that breaks the query, and even destroys things in the database.\n \u2022 As discussed previously, the SQL code might not be portable across DBMS. For instance, creating an automatically increment integer primary key in a table is DBMS specific.\n \u2022 The string is fragile if the database schema changes. Finding whether a schema change impacts any of the\n queries requires looking at all the strings in your application.\n \u2022 performance might be an issue. Whenever you execute a query, the DBMS will analyze it, decide how to execute\n it (for instance, whether it should traverse all the rows of a table, or whether it can do a faster lookup), and then\n \n@@ -179,124 +179,123 @@\n The following sections will ignore the lower layer, and concentrate on the other layers. They share a number of types\n and, again, are fully compatible with each other. You could connect to the database, and then write some queries using\n GNATCOLL.SQL and some using GNATCOLL.SQL.ORM.\n \n 1.2 Database example\n This section describes an example that will be extended throughout this chapter. We will build an application that\n represents a library. Such a library contains various media (books and DVDs for instance), and customers. A customer\n-can borrow multiple media at the same time, but a media is either at a customer\u2019s, or still in the library.\n+can borrow multiple media at the same time, but a media is either at a customer's, or still in the library.\n The GNATColl distribution includes an example directory which contains all the code and data for this example.\n \n 1.3 Database schema\n As was mentioned earlier (Database Abstraction Layers), GNATColl relies on automatic code generation to provide a\n type safe interface to your database. This code is generated by an external tool called gnatcoll_db2ada. In some cases,\n this tool requires an installation of python (www.python.org) on your machine, since part of the code is written in that\n language.\n This tool is able to output various kind of information, and will be fully described later (The gnatcoll_db2ada tool).\n However, the input is always the same: this is the schema of your database, that is the list of tables and fields that make\n up your database. There exist two ways to provide that information:\n \u2022 From a running database\n-If you pass the DBMS vendor (postgresql, sqlite,. . . ) and the connection parameters to gnatcoll_db2ada, it is\n+If you pass the DBMS vendor (postgresql, sqlite,...) and the connection parameters to gnatcoll_db2ada, it is\n able to query the schema on its own. However, this should not be the preferred method: this is similar to reverse\n engineering assembly code into the original high-level code, and some semantic information will be missing. For\n instance, in SQL we have to create tables just to represent the many-to-many relationships. These extra tables\n are part of the implementation of the schema, but are just noise when it comes to the semantics of the schema.\n For this reason, it is better to use the second solution below:\n \u2022 From a textual description\n Using the -dbmodel switch to gnatcoll_db2ada, you can pass a file that describes the schema. We do not use\n SQL as the syntax in this, because as explained above this is too low-level. This text file also provides additional\n capabilities that do not exist when reverse-engineering an existing database, for instance the ability to use name\n to represent reverse relationships for foreign keys (see below and the ORM).\n The most convenient editor for this file is Emacs, using the org-mode which provides convenient key shortcuts\n for editing the contents of ASCII tables. But any text editor will do, and you do not need to align the columns in\n this file.\n-All lines starting with a hash sign (\u2018#\u2019) will be ignored.\n+All lines starting with a hash sign ('#') will be ignored.\n This file is a collection of ASCII tables, each of which relates to one table or one SQL view in your database.\n The paragraphs start with a line containing:\n table ::=\n '|' ('ABSTRACT')? ('TABLE'|'VIEW') ['(' supertable ')']\n '|' '|' \n-\u201cname\u201d is the name of the table. The third pipe and third column are optional, and should be used to specify the\n-name for the element represented by a single row. For instance, if the table is called \u201cbooks\u201d, the third column\n-could contain \u201cbook\u201d. This is used when generating objects for use with GNATCOLL.SQL.ORM.\n+\"name\" is the name of the table. The third pipe and third column are optional, and should be used to specify the\n+name for the element represented by a single row. For instance, if the table is called \"books\", the third column\n+could contain \"book\". This is used when generating objects for use with GNATCOLL.SQL.ORM.\n \n 1.2. Database example\n \n 3\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n If the first line starts with the keyword ABSTRACT, then no instance of that table actually exists in the database.\n This is used in the context of table inheritance, so define shared fields only once among multiple tables.\n The keyword TABLE can be followed by the name of a table from which it inherits the fields. Currently, that\n supertable must be abstract, and the fields declared in that table are simply duplicated in the new table.\n Following the declaration of the table, the file then describe their fields, each on a separate line. Each of these\n-lines must start with a pipe character (\u201c|\u201d), and contain a number of pipe-separated fields. The order of the fields\n+lines must start with a pipe character (\"|\"), and contain a number of pipe-separated fields. The order of the fields\n is always given by the following grammar:\n fields ::=\n '|' '|' \n '|' ('PK'|''|'NULL'|'NOT NULL'|'INDEX'|'UNIQUE'|'NOCASE')\n '|' [default] '|' [doc] '|'\n-The type of the field is the SQL type (\u201cINTEGER\u201d, \u201cTEXT\u201d, \u201cTIMESTAMP\u201d, \u201cDATE\u201d, \u201cDOUBLE PRECISION\u201d, \u201cMONEY\u201d, \u201cBOOLEAN\u201d, \u201cTIME\u201d, \u201cCHARACTER(1)\u201d). Any maximal length can be specified for\n-strings, not just 1 as in this example. The tool will automatically convert these to Ada when generating Ada code.\n-A special type (\u201cAUTOINCREMENT\u201d) is an integer that is automatically incremented according to available ids\n-in the table. The exact type used will depend on the specific DBMS.\n-The property \u2018NOCASE\u2019 indicates that comparison should be case insensitive for this field.\n+The type of the field is the SQL type (\"INTEGER\", \"TEXT\", \"TIMESTAMP\", \"DATE\", \"DOUBLE PRECISION\", \"MONEY\", \"BOOLEAN\", \"TIME\", \"CHARACTER(1)\"). Any maximal length can be specified for\n+strings, not just 1 as in this example. The tool will automatically convert these to Ada when generating Ada\n+code. A special type (\"AUTOINCREMENT\") is an integer that is automatically incremented according to available ids in the table. The exact type used will depend on the specific DBMS.\n+The property 'NOCASE' indicates that comparison should be case insensitive for this field.\n If the field is a foreign key (that is a value that must correspond to a row in another table), you can use the special\n syntax for its type:\n fk_type ::= 'FK' [ '(' ')' ]\n-As you can see, the type of the field is not specified explicitly, but will always be that of the foreign table\u2019s primary\n+As you can see, the type of the field is not specified explicitly, but will always be that of the foreign table's primary\n key. With this syntax, the foreign table must have a single field for its primary key. GNATColl does not force a\n-specific order for the declaration of tables: if is valid to have a foreign key to a table that hasn\u2019t been declared yet.\n+specific order for the declaration of tables: if is valid to have a foreign key to a table that hasn't been declared yet.\n There is however a restriction if you use the model to create a sqlite database (through the -createdb switch of\n-gnatcoll_db2ada): in this case, a reference to a table that hasn\u2019t been defined yet may not be not through a field\n+gnatcoll_db2ada): in this case, a reference to a table that hasn't been defined yet may not be not through a field\n marked as NOT NULL. This is a limitation of the sqlite backend itself. The solution in this case is to reorder the\n declaration of tables, or drop the NOT NULL constraint.\n Another restriction is that a foreign key that is also a primary key must reference a table that has already been\n defined. You need to reorder the declaration of your tables to ensure this is the case.\n-\u201creverse_name\u201d is the optional name that will be generated in the Ada code for the reverse relationship, in the\n-context of GNATCOLL.SQL.ORM. If the \u201creverse_name\u201d is empty (the parenthesis are shown), no reverse relationship is generated. If the parenthesis and the reverse_name are both omitted, a default name is generated\n+\"reverse_name\" is the optional name that will be generated in the Ada code for the reverse relationship, in the\n+context of GNATCOLL.SQL.ORM. If the \"reverse_name\" is empty (the parenthesis are shown), no reverse relationship is generated. If the parenthesis and the reverse_name are both omitted, a default name is generated\n based on the name of the field.\n The third column in the fields definition indicates the constraints of the type. Multiple keywords can be used if\n-they are separated by commas. Thus, \u201cNOT NULL, INDEX\u201d indicates a column that must be set by the user,\n+they are separated by commas. Thus, \"NOT NULL, INDEX\" indicates a column that must be set by the user,\n and for which an index is created to speed up look ups.\n-\u2013 A primary key (\u201cPK\u201d)\n-\u2013 The value must be defined (\u201cNOT NULL\u201d)\n-\u2013 The value can be left undefined (\u201cNULL\u201d)\n-\u2013 A unique constraint and index (\u201cUNIQUE\u201d)\n-\u2013 An index should be created for that column (\u201cINDEX\u201d) to speed up the lookups.\n-\u2013 The automatic index created for a Foreign Key should not be created (\u201cNOINDEX\u201d). Every time a field\n-references another table, GNATColl will by default create an index for it, so that the ORM can more efficiently do a reverse query (from the target table\u2019s row find all the rows in the current table that reference\n+\u2013 A primary key (\"PK\")\n+\u2013 The value must be defined (\"NOT NULL\")\n+\u2013 The value can be left undefined (\"NULL\")\n+\u2013 A unique constraint and index (\"UNIQUE\")\n+\u2013 An index should be created for that column (\"INDEX\") to speed up the lookups.\n+\u2013 The automatic index created for a Foreign Key should not be created (\"NOINDEX\"). Every time a field\n+references another table, GNATColl will by default create an index for it, so that the ORM can more efficiently do a reverse query (from the target table's row find all the rows in the current table that reference\n 4\n \n Chapter 1. SQL: Database interface\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n that target row). This will in general provide more efficiency, but in some cases you never intend to do the\n reverse query and thus can spare the extra index.\n The fourth column gives the default value for the field, and is given in SQL syntax. Strings must be quoted with\n single quotes.\n The fifth column contains documentation for the field (if any). This documentation will be included in the\n-generated code, so that IDEs can provide useful tooltips when navigating your application\u2019s code.\n+generated code, so that IDEs can provide useful tooltips when navigating your application's code.\n After all the fields have been defined, you can specify extract constraints on the table. In particular, if you have\n a foreign key to a table that uses a tuple as its primary key, you can define that foreign key on a new line, as:\n FK ::= '|' \"FK:\" '|' '|' *\n '|' * '|'\n For instance:\n | TABLE | tableA |\n | FK: | tableB | fieldA1, fieldA2 | fieldB1, fieldB2 |\n It is also possible to create multi-column indexes, as in the following example. In this case, the third column\n contains the name of the index to create. If left blank, a default name will be computed by GNATColl:\n | TABLE | tableA |\n | INDEX: | field1,field2,field3 | name |\n The same way the unique multi-column constraint and index can be created. The name is optional.\n TABLE | tableA |\n UNIQUE: | field1,field2,field3 | name |\n-Going back to the example we described earlier (Database example), let\u2019s describe the tables that are involved.\n+Going back to the example we described earlier (Database example), let's describe the tables that are involved.\n The first table contains the customers. Here is its definition:\n | TABLE | customers\n | customer\n || The customer for the library |\n | id\n | AUTOINCREMENT | PK\n || Auto-generated id\n@@ -307,33 +306,33 @@\n |\n | last | TEXT\n | NOT NULL, INDEX || Customer's last name\n |\n We highly recommend to set a primary key on all tables. This is a field whose value is unique in the table,\n and thus that can act as an identifier for a specific row in the table (in this case for a specific customer). We\n recommend using integers for these ids for efficiency reasons. It is possible that the primary key will be made of\n-several fields, in which case they should all have the \u201cPK\u201d constraint in the third column.\n+several fields, in which case they should all have the \"PK\" constraint in the third column.\n A table with no primary key is still usable. The difference is in the code generated for the ORM (The ObjectRelational Mapping layer (ORM)), since the Delete operation for this table will raise a Program_Error instead\n-of doing the actual deletion (that\u2019s because there is no guaranteed unique identifier for the element, so the ORM\n-does not know which one to delete \u2013 we do not depend on having unique internal ids on the table, like some\n+of doing the actual deletion (that's because there is no guaranteed unique identifier for the element, so the ORM\n+does not know which one to delete -- we do not depend on having unique internal ids on the table, like some\n DBMS have). Likewise, the elements extracted from such a primary key-less table will not be cached locally in\n the session, and cannot be updated (only new elements can be created in the table).\n As we mentioned, the library contains two types of media, books and DVDs. Each of those has a title, an author.\n However, a book also has a number of pages and a DVD has a region where it can be viewed. There are various\n ways to represent this in a database. For illustration purposes, we will use table inheritance here: we will declare\n one abstract table (media) which contains the common fields, and two tables to represent the types of media.\n As we mentioned, a media can be borrowed by at most one customer, but a customer can have multiple media\n at any point in time. This is called a one-to-many relationship. In SQL, this is in general described through the\n 1.3. Database schema\n \n 5\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n-use of a foreign key that goes from the table on the \u201cmany\u201d side. In this example, we therefore have a foreign key\n+use of a foreign key that goes from the table on the \"many\" side. In this example, we therefore have a foreign key\n from media to customers. We also provide a name for the reverse relationship, which will become clearer when\n we describe the ORM interface.\n Here are the declarations:\n | ABSTRACT TABLE | media\n | media || The contents of the library |\n | id\n | AUTOINCREMENT\n@@ -371,27 +370,27 @@\n | region\n | INTEGER |\n | 1 |\n |\n For this example, all this description is put in a file called dbschema.txt.\n \n 1.4 The gnatcoll_db2ada tool\n-As stated in the introduction, one of the goals of this library is to make sure the application\u2019s code follows changes in\n+As stated in the introduction, one of the goals of this library is to make sure the application's code follows changes in\n the schema of your database.\n To reach this goal, an external tool, gnatcoll_db2ada is provided with GNATColl, and should be spawned as the first\n step of the build process, or at least whenever the database schema changes. It generates an Ada package (Database by\n default) which reflects the current schema of the database.\n This tool supports a number of command line parameters (the complete list of which is available through the -h switch).\n The most important of those switches are:\n -dbhost host, -dbname name, -dbuser user, -dbpasswd passwd, -dbtype type\n These parameters specify the connection parameters for the database. To find out the schema, gnatcoll_db2ada\n can connect to an existing database (Database schema). The user does not need to have write permission on the\n database, since all queries are read-only.\n -dbmodel file\n-This parameter can replace the above -dbname,. . . It specifies the name of a text file that contains the description\n+This parameter can replace the above -dbname,... It specifies the name of a text file that contains the description\n of the database, therefore avoiding the need for already having a database up-and-running to generate the Ada\n interface.\n The format of this text file was described in the previous section.\n This switch is not compatible with -enum and -vars that really need an access to the database.\n -api PKG\n This is the default behavior if you do not specify -text or -createdb. This will generate several files (PKG.ads,\n PKG.adb and PKG_names.ads, where PKG is the argument given on the command line). These package represent your database schema, that is the list of all tables and their fields, as typed values. This is the building block\n@@ -412,18 +411,18 @@\n This should be used in combination with -api. In addition to the usual output of -api, it will also generate an\n Ada subprogram called Create_Database that can be used to recreate the database and its initial data (if -load\n was specified) from your application, without requiring access to the external files that define the schema and the\n initial data.\n -enum table,id,name,prefix,base\n This parameter can be repeated several times if needed. It identifies one of the special tables of the database that\n acts as an enumeration type. It is indeed often the case that one or more tables in the database have a role similar\n-to Ada\u2019s enumeration types, i.e. contains a list of values for information like the list of possible priorities, a list\n-of countries,. . . Such lists are only manipulated by the maintainer of the database, not interactively, and some\n-of their values have impact on the application\u2019s code (for instance, if a ticket has an urgent priority, we need to\n-send a reminder every day \u2013 but the application needs to know what an urgent priority is). In such a case, it is\n+to Ada's enumeration types, i.e. contains a list of values for information like the list of possible priorities, a list\n+of countries,... Such lists are only manipulated by the maintainer of the database, not interactively, and some\n+of their values have impact on the application's code (for instance, if a ticket has an urgent priority, we need to\n+send a reminder every day -- but the application needs to know what an urgent priority is). In such a case, it is\n convenient to generate these values as constants in the generated package. The output will be similar to:\n subtype Priority_Id is Integer;\n Priority_High\n : constant Priority_Id := 3;\n Priority_Medium : constant Priority_Id := 2;\n Priority_Low\n : constant Priority_Id := 1;\n@@ -447,15 +446,15 @@\n | 4\n | internal\n To generate the above Ada code, you need to pass the following parameter to gnatcoll_db2ada:\n -enum ticket_priorities,Priority,Name,Priority,Integer\n First word in the parameter is the table name where the data to generate constants is stored. Second word is the\n field name in the table where the Ada constant value is stored. The third word is the field where the last part\n the Ada constant name is stored. The forth word is the prefix to add in front of the third word field value to\n-generate the Ada constant\u2019s name. The last optional parameter should be either Integer (default) or String, which\n+generate the Ada constant's name. The last optional parameter should be either Integer (default) or String, which\n influences the way how the Ada constant value is going to be generated (surrounded or not by quotes).\n -enum-image\n If specified in addition to the -enum switch, then a function is generated for each Integer-valued enum that\n converts numeric values to the corresponding name as a string.\n This function is generated as an Ada 2012 expression-function such as:\n function Image_Priority_Id (X : Priority_Id) return String is\n (case X is\n@@ -491,15 +490,15 @@\n 1\n | user1\n We could extract the id that helps detect unassigned tickets with the following command line:\n -var no_assign_id,staff,staff_id,\"login='unassigned'\",\"help\"\n which generates:\n No_Assigne_Id : constant := 0;\n -- help\n-The application should use this constant rather than some hard-coded string \u201cunassigned\u201d or a named constant\n+The application should use this constant rather than some hard-coded string \"unassigned\" or a named constant\n with the same value. The reason is that presumably the login will be made visible somewhere to the user, and\n we could decide to change it (or translate it to another language). In such a case, the application would break.\n On the other hand, using the constant 0 which we just extracted will remain valid, whatever the actual text we\n display for the user.\n -orm PKG\n This will generate two files (PKG.ads and PKG.adb) that support GNATCOLL.SQL.ORM to write queries without writing actual SQL. This is often used in conjunction with -api, as in:\n gnatcoll_db2ada -api Database -orm ORM -dbmodel dbschema.txt\n@@ -561,30 +560,30 @@\n \n 1.4.2 database introspection in Ada\n As described above, the -createdb switch makes it possible to create a database (or at least its schema). This operation\n can also be performed directly from your Ada code by using the services provided in the GNATCOLL.SQL.Inspect\n package. In particular, there are services for reading the schema of a database either from a file or from a live database,\n just as gnatcoll_db2ada does.\n This results in a structure in memory that you can use to find out which are the tables, what are their fields, their primary\n-keys,. . .\n+keys,...\n It is also possible to dump this schema to a text file (with the same format as expected by -dbmodel), or more interestingly\n to output the SQL statements that are needed to create the tables in a database. In the case of Sqlite, creating a table\n-will also create the database file if it doesn\u2019t exist yet, so no special rights are needed.\n+will also create the database file if it doesn't exist yet, so no special rights are needed.\n \n 1.4. The gnatcoll_db2ada tool\n \n 9\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n This input/output mechanism is implemented through an abstract Schema_IO tagged type, with various concrete implementations (either File_Schema_IO to read or write from/to a file, or DB_Schema_IO to read or write from/to a\n database).\n See the specs for more detail on these subprograms.\n \n-1.4.3 Back to the library example. . .\n+1.4.3 Back to the library example...\n In the previous section, we have described our database schema in a text file. We will now perform two operations:\n \u2022 Create an empty database\n This should of course only be done once, not every time you run your application:\n gnatcolldbada -dbtype=sqlite -dbname=library.db -dbmodel=dbschema.txt -createdb\n In the case of this example, the sql commands that are executed for sqlite are:\n CREATE TABLE books (\n pages Integer DEFAULT '100',\n@@ -625,15 +624,15 @@\n of the box (PostgreSQL and Sqlite), although new ones can be added by overriding the appropriate SQL type\n (Database_Connection). When you compile GNATColl, the build scripts will try and detect what systems are installed on your machine, and only build support for those. It is possible, if no database was installed on your machine\n at that time, that the database interface API is available (and your application compiles), but no connection can be done\n to database at run time.\n To connect to a DBMS, you need to specify the various connection parameters. This is done via a GNATCOLL.SQL.Exec.Database_Description object. The creation of this object depends on the specific DBMS you are\n connecting to (and this is the only part of your code that needs to know about the specific system). The packages\n GNATCOLL.SQL.Postgres and GNATCOLL.SQL.Sqlite contain a Setup function, whose parameters depend on the\n-DBMS. They provide full documentation for their parameters. Let\u2019s take a simple example from sqlite:\n+DBMS. They provide full documentation for their parameters. Let's take a simple example from sqlite:\n with GNATCOLL.SQL.Sqlite;\n -- or Postgres\n declare\n DB_Descr : GNATCOLL.SQL.Exec.Database_Description;\n begin\n DB_Descr := GNATCOLL.SQL.Sqlite.Setup (\"dbname.db\");\n end\n@@ -683,15 +682,15 @@\n Reset_Connection (DB);\n In all three cases, the resulting database connection needs to be freed when you no longer needed (which might be\n when your program terminates if you are using pools) to avoid memory leaks. Nothing critical will appear if you do\n not close, though, because the transactions to the DBMS server are saved every time you call Commit in any case. So\n the code would end with:\n Free (DB); -- for all connections you have opened\n Free (DB_Descr);\n-At this point, there still hasn\u2019t been any connection to the DBMS. This will be done the first time a query is executed.\n+At this point, there still hasn't been any connection to the DBMS. This will be done the first time a query is executed.\n If for some reason the connection to the DBMS server is lost, GNATColl will automatically attempt to reconnect a\n number of times before it gives up. This might break if there was an ongoing SQL transaction, but simplifies your code\n since you do not have to handle reconnection when there was a network failure, for instance.\n As we saw before, the database interface can be used in multi-tasking applications. In such a case, it is recommended\n that each thread has its own connection to the database, since that is more efficient and you do not have to handle\n locking. However, this assumes that the database server itself is thread safe, which most often is the case, but not for\n sqlite for instance. In such a case, you can only connect one per application to the database, and you will have to manage\n@@ -710,36 +709,36 @@\n \n Chapter 1. SQL: Database interface\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n shows one of the nice aspects of using a standard DBMS for your application: you can alter the database (for\n instance to do minor fixes in the data) with a lot of external tools that were developed specifically for that purpose\n-and that provide a nice interface. However, this is also tedious and error prone, and can\u2019t be repeat easily every\n+and that provide a nice interface. However, this is also tedious and error prone, and can't be repeat easily every\n time we recreate the database (for instance before running automatic tests).\n \u2022 Using GNATCOLL.SQL.EXEC\n As we will describe later, GNATColl contains all the required machinery for altering the contents of the database\n and creating new objects. Using GNATCOLL.SQL.ORM this can also be done at a high-level and completely\n hide SQL.\n \u2022 Loading a data file\n-A lot of frameworks call such a file that contains initial data a \u201cfixture\u201d. We will use this technique as an example.\n+A lot of frameworks call such a file that contains initial data a \"fixture\". We will use this technique as an example.\n At the Ada level, this is a simple call to GNATCOLL.SQL.Inspect.Load_Data. The package contains a lot more\n than just this subprogram (The gnatcoll_db2ada tool):\n declare\n File : GNATCOLL.VFS.Virtual_File := Create (\"fixture.txt\");\n DB : Database_Connection; -- created earlier\n begin\n GNATCOLL.SQL.Inspect.Load_Data (DB, File);\n DB.Commit;\n end;\n The format of this file is described just below.\n As we mentioned, GNATColl can load data from a file. The format of this file is similar to the one that describes the\n database schema. It is a set of ASCII tables, each of which describes the data that should go in a table (it is valid to\n duplicate tables). Each block starts with two lines: The first one has two mandatory columns, the first of which contains\n-the text \u201cTABLE\u201d, and the second contains the name of the table you want to fill. The second line should contain as\n+the text \"TABLE\", and the second contains the name of the table you want to fill. The second line should contain as\n many columns as there are fields you want to set. Not all the fields of the table need to have a corresponding column if\n you want to set their contents to NULL (provided, of course, that your schema allows it). For instance, we could add\n data for our library example as such:\n | TABLE | customers |\n |\n |\n id | first\n@@ -796,15 +795,15 @@\n 1 | &Smith\n |\n | The Dictator | Chaplin\n |\n 3 | &Dupont\n |\n Here, the title of the column indicates that any value in this column might be a reference to the customers.last value.\n-Values which start with an ampersand (\u201d&\u201d) will therefore be looked up in customers.last, and the id of the corresponding customer will be inserted in the dvds table. It would still be valid to use directly customer ids instead of references,\n+Values which start with an ampersand (\"&\") will therefore be looked up in customers.last, and the id of the corresponding customer will be inserted in the dvds table. It would still be valid to use directly customer ids instead of references,\n this is just an extra flexibility that the references give you to make your fixtures more readable.\n However, if we are using such references we need to provide the database schema to Load_Data so that it can write the\n proper queries. This is done by using other services of the GNATCOLL.SQL.Inspect package.\n The code for our example would be:\n Load_Data\n (DB, Create (\"fixture.txt\"),\n New_Schema_IO (Create (\"dbschema.txt\")).Read_Schema);\n@@ -829,28 +828,28 @@\n & Ticket_Priorities.Category,\n From\n => Ticket_Priorities,\n Where => Ticket_Priorities.Name /= \"low\",\n Group_By => Ticket_Priorities.Category);\n end;\n The above example will return, for each type of priority (internal or customer) the highest possible value. The interest\n-of this query is left to the user. . .\n+of this query is left to the user...\n This is very similar to an actual SQL query. Field and table names come from the package that was automatically\n generated by the gnatcoll_db2ada tool, and therefore we know that our query is only referencing existing fields. The\n syntactic correctness is ensured by standard Ada rules. The SQL_Select accepts several parameters corresponding to\n the usual SQL attributes like GROUP BY, HAVING, ORDER BY and LIMIT.\n \n 14\n \n Chapter 1. SQL: Database interface\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n The From parameter could be a list of tables if we need to join them in some ways. Such a list is created with the\n-overridden \u201c&\u201d operator, just as for fields which you can see in the above example. GNATColl also provides a Left_Join\n+overridden \"&\" operator, just as for fields which you can see in the above example. GNATColl also provides a Left_Join\n function to join two tables when the second might have no matching field (see the SQL documentation).\n Similar functions exist for SQL_Insert, SQL_Update and SQL_Delete. Each of those is extensively documented in the\n gnatcoll-sql.ads file.\n It is worth noting that we do not have to write the query all at once. In fact, we could build it depending on some other\n criteria. For instance, imagine we have a procedure that does the query above, and omits the priority specified as a\n parameter, or shows all priorities if the empty string is passed. Such a procedure could be written as:\n procedure List_Priorities (Omit : String := \"\") is\n@@ -874,16 +873,16 @@\n Auto_Complete (Q);\n This query is exactly the same as before. However, we did not have to specify the list of tables (which GNATColl\n can compute on its own by looking at all the fields referenced in the query), nor the list of fields in the GROUP BY\n clause, which once again can be computed automatically by looking at those fields that are not used in a SQL aggregate\n function. This auto-completion helps the maintenance of those queries.\n There is another case where GNATColl makes it somewhat easier to write the queries, and that is to handle joins\n between tables. If your schema was build with foreign keys, GNATColl can take advantage of those.\n-Going back to our library example, let\u2019s assume we want to find out all the books that were borrowed by the user\n-\u201cSmith\u201d. We need to involve two tables (Books and Customers), and provide a join between them so that the DBMS\n+Going back to our library example, let's assume we want to find out all the books that were borrowed by the user\n+\"Smith\". We need to involve two tables (Books and Customers), and provide a join between them so that the DBMS\n knows how to associate the rows from one with the rows from the other. Here is a first example for such a query:\n Q := SQL_Select\n (Fields => Books.Title & Books.Pages,\n From\n => Books & Customers,\n Where => Books.Borrowed_By = Customers.Id\n and Customers.Last = \"Smith\");\n@@ -898,15 +897,15 @@\n \n Q := SQL_Select\n (Fields => Books.Title & Books.Pages,\n Where => Books.Borrowed_By = Customers.Id\n and Customers.Last = \"Smith\");\n There is one more things we can do to simplify the query and make it more solid if the schema of the database changes.\n For instance, when a table has a primary key made up of several fields, we need to make sure we always have an\n-\u201c=\u201d statement in the WHERE clause for all these fields between the two tables. In our example above, we could at\n+\"=\" statement in the WHERE clause for all these fields between the two tables. In our example above, we could at\n some point modify the schema so that the primary key for customers is multiple (this is unlikely in this example of\n course). To avoid this potential problems and make the query somewhat easier to read, we can take advantage of the\n FK subprograms generated by gnatcoll_db2ada. Using the Ada05 dotted notation for the call, we can thus write:\n Q := SQL_Select\n (Fields => Books.Title & Books.Pages,\n Where => Books.FK (Customers)\n and Customers.Last = \"Smith\");\n@@ -924,15 +923,15 @@\n This reuses the connection we have established previously (DB) (although now we are indeed connecting to the DBMS\n for the first time) and sends it the query. The result of that query is then stored in R, to be used later.\n Some SQL commands execute code on the DBMS, but do not return a result. In this case, you can use Execute instead\n of Fetch. This is the case when you execute an INSERT or UPDATE statement for instance. Using Execute avoids the\n need to declare the local variable R.\n If for some reason the connection to the database is no longer valid (a transient network problem for instance), GNATColl will attempt to reconnect and re-execute your query transparently, so that your application does not need to handle\n this case.\n-We\u2019ll describe later (Getting results) how to analyze the result of the query.\n+We'll describe later (Getting results) how to analyze the result of the query.\n Some versions of Fetch have an extra parameter Use_Cache, set to False by default. If this parameter is true, and\n the exact same query has already been executed before, its result will be reused without even contacting the database\n server. The cache is automatically invalidated every hour in any case. This cache is mostly useful for tables that act\n like enumeration types, as we have seen before when discussing the -enum parameter to gnatcoll_db2ada. In this\n case, the contents of the table changes very rarely, and the cache can provide important speedups, whether the server is\n local or distant. However, we recommend that you do actual measurements to know whether this is indeed beneficial\n for you. You can always invalidate the current cache with a call to Invalidate_Cache to force the query to be done on\n@@ -997,15 +996,15 @@\n Q : constant SQL_Query :=\n SQL_Select\n (Fields => Data.Id & Data.Name\n From\n => Data,\n Where => Data.Id = Integer_Param (1));\n GNATColl provides a number of functions (one per type of field) to indicate that the value is currently unbound.\n-Integer_Param, Text_Param, Boolean_Param,. . . All take a single argument, which is the index of the corresponding\n+Integer_Param, Text_Param, Boolean_Param,... All take a single argument, which is the index of the corresponding\n parameter. A query might need several parameters, and each should have a different index. On the other hand, the same\n parameter could be used in several places in the query.\n Although the query above could be executed as is by providing the values for the parameters, it is more efficient, as\n we mentioned at the beginning, to compile it on the server. In theory, this preparation is done within the context of a\n database connection (thus cannot be done for a global variable, where we do not have connections yet, and where the\n query might be executed by any connection later on).\n GNATColl will let you indicate that the query should be prepared. This basically sets up some internal data, but does\n@@ -1016,39 +1015,39 @@\n P : constant Prepared_Statement :=\n Prepare (Q, On_Server => True);\n Two comments about this code:\n \u2022 You do not have to use global variables. You can prepare the statement locally in a subprogram. A Prepared_Statement is a reference counted type, that will automatically free the memory on the server when it\n goes out of scope.\n \u2022 Here, we prepared the statement on the server. If we had specified On_Server => False, we would still have\n sped things up, since Q would be converted to a string that can be sent to the DBMS, and from then on reused\n-that string (note that this conversion is specific to each DBMS, since they don\u2019t always represent things the same\n+that string (note that this conversion is specific to each DBMS, since they don't always represent things the same\n way, in particular parameters, as we have seen above). Thus every time you use P you save the time of converting\n from the GNATColl tree representation of the query to a string for the DBMS.\n Now that we have a prepared statement, we can simply execute it. If the statement does not require parameters, the\n usual Fetch and Execute subprograms have versions that work exactly the same with prepared statements. They also\n-accept a Params parameter that contains the parameter to pass to the server. A number of \u201c+\u201d operators are provided\n+accept a Params parameter that contains the parameter to pass to the server. A number of \"+\" operators are provided\n to create those parameters:\n declare\n F : Forward_Cursor;\n begin\n F.Fetch (DB, P, Params => (1 => +2));\n F.Fetch (DB, P, Params => (1 => +3));\n end;\n-Note that for string parameters, the \u201c+\u201d operator takes an access to a string. This is for efficiency, to avoid allocating\n+Note that for string parameters, the \"+\" operator takes an access to a string. This is for efficiency, to avoid allocating\n memory and copying the string, and is safe because the parameters are only needed while Fetch executes (even for a\n Forward_Cursor.\n Back to our library example. We showed earlier how to write a query that retrieves the books borrowed by customer\n \n 18\n \n Chapter 1. SQL: Database interface\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n-\u201cSmith\u201d. We will now make this query more general: given a customer name, return all the books he has borrowed.\n+\"Smith\". We will now make this query more general: given a customer name, return all the books he has borrowed.\n Since we expect to use this often, we will prepare it on the server (in real life, this query is of little interest since the\n customer name is not unique, we would instead use a query that takes the id of the customer). In general we would\n create a global variable with:\n Borrowed : constant Prepared_Statement := Prepare\n (SQL_Select\n (Fields => Books.Title & Books.Pages,\n Where => Books.FK (Customers)\n@@ -1102,15 +1101,15 @@\n it proves efficient, since only one row needs to be kept in memory at any point in time.\n For each row, we then call one of the Value or *Value functions which return the value in a specific row and a specific\n column.\n We mentioned earlier there was no way to go back to a row you fetched previously except by executing the query again.\n This is in fact only true if you use a Forward_Cursor to fetch the results.\n But GNATColl provides another notion, a Direct_Cursor. In this case, it fetches all the rows in memory when the\n query executes (thus it needs to allocate more memory to save every thing, which can be costly if the query is big).\n-This behavior is supported natively by PostgreSQL, but doesn\u2019t exist with sqlite, so GNATColl will simulate it as\n+This behavior is supported natively by PostgreSQL, but doesn't exist with sqlite, so GNATColl will simulate it as\n efficiently as possible. But it will almost always be faster to use a Forward_Cursor.\n In exchange for this extra memory overhead, you can now traverse the list of results in both directions, as well as access\n a specific row directly. It is also possible to know the number of rows that matched (something hard to do with a\n Forward_Cursor since you would need to traverse the list once to count, and then execute the query again if you need\n the rows themselves).\n Direct_Cursor, produced from prepared statements, could be indexed by the specified field value and routine Find could\n set the cursor position to the row with specified field value.:\n@@ -1184,31 +1183,31 @@\n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n 1.12 Query logs\n The GNATCOLL.Traces package provides facilities to add logging. The database interface uses this module to log the\n queries that are sent to the server.\n If you activate traces in your application, the user can then activate one of the following trace handles to get more\n information on the exchange that exists between the database and the application. As we saw before, the output of these\n-traces can be sent to the standard output, a file, the system logs,. . .\n+traces can be sent to the standard output, a file, the system logs,...\n The following handles are provided:\n \u2022 SQL.ERROR This stream is activated by default. Any error returned by the database (connection issues, failed\n-transactions,. . . ) will be logged on this stream\n+transactions,...) will be logged on this stream\n \u2022 SQL This stream logs all queries that are not SELECT queries, i.e. mostly all queries that actually modify the\n database\n \u2022 SQL.SELECT This stream logs all select queries. It is separated from SQL because very often you will be mostly\n interested in the queries that impact the database, and logging all selects can generate a lot of output.\n In our library example, we would add the following code to see all SQL statements executed on the server:\n with GNATCOLL.Traces; use GNATCOLL.Traces;\n procedure Main is\n begin\n GNATCOLL.Traces.Parse_Config_File (\".gnatdebug\");\n ... -- code as before\n GNATCOLL.Traces.Finalize; -- reclaim memory\n and then create a .gnatdebug in the directory from which we launch our executable. This file would contain a single\n-line containing \u201c+\u201d to activate all log streams, or the following to activate only the subset of fields related to SQL:\n+line containing \"+\" to activate all log streams, or the following to activate only the subset of fields related to SQL:\n SQL=yes\n SQL.SELECT=yes\n SQL.LITE=yes\n \n 1.13 Writing your own cursors\n The cursor interface we just saw is low-level, in that you get access to each of the fields one by one. Often, when you\n design your own application, it is better to abstract the database interface layer as much as possible. As a result, it is\n@@ -1233,15 +1232,15 @@\n (continued from previous page)\n \n function Element (Self : My_Cursor) return My_Row;\n function Do_Query (DB, ...) return My_Cursor;\n The idea is that you create a function that does the query for you (based on some parameters that are not shown here),\n and then returns a cursor over the resulting set of rows. For each row, you can use the Element function to get an Ada\n record for easier manipulation.\n-Let\u2019s first see how these types would be used in practice:\n+Let's first see how these types would be used in practice:\n declare\n C : My_Cursor := Do_Query (DB, ...);\n begin\n while Has_Row (C) loop\n Put_Line (\"Id = \" & Element (C).Id);\n Next (C);\n end loop;\n@@ -1306,15 +1305,15 @@\n override those two subprograms to return correct values.\n \n 1.14 The Object-Relational Mapping layer (ORM)\n GNATColl provides a high-level interface to manipulate persistent objects stored in a database, using a common\n paradigm called an object-relational mapping. Such mappings exist for most programming languages. In the design of\n GNATColl, we were especially inspired by the python interface in django and sqlalchemy, although the last two rely\n on dynamic run time introspection and GNATColl relies on code generation instead.\n-This API is still compatible with GNATCOLL.SQL. In fact, we\u2019ll show below cases where the two are mixed. It can also\n+This API is still compatible with GNATCOLL.SQL. In fact, we'll show below cases where the two are mixed. It can also\n be mixed with GNATCOLL.SQL.Exec, although this might be more risky. Communication with the DBMS is mostly\n transparent in the ORM, and it uses various caches to optimize things and make sure that if you modify an element the\n next query(ies) will also return it. If you use GNATCOLL.SQL.Exec directly you are bypassing this cache so you risk\n getting inconsistent results in some cases.\n In ORM, a table is not manipulated directly. Instead, you manipulate objects that are read or written to a table. When\n we defined our database schema (Database schema), we gave two names on the first line of a table definition. There\n was the name of the table in the database, and the name of the object that each row represent. So for our library example\n@@ -1331,15 +1330,15 @@\n |\n | 100 |\n |\n | borrowed_by\n | FK customers(borrowed_books) | NULL |\n | Who borrowed the media\n |\n-Let\u2019s thus start by generating this code. We can replace the command we ran earlier (with the -api switch) with one\n+Let's thus start by generating this code. We can replace the command we ran earlier (with the -api switch) with one\n that will also generate the ORM API:\n gnatcoll_db2ada -dbmode dbschema.txt -api Database -orm ORM\n \n 24\n \n Chapter 1. SQL: Database interface\n \n@@ -1352,43 +1351,43 @@\n usage and are only documented in gnatcoll-sql-sessions.ads. Here will we use only specify the mandatory\n parameters and leave the default value for the other parameters:\n GNATCOLL.SQL.Sessions.Setup\n (Descr => GNATCOLL.SQL.Sqlite.Setup (\"library.db\"),\n Max_Sessions => 2);\n The first parameter is the same Database_Description we saw earlier (Connecting to the database), but it will be freed\n automatically by the sessions package, so you should not free it yourself.\n-Once configure, we can now request a session. Through a session, we can perform queries on the database, make objects\n-persistent, write the changes back to the database,. . . . We configured the session pool to have at most 2 sessions. The\n-first time we call Get_New_Session, a new session will be created in the pool and marked as busy. While you have a\n+Once configure, we can now request a session. Through a session, we can perform queries on the database, make\n+objects persistent, write the changes back to the database,.... We configured the session pool to have at most 2 sessions.\n+The first time we call Get_New_Session, a new session will be created in the pool and marked as busy. While you have a\n reference to it in your code (generally as a local variable), the session belongs to this part of the code. When the session\n is no longer in scope, it is automatically released to the pool to be reused for the next call to Get_New_Session. If you\n call Get_New_Session a second time while some part of your code holds a session (for instance in a different task), a\n new session will be created. But if you do that a third time while the other two are busy, the call to Get_New_Session\n is blocking until one of the two sessions is released to the pool.\n This technique ensures optimal use of the resources: we avoid creating a new session every time (with the performance\n cost of connecting to the database), but also avoid creating an unlimited number of sessions which could saturate the\n server. Since the sessions are created lazily the first time they are needed, you can also configure the package with a\n large number of sessions with a limited cost.\n-Let\u2019s then take a new session in our code:\n+Let's then take a new session in our code:\n Session : constant Session_Type := Get_New_Session;\n-and let\u2019s immediately write our first simple query. A customer comes at the library, handles his card and we see his id\n+and let's immediately write our first simple query. A customer comes at the library, handles his card and we see his id\n (1). We need to look up in the database to find out who he is. Fortunately, there is no SQL to write for this:\n C : ORM.Detached_Customer'Class := Get_Customer (Session, Id => 1);\n The call to Get_Customer performs a SQL query transparently, using prepared statements for maximum efficiency.\n This results in a Customer object.\n ORM is the package that was generated automatically by gnatcoll_db2ada. For each table in the database, it generates\n a number of types:\n \u2022 Customer\n This type represents a row of the Customers table. It comes with a number of primitive operations, in particular\n one for each of the fields in the table. Such an object is returned by a cursor, similarly to what was described in\n the previous section (Writing your own cursors). This object is no longer valid as soon as the cursor moves to\n the next row (in the currently implementation, the object will describe the next row, but it is best not to rely on\n this). As a benefit, this object is light weight and does not make a copy of the value of the fields, only reference\n the memory that is already allocated for the cursor.\n-This object redefines the equality operator (\u201c=\u201d) to compare the primary key fields to get expected results.\n+This object redefines the equality operator (\"=\") to compare the primary key fields to get expected results.\n \u2022 Detached_Customer\n A detached object is very similar to the Customer object, but it will remain valid even if the cursor moves or\n is destroyed. In fact, the object has made a copy of the value for all of its fields. This object is heavier than a\n \n 1.14. The Object-Relational Mapping layer (ORM)\n \n 25\n@@ -1406,44 +1405,44 @@\n This type extends a Forward_Cursor (Getting results). In addition to the usual Has_Row and Next operations, it\n also provides an Element operation that returns a Customer for easy manipulation of the results.\n \u2022 Direct_Customer_List\n This type extends a Direct_Cursor. It also adds a Element operation that returns a Customer element.\n \u2022 Customers_Managers\n This type is the base type to perform queries on the DBMS. A manager provides a number of primitive operations\n which end up creating a SQL query operation in the background, without making that explicit.\n-Let\u2019s first write a query that returns all books in the database:\n+Let's first write a query that returns all books in the database:\n declare\n M : Books_Managers := All_Books;\n BL : Book_List := M.Get (Session);\n B : Book;\n begin\n while BL.Has_Row loop\n B := BL.Element;\n Put_Line (\"Book: \" & B.Title);\n Put_Line (\"\n Borrowed by: \" & B.Borrowed_By.Last);\n BL.Next;\n end loop;\n end;\n The manager M corresponds to a query that returns all the books in the database. The second line then executes\n-the query on the database, and returns a list of books. We then traverse the list. Note how we access the book\u2019s\n+the query on the database, and returns a list of books. We then traverse the list. Note how we access the book's\n title by calling a function, rather than by the index of a field as we did with GNATCOLL.SQL.Exec with Value(B,\n 0). The code is much less fragile this way.\n The line that calls Borrowed_By will execute an additional SQL query for each book. This might be inefficient\n if there is a large number of books. We will show later how this can be optimized.\n The manager however has a lot more primitive operations that can be used to alter the result. Each of these\n primitive operations returns a modified copy of the manager, so that you can easily chain calls to those primitive\n operations. Those operations are all declared in the package GNATCOLL.SQL.ORM.Impl if you want to look at\n the documentation. Here are those operations:\n \u2013 Get and Get_Direct\n As seen in the example above, these are the two functions that execute the query on the database, and returns\n a list of objects (respectively a Customer_List and a Direct_Customer_List).\n \u2013 Distinct\n Returns a copy of the manager that does not return twice a row with the same data (in SQL, this is the\n-\u201cDISTINCT\u201d operator)\n+\"DISTINCT\" operator)\n \n 26\n \n Chapter 1. SQL: Database interface\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n@@ -1459,15 +1458,15 @@\n by Alexandre Dumas by using:\n M : Books_Managers := All_Books.Filter (Author => \"Dumas\");\n This version only provides the equality operator for the fields of the table itself. If for instance we wanted\n all books with less than 50 pages, we would use the second version of filter. This version takes a GNATCOLL.SQL.SQL_Criteria similar to what was explained in previous sections, and we would write:\n M : Books_Managers := All_Books.Filter (Condition => Books.Pages < 50);\n More complex conditions are possible, involving other tables. Currently, the ORM does not have a very\n user-friendly interface for those, but you can always do this by falling back partially to SQL. For instance,\n-if we want to retrieve all the books borrowed by user \u201cSmith\u201d, we need to involve the Customers table, and\n+if we want to retrieve all the books borrowed by user \"Smith\", we need to involve the Customers table, and\n thus make a join with the Books table. In the future, we intend to make this join automatic, but for now you\n will need to write:\n M : Books_Managers := All_Books.Filter\n (Books.FK (Customers)\n and Customers.Last = \"Smith\");\n -- SQL query: SELECT books.pages, books.borrowed_by, books.id,\n -books.title, books.author, books.published\n@@ -1491,15 +1490,15 @@\n \n 27\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n The second parameter related to efficiency. When a foreign key was mentioned as NOT NULL in the schema,\n we know it is always pointing to an existing object in another table. Select_Related will always retrieve\n-such objects. If, however, the foreign key can be null, i.e. there isn\u2019t necessarily a corresponding object in\n+such objects. If, however, the foreign key can be null, i.e. there isn't necessarily a corresponding object in\n the other table, the SQL query needs to use a LEFT JOIN, which is less efficient. By default, GNATColl\n will not retrieve such fields unless Follow_Left_Join was set to True.\n In our example, a book is not necessarily borrowed by a customer, so we need to follow the left joins:\n M : Books_Managers := All_Books.Filter\n (Books.FK (Customers)\n and Customers.Last = \"Smith\")\n .Select_Related (1, Follow_Left_Join => True);\n@@ -1516,17 +1515,17 @@\n BL := C.Borrowed_Books.Get (Session);\n -- SQL: SELECT books.pages, books.borrowed_by, books.id, books.title,\n -books.author, books.published FROM books\n -WHERE books.borrowed_by=1\n Borrowed_Books is a function that was generated because there was a reverse_name. It returns a Books_Managers, so\n we could in fact further filter the list of borrowed books with the same primitive operations we just saw. As you can\n see, the resulting SQL is optimal.\n-Let\u2019s optimize further the initial query. We have hard-coded the customer name, but in fact we could be using the same\n+Let's optimize further the initial query. We have hard-coded the customer name, but in fact we could be using the same\n subprograms we were using for prepared statements (Prepared queries), and even prepare the query on the server for\n-maximum efficiency. Since our application is likely to use this query a lot, let\u2019s create a global variable:\n+maximum efficiency. Since our application is likely to use this query a lot, let's create a global variable:\n M : constant Books_Managers := All_Books.Filter\n (Books.FK (Customers)\n and Customers.Id = Integer_Param (1))\n .Select_Related (1, Follow_Left_Join => True);\n MP : constant ORM_Prepared_Statement :=\n M.Prepare (On_Server => True);\n ... later in the code\n@@ -1540,15 +1539,15 @@\n Chapter 1. SQL: Database interface\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n 1.15 Modifying objects in the ORM\n The ORM is much more than writing queries. Once the objects are persistent, they can also be simplify modified, and\n they will be saved in the database transparently.\n-Let\u2019s start with a simple example. In the previous section, we retrieve an object C representing a customer. Let\u2019s change\n+Let's start with a simple example. In the previous section, we retrieve an object C representing a customer. Let's change\n his name, and make sure the change is in the database:\n C := Get_Customer (Session, 1);\n C.Set_Last (\"Smith\");\n C.Set_First (\"Andrew\");\n Session.Commit;\n A reasonable way to modify the database. However, this opens a can of complex issues that need to be dealt with.\n When we called Set_Last, this modify the objects in memory. At this point, printing the value of C.Last would indeed\n@@ -1591,40 +1590,40 @@\n \n (continued from previous page)\n \n while CL.Has_Row loop\n Put_Line (CL.Element.Last);\n CL.Next;\n end loop;\n-The above example uses CL.Element, which is a light-weight Customer object. Such objects will only see the inmemory changes if you have set Flush_Before_Query to true when you configured the sessions in the call to GNATCOLL.SQL.Sessions.Setup. Otherwise, it will always return what\u2019s really in the database.\n+The above example uses CL.Element, which is a light-weight Customer object. Such objects will only see the inmemory changes if you have set Flush_Before_Query to true when you configured the sessions in the call to GNATCOLL.SQL.Sessions.Setup. Otherwise, it will always return what's really in the database.\n If the example was using Detached_Customer object (by calling CL.Element.Detach for instance) then GNATColl looks\n up in its internal cache and returns the cached element when possible. This is a subtlety, but this is because an Customer\n only exists as long as its cursor, and therefore cannot be cached in the session. In practice, the Flush_Before_Query\n should almost always be true and there will be not surprising results.\n \n 1.16 Object factories in ORM\n Often, a database table is used to contain objects that are semantically of a different kind. In this section, we will take\n a slightly different example from the library. We no longer store the books and the dvds in separate tables. Instead, we\n have one single media table which contains the title and the author, as well as a new field kind which is either 0 for a\n book or 1 for a dvd.\n-Let\u2019s now look at all the media borrowed by a customer:\n+Let's now look at all the media borrowed by a customer:\n C : constant Customer'Class := Get_Customer (Session, Id => 1);\n ML : Media_List := C.Borrowed_Media.Get (Session);\n while ML.Has_Row loop\n case ML.Element.Kind is\n when 0 =>\n Put_Line (\"A book \" & ML.Element.Title);\n when 1 =>\n Put_Line (\"A dvd \" & ML.Element.Title);\n end case;\n ML.Next;\n end loop;\n-This code works, but requires a case statement. Now, let\u2019s imagine the check out procedure is different for a book\n+This code works, but requires a case statement. Now, let's imagine the check out procedure is different for a book\n and a DVD (for the latter we need to check that the disk is indeed in the box). We would have two subprograms\n-Checkout_Book and Checkout_DVD and call them from the case. This isn\u2019t object-oriented programming.\n+Checkout_Book and Checkout_DVD and call them from the case. This isn't object-oriented programming.\n Instead, we will declare two new types:\n type My_Media is abstract new ORM.Detached_Media with private;\n procedure Checkout (Self : My_Media) is abstract;\n type Detached_Book is new My_Media with private;\n overriding Checkout (Self : Detached_Book);\n type Detached_DVD is new My_Media with private;\n overriding Checkout (Self : Detached_DVD);\n@@ -1634,16 +1633,16 @@\n \n Chapter 1. SQL: Database interface\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n We will instead use an element factory in the session. This is a function that gets a row of a table (in the form of\n a Customer), and returns the appropriate type to use when the element is detached (by default, the detached type\n-corresponding to a Customer is a Detached_Customer, and that\u2019s what we want to change).\n-So let\u2019s create such a factory:\n+corresponding to a Customer is a Detached_Customer, and that's what we want to change).\n+So let's create such a factory:\n function Media_Factory\n (From\n : Base_Element'Class;\n Default : Detached_Element'Class) return Detached_Element'Class\n is\n begin\n if From in Media'Class then\n@@ -1700,17 +1699,17 @@\n \n When manipulating source code, programmers needs to know where the various symbols are defined, where they are\n used, and so on. This is generally available directly from their IDE and editors. But computing this information in the\n first place is tricky, especially for languages that support overloading of subprograms.\n Some compilers like GNAT and gcc can generate this information for Ada code bases. For instance, GNAT will generate\n .ali files, which contain the navigation information, when compiling Ada or SPARK code.\n GNATCOLL.Xref can then be used to parse and aggregate all those files into a single sqlite database, which can be\n-conveniently used to answer queries such as \u201cgive me the declaration for this entity\u201d, \u201clist all places where this entity is\n-used\u201d, \u201cshow all subprograms that could be called in practice at this dispatching call\u201d, \u201cwhat files does this file depend\n-on\u201d, \u201cshow me the call graph for this application\u201d,. . .\n+conveniently used to answer queries such as \"give me the declaration for this entity\", \"list all places where this entity is\n+used\", \"show all subprograms that could be called in practice at this dispatching call\", \"what files does this file depend\n+on\", \"show me the call graph for this application\",...\n To use this package, some initialization needs to be performed first:\n with GNATCOLL.Xref;\n use GNATCOLL.Xref;\n with GNATCOLL.SQL.Sqlite;\n with GNATCOLL.Projects; use GNATCOLL.Projects;\n with GNATCOLL.VFS;\n use GNATCOLL.VFS;\n@@ -1733,15 +1732,15 @@\n Free (Error);\n Parse_All_LI_Files (DB, Tree.Root_Project);\n -- 4\n end Support;\n GNATCOLL needs to be able to find the *li files. For this, it depends on project files (as supported by GNATCOLL.\n Projects). So the first thing to do is to parse the project (step 2).\n We then need to tell GNATCOLL where the cross-reference information need to be aggregated. In this example, it\n-will be stored in a sqlite database on the disk. By using a name \u201c:memory:\u201d instead, we would create a temporary\n+will be stored in a sqlite database on the disk. By using a name \":memory:\" instead, we would create a temporary\n in-memory database. This is in general faster, but uses more memory and needs to be recreated every time the program\n is restarted. We could also decide to store the information in any other database supported by GNATCOLL.SQL.Exec,\n for instance PostgreSQL.\n \n 33\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n@@ -1790,18 +1789,18 @@\n This example will print all the references to the entity that is referenced in file source.ads at line 2 (the column is\n unspecified).\n Step 5 gets a handle on the source file. Here, we depend on the project to find the precise directory in which the source\n file is located. We can of course use an absolute file name instead.\n Step 6 gets handle on the entity referenced on line 2 in this file. Such an entity is the starting point for most queries\n defined in GNATCOLL.Xref.\n Finally, on step 7 and the loop below we iterate over all references, and print their location on the standard output.\n-Let\u2019s do a much more complex query: we want to see all references to that entity, but also places where the entity might\n+Let's do a much more complex query: we want to see all references to that entity, but also places where the entity might\n be called through a renames statement, or called through a dispatching call via an overriding method defined on a child\n tagged type (assuming this is a primitive operation of a tagged type in the first place). We also want to see all locations\n-where a method that overrides \u201cMethod\u201d is called:\n+where a method that overrides \"Method\" is called:\n declare\n Refs : Recursive_References_Cursor;\n begin\n DB.Recursive (Entity, GNATCOLL.Xref.References'Access,\n From_Overriding => True, From_Overridden => True,\n From_Renames => True);\n while Refs.Has_Element loop\n@@ -1817,15 +1816,15 @@\n (continued from previous page)\n \n Refs.Next;\n end loop;\n end;\n As shown above, the programing pattern is always the same.\n GNATCOLL.Xref provides many more subprogram to get information like the list of fields for a record type (or a C\n-structure), the list of primitive operations or methods for a tagged object or a class, the call graph for a subprogram,. . .\n+structure), the list of primitive operations or methods for a tagged object or a class, the call graph for a subprogram,...\n It is also able to extract documentation for an entity from the source code, by looking at the lines of code just before or\n just after the declaration or the body of the entity.\n \n 35\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n@@ -1845,46 +1844,46 @@\n You can of course access the sqlite database directly. Most programming languages have an interface to sqlite. For\n instance python does.\n But GNATCOLL provides a command line tool dedicated to that purpose, named gnatinspect.\n When it is first started on a project, this tool will refresh the xref database by parsing all the ALI files from the project.\n This might take a while (up to several minutes) the first time, unless of course the xref were already up-to-date because\n you had loaded the project in GPS first, or already run gnatinspect.\n gnatinspect then displays an interactive prompt that lets you perform various queries on the database. The full list of\n-queries is available by typing \u201chelp\u201d at the prompt, but this documentation will demonstrate some of them.\n-Let\u2019s first look at a number of command line switches that might be useful:\n-\u2022 \u2013db=ARG: this switch can be used to specify the name of the database.\n-By default, gnatinspect checks in the project whether there exists an attribute IDE\u2019Xref_Database, which should\n-specify a file name (relative to the project\u2019s object_dir) for the database.\n-If this attribute does not exist, it defaults to \u201cgnatinspect.db\u201d in the project\u2019s object directory.\n-If there is no object directory defined in the project, the file is created in the project\u2019s directory itself. You can\n-however specify any name, including an absolute path, or a path relative to the project\u2019s object directory.\n-An alternative is to specify \u2018:memory:\u2019, which creates the database in memory. This is of course a temporary\n+queries is available by typing \"help\" at the prompt, but this documentation will demonstrate some of them.\n+Let's first look at a number of command line switches that might be useful:\n+\u2022 --db=ARG: this switch can be used to specify the name of the database.\n+By default, gnatinspect checks in the project whether there exists an attribute IDE'Xref_Database, which should\n+specify a file name (relative to the project's object_dir) for the database.\n+If this attribute does not exist, it defaults to \"gnatinspect.db\" in the project's object directory.\n+If there is no object directory defined in the project, the file is created in the project's directory itself. You can\n+however specify any name, including an absolute path, or a path relative to the project's object directory.\n+An alternative is to specify ':memory:', which creates the database in memory. This is of course a temporary\n database which will disappear when gnatinspect exits, and cannot be shared with other tools.\n-\u2022 \u2013nightlydb=ARG: this switch can help speed up the initial startup of gnatinspect. The idea is that in a lot of\n+\u2022 --nightlydb=ARG: this switch can help speed up the initial startup of gnatinspect. The idea is that in a lot of\n cases, the software on which a team works is build nightly in a common setup. Running gnatinspect in that setup\n will create or update an xref database. Individual developers can then create their own copy of the database\n-by starting from the contents of the nightly database (which is pointed to by the \u2013nightlydb switch), and then\n-gnatinspect will parse the ALI files in the user\u2019s setup that are different from the nightly ones.\n-\u2022 \u2013runtime: by default, gnatinspect will only parse the ALI files from your project (and of course the ones from\n+by starting from the contents of the nightly database (which is pointed to by the --nightlydb switch), and then\n+gnatinspect will parse the ALI files in the user's setup that are different from the nightly ones.\n+\u2022 --runtime: by default, gnatinspect will only parse the ALI files from your project (and of course the ones from\n imported projects). It will not however parse the ALI files found in predefined directories, like for instance the\n GNAT runtime. This saves time in general. If you click on a call to one of the runtime subprograms in your\n own code, gnatinspect will be able to point you to its declaration. However, you will not have access to the body,\n because the link from declaration to body is found in the ALI files of the runtime.\n-\u2022 \u2013command=ARG: gnatinspect will update the xref database as usual, then execute a command, display its result,\n+\u2022 --command=ARG: gnatinspect will update the xref database as usual, then execute a command, display its result,\n and exit. This can be convenient when calling gnatinspect from another tool, like Emacs or vi.\n \n 37\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n-\u2022 \u2013file=ARG: similar to \u2013command, but reads the commands to execute from a file. The file can contain comments\n-(starting with \u2018\u2013\u2019. See also the \u2013lead switch.\n-\u2022 \u2013lang=LANG:SPEC:BODY:OBJ: specifies a naming scheme for a language. The preferred approach is to use a\n-configuration project file (such as those generated by gprconfig for instance), that would define attributes such as\n-Naming\u2019Spec_Suffix, Naming\u2019Body_Suffix and Compiler\u2019Object_File_Suffix. However, this switch provides an\n+\u2022 --file=ARG: similar to --command, but reads the commands to execute from a file. The file can contain comments\n+(starting with '--'. See also the --lead switch.\n+\u2022 --lang=LANG:SPEC:BODY:OBJ: specifies a naming scheme for a language. The preferred approach is to use\n+a configuration project file (such as those generated by gprconfig for instance), that would define attributes such\n+as Naming'Spec_Suffix, Naming'Body_Suffix and Compiler'Object_File_Suffix. However, this switch provides an\n alternative whereby you can specify the same values directly on the command line. For instance, the equivalent\n of:\n configuration project Autoconf is\n package Naming is\n for Spec_Suffix (\"MyLang\") use \".myl\";\n end Naming;\n package Compiler is\n@@ -1895,29 +1894,29 @@\n --lang=MyLang:.myl::.ali\n A third alternative is to have the same contents as the configuration project file above, directly in your own project\n file. This has the same effect, but needs to be duplicated in each of your project file.\n Given one of the above, and assuming your project file includes:\n for Languages use (\"Ada\", \"MyLang\");\n then any file with the .myl extension will be correctly detected by the project manager, and any .ali file with\n the same base name will be parsed by gnatinspect to find cross-reference information. Remember that the switch\n-\u2013config=autoconf.cgpr must be passed to gnatinspect if the information is provided via a config project file.\n-\u2022 \u2013lead=ARG should be used in coordination with \u2013file, and specify lines to ignore from the file. All lines starting\n+--config=autoconf.cgpr must be passed to gnatinspect if the information is provided via a config project file.\n+\u2022 --lead=ARG should be used in coordination with --file, and specify lines to ignore from the file. All lines starting\n with the given prefix will be ignored.\n-\u2022 \u2013basenames: controls the display of file names in the output. By default, gnatinspect outputs full path information.\n-\u2022 \u2013exit: if this switch is specified, gnatinspect updates the xref database and exits immediately.\n-\u2022 \u2013project=ARG or -P ARG specifies the name of the project to load. This switch is mandatory.\n+\u2022 --basenames: controls the display of file names in the output. By default, gnatinspect outputs full path information.\n+\u2022 --exit: if this switch is specified, gnatinspect updates the xref database and exits immediately.\n+\u2022 --project=ARG or -P ARG specifies the name of the project to load. This switch is mandatory.\n \u2022 -X VAR=VALUE is used to specify the value of scenario variables used in your project. This is similar to the\n homonym switch in gprbuild.\n-\u2022 \u2013symlinks should be specified if your project uses symbolic links for files. This will ensure that the links are fully\n+\u2022 --symlinks should be specified if your project uses symbolic links for files. This will ensure that the links are fully\n resolved as stored in the database, and thus that when a file is visible through different links, the information is\n appropriately coalesced in the database for that file.\n-\u2022 \u2013subdirs=ARG is similar to the homonym switch in gprbuild\n-\u2022 \u2013tracefile=ARG is used to point to a file compatible with GNATCOLL.Traces that controls the debug information\n-generated by gnatinspect. By default, gnatinspect parses a file called \u2018.gnatdebug\u2019 in the current directory.\n-\u2022 \u2013encoding=ARG is the character encoding used for source and ALI files. By default, gnatinspect assumes they\n+\u2022 --subdirs=ARG is similar to the homonym switch in gprbuild\n+\u2022 --tracefile=ARG is used to point to a file compatible with GNATCOLL.Traces that controls the debug information\n+generated by gnatinspect. By default, gnatinspect parses a file called '.gnatdebug' in the current directory.\n+\u2022 --encoding=ARG is the character encoding used for source and ALI files. By default, gnatinspect assumes they\n are encoded in UTF-8.\n Once it has finished parsing the xref information, gnatinspect displays an interactive prompt, where a number of commands can be used to perform queries. In a lot of cases, these commands take some file information as argument (either\n just the file, or an entity name and the file in which it is defined).\n 38\n \n Chapter 3. Xref: gnatinspect\n \n@@ -1925,15 +1924,15 @@\n \n The file names can be given as either a base name, or relative to the current directory, or even a full name. But file\n names are ambiguous (even when a full path is specified) when aggregate projects are used. It is valid for a given file\n to be part of multiple aggregate projects, and depending on the project we are considering the result of the xref queries\n might vary).\n To remove the ambiguity, it is possible to specify the project to which the file belongs. The project is specified either\n as a project name (which itself could be ambiguous with aggregate projects), or as a full path.\n-In all commands below, whenever the parameter specifies \u201c:file\u201d, you can use instead \u201c:file:project\u201d if there are ambiguities. It is also possible not to specify the file, in which case the entity will be looked for in all sources of the\n+In all commands below, whenever the parameter specifies \":file\", you can use instead \":file:project\" if there are ambiguities. It is also possible not to specify the file, in which case the entity will be looked for in all sources of the\n project.\n Here is the full list of commands supported by gnatinspect:\n \u2022 decl name:file:line:column is probably the most useful command. Given a reference to an entity, it will indicate\n where the entity is declared. The line and column informations are optional:\n >>> decl Func:file.adb:12\n Func:/some/path/file2.adb:20:9\n \u2022 body name:file:line:column is similar to decl, but will return the location of the body of the entity. When the\n@@ -1958,15 +1957,15 @@\n from which it derives. See also child_types.\n \u2022 methods name:file:line:column returns the list of methods (or primitive operations) for the entity.\n \u2022 method_of name:file:line:column returns the class or tagged type for which the entity is a method.\n \u2022 calls name:file:line:column lists all entities called by the entity. This includes all entities defined within the\n scope of the entity (so for a subprogram this will be the list of local variables, but for a package this includes all\n subprograms and nested packages defined within that package).\n \u2022 callers name:file:line:column lists all entities that call the entity. This information is also available from a call\n-to \u2018refs\u2019, but \u2018callers\u2019 return the callers directly, instead of references to the original entity.\n+to 'refs', but 'callers' return the callers directly, instead of references to the original entity.\n 39\n \n \fGNATCOLL Documentation - Database packages, Release 0.0\n \n \u2022 overrides name:file:line:column returns the entity that is overridden by the entity (generally a method from a\n parent class).\n \u2022 overridden name:file:line:column returns the list of entities that override the parameter (generally methods from\n@@ -1984,15 +1983,15 @@\n \u2022 importing filename lists the files that import the file (via with statements in Ada or #include in C for instance)\n \u2022 imports filename lists the files that the file imports (via with statements in Ada or #include in C for instance). See\n also depends_on.\n \u2022 depends filename lists the files that the file depends on (recursively calling imports)\n \u2022 entities file lists all entities referenced or declared in the file.\n Finally, some commands are not related to entities or source files:\n \u2022 refresh refreshes the contents of the xref database, by parsing all ALI files that have been changed.\n-\u2022 shell Execute a shell command (an alternative is to use \u2018!\u2019 as the command).\n+\u2022 shell Execute a shell command (an alternative is to use '!' as the command).\n \u2022 scenario VARIABLE VALUE changes the value of a scenario variable, and reparse the project.\n \u2022 time command arguments executes the command as usual, and report the time it took to execute it.\n \n 40\n \n Chapter 3. Xref: gnatinspect\n \n"}]}]}, {"source1": "./usr/share/doc/libgnatcoll-db-doc/html/index.html", "source2": "./usr/share/doc/libgnatcoll-db-doc/html/index.html", "unified_diff": "@@ -79,15 +79,15 @@\n
  • 1. SQL: Database interface
      \n
    • 1.1. Database Abstraction Layers
      • \n
    • 1.2. Database example
      • \n
    • 1.3. Database schema
      • \n
    • 1.4. The gnatcoll_db2ada tool\n
      • \n
    • 1.5. Connecting to the database
      • \n
    • 1.6. Loading initial data in the database
      • \n
    • 1.7. Writing queries
      • \n
    • 1.8. Executing queries
      • \n
    • 1.9. Prepared queries
      • \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -11,15 +11,15 @@\n * _\b1_\b._\b _\bS\bS_\bQ\bQ_\bL\bL_\b:_\b _\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be\n o _\b1_\b._\b1_\b._\b _\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bA_\bb_\bs_\bt_\br_\ba_\bc_\bt_\bi_\bo_\bn_\b _\bL_\ba_\by_\be_\br_\bs\n o _\b1_\b._\b2_\b._\b _\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\be_\bx_\ba_\bm_\bp_\bl_\be\n o _\b1_\b._\b3_\b._\b _\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bs_\bc_\bh_\be_\bm_\ba\n o _\b1_\b._\b4_\b._\b _\bT_\bh_\be_\b _\bg_\bn_\ba_\bt_\bc_\bo_\bl_\bl_\b__\bd_\bb_\b2_\ba_\bd_\ba_\b _\bt_\bo_\bo_\bl\n # _\b1_\b._\b4_\b._\b1_\b._\b _\bD_\be_\bf_\ba_\bu_\bl_\bt_\b _\bo_\bu_\bt_\bp_\bu_\bt_\b _\bo_\bf_\b _\bg_\bn_\ba_\bt_\bc_\bo_\bl_\bl_\b__\bd_\bb_\b2_\ba_\bd_\ba\n # _\b1_\b._\b4_\b._\b2_\b._\b _\bd_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bi_\bn_\bt_\br_\bo_\bs_\bp_\be_\bc_\bt_\bi_\bo_\bn_\b _\bi_\bn_\b _\bA_\bd_\ba\n- # _\b1_\b._\b4_\b._\b3_\b._\b _\bB_\ba_\bc_\bk_\b _\bt_\bo_\b _\bt_\bh_\be_\b _\bl_\bi_\bb_\br_\ba_\br_\by_\b _\be_\bx_\ba_\bm_\bp_\bl_\be_\b\u2026\n+ # _\b1_\b._\b4_\b._\b3_\b._\b _\bB_\ba_\bc_\bk_\b _\bt_\bo_\b _\bt_\bh_\be_\b _\bl_\bi_\bb_\br_\ba_\br_\by_\b _\be_\bx_\ba_\bm_\bp_\bl_\be_\b._\b._\b.\n o _\b1_\b._\b5_\b._\b _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bn_\bg_\b _\bt_\bo_\b _\bt_\bh_\be_\b _\bd_\ba_\bt_\ba_\bb_\ba_\bs_\be\n o _\b1_\b._\b6_\b._\b _\bL_\bo_\ba_\bd_\bi_\bn_\bg_\b _\bi_\bn_\bi_\bt_\bi_\ba_\bl_\b _\bd_\ba_\bt_\ba_\b _\bi_\bn_\b _\bt_\bh_\be_\b _\bd_\ba_\bt_\ba_\bb_\ba_\bs_\be\n o _\b1_\b._\b7_\b._\b _\bW_\br_\bi_\bt_\bi_\bn_\bg_\b _\bq_\bu_\be_\br_\bi_\be_\bs\n o _\b1_\b._\b8_\b._\b _\bE_\bx_\be_\bc_\bu_\bt_\bi_\bn_\bg_\b _\bq_\bu_\be_\br_\bi_\be_\bs\n o _\b1_\b._\b9_\b._\b _\bP_\br_\be_\bp_\ba_\br_\be_\bd_\b _\bq_\bu_\be_\br_\bi_\be_\bs\n o _\b1_\b._\b1_\b0_\b._\b _\bG_\be_\bt_\bt_\bi_\bn_\bg_\b _\br_\be_\bs_\bu_\bl_\bt_\bs\n o _\b1_\b._\b1_\b1_\b._\b _\bC_\br_\be_\ba_\bt_\bi_\bn_\bg_\b _\by_\bo_\bu_\br_\b _\bo_\bw_\bn_\b _\bS_\bQ_\bL_\b _\bt_\by_\bp_\be_\bs\n"}]}, {"source1": "./usr/share/doc/libgnatcoll-db-doc/html/searchindex.js", "source2": "./usr/share/doc/libgnatcoll-db-doc/html/searchindex.js", "unified_diff": null, "details": [{"source1": "js-beautify {}", "source2": "js-beautify {}", "unified_diff": "@@ -1485,15 +1485,15 @@\n ],\n \"Default output of gnatcoll_db2ada\": [\n [1, \"default-output-of-gnatcoll-db2ada\"]\n ],\n \"database introspection in Ada\": [\n [1, \"database-introspection-in-ada\"]\n ],\n- \"Back to the library example\\u2026\": [\n+ \"Back to the library example...\": [\n [1, \"back-to-the-library-example\"]\n ],\n \"Connecting to the database\": [\n [1, \"connecting-to-the-database\"]\n ],\n \"Loading initial data in the database\": [\n [1, \"loading-initial-data-in-the-database\"]\n"}]}, {"source1": "./usr/share/doc/libgnatcoll-db-doc/html/sql.html", "source2": "./usr/share/doc/libgnatcoll-db-doc/html/sql.html", "unified_diff": "@@ -48,15 +48,15 @@\n
    • 1. SQL: Database interface\n

      Traditionally, writing the SQL queries is done inline: special markers\n are inserted into your code to delimit sections that contain SQL code (as\n opposed to Ada code), and these are then preprocessed to generate actual\n-code. This isn\u2019t the approach chosen in GNATColl: there are\n+code. This isn't the approach chosen in GNATColl: there are\n several drawbacks, in particular your code is no longer Ada and various\n tools will choke on it.

      \n

      The other usual approach is to write the queries as strings, which are\n passed, via a DBMS-specific API, to the DBMS server. This approach is\n very fragile:

      \n
        \n

      • The string might not contain well-formed SQL. This will\n unfortunately only be detected at run time when the DBMS complains.

        • \n

      • This is not type safe. You might be comparing a text field\n with an integer, for instance. In some cases, the DBMS will accept that\n-(sqlite for instance), but in some other cases it won\u2019t (PostgreSQL). The\n+(sqlite for instance), but in some other cases it won't (PostgreSQL). The\n result might then either raise an error, or return an empty list.

        • \n

      • There is a risk of SQL injection. Assuming the string is\n-constructed dynamically (using Ada\u2019s & operator), it might be easy\n+constructed dynamically (using Ada's & operator), it might be easy\n for a user to pass a string that breaks the query, and even destroys\n things in the database.

        • \n

      • As discussed previously, the SQL code might not be portable\n across DBMS. For instance, creating an automatically increment integer\n primary key in a table is DBMS specific.

        • \n

      • The string is fragile if the database schema changes. Finding\n whether a schema change impacts any of the queries requires looking at\n@@ -230,15 +230,15 @@\n \n

        \n

        1.2. Database example\uf0c1

        \n

        This section describes an example that will be extended throughout this\n chapter. We will build an application that represents a library. Such\n a library contains various media (books and DVDs for instance), and\n customers. A customer can borrow multiple media at the same time, but a\n-media is either at a customer\u2019s, or still in the library.

        \n+media is either at a customer's, or still in the library.

        \n

        The GNATColl distribution includes an example directory which\n contains all the code and data for this example.

        \n
        \n
        \n

        1.3. Database schema\uf0c1

        \n

        As was mentioned earlier (Database Abstraction Layers),\n GNATColl relies on automatic code generation to provide a type\n@@ -249,15 +249,15 @@\n

        This tool is able to output various kind of information, and will be fully\n described later (The gnatcoll_db2ada tool). However, the input\n is always the same: this is the schema of your database, that is the list\n of tables and fields that make up your database. There exist two ways to\n provide that information:

        \n
          \n

        • From a running database

          \n-

          If you pass the DBMS vendor (postgresql, sqlite,\u2026) and the connection\n+

          If you pass the DBMS vendor (postgresql, sqlite,...) and the connection\n parameters to gnatcoll_db2ada, it is able to query the schema on\n its own. However, this should not be the preferred method: this is similar\n to reverse engineering assembly code into the original high-level code, and\n some semantic information will be missing. For instance, in SQL\n we have to create tables just to represent the many-to-many relationships.\n These extra tables are part of the implementation of the schema, but are\n just noise when it comes to the semantics of the schema. For this reason,\n@@ -270,101 +270,101 @@\n provides additional capabilities that do not exist when reverse-engineering\n an existing database, for instance the ability to use name to represent\n reverse relationships for foreign keys (see below and the ORM).

          \n

          The most convenient editor for this file is Emacs, using the org-mode\n which provides convenient key shortcuts for editing the contents of ASCII\n tables. But any text editor will do, and you do not need to align the columns\n in this file.

          \n-

          All lines starting with a hash sign (\u2018#\u2019) will be ignored.

          \n+

          All lines starting with a hash sign ('#') will be ignored.

          \n

          This file is a collection of ASCII tables, each of which relates to one table\n or one SQL view in your database. The paragraphs start with a line\n containing:

          \n 
          table ::=\n    '|' ('ABSTRACT')? ('TABLE'|'VIEW') ['(' supertable ')']\n    '|' <name> '|' <name_row>\n
          \n
          \n-

          \u201cname\u201d is the name of the table. The third pipe and third column are optional,\n+

          "name" is the name of the table. The third pipe and third column are optional,\n and should be used to specify the name for the element represented by a single\n-row. For instance, if the table is called \u201cbooks\u201d, the third column could\n-contain \u201cbook\u201d. This is used when generating objects for use with\n+row. For instance, if the table is called "books", the third column could\n+contain "book". This is used when generating objects for use with\n GNATCOLL.SQL.ORM.

          \n

          If the first line starts with the keyword ABSTRACT, then no instance\n of that table actually exists in the database. This is used in the context\n of table inheritance, so define shared fields only once among multiple tables.

          \n

          The keyword TABLE can be followed by the name of a table from which it\n inherits the fields. Currently, that supertable must be abstract, and the\n fields declared in that table are simply duplicated in the new table.

          \n

          Following the declaration of the table, the file then describe their fields,\n each on a separate line. Each of these lines must start with a pipe\n-character (\u201c|\u201d), and contain a number of pipe-separated fields. The order of\n+character ("|"), and contain a number of pipe-separated fields. The order of\n the fields is always given by the following grammar:

          \n 
          fields ::=\n    '|' <name> '|' <type>\n    '|' ('PK'|''|'NULL'|'NOT NULL'|'INDEX'|'UNIQUE'|'NOCASE')\n    '|' [default] '|' [doc] '|'\n
          \n
          \n-

          The type of the field is the SQL type (\u201cINTEGER\u201d, \u201cTEXT\u201d, \u201cTIMESTAMP\u201d, \u201cDATE\u201d,\n-\u201cDOUBLE PRECISION\u201d, \u201cMONEY\u201d, \u201cBOOLEAN\u201d, \u201cTIME\u201d, \u201cCHARACTER(1)\u201d). Any maximal\n+

          The type of the field is the SQL type ("INTEGER", "TEXT", "TIMESTAMP", "DATE",\n+"DOUBLE PRECISION", "MONEY", "BOOLEAN", "TIME", "CHARACTER(1)"). Any maximal\n length can be specified for strings, not just 1 as in this example.\n The tool will automatically convert these to\n-Ada when generating Ada code. A special type (\u201cAUTOINCREMENT\u201d) is an integer\n+Ada when generating Ada code. A special type ("AUTOINCREMENT") is an integer\n that is automatically incremented according to available ids in the table.\n The exact type used will depend on the specific DBMS.

          \n-

          The property \u2018NOCASE\u2019 indicates that comparison should be case insensitive\n+

          The property 'NOCASE' indicates that comparison should be case insensitive\n for this field.

          \n

          If the field is a foreign key (that is a value that must correspond to a row\n in another table), you can use the special syntax for its type:

          \n 
          fk_type ::= 'FK' <table_name> [ '(' <reverse_name> ')' ]\n
          \n
          \n

          As you can see, the type of the field is not specified explicitly, but will\n-always be that of the foreign table\u2019s primary key. With this syntax, the\n+always be that of the foreign table's primary key. With this syntax, the\n foreign table must have a single field for its primary key. GNATColl\n does not force a specific order for the declaration of tables: if is valid to\n-have a foreign key to a table that hasn\u2019t been declared yet. There is however\n+have a foreign key to a table that hasn't been declared yet. There is however\n a restriction if you use the model to create a sqlite database (through the\n -createdb switch of gnatcoll_db2ada): in this case, a reference\n-to a table that hasn\u2019t been defined yet may not be not through a field marked\n+to a table that hasn't been defined yet may not be not through a field marked\n as NOT NULL. This is a limitation of the sqlite backend itself. The solution\n in this case is to reorder the declaration of tables, or drop the NOT NULL\n constraint.

          \n

          Another restriction is that a foreign key that is also a primary key must\n reference a table that has already been defined. You need to reorder the\n declaration of your tables to ensure this is the case.

          \n-

          \u201creverse_name\u201d is the optional name that will be generated in the Ada code for the\n+

          "reverse_name" is the optional name that will be generated in the Ada code for the\n reverse relationship, in the context of GNATCOLL.SQL.ORM.\n-If the \u201creverse_name\u201d is empty (the parenthesis are shown), no reverse\n+If the "reverse_name" is empty (the parenthesis are shown), no reverse\n relationship is generated. If the parenthesis and the reverse_name are both\n omitted, a default name is generated based on the name of the field.

          \n

          The third column in the fields definition indicates the constraints of the\n type. Multiple keywords can be used if they are separated by commas. Thus,\n-\u201cNOT NULL, INDEX\u201d indicates a column that must be set by the user, and for\n+"NOT NULL, INDEX" indicates a column that must be set by the user, and for\n which an index is created to speed up look ups.

          \n
            \n-

          • A primary key (\u201cPK\u201d)

            • \n-

          • The value must be defined (\u201cNOT NULL\u201d)

            • \n-

          • The value can be left undefined (\u201cNULL\u201d)

            • \n-

          • A unique constraint and index (\u201cUNIQUE\u201d)

            • \n-

          • An index should be created for that column (\u201cINDEX\u201d) to speed up\n+

          • A primary key ("PK")

            • \n+

          • The value must be defined ("NOT NULL")

            • \n+

          • The value can be left undefined ("NULL")

            • \n+

          • A unique constraint and index ("UNIQUE")

            • \n+

          • An index should be created for that column ("INDEX") to speed up\n the lookups.

            • \n

          • The automatic index created for a Foreign Key should not be created\n-(\u201cNOINDEX\u201d). Every time a field references another table, GNATColl will by\n+("NOINDEX"). Every time a field references another table, GNATColl will by\n default create an index for it, so that the ORM can more efficiently do a\n-reverse query (from the target table\u2019s row find all the rows in the current\n+reverse query (from the target table's row find all the rows in the current\n table that reference that target row). This will in general provide more\n efficiency, but in some cases you never intend to do the reverse query and\n thus can spare the extra index.

            • \n
          \n

          The fourth column gives the default value for the field, and is given in SQL\n syntax. Strings must be quoted with single quotes.

          \n

          The fifth column contains documentation for the field (if any). This\n documentation will be included in the generated code, so that IDEs can\n-provide useful tooltips when navigating your application\u2019s code.

          \n+provide useful tooltips when navigating your application's code.

          \n

          After all the fields have been defined, you can specify extract constraints\n on the table. In particular, if you have a foreign key to a table that uses a\n tuple as its primary key, you can define that foreign key on a new line, as:

          \n 
          FK ::= '|' "FK:" '|' <table> '|' <field_names>*\n    '|' <field_names>* '|'\n
          \n
          \n@@ -385,48 +385,48 @@\n
          \n
          \n
          TABLE | tableA |
          \n
          UNIQUE: | field1,field2,field3 | name |
          \n
          \n
          \n

          Going back to the example we described earlier (Database example),\n-let\u2019s describe the tables that are involved.

          \n+let's describe the tables that are involved.

          \n

          The first table contains the customers. Here is its definition:

          \n 
          | TABLE | customers     | customer        || The customer for the library |\n | id    | AUTOINCREMENT | PK              || Auto-generated id            |\n | first | TEXT          | NOT NULL        || Customer's first name        |\n | last  | TEXT          | NOT NULL, INDEX || Customer's last name         |\n
          \n
          \n

          We highly recommend to set a primary key on all tables.\n This is a field whose value is\n unique in the table, and thus that can act as an identifier for a specific\n row in the table (in this case for a specific customer). We recommend using\n integers for these ids for efficiency reasons. It is possible that the\n primary key will be made of several fields, in which case they should all\n-have the \u201cPK\u201d constraint in the third column.

          \n+have the "PK" constraint in the third column.

          \n

          A table with no primary key is still usable. The difference is in the\n code generated for the ORM (The Object-Relational Mapping layer (ORM)),\n since the Delete operation for this table will raise a\n-Program_Error instead of doing the actual deletion (that\u2019s because there\n+Program_Error instead of doing the actual deletion (that's because there\n is no guaranteed unique identifier for the element, so the ORM does not know\n-which one to delete \u2013 we do not depend on having unique internal ids on the\n+which one to delete -- we do not depend on having unique internal ids on the\n table, like some DBMS have). Likewise, the elements extracted from such a\n primary key-less table will not be cached locally in the session, and cannot\n be updated (only new elements can be created in the table).

          \n

          As we mentioned, the library contains two types of media, books and DVDs.\n Each of those has a title, an author. However, a book also has a number of\n pages and a DVD has a region where it can be viewed. There are various ways\n to represent this in a database. For illustration purposes, we will use\n table inheritance here: we will declare one abstract table (media) which\n contains the common fields, and two tables to represent the types of media.

          \n

          As we mentioned, a media can be borrowed by at most one customer, but a\n customer can have multiple media at any point in time. This is called a\n one-to-many relationship. In SQL, this is in general described through\n-the use of a foreign key that goes from the table on the \u201cmany\u201d side. In\n+the use of a foreign key that goes from the table on the "many" side. In\n this example, we therefore have a foreign key from media to customers. We\n also provide a name for the reverse relationship, which will become clearer\n when we describe the ORM interface.

          \n

          Here are the declarations:

          \n 
          | ABSTRACT TABLE | media               | media || The contents of the library |\n | id             | AUTOINCREMENT       | PK    || Auto-generated id           |\n | title          | TEXT                |       || The title of the media      |\n@@ -445,15 +445,15 @@\n dbschema.txt.
          \n
          • \n
        \n
        \n
        \n

        1.4. The gnatcoll_db2ada tool\uf0c1

        \n

        As stated in the introduction, one of the goals of this library is to\n-make sure the application\u2019s code follows changes in the schema of your\n+make sure the application's code follows changes in the schema of your\n database.

        \n

        To reach this goal, an external tool, gnatcoll_db2ada is provided\n with GNATColl, and should be spawned as the first step of the\n build process, or at least whenever the database schema changes. It\n generates an Ada package (Database by default) which reflects the\n current schema of the database.

        \n

        This tool supports a number of command line parameters (the complete list\n@@ -461,15 +461,15 @@\n those switches are:

        \n
        \n
        -dbhost host, -dbname name, -dbuser user, -dbpasswd passwd, -dbtype type

        These parameters specify the connection parameters for the database. To\n find out the schema, gnatcoll_db2ada can connect to an existing\n database (Database schema). The user does not need to have\n write permission on the database, since all queries are read-only.

        \n
        \n-
        -dbmodel file

        This parameter can replace the above -dbname,\u2026 It specifies the\n+

        -dbmodel file

        This parameter can replace the above -dbname,... It specifies the\n name of a text file that contains the description of the database, therefore\n avoiding the need for already having a database up-and-running to generate\n the Ada interface.

        \n

        The format of this text file was described in the previous section.

        \n

        This switch is not compatible with -enum and -vars that\n really need an access to the database.

        \n
        \n@@ -493,20 +493,20 @@\n initial data (if -load was specified) from your application, without\n requiring access to the external files that define the schema and the\n initial data.

        \n \n
        -enum table,id,name,prefix,base

        This parameter can be repeated several times if needed. It identifies\n one of the special tables of the database that acts as an enumeration\n type. It is indeed often the case that one or more tables in the\n-database have a role similar to Ada\u2019s enumeration types, i.e. contains\n+database have a role similar to Ada's enumeration types, i.e. contains\n a list of values for information like the list of possible priorities,\n-a list of countries,\u2026 Such lists are only manipulated by the\n+a list of countries,... Such lists are only manipulated by the\n maintainer of the database, not interactively, and some of their\n-values have impact on the application\u2019s code (for instance, if a\n-ticket has an urgent priority, we need to send a reminder every day \u2013\n+values have impact on the application's code (for instance, if a\n+ticket has an urgent priority, we need to send a reminder every day --\n but the application needs to know what an urgent priority is).\n In such a case, it is convenient to generate these values as\n constants in the generated package. The output will be similar to:

        \n 
        subtype Priority_Id is Integer;\n Priority_High   : constant Priority_Id := 3;\n Priority_Medium : constant Priority_Id := 2;\n Priority_Low    : constant Priority_Id := 1;\n@@ -528,15 +528,15 @@\n 
        -enum ticket_priorities,Priority,Name,Priority,Integer\n 
        \n 
        \n 
        First word in the parameter is the table name where the data to generate\n constants is stored. Second word is the field name in the table where the\n Ada constant value is stored. The third word is the field where the last\n part the Ada constant name is stored. The forth word is the prefix to add\n-in front of the third word field value to generate the Ada constant\u2019s name.\n+in front of the third word field value to generate the Ada constant's name.\n The last optional parameter should be either Integer (default) or\n String, which influences the way how the Ada constant value is going to\n be generated (surrounded or not by quotes).
        \n
        \n
        -enum-image

        If specified in addition to the -enum switch, then a function is\n generated for each Integer-valued enum that converts numeric\n values to the corresponding name as a string.

        \n@@ -570,15 +570,15 @@\n \n

        which generates:

        \n 
        No_Assigne_Id : constant := 0;\n --  help\n
        \n
        \n

        The application should use this constant rather than some hard-coded\n-string \u201cunassigned\u201d or a named constant with the same value.\n+string "unassigned" or a named constant with the same value.\n The reason is that presumably the login will be made visible somewhere\n to the user, and we could decide to change it (or translate it to\n another language). In such a case, the application would break. On the\n other hand, using the constant 0 which we just extracted will\n remain valid, whatever the actual text we display for the user.

        \n
        \n
        -orm PKG

        This will generate two files (PKG.ads and PKG.adb) that\n@@ -663,28 +663,28 @@\n

        As described above, the -createdb switch makes it possible to\n create a database (or at least its schema). This operation can also be\n performed directly from your Ada code by using the services provided in the\n GNATCOLL.SQL.Inspect package. In particular, there are services for\n reading the schema of a database either from a file or from a live\n database, just as gnatcoll_db2ada does.

        \n

        This results in a structure in memory that you can use to find out which\n-are the tables, what are their fields, their primary keys,\u2026

        \n+are the tables, what are their fields, their primary keys,...

        \n

        It is also possible to dump this schema to a text file (with the same\n format as expected by -dbmodel), or more interestingly to output\n the SQL statements that are needed to create the tables in a database. In\n the case of Sqlite, creating a table will also create the database file\n-if it doesn\u2019t exist yet, so no special rights are needed.

        \n+if it doesn't exist yet, so no special rights are needed.

        \n

        This input/output mechanism is implemented through an abstract\n Schema_IO tagged type, with various concrete implementations (either\n File_Schema_IO to read or write from/to a file, or\n DB_Schema_IO to read or write from/to a database).

        \n

        See the specs for more detail on these subprograms.

        \n
        \n
        \n-

        1.4.3. Back to the library example\u2026\uf0c1

        \n+

        1.4.3. Back to the library example...\uf0c1

        \n

        In the previous section, we have described our database schema in a text\n file. We will now perform two operations:

        \n
          \n

        • Create an empty database

          \n

          This should of course only be done once, not every time you run your\n application:

          \n 
          gnatcolldbada -dbtype=sqlite -dbname=library.db -dbmodel=dbschema.txt -createdb\n@@ -746,15 +746,15 @@\n 
          To connect to a DBMS, you need to specify the various connection parameters.\n This is done via a GNATCOLL.SQL.Exec.Database_Description object.\n The creation of this object depends on the specific DBMS you are connecting\n to (and this is the only part of your code that needs to know about the\n specific system). The packages GNATCOLL.SQL.Postgres and\n GNATCOLL.SQL.Sqlite contain a Setup function, whose parameters\n depend on the DBMS. They provide full documentation for their parameters.\n-Let\u2019s take a simple example from sqlite:
          \n+Let's take a simple example from sqlite:
          \n 
          with GNATCOLL.SQL.Sqlite;   -- or Postgres\n declare\n    DB_Descr : GNATCOLL.SQL.Exec.Database_Description;\n begin\n    DB_Descr := GNATCOLL.SQL.Sqlite.Setup ("dbname.db");\n end\n 
          \n@@ -821,15 +821,15 @@\n using pools) to avoid memory leaks. Nothing critical will appear if you do\n not close, though, because the transactions to the DBMS server are saved\n every time you call Commit in any case. So the code would end with:
          \n 
          Free (DB);  --  for all connections you have opened\n Free (DB_Descr);\n 
          \n 
          \n-
          At this point, there still hasn\u2019t been any connection to the DBMS. This will\n+
          At this point, there still hasn't been any connection to the DBMS. This will\n be done the first time a query is executed. If for some reason the connection\n to the DBMS server is lost, GNATColl will automatically attempt to\n reconnect a number of times before it gives up. This might break if there\n was an ongoing SQL transaction, but simplifies your code since you do not\n have to handle reconnection when there was a network failure, for instance.
          \n 
          As we saw before, the database interface can be used in multi-tasking\n applications. In such a case, it is recommended that each thread has its\n@@ -854,26 +854,26 @@\n 
          One can connect to the database with an external tool (a web interface\n when the DBMS provides one for instance), or via a command line tool\n (psql for PostgreSQL or sqlite3 for Sqlite), and start\n inserting data manually. This shows one of the nice aspects of using a\n standard DBMS for your application: you can alter the database (for instance\n to do minor fixes in the data) with a lot of external tools that were\n developed specifically for that purpose and that provide a nice interface.\n-However, this is also tedious and error prone, and can\u2019t be repeat easily\n+However, this is also tedious and error prone, and can't be repeat easily\n every time we recreate the database (for instance before running automatic\n tests).
          \n
          • \n

        • Using GNATCOLL.SQL.EXEC

          \n

          As we will describe later, GNATColl contains all the required\n machinery for altering the contents of the database and creating new\n objects. Using GNATCOLL.SQL.ORM this can also be done at a high-level\n and completely hide SQL.

          \n
          • \n

        • Loading a data file

          \n-

          A lot of frameworks call such a file that contains initial data a \u201cfixture\u201d.\n+

          A lot of frameworks call such a file that contains initial data a "fixture".\n We will use this technique as an example. At the Ada level, this is a simple\n call to GNATCOLL.SQL.Inspect.Load_Data. The package contains a lot\n more than just this subprogram (The gnatcoll_db2ada tool):

          \n 
          declare\n    File : GNATCOLL.VFS.Virtual_File := Create ("fixture.txt");\n    DB : Database_Connection;  --  created earlier\n begin\n@@ -886,15 +886,15 @@\n
          • \n
        \n

        As we mentioned, GNATColl can load data from a file. The format\n of this file is similar to the one that describes the database schema. It\n is a set of ASCII tables, each of which describes the data that should go\n in a table (it is valid to duplicate tables). Each block starts with two\n lines: The first one has two mandatory columns, the first of which contains\n-the text \u201cTABLE\u201d, and the second contains the name of the table you want to\n+the text "TABLE", and the second contains the name of the table you want to\n fill. The second line should contain as many columns as there are fields you\n want to set. Not all the fields of the table need to have a corresponding\n column if you want to set their contents to NULL (provided, of course,\n that your schema allows it). For instance, we could add data for our\n library example as such:

        \n 
        | TABLE | customers |        |\n |    id | first     | last   |\n@@ -924,15 +924,15 @@\n |--------------+-----------+--------+--------------------|\n | The Birds    | Hitchcock |      1 | &Smith             |\n | The Dictator | Chaplin   |      3 | &Dupont            |\n
        \n
        \n

        Here, the title of the column indicates that any value in this column might\n be a reference to the customers.last value. Values which start\n-with an ampersand (\u201d&\u201d) will therefore be looked up in customers.last,\n+with an ampersand ("&") will therefore be looked up in customers.last,\n and the id of the corresponding customer will be inserted in the\n dvds table. It would still be valid to use directly customer ids\n instead of references, this is just an extra flexibility that the references\n give you to make your fixtures more readable.

        \n

        However, if we are using such references we need to provide the database\n schema to Load_Data so that it can write the proper queries. This\n is done by using other services of the GNATCOLL.SQL.Inspect package.

        \n@@ -973,24 +973,24 @@\n Where => Ticket_Priorities.Name /= "low",\n Group_By => Ticket_Priorities.Category);\n end;\n \n \n

        The above example will return, for each type of priority (internal or\n customer) the highest possible value. The interest of this query is\n-left to the user\u2026

        \n+left to the user...

        \n

        This is very similar to an actual SQL query. Field and table names come\n from the package that was automatically generated by the\n gnatcoll_db2ada tool, and therefore we know that our query is\n only referencing existing fields. The syntactic correctness is ensured by\n standard Ada rules. The SQL_Select accepts several parameters\n corresponding to the usual SQL attributes like GROUP BY,\n HAVING, ORDER BY and LIMIT.

        \n

        The From parameter could be a list of tables if we need to join\n-them in some ways. Such a list is created with the overridden \u201c&\u201d\n+them in some ways. Such a list is created with the overridden "&"\n operator, just as for fields which you can see in the above example.\n GNATColl also provides a Left_Join function to join two\n tables when the second might have no matching field (see the SQL\n documentation).

        \n

        Similar functions exist for SQL_Insert, SQL_Update and\n SQL_Delete. Each of those is extensively documented in the\n gnatcoll-sql.ads file.

        \n@@ -1033,16 +1033,16 @@\n automatically by looking at those fields that are not used in a SQL\n aggregate function. This auto-completion helps the maintenance of those\n queries.

        \n

        There is another case where GNATColl makes it somewhat easier\n to write the queries, and that is to handle joins between tables. If your\n schema was build with foreign keys, GNATColl can take advantage\n of those.

        \n-

        Going back to our library example, let\u2019s assume we want to find out all\n-the books that were borrowed by the user \u201cSmith\u201d. We need to involve two\n+

        Going back to our library example, let's assume we want to find out all\n+the books that were borrowed by the user "Smith". We need to involve two\n tables (Books and Customers), and provide a join between them\n so that the DBMS knows how to associate the rows from one with the rows from\n the other. Here is a first example for such a query:

        \n 
        Q := SQL_Select\n    (Fields => Books.Title & Books.Pages,\n     From   => Books & Customers,\n     Where  => Books.Borrowed_By = Customers.Id\n@@ -1056,15 +1056,15 @@\n     Where  => Books.Borrowed_By = Customers.Id\n        and Customers.Last = "Smith");\n
        \n
        \n

        There is one more things we can do to simplify the query and make it more\n solid if the schema of the database changes. For instance, when a table\n has a primary key made up of several fields, we need to make sure we always\n-have an \u201c=\u201d statement in the WHERE clause for all these fields between the\n+have an "=" statement in the WHERE clause for all these fields between the\n two tables. In our example above, we could at some point modify the schema\n so that the primary key for customers is multiple (this is unlikely\n in this example of course). To avoid this potential problems and make the\n query somewhat easier to read, we can take advantage of the FK\n subprograms generated by gnatcoll_db2ada. Using the Ada05 dotted\n notation for the call, we can thus write:

        \n 
        Q := SQL_Select\n@@ -1099,15 +1099,15 @@\n is the case when you execute an INSERT or UPDATE statement\n for instance. Using Execute avoids the need to declare the local\n variable R.
        \n 
        If for some reason the connection to the database is no longer valid\n (a transient network problem for instance), GNATColl will\n attempt to reconnect and re-execute your query transparently, so that\n your application does not need to handle this case.
        \n-
        We\u2019ll describe later (Getting results) how to analyze the result\n+
        We'll describe later (Getting results) how to analyze the result\n of the query.
        \n 
        Some versions of Fetch have an extra parameter Use_Cache,\n set to False by default. If this parameter is true, and the exact same\n query has already been executed before, its result will be reused\n without even contacting the database server. The cache is automatically\n invalidated every hour in any case. This cache is mostly useful for\n tables that act like enumeration types, as we have seen before when\n@@ -1190,15 +1190,15 @@\n        (Fields => Data.Id & Data.Name\n         From   => Data,\n         Where  => Data.Id = Integer_Param (1));\n
        \n
        \n

        GNATColl provides a number of functions (one per type of\n field) to indicate that the value is currently unbound. Integer_Param,\n-Text_Param, Boolean_Param,\u2026 All take a single argument,\n+Text_Param, Boolean_Param,... All take a single argument,\n which is the index of the corresponding parameter. A query might need\n several parameters, and each should have a different index. On the other\n hand, the same parameter could be used in several places in the query.

        \n

        Although the query above could be executed as is by providing the values\n for the parameters, it is more efficient, as we mentioned at the beginning,\n to compile it on the server. In theory, this preparation is done within the\n context of a database connection (thus cannot be done for a global variable,\n@@ -1221,39 +1221,39 @@\n statement locally in a subprogram. A Prepared_Statement is a\n reference counted type, that will automatically free the memory on the\n server when it goes out of scope.

        • \n

      • Here, we prepared the statement on the server. If we had specified\n On_Server => False, we would still have sped things up, since Q\n would be converted to a string that can be sent to the DBMS, and from\n then on reused that string (note that this conversion is specific to\n-each DBMS, since they don\u2019t always represent things the same way, in\n+each DBMS, since they don't always represent things the same way, in\n particular parameters, as we have seen above). Thus every time you use\n P you save the time of converting from the GNATColl tree\n representation of the query to a string for the DBMS.

        • \n
      \n

      Now that we have a prepared statement, we can simply execute it.\n If the statement does not require parameters, the usual Fetch\n and Execute subprograms have versions that work exactly the same\n with prepared statements. They also accept a Params parameter that\n-contains the parameter to pass to the server. A number of \u201c+\u201d\n+contains the parameter to pass to the server. A number of "+"\n operators are provided to create those parameters:

      \n 
      declare\n    F : Forward_Cursor;\n begin\n    F.Fetch (DB, P, Params => (1 => +2));\n    F.Fetch (DB, P, Params => (1 => +3));\n end;\n
      \n
      \n-

      Note that for string parameters, the \u201c+\u201d operator takes an\n+

      Note that for string parameters, the "+" operator takes an\n access to a string. This is for efficiency, to avoid allocating memory\n and copying the string, and is safe because the parameters are only needed\n while Fetch executes (even for a Forward_Cursor.

      \n

      Back to our library example. We showed earlier how to write a query that\n-retrieves the books borrowed by customer \u201cSmith\u201d. We will now make this\n+retrieves the books borrowed by customer "Smith". We will now make this\n query more general: given a customer name, return all the books he has\n borrowed. Since we expect to use this often, we will prepare it on the\n server (in real life, this query is of little interest since the customer\n name is not unique, we would instead use a query that takes the id of the\n customer). In general we would create a global variable with:

      \n 
      Borrowed : constant Prepared_Statement := Prepare\n   (SQL_Select\n@@ -1329,15 +1329,15 @@\n 
      We mentioned earlier there was no way to go back to a row you fetched\n previously except by executing the query again. This is in fact only\n true if you use a Forward_Cursor to fetch the results.
      \n 
      But GNATColl provides another notion, a Direct_Cursor. In\n this case, it fetches all the rows in memory when the query executes (thus\n it needs to allocate more memory to save every thing, which can be costly\n if the query is big). This behavior is supported natively by PostgreSQL,\n-but doesn\u2019t exist with sqlite, so GNATColl will simulate it\n+but doesn't exist with sqlite, so GNATColl will simulate it\n as efficiently as possible. But it will almost always be faster to use\n a Forward_Cursor.
      \n 
      In exchange for this extra memory overhead, you can now traverse the list\n of results in both directions, as well as access a specific row directly.\n It is also possible to know the number of rows that matched (something hard\n to do with a Forward_Cursor since you would need to traverse the\n list once to count, and then execute the query again if you need the rows\n@@ -1428,20 +1428,20 @@\n 
      1.12. Query logs\uf0c1
      \n 
      The GNATCOLL.Traces package provides facilities to add logging.  The database\n interface uses this module to log the queries that are sent to the server.
      \n 
      If you activate traces in your application, the user can then activate\n one of the following trace handles to get more information on the\n exchange that exists between the database and the application. As we saw\n before, the output of these traces can be sent to the standard output, a\n-file, the system logs,\u2026
      \n+file, the system logs,...
      \n 
      The following handles are provided:
      \n 
        \n 
      • SQL.ERROR\n This stream is activated by default. Any error returned by the database\n-(connection issues, failed transactions,\u2026) will be logged on this stream
        • \n+(connection issues, failed transactions,...) will be logged on this stream
        \n 
      • SQL\n This stream logs all queries that are not SELECT queries, i.e. mostly all\n queries that actually modify the database
        • \n 
      • SQL.SELECT\n This stream logs all select queries. It is separated from SQL because\n very often you will be mostly interested in the queries that impact the\n database, and logging all selects can generate a lot of output.
        • \n@@ -1453,15 +1453,15 @@\n begin\n    GNATCOLL.Traces.Parse_Config_File (".gnatdebug");\n    ... --  code as before\n    GNATCOLL.Traces.Finalize;  --  reclaim memory\n
      \n
      \n

      and then create a .gnatdebug in the directory from which we launch our\n-executable. This file would contain a single line containing \u201c+\u201d to\n+executable. This file would contain a single line containing "+" to\n activate all log streams, or the following to activate only the subset of\n fields related to SQL:

      \n 
      SQL=yes\n SQL.SELECT=yes\n SQL.LITE=yes\n
      \n
      \n@@ -1489,15 +1489,15 @@\n function Do_Query (DB, ...) return My_Cursor;\n \n \n

      The idea is that you create a function that does the query for you (based\n on some parameters that are not shown here), and then returns a cursor over\n the resulting set of rows. For each row, you can use the Element\n function to get an Ada record for easier manipulation.

      \n-

      Let\u2019s first see how these types would be used in practice:

      \n+

      Let's first see how these types would be used in practice:

      \n 
      declare\n   C : My_Cursor := Do_Query (DB, ...);\n begin\n   while Has_Row (C) loop\n      Put_Line ("Id = " & Element (C).Id);\n      Next (C);\n   end loop;\n@@ -1572,15 +1572,15 @@\n 
      GNATColl provides a high-level interface to manipulate persistent\n objects stored in a database, using a common paradigm called an\n object-relational mapping. Such mappings exist for most programming\n languages. In the design of GNATColl, we were especially inspired\n by the python interface in django and sqlalchemy, although the\n last two rely on dynamic run time introspection and GNATColl relies\n on code generation instead.
      \n-
      This API is still compatible with GNATCOLL.SQL. In fact, we\u2019ll\n+
      This API is still compatible with GNATCOLL.SQL. In fact, we'll\n show below cases where the two are mixed. It can also be mixed with\n GNATCOLL.SQL.Exec, although this might be more risky. Communication\n with the DBMS is mostly transparent in the ORM, and it uses various caches\n to optimize things and make sure that if you modify an element the next\n query(ies) will also return it. If you use GNATCOLL.SQL.Exec directly\n you are bypassing this cache so you risk getting inconsistent results in\n some cases.
      \n@@ -1596,15 +1596,15 @@\n foreign keys to other tables. So we remove the borrowed_by field\n from the Media table, and change the books table to be:
      \n 
      | TABLE (media) | books                        | book |     | The books in the library |\n | pages         | INTEGER                      |      | 100 |                          |\n | borrowed_by   | FK customers(borrowed_books) | NULL |     | Who borrowed the media   |\n 
      \n 
      \n-
      Let\u2019s thus start by generating this code. We can replace the command we\n+
      Let's thus start by generating this code. We can replace the command we\n ran earlier (with the -api switch) with one that will also generate\n the ORM API:
      \n 
      gnatcoll_db2ada -dbmode dbschema.txt -api Database -orm ORM\n 
      \n 
      \n 
      The ORM provides a pool of database connections through the package\n GNATCOLL.SQL.Sessions. A session therefore acts as a wrapper around\n@@ -1623,15 +1623,15 @@\n
      \n

      The first parameter is the same Database_Description we saw\n earlier (Connecting to the database), but it will be freed\n automatically by the sessions package, so you should not free it\n yourself.

      \n

      Once configure, we can now request a session. Through a session, we can\n perform queries on the database, make objects persistent, write the\n-changes back to the database,\u2026. We configured the session pool\n+changes back to the database,.... We configured the session pool\n to have at most 2 sessions. The first time we call Get_New_Session,\n a new session will be created in the pool and marked as busy. While you\n have a reference to it in your code (generally as a local variable), the\n session belongs to this part of the code. When the session is no longer\n in scope, it is automatically released to the pool to be reused for the\n next call to Get_New_Session. If you call Get_New_Session\n a second time while some part of your code holds a session (for instance\n@@ -1640,19 +1640,19 @@\n is blocking until one of the two sessions is released to the pool.

      \n

      This technique ensures optimal use of the resources: we avoid creating\n a new session every time (with the performance cost of connecting to the\n database), but also avoid creating an unlimited number of sessions which\n could saturate the server. Since the sessions are created lazily the first\n time they are needed, you can also configure the package with a large\n number of sessions with a limited cost.

      \n-

      Let\u2019s then take a new session in our code:

      \n+

      Let's then take a new session in our code:

      \n 
      Session : constant Session_Type := Get_New_Session;\n
      \n
      \n-

      and let\u2019s immediately write our first simple query. A customer comes at\n+

      and let's immediately write our first simple query. A customer comes at\n the library, handles his card and we see his id (1). We need to look up\n in the database to find out who he is. Fortunately, there is no SQL to\n write for this:

      \n 
      C : ORM.Detached_Customer'Class := Get_Customer (Session, Id => 1);\n
      \n
      \n

      The call to Get_Customer performs a SQL query transparently, using\n@@ -1668,15 +1668,15 @@\n fields in the table. Such an object is returned by a cursor, similarly\n to what was described in the previous section (Writing your own cursors).\n This object is no longer valid as soon as the cursor moves to\n the next row (in the currently implementation, the object will describe\n the next row, but it is best not to rely on this). As a benefit, this\n object is light weight and does not make a copy of the value of the\n fields, only reference the memory that is already allocated for the cursor.

      \n-

      This object redefines the equality operator (\u201c=\u201d) to compare the\n+

      This object redefines the equality operator ("=") to compare the\n primary key fields to get expected results.

      \n
      • \n

    • Detached_Customer

      \n

      A detached object is very similar to the Customer object, but it\n will remain valid even if the cursor moves or is destroyed. In fact, the\n object has made a copy of the value for all of its fields. This object\n is heavier than a Customer, but sometimes easier to manager. If\n@@ -1702,15 +1702,15 @@\n

      This type extends a Direct_Cursor. It also adds a Element\n operation that returns a Customer element.

      \n
      • \n

    • Customers_Managers

      \n

      This type is the base type to perform queries on the DBMS. A manager\n provides a number of primitive operations which end up creating a SQL\n query operation in the background, without making that explicit.

      \n-

      Let\u2019s first write a query that returns all books in the database:

      \n+

      Let's first write a query that returns all books in the database:

      \n 
      declare\n    M : Books_Managers := All_Books;\n    BL : Book_List := M.Get (Session);\n    B : Book;\n begin\n    while BL.Has_Row loop\n       B := BL.Element;\n@@ -1720,15 +1720,15 @@\n    end loop;\n end;\n
      \n
      \n

      The manager M corresponds to a query that returns all the books\n in the database. The second line then executes the query on the database,\n and returns a list of books. We then traverse the list. Note how we access\n-the book\u2019s title by calling a function, rather than by the index of a\n+the book's title by calling a function, rather than by the index of a\n field as we did with GNATCOLL.SQL.Exec with Value(B, 0). The code\n is much less fragile this way.

      \n

      The line that calls Borrowed_By will execute an additional SQL\n query for each book. This might be inefficient if there is a large number\n of books. We will show later how this can be optimized.

      \n

      The manager however has a lot more primitive operations that can be used\n to alter the result. Each of these primitive operations returns a modified\n@@ -1740,15 +1740,15 @@\n

    • Get and Get_Direct

      \n

      As seen in the example above, these are the two functions that execute the\n query on the database, and returns a list of objects (respectively a\n Customer_List and a Direct_Customer_List).

      \n
      • \n

    • Distinct

      \n

      Returns a copy of the manager that does not return twice a row with the\n-same data (in SQL, this is the \u201cDISTINCT\u201d operator)

      \n+same data (in SQL, this is the "DISTINCT" operator)

      \n
      • \n

    • Limit (Count : Natural; From : Natural := 0)

      \n

      Returns a copy of the manager that returns a subset of the results, for\n instance the first Count ones.

      \n
      • \n

    • Order_By (By : SQL_Field_List)

      \n

      Returns a copy of the manager that sorts the results according to a criteria.\n@@ -1774,15 +1774,15 @@\n sections, and we would write:

      \n 
      M : Books_Managers := All_Books.Filter (Condition => Books.Pages < 50);\n
      \n
      \n

      More complex conditions are possible, involving other tables. Currently,\n the ORM does not have a very user-friendly interface for those, but you\n can always do this by falling back partially to SQL. For instance, if we\n-want to retrieve all the books borrowed by user \u201cSmith\u201d, we need to\n+want to retrieve all the books borrowed by user "Smith", we need to\n involve the Customers table, and thus make a join with the\n Books table. In the future, we intend to make this join automatic,\n but for now you will need to write:

      \n 
      M : Books_Managers := All_Books.Filter\n   (Books.FK (Customers)\n    and Customers.Last = "Smith");\n \n@@ -1811,15 +1811,15 @@\n then call B.Borrowed_By.Address this will result in a query. So\n if you pass 2 for Depth the data for book, customers and addresses\n will be retrieved.
      \n 
      The second parameter related to efficiency. When a foreign key was mentioned\n as NOT NULL in the schema, we know it is always pointing to an\n existing object in another table. Select_Related will always\n retrieve such objects. If, however, the foreign key can be null, i.e. there\n-isn\u2019t necessarily a corresponding object in the other table, the SQL\n+isn't necessarily a corresponding object in the other table, the SQL\n query needs to use a LEFT JOIN, which is less efficient.  By default,\n GNATColl will not retrieve such fields unless Follow_Left_Join\n was set to True.
      \n 
      In our example, a book is not necessarily borrowed by a customer, so we need\n to follow the left joins:
      \n 
      M : Books_Managers := All_Books.Filter\n   (Books.FK (Customers)\n@@ -1851,19 +1851,19 @@\n --    WHERE books.borrowed_by=1\n 
      \n 
      \n 
      Borrowed_Books is a function that was generated because there was\n a reverse_name. It returns a Books_Managers, so we could\n in fact further filter the list of borrowed books with the same primitive\n operations we just saw. As you can see, the resulting SQL is optimal.
      \n-
      Let\u2019s optimize further the initial query. We have hard-coded the\n+
      Let's optimize further the initial query. We have hard-coded the\n customer name, but in fact we could be using the same subprograms we\n were using for prepared statements (Prepared queries), and even\n prepare the query on the server for maximum efficiency. Since our application\n-is likely to use this query a lot, let\u2019s create a global variable:
      \n+is likely to use this query a lot, let's create a global variable:
      \n 
      M : constant Books_Managers := All_Books.Filter\n   (Books.FK (Customers)\n    and Customers.Id = Integer_Param (1))\n   .Select_Related (1, Follow_Left_Join => True);\n \n MP : constant ORM_Prepared_Statement :=\n   M.Prepare (On_Server => True);\n@@ -1880,16 +1880,16 @@\n \n \n 
      \n 
      1.15. Modifying objects in the ORM\uf0c1
      \n 
      The ORM is much more than writing queries. Once the objects are persistent,\n they can also be simplify modified, and they will be saved in the database\n transparently.
      \n-
      Let\u2019s start with a simple example. In the previous section, we retrieve an\n-object C representing a customer. Let\u2019s change his name, and make\n+
      Let's start with a simple example. In the previous section, we retrieve an\n+object C representing a customer. Let's change his name, and make\n sure the change is in the database:
      \n 
      C := Get_Customer (Session, 1);\n C.Set_Last ("Smith");\n C.Set_First ("Andrew");\n Session.Commit;\n 
      \n 
      \n@@ -1951,15 +1951,15 @@\n end loop;\n 
      \n 
      \n 
      The above example uses CL.Element, which is a light-weight\n Customer object. Such objects will only see the in-memory changes\n if you have set Flush_Before_Query to true when you configured\n the sessions in the call to GNATCOLL.SQL.Sessions.Setup. Otherwise,\n-it will always return what\u2019s really in the database.
      \n+it will always return what's really in the database.
      \n 
      If the example was using Detached_Customer object (by calling\n CL.Element.Detach for instance) then GNATColl looks up in\n its internal cache and returns the cached element when possible. This is\n a subtlety, but this is because an Customer only exists as long as\n its cursor, and therefore cannot be cached in the session. In practice, the\n Flush_Before_Query should almost always be true and there will be\n not surprising results.
      \n@@ -1968,34 +1968,34 @@\n 
      1.16. Object factories in ORM\uf0c1
      \n 
      Often, a database table is used to contain objects that are semantically\n of a different kind. In this section, we will take a slightly different\n example from the library. We no longer store the books and the dvds in\n separate tables. Instead, we have one single media table which\n contains the title and the author, as well as a new field kind\n which is either 0 for a book or 1 for a dvd.
      \n-
      Let\u2019s now look at all the media borrowed by a customer:
      \n+
      Let's now look at all the media borrowed by a customer:
      \n 
      C : constant Customer'Class := Get_Customer (Session, Id => 1);\n ML : Media_List := C.Borrowed_Media.Get (Session);\n \n while ML.Has_Row loop\n    case ML.Element.Kind is\n       when 0 =>\n          Put_Line ("A book " & ML.Element.Title);\n       when 1 =>\n          Put_Line ("A dvd " & ML.Element.Title);\n    end case;\n    ML.Next;\n end loop;\n 
      \n 
      \n-
      This code works, but requires a case statement. Now, let\u2019s imagine\n+
      This code works, but requires a case statement. Now, let's imagine\n the check out procedure is different for a book and a DVD (for the latter\n we need to check that the disk is indeed in the box). We would have two\n subprograms Checkout_Book and Checkout_DVD and call them\n-from the case. This isn\u2019t object-oriented programming.
      \n+from the case. This isn't object-oriented programming.
      \n 
      Instead, we will declare two new types:
      \n 
      type My_Media is abstract new ORM.Detached_Media with private;\n procedure Checkout (Self : My_Media) is abstract;\n \n type Detached_Book is new My_Media with private;\n overriding Checkout (Self : Detached_Book);\n \n@@ -2007,16 +2007,16 @@\n that it returns either of the two types instead of a Media.\n But then we would also need to override Get so that it returns our\n new list. This is tedious.
      \n 
      We will instead use an element factory in the session. This is a function\n that gets a row of a table (in the form of a Customer), and returns\n the appropriate type to use when the element is detached (by default,\n the detached type corresponding to a Customer is a\n-Detached_Customer, and that\u2019s what we want to change).
      \n-
      So let\u2019s create such a factory:
      \n+Detached_Customer, and that's what we want to change).
      \n+
      So let's create such a factory:
      \n 
      function Media_Factory\n    (From    : Base_Element'Class;\n     Default : Detached_Element'Class) return Detached_Element'Class\n is\n begin\n    if From in Media'Class then\n       case Media (From).Kind is\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -4,15 +4,15 @@\n     * _\b1_\b._\b _\bS\bS_\bQ\bQ_\bL\bL_\b:_\b _\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be\n           o _\b1_\b._\b1_\b._\b _\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bA_\bb_\bs_\bt_\br_\ba_\bc_\bt_\bi_\bo_\bn_\b _\bL_\ba_\by_\be_\br_\bs\n           o _\b1_\b._\b2_\b._\b _\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\be_\bx_\ba_\bm_\bp_\bl_\be\n           o _\b1_\b._\b3_\b._\b _\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bs_\bc_\bh_\be_\bm_\ba\n           o _\b1_\b._\b4_\b._\b _\bT_\bh_\be_\b _\bg_\bn_\ba_\bt_\bc_\bo_\bl_\bl_\b__\bd_\bb_\b2_\ba_\bd_\ba_\b _\bt_\bo_\bo_\bl\n                 # _\b1_\b._\b4_\b._\b1_\b._\b _\bD_\be_\bf_\ba_\bu_\bl_\bt_\b _\bo_\bu_\bt_\bp_\bu_\bt_\b _\bo_\bf_\b _\bg_\bn_\ba_\bt_\bc_\bo_\bl_\bl_\b__\bd_\bb_\b2_\ba_\bd_\ba\n                 # _\b1_\b._\b4_\b._\b2_\b._\b _\bd_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bi_\bn_\bt_\br_\bo_\bs_\bp_\be_\bc_\bt_\bi_\bo_\bn_\b _\bi_\bn_\b _\bA_\bd_\ba\n-                # _\b1_\b._\b4_\b._\b3_\b._\b _\bB_\ba_\bc_\bk_\b _\bt_\bo_\b _\bt_\bh_\be_\b _\bl_\bi_\bb_\br_\ba_\br_\by_\b _\be_\bx_\ba_\bm_\bp_\bl_\be_\b\u2026\n+                # _\b1_\b._\b4_\b._\b3_\b._\b _\bB_\ba_\bc_\bk_\b _\bt_\bo_\b _\bt_\bh_\be_\b _\bl_\bi_\bb_\br_\ba_\br_\by_\b _\be_\bx_\ba_\bm_\bp_\bl_\be_\b._\b._\b.\n           o _\b1_\b._\b5_\b._\b _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bn_\bg_\b _\bt_\bo_\b _\bt_\bh_\be_\b _\bd_\ba_\bt_\ba_\bb_\ba_\bs_\be\n           o _\b1_\b._\b6_\b._\b _\bL_\bo_\ba_\bd_\bi_\bn_\bg_\b _\bi_\bn_\bi_\bt_\bi_\ba_\bl_\b _\bd_\ba_\bt_\ba_\b _\bi_\bn_\b _\bt_\bh_\be_\b _\bd_\ba_\bt_\ba_\bb_\ba_\bs_\be\n           o _\b1_\b._\b7_\b._\b _\bW_\br_\bi_\bt_\bi_\bn_\bg_\b _\bq_\bu_\be_\br_\bi_\be_\bs\n           o _\b1_\b._\b8_\b._\b _\bE_\bx_\be_\bc_\bu_\bt_\bi_\bn_\bg_\b _\bq_\bu_\be_\br_\bi_\be_\bs\n           o _\b1_\b._\b9_\b._\b _\bP_\br_\be_\bp_\ba_\br_\be_\bd_\b _\bq_\bu_\be_\br_\bi_\be_\bs\n           o _\b1_\b._\b1_\b0_\b._\b _\bG_\be_\bt_\bt_\bi_\bn_\bg_\b _\br_\be_\bs_\bu_\bl_\bt_\bs\n           o _\b1_\b._\b1_\b1_\b._\b _\bC_\br_\be_\ba_\bt_\bi_\bn_\bg_\b _\by_\bo_\bu_\br_\b _\bo_\bw_\bn_\b _\bS_\bQ_\bL_\b _\bt_\by_\bp_\be_\bs\n@@ -52,26 +52,26 @@\n       document refers to this meaning. In a relational database, this place is\n       organized into tables, each of which contains a number of fields. A row\n       in a table represents one object. The set of tables and their fields is\n       called the s\bsc\bch\bhe\bem\bma\ba of the database.\n Traditionally, writing the SQL queries is done inline: special markers are\n inserted into your code to delimit sections that contain SQL code (as opposed\n to Ada code), and these are then preprocessed to generate actual code. This\n-isn\u2019t the approach chosen in GNATColl: there are several drawbacks, in\n+isn't the approach chosen in GNATColl: there are several drawbacks, in\n particular your code is no longer Ada and various tools will choke on it.\n The other usual approach is to write the queries as strings, which are passed,\n via a DBMS-specific API, to the DBMS server. This approach is very fragile:\n     * The string might not contain w\bwe\bel\bll\bl-\b-f\bfo\bor\brm\bme\bed\bd SQL. This will unfortunately\n       only be detected at run time when the DBMS complains.\n     * This is not t\bty\byp\bpe\be s\bsa\baf\bfe\be. You might be comparing a text field with an\n       integer, for instance. In some cases, the DBMS will accept that (sqlite\n-      for instance), but in some other cases it won\u2019t (PostgreSQL). The result\n+      for instance), but in some other cases it won't (PostgreSQL). The result\n       might then either raise an error, or return an empty list.\n     * There is a risk of S\bSQ\bQL\bL i\bin\bnj\bje\bec\bct\bti\bio\bon\bn. Assuming the string is constructed\n-      dynamically (using Ada\u2019s&operator), it might be easy for a user to pass a\n+      dynamically (using Ada's&operator), it might be easy for a user to pass a\n       string that breaks the query, and even destroys things in the database.\n     * As discussed previously, the SQL code might not be p\bpo\bor\brt\bta\bab\bbl\ble\be across DBMS.\n       For instance, creating an automatically increment integer primary key in\n       a table is DBMS specific.\n     * The string is fragile if the database s\bsc\bch\bhe\bem\bma\ba c\bch\bha\ban\bng\bge\bes\bs. Finding whether a\n       schema change impacts any of the queries requires looking at all the\n       strings in your application.\n@@ -142,30 +142,30 @@\n with each other. You could connect to the database, and then write some queries\n using G\bGN\bNA\bAT\bTC\bCO\bOL\bLL\bL.\b.S\bSQ\bQL\bL and some using G\bGN\bNA\bAT\bTC\bCO\bOL\bLL\bL.\b.S\bSQ\bQL\bL.\b.O\bOR\bRM\bM.\n *\b**\b**\b**\b**\b* 1\b1.\b.2\b2.\b. D\bDa\bat\bta\bab\bba\bas\bse\be e\bex\bxa\bam\bmp\bpl\ble\be_\b?\b\uf0c1 *\b**\b**\b**\b**\b*\n This section describes an example that will be extended throughout this\n chapter. We will build an application that represents a library. Such a library\n contains various media (books and DVDs for instance), and customers. A customer\n can borrow multiple media at the same time, but a media is either at a\n-customer\u2019s, or still in the library.\n+customer's, or still in the library.\n The GNATColl distribution includes an example directory which contains all the\n code and data for this example.\n *\b**\b**\b**\b**\b* 1\b1.\b.3\b3.\b. D\bDa\bat\bta\bab\bba\bas\bse\be s\bsc\bch\bhe\bem\bma\ba_\b?\b\uf0c1 *\b**\b**\b**\b**\b*\n As was mentioned earlier (_\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bA_\bb_\bs_\bt_\br_\ba_\bc_\bt_\bi_\bo_\bn_\b _\bL_\ba_\by_\be_\br_\bs), GNATColl relies on\n automatic code generation to provide a type safe interface to your database.\n This code is generated by an external tool calledgnatcoll_db2ada. In some\n cases, this tool requires an installation of python (_\bw_\bw_\bw_\b._\bp_\by_\bt_\bh_\bo_\bn_\b._\bo_\br_\bg) on your\n machine, since part of the code is written in that language.\n This tool is able to output various kind of information, and will be fully\n described later (_\bT_\bh_\be_\b _\bg_\bn_\ba_\bt_\bc_\bo_\bl_\bl_\b__\bd_\bb_\b2_\ba_\bd_\ba_\b _\bt_\bo_\bo_\bl). However, the input is always the\n same: this is the schema of your database, that is the list of tables and\n fields that make up your database. There exist two ways to provide that\n information:\n     * From a running database\n-      If you pass the DBMS vendor (postgresql, sqlite,\u2026) and the connection\n+      If you pass the DBMS vendor (postgresql, sqlite,...) and the connection\n       parameters tognatcoll_db2ada, it is able to query the schema on its own.\n       However, this should not be the preferred method: this is similar to\n       reverse engineering assembly code into the original high-level code, and\n       some semantic information will be missing. For instance, in SQL we have\n       to create tables just to represent the many-to-many relationships. These\n       extra tables are part of the implementation of the schema, but are just\n       noise when it comes to the semantics of the schema. For this reason, it\n@@ -177,95 +177,95 @@\n       additional capabilities that do not exist when reverse-engineering an\n       existing database, for instance the ability to use name to represent\n       reverse relationships for foreign keys (see below and the ORM).\n       The most convenient editor for this file is Emacs, using theorg-modewhich\n       provides convenient key shortcuts for editing the contents of ASCII\n       tables. But any text editor will do, and you do not need to align the\n       columns in this file.\n-      All lines starting with a hash sign (\u2018#\u2019) will be ignored.\n+      All lines starting with a hash sign ('#') will be ignored.\n       This file is a collection of ASCII tables, each of which relates to one\n       table or one SQL view in your database. The paragraphs start with a line\n       containing:\n       table ::=\n          '|' ('ABSTRACT')? ('TABLE'|'VIEW') ['(' supertable ')']\n          '|'  '|' \n-      \u201cname\u201d is the name of the table. The third pipe and third column are\n+      \"name\" is the name of the table. The third pipe and third column are\n       optional, and should be used to specify the name for the element\n       represented by a single row. For instance, if the table is called\n-      \u201cbooks\u201d, the third column could contain \u201cbook\u201d. This is used when\n+      \"books\", the third column could contain \"book\". This is used when\n       generating objects for use withGNATCOLL.SQL.ORM.\n       If the first line starts with the keywordABSTRACT, then no instance of\n       that table actually exists in the database. This is used in the context\n       of table inheritance, so define shared fields only once among multiple\n       tables.\n       The keywordTABLEcan be followed by the name of a table from which it\n       inherits the fields. Currently, that supertable must be abstract, and the\n       fields declared in that table are simply duplicated in the new table.\n       Following the declaration of the table, the file then describe their\n       fields, each on a separate line. Each of these lines must start with a\n-      pipe character (\u201c|\u201d), and contain a number of pipe-separated fields. The\n+      pipe character (\"|\"), and contain a number of pipe-separated fields. The\n       order of the fields is always given by the following grammar:\n       fields ::=\n          '|'  '|' \n          '|' ('PK'|''|'NULL'|'NOT NULL'|'INDEX'|'UNIQUE'|'NOCASE')\n          '|' [default] '|' [doc] '|'\n-      The type of the field is the SQL type (\u201cINTEGER\u201d, \u201cTEXT\u201d, \u201cTIMESTAMP\u201d,\n-      \u201cDATE\u201d, \u201cDOUBLE PRECISION\u201d, \u201cMONEY\u201d, \u201cBOOLEAN\u201d, \u201cTIME\u201d, \u201cCHARACTER(1)\u201d).\n+      The type of the field is the SQL type (\"INTEGER\", \"TEXT\", \"TIMESTAMP\",\n+      \"DATE\", \"DOUBLE PRECISION\", \"MONEY\", \"BOOLEAN\", \"TIME\", \"CHARACTER(1)\").\n       Any maximal length can be specified for strings, not just 1 as in this\n       example. The tool will automatically convert these to Ada when generating\n-      Ada code. A special type (\u201cAUTOINCREMENT\u201d) is an integer that is\n+      Ada code. A special type (\"AUTOINCREMENT\") is an integer that is\n       automatically incremented according to available ids in the table. The\n       exact type used will depend on the specific DBMS.\n-      The property \u2018NOCASE\u2019 indicates that comparison should be case\n+      The property 'NOCASE' indicates that comparison should be case\n       insensitive for this field.\n       If the field is a foreign key (that is a value that must correspond to a\n       row in another table), you can use the special syntax for its type:\n       fk_type ::= 'FK'  [ '('  ')' ]\n       As you can see, the type of the field is not specified explicitly, but\n-      will always be that of the foreign table\u2019s primary key. With this syntax,\n+      will always be that of the foreign table's primary key. With this syntax,\n       the foreign table must have a single field for its primary key. GNATColl\n       does not force a specific order for the declaration of tables: if is\n-      valid to have a foreign key to a table that hasn\u2019t been declared yet.\n+      valid to have a foreign key to a table that hasn't been declared yet.\n       There is however a restriction if you use the model to create a sqlite\n       database (through the-createdbswitch ofgnatcoll_db2ada): in this case, a\n-      reference to a table that hasn\u2019t been defined yet may not be not through\n+      reference to a table that hasn't been defined yet may not be not through\n       a field marked as NOT NULL. This is a limitation of the sqlite backend\n       itself. The solution in this case is to reorder the declaration of\n       tables, or drop the NOT NULL constraint.\n       Another restriction is that a foreign key that is also a primary key must\n       reference a table that has already been defined. You need to reorder the\n       declaration of your tables to ensure this is the case.\n-      \u201creverse_name\u201d is the optional name that will be generated in the Ada\n+      \"reverse_name\" is the optional name that will be generated in the Ada\n       code for the reverse relationship, in the context ofGNATCOLL.SQL.ORM. If\n-      the \u201creverse_name\u201d is empty (the parenthesis are shown), no reverse\n+      the \"reverse_name\" is empty (the parenthesis are shown), no reverse\n       relationship is generated. If the parenthesis and the reverse_name are\n       both omitted, a default name is generated based on the name of the field.\n       The third column in the fields definition indicates the constraints of\n       the type. Multiple keywords can be used if they are separated by commas.\n-      Thus, \u201cNOT NULL, INDEX\u201d indicates a column that must be set by the user,\n+      Thus, \"NOT NULL, INDEX\" indicates a column that must be set by the user,\n       and for which an index is created to speed up look ups.\n-          o A primary key (\u201cPK\u201d)\n-          o The value must be defined (\u201cNOT NULL\u201d)\n-          o The value can be left undefined (\u201cNULL\u201d)\n-          o A unique constraint and index (\u201cUNIQUE\u201d)\n-          o An index should be created for that column (\u201cINDEX\u201d) to speed up\n+          o A primary key (\"PK\")\n+          o The value must be defined (\"NOT NULL\")\n+          o The value can be left undefined (\"NULL\")\n+          o A unique constraint and index (\"UNIQUE\")\n+          o An index should be created for that column (\"INDEX\") to speed up\n             the lookups.\n           o The automatic index created for a Foreign Key should not be created\n-            (\u201cNOINDEX\u201d). Every time a field references another table, GNATColl\n+            (\"NOINDEX\"). Every time a field references another table, GNATColl\n             will by default create an index for it, so that the ORM can more\n-            efficiently do a reverse query (from the target table\u2019s row find\n+            efficiently do a reverse query (from the target table's row find\n             all the rows in the current table that reference that target row).\n             This will in general provide more efficiency, but in some cases you\n             never intend to do the reverse query and thus can spare the extra\n             index.\n       The fourth column gives the default value for the field, and is given in\n       SQL syntax. Strings must be quoted with single quotes.\n       The fifth column contains documentation for the field (if any). This\n       documentation will be included in the generated code, so that IDEs can\n-      provide useful tooltips when navigating your application\u2019s code.\n+      provide useful tooltips when navigating your application's code.\n       After all the fields have been defined, you can specify extract\n       constraints on the table. In particular, if you have a foreign key to a\n       table that uses a tuple as its primary key, you can define that foreign\n       key on a new line, as:\n       FK ::= '|' \"FK:\" '|'
    • '|' *\n '|' * '|'\n For instance:\n@@ -276,15 +276,15 @@\n create. If left blank, a default name will be computed by GNATColl:\n | TABLE | tableA |\n | INDEX: | field1,field2,field3 | name |\n The same way the unique multi-column constraint and index can be created.\n The name is optional.\n TABLE | tableA |\n UNIQUE: | field1,field2,field3 | name |\n- Going back to the example we described earlier (_\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\be_\bx_\ba_\bm_\bp_\bl_\be), let\u2019s\n+ Going back to the example we described earlier (_\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\be_\bx_\ba_\bm_\bp_\bl_\be), let's\n describe the tables that are involved.\n The first table contains the customers. Here is its definition:\n | TABLE | customers | customer || The customer for the library\n |\n | id | AUTOINCREMENT | PK || Auto-generated id\n |\n | first | TEXT | NOT NULL || Customer's first name\n@@ -292,36 +292,36 @@\n | last | TEXT | NOT NULL, INDEX || Customer's last name\n |\n We highly recommend to set a primary key on all tables. This is a field\n whose value is unique in the table, and thus that can act as an\n identifier for a specific row in the table (in this case for a specific\n customer). We recommend using integers for these ids for efficiency\n reasons. It is possible that the primary key will be made of several\n- fields, in which case they should all have the \u201cPK\u201d constraint in the\n+ fields, in which case they should all have the \"PK\" constraint in the\n third column.\n A table with no primary key is still usable. The difference is in the\n code generated for the ORM (_\bT_\bh_\be_\b _\bO_\bb_\bj_\be_\bc_\bt_\b-_\bR_\be_\bl_\ba_\bt_\bi_\bo_\bn_\ba_\bl_\b _\bM_\ba_\bp_\bp_\bi_\bn_\bg_\b _\bl_\ba_\by_\be_\br_\b _\b(_\bO_\bR_\bM_\b)),\n since theDeleteoperation for this table will raise aProgram_Errorinstead\n- of doing the actual deletion (that\u2019s because there is no guaranteed\n+ of doing the actual deletion (that's because there is no guaranteed\n unique identifier for the element, so the ORM does not know which one to\n- delete \u2013 we do not depend on having unique internal ids on the table,\n+ delete -- we do not depend on having unique internal ids on the table,\n like some DBMS have). Likewise, the elements extracted from such a\n primary key-less table will not be cached locally in the session, and\n cannot be updated (only new elements can be created in the table).\n As we mentioned, the library contains two types of media, books and DVDs.\n Each of those has a title, an author. However, a book also has a number\n of pages and a DVD has a region where it can be viewed. There are various\n ways to represent this in a database. For illustration purposes, we will\n use table inheritance here: we will declare one abstract table (media)\n which contains the common fields, and two tables to represent the types\n of media.\n As we mentioned, a media can be borrowed by at most one customer, but a\n customer can have multiple media at any point in time. This is called a\n o\bon\bne\be-\b-t\bto\bo-\b-m\bma\ban\bny\by relationship. In SQL, this is in general described through\n- the use of a foreign key that goes from the table on the \u201cmany\u201d side. In\n+ the use of a foreign key that goes from the table on the \"many\" side. In\n this example, we therefore have a foreign key from media to customers. We\n also provide a name for the reverse relationship, which will become\n clearer when we describe the ORM interface.\n Here are the declarations:\n | ABSTRACT TABLE | media | media || The contents of the\n library |\n | id | AUTOINCREMENT | PK || Auto-generated id\n@@ -340,30 +340,30 @@\n \n | TABLE (media) | dvds | dvd | | The dvds in the library |\n | region | INTEGER | | 1 | |\n For this example, all this description is put in a file called\n dbschema.txt.\n *\b**\b**\b**\b**\b* 1\b1.\b.4\b4.\b. T\bTh\bhe\be g\bgn\bna\bat\btc\bco\bol\bll\bl_\b_d\bdb\bb2\b2a\bad\bda\ba t\bto\boo\bol\bl_\b?\b\uf0c1 *\b**\b**\b**\b**\b*\n As stated in the introduction, one of the goals of this library is to make sure\n-the application\u2019s code follows changes in the schema of your database.\n+the application's code follows changes in the schema of your database.\n To reach this goal, an external tool, gnatcoll_db2ada is provided with\n GNATColl, and should be spawned as the first step of the build process, or at\n least whenever the database schema changes. It generates an Ada package\n (Databaseby default) which reflects the current schema of the database.\n This tool supports a number of command line parameters (the complete list of\n which is available through the -h switch). The most important of those switches\n are:\n -\b-d\bdb\bbh\bho\bos\bst\bt h\bho\bos\bst\bt, -\b-d\bdb\bbn\bna\bam\bme\be n\bna\bam\bme\be, -\b-d\bdb\bbu\bus\bse\ber\br u\bus\bse\ber\br, -\b-d\bdb\bbp\bpa\bas\bss\bsw\bwd\bd p\bpa\bas\bss\bsw\bwd\bd, -\b-d\bdb\bbt\bty\byp\bpe\be t\bty\byp\bpe\be\n These parameters specify the connection parameters for the database. To\n find out the schema, gnatcoll_db2ada can connect to an existing database\n (_\bD_\ba_\bt_\ba_\bb_\ba_\bs_\be_\b _\bs_\bc_\bh_\be_\bm_\ba). The user does not need to have write permission on the\n database, since all queries are read-only.\n -\b-d\bdb\bbm\bmo\bod\bde\bel\bl f\bfi\bil\ble\be\n- This parameter can replace the above-dbname,\u2026 It specifies the name of a\n- text file that contains the description of the database, therefore\n+ This parameter can replace the above-dbname,... It specifies the name of\n+ a text file that contains the description of the database, therefore\n avoiding the need for already having a database up-and-running to\n generate the Ada interface.\n The format of this text file was described in the previous section.\n This switch is not compatible with-enumand-varsthat really need an access\n to the database.\n -\b-a\bap\bpi\bi P\bPK\bKG\bG\n This is the default behavior if you do not specify-textor-createdb. This\n@@ -385,20 +385,20 @@\n initial data (if-loadwas specified) from your application, without\n requiring access to the external files that define the schema and the\n initial data.\n -\b-e\ben\bnu\bum\bm t\bta\bab\bbl\ble\be,\b,i\bid\bd,\b,n\bna\bam\bme\be,\b,p\bpr\bre\bef\bfi\bix\bx,\b,b\bba\bas\bse\be\n This parameter can be repeated several times if needed. It identifies one\n of the special tables of the database that acts as an enumeration type.\n It is indeed often the case that one or more tables in the database have\n- a role similar to Ada\u2019s enumeration types, i.e. contains a list of values\n+ a role similar to Ada's enumeration types, i.e. contains a list of values\n for information like the list of possible priorities, a list of\n- countries,\u2026 Such lists are only manipulated by the maintainer of the\n+ countries,... Such lists are only manipulated by the maintainer of the\n database, not interactively, and some of their values have impact on the\n- application\u2019s code (for instance, if a ticket has an urgent priority, we\n- need to send a reminder every day \u2013 but the application needs to know\n+ application's code (for instance, if a ticket has an urgent priority, we\n+ need to send a reminder every day -- but the application needs to know\n what an urgent priority is). In such a case, it is convenient to generate\n these values as constants in the generated package. The output will be\n similar to:\n subtype Priority_Id is Integer;\n Priority_High : constant Priority_Id := 3;\n Priority_Medium : constant Priority_Id := 2;\n Priority_Low : constant Priority_Id := 1;\n@@ -414,15 +414,15 @@\n To generate the above Ada code, you need to pass the following parameter\n to gnatcoll_db2ada:\n -enum ticket_priorities,Priority,Name,Priority,Integer\n First word in the parameter is the table name where the data to generate\n constants is stored. Second word is the field name in the table where the\n Ada constant value is stored. The third word is the field where the last\n part the Ada constant name is stored. The forth word is the prefix to add\n- in front of the third word field value to generate the Ada constant\u2019s\n+ in front of the third word field value to generate the Ada constant's\n name. The last optional parameter should be eitherInteger(default)\n orString, which influences the way how the Ada constant value is going to\n be generated (surrounded or not by quotes).\n -\b-e\ben\bnu\bum\bm-\b-i\bim\bma\bag\bge\be\n If specified in addition to the-enumswitch, then a function is generated\n for eachInteger-valued enum that converts numeric values to the\n corresponding name as a string.\n@@ -448,15 +448,15 @@\n We could extract the id that helps detect unassigned tickets with the\n following command line:\n -var no_assign_id,staff,staff_id,\"login='unassigned'\",\"help\"\n which generates:\n No_Assigne_Id : constant := 0;\n -- help\n The application should use this constant rather than some hard-coded\n- string\u201cunassigned\u201dor a named constant with the same value. The reason is\n+ string\"unassigned\"or a named constant with the same value. The reason is\n that presumably the login will be made visible somewhere to the user, and\n we could decide to change it (or translate it to another language). In\n such a case, the application would break. On the other hand, using the\n constant0which we just extracted will remain valid, whatever the actual\n text we display for the user.\n -\b-o\bor\brm\bm P\bPK\bKG\bG\n This will generate two files (PKG.ads and PKG.adb) that\n@@ -532,25 +532,25 @@\n *\b**\b**\b**\b* 1\b1.\b.4\b4.\b.2\b2.\b. d\bda\bat\bta\bab\bba\bas\bse\be i\bin\bnt\btr\bro\bos\bsp\bpe\bec\bct\bti\bio\bon\bn i\bin\bn A\bAd\bda\ba_\b?\b\uf0c1 *\b**\b**\b**\b*\n As described above, the-createdbswitch makes it possible to create a database\n (or at least its schema). This operation can also be performed directly from\n your Ada code by using the services provided in theGNATCOLL.SQL.Inspectpackage.\n In particular, there are services for reading the schema of a database either\n from a file or from a live database, just asgnatcoll_db2adadoes.\n This results in a structure in memory that you can use to find out which are\n-the tables, what are their fields, their primary keys,\u2026\n+the tables, what are their fields, their primary keys,...\n It is also possible to dump this schema to a text file (with the same format as\n expected by-dbmodel), or more interestingly to output the SQL statements that\n are needed to create the tables in a database. In the case of Sqlite, creating\n-a table will also create the database file if it doesn\u2019t exist yet, so no\n+a table will also create the database file if it doesn't exist yet, so no\n special rights are needed.\n This input/output mechanism is implemented through an abstractSchema_IOtagged\n type, with various concrete implementations (eitherFile_Schema_IOto read or\n write from/to a file, orDB_Schema_IOto read or write from/to a database).\n See the specs for more detail on these subprograms.\n-*\b**\b**\b**\b* 1\b1.\b.4\b4.\b.3\b3.\b. B\bBa\bac\bck\bk t\bto\bo t\bth\bhe\be l\bli\bib\bbr\bra\bar\bry\by e\bex\bxa\bam\bmp\bpl\ble\be?\b\u2026_\b?\b\uf0c1 *\b**\b**\b**\b*\n+*\b**\b**\b**\b* 1\b1.\b.4\b4.\b.3\b3.\b. B\bBa\bac\bck\bk t\bto\bo t\bth\bhe\be l\bli\bib\bbr\bra\bar\bry\by e\bex\bxa\bam\bmp\bpl\ble\be.\b..\b..\b._\b?\b\uf0c1 *\b**\b**\b**\b*\n In the previous section, we have described our database schema in a text file.\n We will now perform two operations:\n * Create an empty database\n This should of course only be done once, not every time you run your\n application:\n gnatcolldbada -dbtype=sqlite -dbname=library.db -dbmodel=dbschema.txt -\n createdb\n@@ -596,15 +596,15 @@\n can be done to database at run time.\n To connect to a DBMS, you need to specify the various connection parameters.\n This is done via aGNATCOLL.SQL.Exec.Database_Descriptionobject. The creation of\n this object depends on the specific DBMS you are connecting to (and this is the\n only part of your code that needs to know about the specific system). The\n packagesGNATCOLL.SQL.PostgresandGNATCOLL.SQL.Sqlitecontain aSetupfunction,\n whose parameters depend on the DBMS. They provide full documentation for their\n-parameters. Let\u2019s take a simple example from sqlite:\n+parameters. Let's take a simple example from sqlite:\n with GNATCOLL.SQL.Sqlite; -- or Postgres\n declare\n DB_Descr : GNATCOLL.SQL.Exec.Database_Description;\n begin\n DB_Descr := GNATCOLL.SQL.Sqlite.Setup (\"dbname.db\");\n end\n At this point, no connection to the DBMS has been done, and no information was\n@@ -657,15 +657,15 @@\n In all three cases, the resulting database connection needs to be freed when\n you no longer needed (which might be when your program terminates if you are\n using pools) to avoid memory leaks. Nothing critical will appear if you do not\n close, though, because the transactions to the DBMS server are saved every time\n you callCommitin any case. So the code would end with:\n Free (DB); -- for all connections you have opened\n Free (DB_Descr);\n-At this point, there still hasn\u2019t been any connection to the DBMS. This will be\n+At this point, there still hasn't been any connection to the DBMS. This will be\n done the first time a query is executed. If for some reason the connection to\n the DBMS server is lost, GNATColl will automatically attempt to reconnect a\n number of times before it gives up. This might break if there was an ongoing\n SQL transaction, but simplifies your code since you do not have to handle\n reconnection when there was a network failure, for instance.\n As we saw before, the database interface can be used in multi-tasking\n applications. In such a case, it is recommended that each thread has its own\n@@ -686,40 +686,40 @@\n One can connect to the database with an external tool (a web interface\n when the DBMS provides one for instance), or via a command line tool\n (psqlfor PostgreSQL orsqlite3for Sqlite), and start inserting data\n manually. This shows one of the nice aspects of using a standard DBMS for\n your application: you can alter the database (for instance to do minor\n fixes in the data) with a lot of external tools that were developed\n specifically for that purpose and that provide a nice interface. However,\n- this is also tedious and error prone, and can\u2019t be repeat easily every\n+ this is also tedious and error prone, and can't be repeat easily every\n time we recreate the database (for instance before running automatic\n tests).\n * UsingGNATCOLL.SQL.EXEC\n As we will describe later, GNATColl contains all the required machinery\n for altering the contents of the database and creating new objects.\n UsingGNATCOLL.SQL.ORMthis can also be done at a high-level and completely\n hide SQL.\n * Loading a data file\n A lot of frameworks call such a file that contains initial data a\n- \u201cfixture\u201d. We will use this technique as an example. At the Ada level,\n+ \"fixture\". We will use this technique as an example. At the Ada level,\n this is a simple call toGNATCOLL.SQL.Inspect.Load_Data. The package\n contains a lot more than just this subprogram (_\bT_\bh_\be_\b _\bg_\bn_\ba_\bt_\bc_\bo_\bl_\bl_\b__\bd_\bb_\b2_\ba_\bd_\ba_\b _\bt_\bo_\bo_\bl):\n declare\n File : GNATCOLL.VFS.Virtual_File := Create (\"fixture.txt\");\n DB : Database_Connection; -- created earlier\n begin\n GNATCOLL.SQL.Inspect.Load_Data (DB, File);\n DB.Commit;\n end;\n The format of this file is described just below.\n As we mentioned, GNATColl can load data from a file. The format of this file is\n similar to the one that describes the database schema. It is a set of ASCII\n tables, each of which describes the data that should go in a table (it is valid\n to duplicate tables). Each block starts with two lines: The first one has two\n-mandatory columns, the first of which contains the text \u201cTABLE\u201d, and the second\n+mandatory columns, the first of which contains the text \"TABLE\", and the second\n contains the name of the table you want to fill. The second line should contain\n as many columns as there are fields you want to set. Not all the fields of the\n table need to have a corresponding column if you want to set their contents to\n NULL (provided, of course, that your schema allows it). For instance, we could\n add data for our library example as such:\n | TABLE | customers | |\n | id | first | last |\n@@ -744,15 +744,15 @@\n | TABLE | dvds | | |\n | title | author | region | borrowed_by(&last) |\n |--------------+-----------+--------+--------------------|\n | The Birds | Hitchcock | 1 | &Smith |\n | The Dictator | Chaplin | 3 | &Dupont |\n Here, the title of the column indicates that any value in this column might be\n a reference to thecustomers.lastvalue. Values which start with an ampersand\n-(\u201d&\u201d) will therefore be looked up incustomers.last, and theidof the\n+(\"&\") will therefore be looked up incustomers.last, and theidof the\n corresponding customer will be inserted in thedvdstable. It would still be\n valid to use directly customer ids instead of references, this is just an extra\n flexibility that the references give you to make your fixtures more readable.\n However, if we are using such references we need to provide the database schema\n toLoad_Dataso that it can write the proper queries. This is done by using other\n services of theGNATCOLL.SQL.Inspectpackage.\n The code for our example would be:\n@@ -782,23 +782,23 @@\n (Fields => Max (Ticket_Priorities.Priority)\n & Ticket_Priorities.Category,\n From => Ticket_Priorities,\n Where => Ticket_Priorities.Name /= \"low\",\n Group_By => Ticket_Priorities.Category);\n end;\n The above example will return, for each type of priority (internal or customer)\n-the highest possible value. The interest of this query is left to the user\u2026\n+the highest possible value. The interest of this query is left to the user...\n This is very similar to an actual SQL query. Field and table names come from\n the package that was automatically generated by thegnatcoll_db2adatool, and\n therefore we know that our query is only referencing existing fields. The\n syntactic correctness is ensured by standard Ada rules. TheSQL_Selectaccepts\n several parameters corresponding to the usual SQL attributes likeGROUP\n BY,HAVING,ORDER BYandLIMIT.\n TheFromparameter could be a list of tables if we need to join them in some\n-ways. Such a list is created with the overridden\u201c&\u201doperator, just as for fields\n+ways. Such a list is created with the overridden\"&\"operator, just as for fields\n which you can see in the above example. GNATColl also provides\n aLeft_Joinfunction to join two tables when the second might have no matching\n field (see the SQL documentation).\n Similar functions exist forSQL_Insert,SQL_UpdateandSQL_Delete. Each of those is\n extensively documented in the gnatcoll-sql.ads file.\n It is worth noting that we do not have to write the query all at once. In fact,\n we could build it depending on some other criteria. For instance, imagine we\n@@ -833,16 +833,16 @@\n fields referenced in the query), nor the list of fields in theGROUP BYclause,\n which once again can be computed automatically by looking at those fields that\n are not used in a SQL aggregate function. This auto-completion helps the\n maintenance of those queries.\n There is another case where GNATColl makes it somewhat easier to write the\n queries, and that is to handle joins between tables. If your schema was build\n with foreign keys, GNATColl can take advantage of those.\n-Going back to our library example, let\u2019s assume we want to find out all the\n-books that were borrowed by the user \u201cSmith\u201d. We need to involve two tables\n+Going back to our library example, let's assume we want to find out all the\n+books that were borrowed by the user \"Smith\". We need to involve two tables\n (BooksandCustomers), and provide a join between them so that the DBMS knows how\n to associate the rows from one with the rows from the other. Here is a first\n example for such a query:\n Q := SQL_Select\n (Fields => Books.Title & Books.Pages,\n From => Books & Customers,\n Where => Books.Borrowed_By = Customers.Id\n@@ -851,15 +851,15 @@\n involved tables on its own. We thus write the simpler:\n Q := SQL_Select\n (Fields => Books.Title & Books.Pages,\n Where => Books.Borrowed_By = Customers.Id\n and Customers.Last = \"Smith\");\n There is one more things we can do to simplify the query and make it more solid\n if the schema of the database changes. For instance, when a table has a primary\n-key made up of several fields, we need to make sure we always have an \u201c=\u201d\n+key made up of several fields, we need to make sure we always have an \"=\"\n statement in the WHERE clause for all these fields between the two tables. In\n our example above, we could at some point modify the schema so that the primary\n key forcustomersis multiple (this is unlikely in this example of course). To\n avoid this potential problems and make the query somewhat easier to read, we\n can take advantage of theFKsubprograms generated bygnatcoll_db2ada. Using the\n Ada05 dotted notation for the call, we can thus write:\n Q := SQL_Select\n@@ -886,15 +886,15 @@\n case, you can useExecuteinstead ofFetch. This is the case when you execute\n anINSERTorUPDATEstatement for instance. UsingExecuteavoids the need to declare\n the local variableR.\n If for some reason the connection to the database is no longer valid (a\n transient network problem for instance), GNATColl will attempt to reconnect and\n re-execute your query transparently, so that your application does not need to\n handle this case.\n-We\u2019ll describe later (_\bG_\be_\bt_\bt_\bi_\bn_\bg_\b _\br_\be_\bs_\bu_\bl_\bt_\bs) how to analyze the result of the query.\n+We'll describe later (_\bG_\be_\bt_\bt_\bi_\bn_\bg_\b _\br_\be_\bs_\bu_\bl_\bt_\bs) how to analyze the result of the query.\n Some versions ofFetchhave an extra parameterUse_Cache, set toFalseby default.\n If this parameter is true, and the exact same query has already been executed\n before, its result will be reused without even contacting the database server.\n The cache is automatically invalidated every hour in any case. This cache is\n mostly useful for tables that act like enumeration types, as we have seen\n before when discussing the-enumparameter to gnatcoll_db2ada. In this case, the\n contents of the table changes very rarely, and the cache can provide important\n@@ -959,15 +959,15 @@\n \n Q : constant SQL_Query :=\n SQL_Select\n (Fields => Data.Id & Data.Name\n From => Data,\n Where => Data.Id = Integer_Param (1));\n GNATColl provides a number of functions (one per type of field) to indicate\n-that the value is currently unbound.Integer_Param,Text_Param,Boolean_Param,\u2026\n+that the value is currently unbound.Integer_Param,Text_Param,Boolean_Param,...\n All take a single argument, which is the index of the corresponding parameter.\n A query might need several parameters, and each should have a different index.\n On the other hand, the same parameter could be used in several places in the\n query.\n Although the query above could be executed as is by providing the values for\n the parameters, it is more efficient, as we mentioned at the beginning, to\n compile it on the server. In theory, this preparation is done within the\n@@ -988,35 +988,35 @@\n locally in a subprogram. APrepared_Statementis a reference counted type,\n that will automatically free the memory on the server when it goes out of\n scope.\n * Here, we prepared the statement on the server. If we had\n specifiedOn_Server => False, we would still have sped things up, since Q\n would be converted to a string that can be sent to the DBMS, and from\n then on reused that string (note that this conversion is specific to each\n- DBMS, since they don\u2019t always represent things the same way, in\n+ DBMS, since they don't always represent things the same way, in\n particular parameters, as we have seen above). Thus every time you use P\n you save the time of converting from the GNATColl tree representation of\n the query to a string for the DBMS.\n Now that we have a prepared statement, we can simply execute it. If the\n statement does not require parameters, the usualFetchandExecutesubprograms have\n versions that work exactly the same with prepared statements. They also accept\n aParamsparameter that contains the parameter to pass to the server. A number\n-of\u201c+\u201doperators are provided to create those parameters:\n+of\"+\"operators are provided to create those parameters:\n declare\n F : Forward_Cursor;\n begin\n F.Fetch (DB, P, Params => (1 => +2));\n F.Fetch (DB, P, Params => (1 => +3));\n end;\n-Note that for string parameters, the\u201c+\u201doperator takes an access to a string.\n+Note that for string parameters, the\"+\"operator takes an access to a string.\n This is for efficiency, to avoid allocating memory and copying the string, and\n is safe because the parameters are only needed whileFetchexecutes (even for\n aForward_Cursor.\n Back to our library example. We showed earlier how to write a query that\n-retrieves the books borrowed by customer \u201cSmith\u201d. We will now make this query\n+retrieves the books borrowed by customer \"Smith\". We will now make this query\n more general: given a customer name, return all the books he has borrowed.\n Since we expect to use this often, we will prepare it on the server (in real\n life, this query is of little interest since the customer name is not unique,\n we would instead use a query that takes the id of the customer). In general we\n would create a global variable with:\n Borrowed : constant Prepared_Statement := Prepare\n (SQL_Select\n@@ -1078,15 +1078,15 @@\n value in a specific row and a specific column.\n We mentioned earlier there was no way to go back to a row you fetched\n previously except by executing the query again. This is in fact only true if\n you use aForward_Cursorto fetch the results.\n But GNATColl provides another notion, aDirect_Cursor. In this case, it fetches\n all the rows in memory when the query executes (thus it needs to allocate more\n memory to save every thing, which can be costly if the query is big). This\n-behavior is supported natively byPostgreSQL, but doesn\u2019t exist withsqlite, so\n+behavior is supported natively byPostgreSQL, but doesn't exist withsqlite, so\n GNATColl will simulate it as efficiently as possible. But it will almost always\n be faster to use aForward_Cursor.\n In exchange for this extra memory overhead, you can now traverse the list of\n results in both directions, as well as access a specific row directly. It is\n also possible to know the number of rows that matched (something hard to do\n with aForward_Cursorsince you would need to traverse the list once to count,\n and then execute the query again if you need the rows themselves).\n@@ -1162,18 +1162,18 @@\n with other parts ofGNATCOLL.SQL.\n *\b**\b**\b**\b**\b* 1\b1.\b.1\b12\b2.\b. Q\bQu\bue\ber\bry\by l\blo\bog\bgs\bs_\b?\b\uf0c1 *\b**\b**\b**\b**\b*\n TheGNATCOLL.Tracespackage provides facilities to add logging. The database\n interface uses this module to log the queries that are sent to the server.\n If you activate traces in your application, the user can then activate one of\n the following trace handles to get more information on the exchange that exists\n between the database and the application. As we saw before, the output of these\n-traces can be sent to the standard output, a file, the system logs,\u2026\n+traces can be sent to the standard output, a file, the system logs,...\n The following handles are provided:\n * SQL.ERROR This stream is activated by default. Any error returned by the\n- database (connection issues, failed transactions,\u2026) will be logged on\n+ database (connection issues, failed transactions,...) will be logged on\n this stream\n * SQL This stream logs all queries that are not SELECT queries, i.e. mostly\n all queries that actually modify the database\n * SQL.SELECT This stream logs all select queries. It is separated from SQL\n because very often you will be mostly interested in the queries that\n impact the database, and logging all selects can generate a lot of\n output.\n@@ -1182,15 +1182,15 @@\n with GNATCOLL.Traces; use GNATCOLL.Traces;\n procedure Main is\n begin\n GNATCOLL.Traces.Parse_Config_File (\".gnatdebug\");\n ... -- code as before\n GNATCOLL.Traces.Finalize; -- reclaim memory\n and then create a .gnatdebug in the directory from which we launch our\n-executable. This file would contain a single line containing \u201c+\u201d to activate\n+executable. This file would contain a single line containing \"+\" to activate\n all log streams, or the following to activate only the subset of fields related\n to SQL:\n SQL=yes\n SQL.SELECT=yes\n SQL.LITE=yes\n *\b**\b**\b**\b**\b* 1\b1.\b.1\b13\b3.\b. W\bWr\bri\bit\bti\bin\bng\bg y\byo\bou\bur\br o\bow\bwn\bn c\bcu\bur\brs\bso\bor\brs\bs_\b?\b\uf0c1 *\b**\b**\b**\b**\b*\n The cursor interface we just saw is low-level, in that you get access to each\n@@ -1211,15 +1211,15 @@\n type My_Cursor is new Forward_Cursor with null record;\n function Element (Self : My_Cursor) return My_Row;\n function Do_Query (DB, ...) return My_Cursor;\n The idea is that you create a function that does the query for you (based on\n some parameters that are not shown here), and then returns a cursor over the\n resulting set of rows. For each row, you can use theElementfunction to get an\n Ada record for easier manipulation.\n-Let\u2019s first see how these types would be used in practice:\n+Let's first see how these types would be used in practice:\n declare\n C : My_Cursor := Do_Query (DB, ...);\n begin\n while Has_Row (C) loop\n Put_Line (\"Id = \" & Element (C).Id);\n Next (C);\n end loop;\n@@ -1281,15 +1281,15 @@\n *\b**\b**\b**\b**\b* 1\b1.\b.1\b14\b4.\b. T\bTh\bhe\be O\bOb\bbj\bje\bec\bct\bt-\b-R\bRe\bel\bla\bat\bti\bio\bon\bna\bal\bl M\bMa\bap\bpp\bpi\bin\bng\bg l\bla\bay\bye\ber\br (\b(O\bOR\bRM\bM)\b)_\b?\b\uf0c1 *\b**\b**\b**\b**\b*\n GNATColl provides a high-level interface to manipulate persistent objects\n stored in a database, using a common paradigm called an object-relational\n mapping. Such mappings exist for most programming languages. In the design of\n GNATColl, we were especially inspired by the python interface\n indjangoandsqlalchemy, although the last two rely on dynamic run time\n introspection and GNATColl relies on code generation instead.\n-This API is still compatible withGNATCOLL.SQL. In fact, we\u2019ll show below cases\n+This API is still compatible withGNATCOLL.SQL. In fact, we'll show below cases\n where the two are mixed. It can also be mixed withGNATCOLL.SQL.Exec, although\n this might be more risky. Communication with the DBMS is mostly transparent in\n the ORM, and it uses various caches to optimize things and make sure that if\n you modify an element the next query(ies) will also return it. If you\n useGNATCOLL.SQL.Execdirectly you are bypassing this cache so you risk getting\n inconsistent results in some cases.\n In ORM, a table is not manipulated directly. Instead, you manipulate objects\n@@ -1305,15 +1305,15 @@\n change thebookstable to be:\n | TABLE (media) | books | book | | The books in the\n library |\n | pages | INTEGER | | 100 |\n |\n | borrowed_by | FK customers(borrowed_books) | NULL | | Who borrowed the\n media |\n-Let\u2019s thus start by generating this code. We can replace the command we ran\n+Let's thus start by generating this code. We can replace the command we ran\n earlier (with the-apiswitch) with one that will also generate the ORM API:\n gnatcoll_db2ada -dbmode dbschema.txt -api Database -orm ORM\n The ORM provides a pool of database connections through the\n packageGNATCOLL.SQL.Sessions. A session therefore acts as a wrapper around a\n connection, and provides a lot more advanced features that will be described\n later. The first thing to do in the code is to configure the session pool.\n TheSetupprocedure takes a lot of parameters to make sessions highly\n@@ -1325,15 +1325,15 @@\n (Descr => GNATCOLL.SQL.Sqlite.Setup (\"library.db\"),\n Max_Sessions => 2);\n The first parameter is the sameDatabase_Descriptionwe saw earlier (_\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bn_\bg\n _\bt_\bo_\b _\bt_\bh_\be_\b _\bd_\ba_\bt_\ba_\bb_\ba_\bs_\be), but it will be freed automatically by the sessions package,\n so you should not free it yourself.\n Once configure, we can now request a session. Through a session, we can perform\n queries on the database, make objects persistent, write the changes back to the\n-database,\u2026. We configured the session pool to have at most 2 sessions. The\n+database,.... We configured the session pool to have at most 2 sessions. The\n first time we callGet_New_Session, a new session will be created in the pool\n and marked as busy. While you have a reference to it in your code (generally as\n a local variable), the session belongs to this part of the code. When the\n session is no longer in scope, it is automatically released to the pool to be\n reused for the next call toGet_New_Session. If you callGet_New_Sessiona second\n time while some part of your code holds a session (for instance in a different\n task), a new session will be created. But if you do that a third time while the\n@@ -1341,17 +1341,17 @@\n sessions is released to the pool.\n This technique ensures optimal use of the resources: we avoid creating a new\n session every time (with the performance cost of connecting to the database),\n but also avoid creating an unlimited number of sessions which could saturate\n the server. Since the sessions are created lazily the first time they are\n needed, you can also configure the package with a large number of sessions with\n a limited cost.\n-Let\u2019s then take a new session in our code:\n+Let's then take a new session in our code:\n Session : constant Session_Type := Get_New_Session;\n-and let\u2019s immediately write our first simple query. A customer comes at the\n+and let's immediately write our first simple query. A customer comes at the\n library, handles his card and we see his id (1). We need to look up in the\n database to find out who he is. Fortunately, there is no SQL to write for this:\n C : ORM.Detached_Customer'Class := Get_Customer (Session, Id => 1);\n The call toGet_Customerperforms a SQL query transparently, using prepared\n statements for maximum efficiency. This results in aCustomerobject.\n ORMis the package that was generated automatically bygnatcoll_db2ada. For each\n table in the database, it generates a number of types:\n@@ -1361,15 +1361,15 @@\n table. Such an object is returned by a cursor, similarly to what was\n described in the previous section (_\bW_\br_\bi_\bt_\bi_\bn_\bg_\b _\by_\bo_\bu_\br_\b _\bo_\bw_\bn_\b _\bc_\bu_\br_\bs_\bo_\br_\bs). This object\n is no longer valid as soon as the cursor moves to the next row (in the\n currently implementation, the object will describe the next row, but it\n is best not to rely on this). As a benefit, this object is light weight\n and does not make a copy of the value of the fields, only reference the\n memory that is already allocated for the cursor.\n- This object redefines the equality operator (\u201c=\u201d) to compare the primary\n+ This object redefines the equality operator (\"=\") to compare the primary\n key fields to get expected results.\n * Detached_Customer\n A detached object is very similar to theCustomerobject, but it will\n remain valid even if the cursor moves or is destroyed. In fact, the\n object has made a copy of the value for all of its fields. This object is\n heavier than aCustomer, but sometimes easier to manager. If you want to\n store an object in a data structure, you must always store a detached\n@@ -1389,15 +1389,15 @@\n * Direct_Customer_List\n This type extends aDirect_Cursor. It also adds aElementoperation that\n returns aCustomerelement.\n * Customers_Managers\n This type is the base type to perform queries on the DBMS. A manager\n provides a number of primitive operations which end up creating a SQL\n query operation in the background, without making that explicit.\n- Let\u2019s first write a query that returns all books in the database:\n+ Let's first write a query that returns all books in the database:\n declare\n M : Books_Managers := All_Books;\n BL : Book_List := M.Get (Session);\n B : Book;\n begin\n while BL.Has_Row loop\n B := BL.Element;\n@@ -1405,15 +1405,15 @@\n Put_Line (\" Borrowed by: \" & B.Borrowed_By.Last);\n BL.Next;\n end loop;\n end;\n The managerMcorresponds to a query that returns all the books in the\n database. The second line then executes the query on the database, and\n returns a list of books. We then traverse the list. Note how we access\n- the book\u2019s title by calling a function, rather than by the index of a\n+ the book's title by calling a function, rather than by the index of a\n field as we did withGNATCOLL.SQL.Execwith Value(B, 0). The code is much\n less fragile this way.\n The line that callsBorrowed_Bywill execute an additional SQL query for\n each book. This might be inefficient if there is a large number of books.\n We will show later how this can be optimized.\n The manager however has a lot more primitive operations that can be used\n to alter the result. Each of these primitive operations returns a\n@@ -1423,15 +1423,15 @@\n Here are those operations:\n o GetandGet_Direct\n As seen in the example above, these are the two functions that\n execute the query on the database, and returns a list of objects\n (respectively aCustomer_Listand aDirect_Customer_List).\n o Distinct\n Returns a copy of the manager that does not return twice a row with\n- the same data (in SQL, this is the \u201cDISTINCT\u201d operator)\n+ the same data (in SQL, this is the \"DISTINCT\" operator)\n o Limit(Count : Natural; From : Natural := 0)\n Returns a copy of the manager that returns a subset of the results,\n for instance the firstCountones.\n o Order_By(By : SQL_Field_List)\n Returns a copy of the manager that sorts the results according to a\n criteria. The criteria is a list of field as was defined\n inGNATCOLL.SQL. We can for instance returns the list of books\n@@ -1451,15 +1451,15 @@\n explained in previous sections, and we would write:\n M : Books_Managers := All_Books.Filter (Condition => Books.Pages <\n 50);\n More complex conditions are possible, involving other tables.\n Currently, the ORM does not have a very user-friendly interface for\n those, but you can always do this by falling back partially to SQL.\n For instance, if we want to retrieve all the books borrowed by user\n- \u201cSmith\u201d, we need to involve theCustomerstable, and thus make a join\n+ \"Smith\", we need to involve theCustomerstable, and thus make a join\n with theBookstable. In the future, we intend to make this join\n automatic, but for now you will need to write:\n M : Books_Managers := All_Books.Filter\n (Books.FK (Customers)\n and Customers.Last = \"Smith\");\n \n -- SQL query: SELECT books.pages, books.borrowed_by, books.id,\n@@ -1487,15 +1487,15 @@\n If however you then callB.Borrowed_By.Addressthis will result in a\n query. So if you pass 2 forDepththe data for book, customers and\n addresses will be retrieved.\n The second parameter related to efficiency. When a foreign key was\n mentioned asNOT NULLin the schema, we know it is always pointing to\n an existing object in another table.Select_Relatedwill always\n retrieve such objects. If, however, the foreign key can be null,\n- i.e. there isn\u2019t necessarily a corresponding object in the other\n+ i.e. there isn't necessarily a corresponding object in the other\n table, the SQL query needs to use aLEFT JOIN, which is less\n efficient. By default, GNATColl will not retrieve such fields\n unlessFollow_Left_Joinwas set to True.\n In our example, a book is not necessarily borrowed by a customer,\n so we need to follow the left joins:\n M : Books_Managers := All_Books.Filter\n (Books.FK (Customers)\n@@ -1519,19 +1519,19 @@\n -- SQL: SELECT books.pages, books.borrowed_by, books.id, books.title,\n -- books.author, books.published FROM books\n -- WHERE books.borrowed_by=1\n Borrowed_Booksis a function that was generated because there was areverse_name.\n It returns aBooks_Managers, so we could in fact further filter the list of\n borrowed books with the same primitive operations we just saw. As you can see,\n the resulting SQL is optimal.\n-Let\u2019s optimize further the initial query. We have hard-coded the customer name,\n+Let's optimize further the initial query. We have hard-coded the customer name,\n but in fact we could be using the same subprograms we were using for prepared\n statements (_\bP_\br_\be_\bp_\ba_\br_\be_\bd_\b _\bq_\bu_\be_\br_\bi_\be_\bs), and even prepare the query on the server for\n maximum efficiency. Since our application is likely to use this query a lot,\n-let\u2019s create a global variable:\n+let's create a global variable:\n M : constant Books_Managers := All_Books.Filter\n (Books.FK (Customers)\n and Customers.Id = Integer_Param (1))\n .Select_Related (1, Follow_Left_Join => True);\n \n MP : constant ORM_Prepared_Statement :=\n M.Prepare (On_Server => True);\n@@ -1542,16 +1542,16 @@\n BL : Book_List := MP.Get (Session, Params => (1 => Smith_Id));\n The last call toGetis very efficient, with timing improvements similar to the\n ones we discussed on the session about prepared statements (_\bP_\br_\be_\bp_\ba_\br_\be_\bd_\b _\bq_\bu_\be_\br_\bi_\be_\bs).\n *\b**\b**\b**\b**\b* 1\b1.\b.1\b15\b5.\b. M\bMo\bod\bdi\bif\bfy\byi\bin\bng\bg o\bob\bbj\bje\bec\bct\bts\bs i\bin\bn t\bth\bhe\be O\bOR\bRM\bM_\b?\b\uf0c1 *\b**\b**\b**\b**\b*\n The ORM is much more than writing queries. Once the objects are persistent,\n they can also be simplify modified, and they will be saved in the database\n transparently.\n-Let\u2019s start with a simple example. In the previous section, we retrieve an\n-objectCrepresenting a customer. Let\u2019s change his name, and make sure the change\n+Let's start with a simple example. In the previous section, we retrieve an\n+objectCrepresenting a customer. Let's change his name, and make sure the change\n is in the database:\n C := Get_Customer (Session, 1);\n C.Set_Last (\"Smith\");\n C.Set_First (\"Andrew\");\n Session.Commit;\n A reasonable way to modify the database. However, this opens a can of complex\n issues that need to be dealt with.\n@@ -1601,45 +1601,45 @@\n while CL.Has_Row loop\n Put_Line (CL.Element.Last);\n CL.Next;\n end loop;\n The above example usesCL.Element, which is a light-weightCustomerobject. Such\n objects will only see the in-memory changes if you have setFlush_Before_Queryto\n true when you configured the sessions in the call\n-toGNATCOLL.SQL.Sessions.Setup. Otherwise, it will always return what\u2019s really\n+toGNATCOLL.SQL.Sessions.Setup. Otherwise, it will always return what's really\n in the database.\n If the example was usingDetached_Customerobject (by callingCL.Element.Detachfor\n instance) then GNATColl looks up in its internal cache and returns the cached\n element when possible. This is a subtlety, but this is because anCustomeronly\n exists as long as its cursor, and therefore cannot be cached in the session. In\n practice, theFlush_Before_Queryshould almost always be true and there will be\n not surprising results.\n *\b**\b**\b**\b**\b* 1\b1.\b.1\b16\b6.\b. O\bOb\bbj\bje\bec\bct\bt f\bfa\bac\bct\bto\bor\bri\bie\bes\bs i\bin\bn O\bOR\bRM\bM_\b?\b\uf0c1 *\b**\b**\b**\b**\b*\n Often, a database table is used to contain objects that are semantically of a\n different kind. In this section, we will take a slightly different example from\n the library. We no longer store the books and the dvds in separate tables.\n Instead, we have one singlemediatable which contains the title and the author,\n as well as a new fieldkindwhich is either 0 for a book or 1 for a dvd.\n-Let\u2019s now look at all the media borrowed by a customer:\n+Let's now look at all the media borrowed by a customer:\n C : constant Customer'Class := Get_Customer (Session, Id => 1);\n ML : Media_List := C.Borrowed_Media.Get (Session);\n \n while ML.Has_Row loop\n case ML.Element.Kind is\n when 0 =>\n Put_Line (\"A book \" & ML.Element.Title);\n when 1 =>\n Put_Line (\"A dvd \" & ML.Element.Title);\n end case;\n ML.Next;\n end loop;\n-This code works, but requires a case statement. Now, let\u2019s imagine the check\n+This code works, but requires a case statement. Now, let's imagine the check\n out procedure is different for a book and a DVD (for the latter we need to\n check that the disk is indeed in the box). We would have two\n-subprogramsCheckout_BookandCheckout_DVDand call them from the case. This isn\u2019t\n+subprogramsCheckout_BookandCheckout_DVDand call them from the case. This isn't\n object-oriented programming.\n Instead, we will declare two new types:\n type My_Media is abstract new ORM.Detached_Media with private;\n procedure Checkout (Self : My_Media) is abstract;\n \n type Detached_Book is new My_Media with private;\n overriding Checkout (Self : Detached_Book);\n@@ -1648,17 +1648,17 @@\n overriding Checkout (Self : Detached_DVD);\n We could manually declare a new Media_List and overrideElementso that it\n returns either of the two types instead of aMedia. But then we would also need\n to overrideGetso that it returns our new list. This is tedious.\n We will instead use an element factory in the session. This is a function that\n gets a row of a table (in the form of aCustomer), and returns the appropriate\n type to use when the element is detached (by default, the detached type\n-corresponding to aCustomeris aDetached_Customer, and that\u2019s what we want to\n+corresponding to aCustomeris aDetached_Customer, and that's what we want to\n change).\n-So let\u2019s create such a factory:\n+So let's create such a factory:\n function Media_Factory\n (From : Base_Element'Class;\n Default : Detached_Element'Class) return Detached_Element'Class\n is\n begin\n if From in Media'Class then\n case Media (From).Kind is\n"}]}, {"source1": "./usr/share/doc/libgnatcoll-db-doc/html/xref.html", "source2": "./usr/share/doc/libgnatcoll-db-doc/html/xref.html", "unified_diff": "@@ -80,18 +80,18 @@\n in the first place is tricky, especially for languages that support\n overloading of subprograms.

    \n

    Some compilers like GNAT and gcc can generate this information for Ada\n code bases. For instance, GNAT will generate .ali files, which\n contain the navigation information, when compiling Ada or SPARK code.

    \n

    GNATCOLL.Xref can then be used to parse and aggregate all those\n files into a single sqlite database, which can be conveniently used to\n-answer queries such as \u201cgive me the declaration for this entity\u201d, \u201clist all\n-places where this entity is used\u201d, \u201cshow all subprograms that could be called\n-in practice at this dispatching call\u201d, \u201cwhat files does this file depend on\u201d,\n-\u201cshow me the call graph for this application\u201d,\u2026

    \n+answer queries such as "give me the declaration for this entity", "list all\n+places where this entity is used", "show all subprograms that could be called\n+in practice at this dispatching call", "what files does this file depend on",\n+"show me the call graph for this application",...

    \n

    To use this package, some initialization needs to be performed first:

    \n 
    with GNATCOLL.Xref;     use GNATCOLL.Xref;\n with GNATCOLL.SQL.Sqlite;\n with GNATCOLL.Projects; use GNATCOLL.Projects;   --  1\n with GNATCOLL.VFS;      use GNATCOLL.VFS;\n with GNAT.Strings;\n \n@@ -112,15 +112,15 @@\n
    \n
    \n

    GNATCOLL needs to be able to find the *li files. For this, it depends\n on project files (as supported by GNATCOLL.Projects). So the first\n thing to do is to parse the project (step 2).

    \n

    We then need to tell GNATCOLL where the cross-reference information need to be\n aggregated. In this example, it will be stored in a sqlite database on the disk.\n-By using a name \u201c:memory:\u201d instead, we would create a temporary in-memory\n+By using a name ":memory:" instead, we would create a temporary in-memory\n database. This is in general faster, but uses more memory and needs to be\n recreated every time the program is restarted. We could also decide to store\n the information in any other database supported by GNATCOLL.SQL.Exec,\n for instance PostgreSQL.

    \n

    Finally, in step 4 we let GNATCOLL parse all the *li files that are\n relevant for this project. This operation can take a while, depending on the\n size of the project. However, if the database already exists on the disk, it\n@@ -161,20 +161,20 @@\n

    Step 5 gets a handle on the source file. Here, we depend on the project to\n find the precise directory in which the source file is located.\n We can of course use an absolute file name instead.

    \n

    Step 6 gets handle on the entity referenced on line 2 in this file. Such an\n entity is the starting point for most queries defined in GNATCOLL.Xref.

    \n

    Finally, on step 7 and the loop below we iterate over all references, and\n print their location on the standard output.

    \n-

    Let\u2019s do a much more complex query: we want to see all references to that\n+

    Let's do a much more complex query: we want to see all references to that\n entity, but also places where the entity might be called through a renames\n statement, or called through a dispatching call via an overriding method\n defined on a child tagged type (assuming this is a primitive operation of\n a tagged type in the first place). We also want to see all locations\n-where a method that overrides \u201cMethod\u201d is called:

    \n+where a method that overrides "Method" is called:

    \n 
    declare\n    Refs : Recursive_References_Cursor;\n begin\n    DB.Recursive (Entity, GNATCOLL.Xref.References'Access,\n                  From_Overriding => True, From_Overridden => True,\n                  From_Renames => True);\n    while Refs.Has_Element loop\n@@ -183,15 +183,15 @@\n    end loop;\n end;\n
    \n
    \n

    As shown above, the programing pattern is always the same.

    \n

    GNATCOLL.Xref provides many more subprogram to get information like the list\n of fields for a record type (or a C structure), the list of primitive operations\n-or methods for a tagged object or a class, the call graph for a subprogram,\u2026

    \n+or methods for a tagged object or a class, the call graph for a subprogram,...

    \n

    It is also able to extract documentation for an entity from the source code, by\n looking at the lines of code just before or just after the declaration or the\n body of the entity.

    \n \n
    \n

    3. Xref: gnatinspect\uf0c1

    \n

    As discussed in the previous section, GNATCOLL provides an Ada API to\n@@ -205,60 +205,60 @@\n

    When it is first started on a project, this tool will refresh the xref\n database by parsing all the ALI files from the project. This might take\n a while (up to several minutes) the first time, unless of course the\n xref were already up-to-date because you had loaded the project in GPS\n first, or already run gnatinspect.

    \n

    gnatinspect then displays an interactive prompt that lets you perform\n various queries on the database. The full list of queries is available\n-by typing \u201chelp\u201d at the prompt, but this documentation will demonstrate\n+by typing "help" at the prompt, but this documentation will demonstrate\n some of them.

    \n-

    Let\u2019s first look at a number of command line switches that might be\n+

    Let's first look at a number of command line switches that might be\n useful:

    \n
      \n-

    • \u2013db=ARG: this switch can be used to specify the name of the database.

      \n+

    • --db=ARG: this switch can be used to specify the name of the database.

      \n

      By default, gnatinspect checks in the project whether there exists an\n-attribute IDE\u2019Xref_Database, which should specify a file name (relative to\n-the project\u2019s object_dir) for the database.

      \n-

      If this attribute does not exist, it defaults to \u201cgnatinspect.db\u201d in\n-the project\u2019s object directory.

      \n+attribute IDE'Xref_Database, which should specify a file name (relative to\n+the project's object_dir) for the database.

      \n+

      If this attribute does not exist, it defaults to "gnatinspect.db" in\n+the project's object directory.

      \n

      If there is no object directory defined in the project, the file is created\n-in the project\u2019s directory itself. You can however specify any name,\n-including an absolute path, or a path relative to the project\u2019s object\n+in the project's directory itself. You can however specify any name,\n+including an absolute path, or a path relative to the project's object\n directory.

      \n-

      An alternative is to specify \u2018:memory:\u2019, which creates the database in\n+

      An alternative is to specify ':memory:', which creates the database in\n memory. This is of course a temporary database which will disappear when\n gnatinspect exits, and cannot be shared with other tools.

      \n
      • \n-

    • \u2013nightlydb=ARG: this switch can help speed up the initial startup\n+

    • --nightlydb=ARG: this switch can help speed up the initial startup\n of gnatinspect. The idea is that in a lot of cases, the software on which\n a team works is build nightly in a common setup. Running gnatinspect in\n that setup will create or update an xref database.\n Individual developers can then create their own copy of the database by\n starting from the contents of the nightly database (which is pointed to\n-by the \u2013nightlydb switch), and then gnatinspect will parse the ALI files\n-in the user\u2019s setup that are different from the nightly ones.

      • \n-

    • \u2013runtime: by default, gnatinspect will only parse the ALI files from\n+by the --nightlydb switch), and then gnatinspect will parse the ALI files\n+in the user's setup that are different from the nightly ones.

      • \n+

    • --runtime: by default, gnatinspect will only parse the ALI files from\n your project (and of course the ones from imported projects). It will not\n however parse the ALI files found in predefined directories, like for\n instance the GNAT runtime. This saves time in general. If you click on\n a call to one of the runtime subprograms in your own code, gnatinspect\n will be able to point you to its declaration. However, you will not have\n access to the body, because the link from declaration to body is found in\n the ALI files of the runtime.

      • \n-

    • \u2013command=ARG: gnatinspect will update the xref database as usual, then\n+

    • --command=ARG: gnatinspect will update the xref database as usual, then\n execute a command, display its result, and exit. This can be convenient\n when calling gnatinspect from another tool, like Emacs or vi.

      • \n-

    • \u2013file=ARG: similar to \u2013command, but reads the commands to execute from\n-a file. The file can contain comments (starting with \u2018\u2013\u2019. See also the\n-\u2013lead switch.

      • \n-

    • \u2013lang=LANG:SPEC:BODY:OBJ: specifies a naming scheme for a language. The\n+

    • --file=ARG: similar to --command, but reads the commands to execute from\n+a file. The file can contain comments (starting with '--'. See also the\n+--lead switch.

      • \n+

    • --lang=LANG:SPEC:BODY:OBJ: specifies a naming scheme for a language. The\n preferred approach is to use a configuration project file (such as those\n generated by gprconfig for instance), that would define attributes such as\n-Naming\u2019Spec_Suffix, Naming\u2019Body_Suffix and\n-Compiler\u2019Object_File_Suffix. However, this switch provides an alternative\n+Naming'Spec_Suffix, Naming'Body_Suffix and\n+Compiler'Object_File_Suffix. However, this switch provides an alternative\n whereby you can specify the same values directly on the command line. For\n instance, the equivalent of:

      \n 
      configuration project Autoconf is\n    package Naming is\n       for Spec_Suffix ("MyLang") use ".myl";\n    end Naming;\n    package Compiler is\n@@ -277,37 +277,37 @@\n 
      Given one of the above, and assuming your project file includes:
      \n 
      for Languages use ("Ada", "MyLang");\n 
      \n 
      \n 
      then any file with the .myl extension will be correctly detected\n by the project manager, and any .ali file with the same base name\n will be parsed by gnatinspect to find cross-reference information.\n-Remember that the switch \u2013config=autoconf.cgpr must be passed to\n+Remember that the switch --config=autoconf.cgpr must be passed to\n gnatinspect if the information is provided via a config project file.
      \n
      • \n-

    • \u2013lead=ARG should be used in coordination with \u2013file, and specify lines\n+

    • --lead=ARG should be used in coordination with --file, and specify lines\n to ignore from the file. All lines starting with the given prefix will be\n ignored.

      • \n-

    • \u2013basenames: controls the display of file names in the output. By default,\n+

    • --basenames: controls the display of file names in the output. By default,\n gnatinspect outputs full path information.

      • \n-

    • \u2013exit: if this switch is specified, gnatinspect updates the xref database\n+

    • --exit: if this switch is specified, gnatinspect updates the xref database\n and exits immediately.

      • \n-

    • \u2013project=ARG or -P ARG specifies the name of the project to load. This\n+

    • --project=ARG or -P ARG specifies the name of the project to load. This\n switch is mandatory.

      • \n

    • -X VAR=VALUE is used to specify the value of scenario variables used in\n your project. This is similar to the homonym switch in gprbuild.

      • \n-

    • \u2013symlinks should be specified if your project uses symbolic links for\n+

    • --symlinks should be specified if your project uses symbolic links for\n files. This will ensure that the links are fully resolved as stored in the\n database, and thus that when a file is visible through different links, the\n information is appropriately coalesced in the database for that file.

      • \n-

    • \u2013subdirs=ARG is similar to the homonym switch in gprbuild

      • \n-

    • \u2013tracefile=ARG is used to point to a file compatible with GNATCOLL.Traces\n+

    • --subdirs=ARG is similar to the homonym switch in gprbuild

      • \n+

    • --tracefile=ARG is used to point to a file compatible with GNATCOLL.Traces\n that controls the debug information generated by gnatinspect. By default,\n-gnatinspect parses a file called \u2018.gnatdebug\u2019 in the current directory.

      • \n-

    • \u2013encoding=ARG is the character encoding used for source and ALI files.\n+gnatinspect parses a file called '.gnatdebug' in the current directory.

      • \n+

    • --encoding=ARG is the character encoding used for source and ALI files.\n By default, gnatinspect assumes they are encoded in UTF-8.

      • \n
    \n

    Once it has finished parsing the xref information, gnatinspect displays an\n interactive prompt, where a number of commands can be used to perform\n queries. In a lot of cases, these commands take some file information as\n argument (either just the file, or an entity name and the file in which it\n is defined).

    \n@@ -315,16 +315,16 @@\n directory, or even a full name. But file names are ambiguous (even when a full\n path is specified) when aggregate projects are used. It is valid for a given\n file to be part of multiple aggregate projects, and depending on the project we\n are considering the result of the xref queries might vary).

    \n

    To remove the ambiguity, it is possible to specify the project to which the\n file belongs. The project is specified either as a project name (which itself\n could be ambiguous with aggregate projects), or as a full path.

    \n-

    In all commands below, whenever the parameter specifies \u201c:file\u201d, you can\n-use instead \u201c:file:project\u201d if there are ambiguities. It is also possible\n+

    In all commands below, whenever the parameter specifies ":file", you can\n+use instead ":file:project" if there are ambiguities. It is also possible\n not to specify the file, in which case the entity will be looked for in all\n sources of the project.

    \n

    Here is the full list of commands supported by gnatinspect:

    \n
      \n

    • decl name:file:line:column is probably the most useful command. Given a\n reference to an entity, it will indicate where the entity is declared. The\n line and column informations are optional:

      \n@@ -373,15 +373,15 @@\n which the entity is a method.

      • \n

    • calls name:file:line:column lists all entities called by the entity. This\n includes all entities defined within the scope of the entity (so for a\n subprogram this will be the list of local variables, but for a package\n this includes all subprograms and nested packages defined within that\n package).

      • \n

    • callers name:file:line:column lists all entities that call the entity. This\n-information is also available from a call to \u2018refs\u2019, but \u2018callers\u2019 return the\n+information is also available from a call to 'refs', but 'callers' return the\n callers directly, instead of references to the original entity.

      • \n

    • overrides name:file:line:column returns the entity that is overridden by\n the entity (generally a method from a parent class).

      • \n

    • overridden name:file:line:column returns the list of entities that override\n the parameter (generally methods from children classes).

      • \n

    • overridden_recursive name:file:line:column returns the list of entities\n that override the parameter (generally methods from children classes). This is\n@@ -409,15 +409,15 @@\n calling imports)

      • \n

    • entities file lists all entities referenced or declared in the file.

      • \n
    \n

    Finally, some commands are not related to entities or source files:

    \n
      \n

    • refresh refreshes the contents of the xref database, by parsing all ALI\n files that have been changed.

      • \n-

    • shell Execute a shell command (an alternative is to use \u2018!\u2019 as the\n+

    • shell Execute a shell command (an alternative is to use '!' as the\n command).

      • \n

    • scenario VARIABLE VALUE changes the value of a scenario variable, and\n reparse the project.

      • \n

    • time command arguments executes the command as usual, and report the time\n it took to execute it.

      • \n
    \n
    \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -14,18 +14,18 @@\n in the first place is tricky, especially for languages that support overloading\n of subprograms.\n Some compilers like GNAT and gcc can generate this information for Ada code\n bases. For instance, GNAT will generate .ali files, which contain the\n navigation information, when compiling Ada or SPARK code.\n GNATCOLL.Xref can then be used to parse and aggregate all those files into a\n single sqlite database, which can be conveniently used to answer queries such\n-as \u201cgive me the declaration for this entity\u201d, \u201clist all places where this\n-entity is used\u201d, \u201cshow all subprograms that could be called in practice at this\n-dispatching call\u201d, \u201cwhat files does this file depend on\u201d, \u201cshow me the call\n-graph for this application\u201d,\u2026\n+as \"give me the declaration for this entity\", \"list all places where this\n+entity is used\", \"show all subprograms that could be called in practice at this\n+dispatching call\", \"what files does this file depend on\", \"show me the call\n+graph for this application\",...\n To use this package, some initialization needs to be performed first:\n with GNATCOLL.Xref; use GNATCOLL.Xref;\n with GNATCOLL.SQL.Sqlite;\n with GNATCOLL.Projects; use GNATCOLL.Projects; -- 1\n with GNATCOLL.VFS; use GNATCOLL.VFS;\n with GNAT.Strings;\n \n@@ -44,15 +44,15 @@\n Parse_All_LI_Files (DB, Tree.Root_Project); -- 4\n end Support;\n GNATCOLL needs to be able to find the *li files. For this, it depends on\n project files (as supported by GNATCOLL.Projects). So the first thing to do is\n to parse the project (step 2).\n We then need to tell GNATCOLL where the cross-reference information need to be\n aggregated. In this example, it will be stored in a sqlite database on the\n-disk. By using a name \u201c:memory:\u201d instead, we would create a temporary in-memory\n+disk. By using a name \":memory:\" instead, we would create a temporary in-memory\n database. This is in general faster, but uses more memory and needs to be\n recreated every time the program is restarted. We could also decide to store\n the information in any other database supported by GNATCOLL.SQL.Exec, for\n instance PostgreSQL.\n Finally, in step 4 we let GNATCOLL parse all the *li files that are relevant\n for this project. This operation can take a while, depending on the size of the\n project. However, if the database already exists on the disk, it will simply be\n@@ -91,35 +91,35 @@\n Step 5 gets a handle on the source file. Here, we depend on the project to find\n the precise directory in which the source file is located. We can of course use\n an absolute file name instead.\n Step 6 gets handle on the entity referenced on line 2 in this file. Such an\n entity is the starting point for most queries defined inGNATCOLL.Xref.\n Finally, on step 7 and the loop below we iterate over all references, and print\n their location on the standard output.\n-Let\u2019s do a much more complex query: we want to see all references to that\n+Let's do a much more complex query: we want to see all references to that\n entity, but also places where the entity might be called through\n arenamesstatement, or called through a dispatching call via an overriding\n method defined on a child tagged type (assuming this is a primitive operation\n of a tagged type in the first place). We also want to see all locations where a\n-method that overrides \u201cMethod\u201d is called:\n+method that overrides \"Method\" is called:\n declare\n Refs : Recursive_References_Cursor;\n begin\n DB.Recursive (Entity, GNATCOLL.Xref.References'Access,\n From_Overriding => True, From_Overridden => True,\n From_Renames => True);\n while Refs.Has_Element loop\n ... same as before\n Refs.Next;\n end loop;\n end;\n As shown above, the programing pattern is always the same.\n GNATCOLL.Xref provides many more subprogram to get information like the list of\n fields for a record type (or a C structure), the list of primitive operations\n-or methods for a tagged object or a class, the call graph for a subprogram,\u2026\n+or methods for a tagged object or a class, the call graph for a subprogram,...\n It is also able to extract documentation for an entity from the source code, by\n looking at the lines of code just before or just after the declaration or the\n body of the entity.\n *\b**\b**\b**\b**\b**\b* 3\b3.\b. X\bXr\bre\bef\bf:\b: g\bgn\bna\bat\bti\bin\bns\bsp\bpe\bec\bct\bt_\b?\b\uf0c1 *\b**\b**\b**\b**\b**\b*\n As discussed in the previous section, GNATCOLL provides an Ada API to perform\n cross-references queries.\n There exist a few alternatives when you want to reuse that cross-reference\n@@ -130,56 +130,56 @@\n g\bgn\bna\bat\bti\bin\bns\bsp\bpe\bec\bct\bt.\n When it is first started on a project, this tool will refresh the xref database\n by parsing all the ALI files from the project. This might take a while (up to\n several minutes) the first time, unless of course the xref were already up-to-\n date because you had loaded the project in GPS first, or already run\n gnatinspect.\n gnatinspect then displays an interactive prompt that lets you perform various\n-queries on the database. The full list of queries is available by typing \u201chelp\u201d\n+queries on the database. The full list of queries is available by typing \"help\"\n at the prompt, but this documentation will demonstrate some of them.\n-Let\u2019s first look at a number of command line switches that might be useful:\n- * ?\b\u2013d\bdb\bb=\b=A\bAR\bRG\bG: this switch can be used to specify the name of the database.\n+Let's first look at a number of command line switches that might be useful:\n+ * -\b--\b-d\bdb\bb=\b=A\bAR\bRG\bG: this switch can be used to specify the name of the database.\n By default, gnatinspect checks in the project whether there exists an\n- attribute IDE\u2019Xref_Database, which should specify a file name (relative\n- to the project\u2019s object_dir) for the database.\n- If this attribute does not exist, it defaults to \u201cgnatinspect.db\u201d in the\n- project\u2019s object directory.\n+ attribute IDE'Xref_Database, which should specify a file name (relative\n+ to the project's object_dir) for the database.\n+ If this attribute does not exist, it defaults to \"gnatinspect.db\" in the\n+ project's object directory.\n If there is no object directory defined in the project, the file is\n- created in the project\u2019s directory itself. You can however specify any\n- name, including an absolute path, or a path relative to the project\u2019s\n+ created in the project's directory itself. You can however specify any\n+ name, including an absolute path, or a path relative to the project's\n object directory.\n- An alternative is to specify \u2018:memory:\u2019, which creates the database in\n+ An alternative is to specify ':memory:', which creates the database in\n memory. This is of course a temporary database which will disappear when\n gnatinspect exits, and cannot be shared with other tools.\n- * ?\b\u2013n\bni\big\bgh\bht\btl\bly\byd\bdb\bb=\b=A\bAR\bRG\bG: this switch can help speed up the initial startup of\n+ * -\b--\b-n\bni\big\bgh\bht\btl\bly\byd\bdb\bb=\b=A\bAR\bRG\bG: this switch can help speed up the initial startup of\n gnatinspect. The idea is that in a lot of cases, the software on which a\n team works is build nightly in a common setup. Running gnatinspect in\n that setup will create or update an xref database. Individual developers\n can then create their own copy of the database by starting from the\n- contents of the nightly database (which is pointed to by the \u2013nightlydb\n- switch), and then gnatinspect will parse the ALI files in the user\u2019s\n+ contents of the nightly database (which is pointed to by the --nightlydb\n+ switch), and then gnatinspect will parse the ALI files in the user's\n setup that are different from the nightly ones.\n- * ?\b\u2013r\bru\bun\bnt\bti\bim\bme\be: by default, gnatinspect will only parse the ALI files from your\n- project (and of course the ones from imported projects). It will not\n+ * -\b--\b-r\bru\bun\bnt\bti\bim\bme\be: by default, gnatinspect will only parse the ALI files from\n+ your project (and of course the ones from imported projects). It will not\n however parse the ALI files found in predefined directories, like for\n instance the GNAT runtime. This saves time in general. If you click on a\n call to one of the runtime subprograms in your own code, gnatinspect will\n be able to point you to its declaration. However, you will not have\n access to the body, because the link from declaration to body is found in\n the ALI files of the runtime.\n- * ?\b\u2013c\bco\bom\bmm\bma\ban\bnd\bd=\b=A\bAR\bRG\bG: gnatinspect will update the xref database as usual, then\n+ * -\b--\b-c\bco\bom\bmm\bma\ban\bnd\bd=\b=A\bAR\bRG\bG: gnatinspect will update the xref database as usual, then\n execute a command, display its result, and exit. This can be convenient\n when calling gnatinspect from another tool, like Emacs or vi.\n- * ?\b\u2013f\bfi\bil\ble\be=\b=A\bAR\bRG\bG: similar to \u2013command, but reads the commands to execute from a\n- file. The file can contain comments (starting with \u2018\u2013\u2019. See also the\n- \u2013lead switch.\n- * ?\b\u2013l\bla\ban\bng\bg=\b=L\bLA\bAN\bNG\bG:\b:S\bSP\bPE\bEC\bC:\b:B\bBO\bOD\bDY\bY:\b:O\bOB\bBJ\bJ: specifies a naming scheme for a language. The\n+ * -\b--\b-f\bfi\bil\ble\be=\b=A\bAR\bRG\bG: similar to --command, but reads the commands to execute from\n+ a file. The file can contain comments (starting with '--'. See also the -\n+ -lead switch.\n+ * -\b--\b-l\bla\ban\bng\bg=\b=L\bLA\bAN\bNG\bG:\b:S\bSP\bPE\bEC\bC:\b:B\bBO\bOD\bDY\bY:\b:O\bOB\bBJ\bJ: specifies a naming scheme for a language. The\n preferred approach is to use a configuration project file (such as those\n generated by gprconfig for instance), that would define attributes such\n- asNaming\u2019Spec_Suffix,Naming\u2019Body_SuffixandCompiler\u2019Object_File_Suffix.\n+ asNaming'Spec_Suffix,Naming'Body_SuffixandCompiler'Object_File_Suffix.\n However, this switch provides an alternative whereby you can specify the\n same values directly on the command line. For instance, the equivalent\n of:\n configuration project Autoconf is\n package Naming is\n for Spec_Suffix (\"MyLang\") use \".myl\";\n end Naming;\n@@ -193,52 +193,53 @@\n project file above, directly in your own project file. This has the same\n effect, but needs to be duplicated in each of your project file.\n Given one of the above, and assuming your project file includes:\n for Languages use (\"Ada\", \"MyLang\");\n then any file with the .myl extension will be correctly detected by the\n project manager, and any .ali file with the same base name will be parsed\n by gnatinspect to find cross-reference information. Remember that the\n- switch\u2013config=autoconf.cgprmust be passed to gnatinspect if the\n+ switch--config=autoconf.cgprmust be passed to gnatinspect if the\n information is provided via a config project file.\n- * ?\b\u2013l\ble\bea\bad\bd=\b=A\bAR\bRG\bG should be used in coordination with \u2013file, and specify lines to\n- ignore from the file. All lines starting with the given prefix will be\n+ * -\b--\b-l\ble\bea\bad\bd=\b=A\bAR\bRG\bG should be used in coordination with --file, and specify lines\n+ to ignore from the file. All lines starting with the given prefix will be\n ignored.\n- * ?\b\u2013b\bba\bas\bse\ben\bna\bam\bme\bes\bs: controls the display of file names in the output. By default,\n- gnatinspect outputs full path information.\n- * ?\b\u2013e\bex\bxi\bit\bt: if this switch is specified, gnatinspect updates the xref database\n- and exits immediately.\n- * ?\b\u2013p\bpr\bro\boj\bje\bec\bct\bt=\b=A\bAR\bRG\bG or -\b-P\bP A\bAR\bRG\bG specifies the name of the project to load. This\n+ * -\b--\b-b\bba\bas\bse\ben\bna\bam\bme\bes\bs: controls the display of file names in the output. By\n+ default, gnatinspect outputs full path information.\n+ * -\b--\b-e\bex\bxi\bit\bt: if this switch is specified, gnatinspect updates the xref\n+ database and exits immediately.\n+ * -\b--\b-p\bpr\bro\boj\bje\bec\bct\bt=\b=A\bAR\bRG\bG or -\b-P\bP A\bAR\bRG\bG specifies the name of the project to load. This\n switch is mandatory.\n * -\b-X\bX V\bVA\bAR\bR=\b=V\bVA\bAL\bLU\bUE\bE is used to specify the value of scenario variables used in\n your project. This is similar to the homonym switch in gprbuild.\n- * ?\b\u2013s\bsy\bym\bml\bli\bin\bnk\bks\bs should be specified if your project uses symbolic links for\n+ * -\b--\b-s\bsy\bym\bml\bli\bin\bnk\bks\bs should be specified if your project uses symbolic links for\n files. This will ensure that the links are fully resolved as stored in\n the database, and thus that when a file is visible through different\n links, the information is appropriately coalesced in the database for\n that file.\n- * ?\b\u2013s\bsu\bub\bbd\bdi\bir\brs\bs=\b=A\bAR\bRG\bG is similar to the homonym switch in gprbuild\n- * ?\b\u2013t\btr\bra\bac\bce\bef\bfi\bil\ble\be=\b=A\bAR\bRG\bG is used to point to a file compatible with GNATCOLL.Traces\n- that controls the debug information generated by gnatinspect. By default,\n- gnatinspect parses a file called \u2018.gnatdebug\u2019 in the current directory.\n- * ?\b\u2013e\ben\bnc\bco\bod\bdi\bin\bng\bg=\b=A\bAR\bRG\bG is the character encoding used for source and ALI files. By\n- default, gnatinspect assumes they are encoded in UTF-8.\n+ * -\b--\b-s\bsu\bub\bbd\bdi\bir\brs\bs=\b=A\bAR\bRG\bG is similar to the homonym switch in gprbuild\n+ * -\b--\b-t\btr\bra\bac\bce\bef\bfi\bil\ble\be=\b=A\bAR\bRG\bG is used to point to a file compatible with\n+ GNATCOLL.Traces that controls the debug information generated by\n+ gnatinspect. By default, gnatinspect parses a file called '.gnatdebug' in\n+ the current directory.\n+ * -\b--\b-e\ben\bnc\bco\bod\bdi\bin\bng\bg=\b=A\bAR\bRG\bG is the character encoding used for source and ALI files.\n+ By default, gnatinspect assumes they are encoded in UTF-8.\n Once it has finished parsing the xref information, gnatinspect displays an\n interactive prompt, where a number of commands can be used to perform queries.\n In a lot of cases, these commands take some file information as argument\n (either just the file, or an entity name and the file in which it is defined).\n The file names can be given as either a base name, or relative to the current\n directory, or even a full name. But file names are ambiguous (even when a full\n path is specified) when aggregate projects are used. It is valid for a given\n file to be part of multiple aggregate projects, and depending on the project we\n are considering the result of the xref queries might vary).\n To remove the ambiguity, it is possible to specify the project to which the\n file belongs. The project is specified either as a project name (which itself\n could be ambiguous with aggregate projects), or as a full path.\n-In all commands below, whenever the parameter specifies \u201c:file\u201d, you can use\n-instead \u201c:_\bf_\bi_\bl_\be_\b:_\bp_\br_\bo_\bj_\be_\bc_\bt\u201d if there are ambiguities. It is also possible not to\n+In all commands below, whenever the parameter specifies \":file\", you can use\n+instead \":_\bf_\bi_\bl_\be_\b:_\bp_\br_\bo_\bj_\be_\bc_\bt\" if there are ambiguities. It is also possible not to\n specify the file, in which case the entity will be looked for in all sources of\n the project.\n Here is the full list of commands supported by gnatinspect:\n * d\bde\bec\bcl\bl n\bna\bam\bme\be:\b:f\bfi\bil\ble\be:\b:l\bli\bin\bne\be:\b:c\bco\bol\blu\bum\bmn\bn is probably the most useful command. Given a\n reference to an entity, it will indicate where the entity is declared.\n The line and column informations are optional:\n >>> decl Func:file.adb:12\n@@ -279,15 +280,15 @@\n which the entity is a method.\n * c\bca\bal\bll\bls\bs n\bna\bam\bme\be:\b:f\bfi\bil\ble\be:\b:l\bli\bin\bne\be:\b:c\bco\bol\blu\bum\bmn\bn lists all entities called by the entity. This\n includes all entities defined within the scope of the entity (so for a\n subprogram this will be the list of local variables, but for a package\n this includes all subprograms and nested packages defined within that\n package).\n * c\bca\bal\bll\ble\ber\brs\bs n\bna\bam\bme\be:\b:f\bfi\bil\ble\be:\b:l\bli\bin\bne\be:\b:c\bco\bol\blu\bum\bmn\bn lists all entities that call the entity.\n- This information is also available from a call to \u2018refs\u2019, but \u2018callers\u2019\n+ This information is also available from a call to 'refs', but 'callers'\n return the callers directly, instead of references to the original\n entity.\n * o\bov\bve\ber\brr\bri\bid\bde\bes\bs n\bna\bam\bme\be:\b:f\bfi\bil\ble\be:\b:l\bli\bin\bne\be:\b:c\bco\bol\blu\bum\bmn\bn returns the entity that is overridden by\n the entity (generally a method from a parent class).\n * o\bov\bve\ber\brr\bri\bid\bdd\bde\ben\bn n\bna\bam\bme\be:\b:f\bfi\bil\ble\be:\b:l\bli\bin\bne\be:\b:c\bco\bol\blu\bum\bmn\bn returns the list of entities that\n override the parameter (generally methods from children classes).\n * o\bov\bve\ber\brr\bri\bid\bdd\bde\ben\bn_\b_r\bre\bec\bcu\bur\brs\bsi\biv\bve\be n\bna\bam\bme\be:\b:f\bfi\bil\ble\be:\b:l\bli\bin\bne\be:\b:c\bco\bol\blu\bum\bmn\bn returns the list of entities\n@@ -312,15 +313,15 @@\n statements in Ada or #include in C for instance). See also d\bde\bep\bpe\ben\bnd\bds\bs_\b_o\bon\bn.\n * d\bde\bep\bpe\ben\bnd\bds\bs f\bfi\bil\ble\ben\bna\bam\bme\be lists the files that the file depends on (recursively\n calling i\bim\bmp\bpo\bor\brt\bts\bs)\n * e\ben\bnt\bti\bit\bti\bie\bes\bs f\bfi\bil\ble\be lists all entities referenced or declared in the file.\n Finally, some commands are not related to entities or source files:\n * r\bre\bef\bfr\bre\bes\bsh\bh refreshes the contents of the xref database, by parsing all ALI\n files that have been changed.\n- * s\bsh\bhe\bel\bll\bl Execute a shell command (an alternative is to use \u2018!\u2019 as the\n+ * s\bsh\bhe\bel\bll\bl Execute a shell command (an alternative is to use '!' as the\n command).\n * s\bsc\bce\ben\bna\bar\bri\bio\bo V\bVA\bAR\bRI\bIA\bAB\bBL\bLE\bE V\bVA\bAL\bLU\bUE\bE changes the value of a scenario variable, and\n reparse the project.\n * t\bti\bim\bme\be c\bco\bom\bmm\bma\ban\bnd\bd a\bar\brg\bgu\bum\bme\ben\bnt\bts\bs executes the command as usual, and report the time\n it took to execute it.\n _\bP_\br_\be_\bv_\bi_\bo_\bu_\bs\n ===============================================================================\n"}]}]}]}]}]}