chooser_overview.txt:

2016-04-05 // Another attempt to create an overview ...

 = precondition
 - assume a "database" which reflects the info from setup.ini ... (packagedb::packages)
    - it list each package and every version of that pkg ...
 - this database even tells us what version has been installed if that is the case (reflecting installed.db)
 - furthermore we (setup.exe) are able to ascertain whether the tarball, associated with a version, is available
   or not -- the source code of setup.exe uses the term "accessible" for availability

 = D w/o I (Download without Installing)
 - setup.exe should show us ALL the pkgs and every version of that pkg ...
    - assume all tarballs are available (stable mirror)

 = I f LD (Install from Local Directory)
 - setup.exe should show us the installed pkgs and the versions of that pkg that are not installed, but are available
   in the repo ...
    - the tarball of an installed version may or may not be available in the repo ...
 - furthermore it should show us each non-installed pkg if at least one version of that pkg is available in the repo

ChooserPage::OnInit has the following call flow in both cases (D w/o I and I f LD)

ChooserPage::OnInit
  packagemeta::ScanDownLoadedFiles
  packagedb::setExistence
  packagemeta::trustp(true, ...

 = D w/o I

 // (pkg.installed == version) => pkg is installed
 - ScanDownloadedFiles # method name is a misnomer here
    ! (pkg is installed || a version is acccessible) => erase version from packagemeta.versions
    - here all versions will be kept (stable mirror) in packagemeta.versions
 - setExistence
    ! (pkg is installed || a version is acccessible) => erase pkg from packages
    - the test whether the pkg is installed or not, is useless here ...
    - ... as all pkgs (i.e. all versions of each pkg) are available (accessible): UNmodified database
 End result: setup.up will show us all the pkgs and every version of each pkg ...

 = I f LD

 // (pkg.installed == version) => pkg is installed
 - ScanDownloadedFiles
    ! (pkg is installed || a version is accessible) => erase version from packagemeta.versions
    - not-installed pkgs: available versions will be kept in packagemeta.versions
    - installed pkgs: the installed version will be kept
    - installed pkgs: non-available versions will be removed from packagemeta.versions
 - setExistence
    ! (pkg is installed || a version is accessible) => erase pkg from packages
    - a not-installed pkg, of which at least one version is available: this pkg will be kept in the database
      (versions will show the available versions)
    - installed pkgs: these pkgs will be kept in the database
      (versions will show the installed version and available versions that are not installed)
 End result: setup.exe will show us all the available versions of each pkg, if it has not been installed yet, and all
 the pkgs (both the installed version and available versions that are not installed) which have been installed ...

----- Ignoring the issue of source tarballs ...

Each "package entry" (p, c and/or t) in setup.ini is represeneted by an object of type packagemeta ...

 - class variable packages (of type packagedb): std::map <std::string, *packagemeta>
   or: a mapping from a packagename to a pointer to an object of type packagemeta

A simplified view of the data members of class packagemeta is as follows:

 - prev of type packageversion
 - curr ditto
 - exp ditto
 - installed ditto
 - versions of type std::set <packageversion>
-
prev, curr, exp and installed reflect the "static" part of a "package entry": these data members reflect the info from both
setup.ini and installed.db ...
"Nullifying" these data members, as currently happens in ScanDownLoadedFiles is ... stupid?

versions tells what versions of the pkg are available (accessible); versions is managed by ScanDownLoadedFiles ...

Attempting to grasp the general flow of computation:

packagemeta::ScanDownLoadedFiles =>
for each pkg // from packagedb::packages
  for each version // from metapackage::versions
    [ <this>.scan() ] // packageversion::scan() -- simplified!
    // (pkg.installed == version) => pkg is installed
    if ! (pkg is installed || version is accessible) // packagemeta::installed, packageversion::accessible()
        erase version from versions
Note: a version is NOT erased if the version is installed OR if the version is available

packagemeta::accessible => // called by setExistence
for each version // from metapackage::versions
  if version is accessible // packageversion::accessible()
    return true // pkg is available in (local) repo
  return false

packageversion::accessible =>
_packageversion::accessible =>
...

packagedb::setExistence
for each pkg // from packagedb::packages
  // (pkg.installed == version) => pkg is installed
  if ! (pkg is installed || a version is accessible) // packagemeta::installed, packagemeta::accessible()
    erase pkg from packages
Note: a pkg is NOT erased if it is installed, OR if at least one version is available if the pkg is not installed

packagemeta:trustp =>
... only the default trust for the moment ...
if (pkg is installed)
  if (installed version > current version) // requires curr to be properly initialized, i.e. setup.ini MUST have
                                           // a current entry for this package
    if (the experimental version is available
        && experimental version > installed version) // requires exp to be properly initialized ...
          return exp;
    else
      return installed;
else
  if (the current version is available) // requires curr to be properly initialized ...
    return curr;
return installed;

=====