Merge branch 'release/2.0.0'

Author: delphidabbler

Diff for: .gitignore

@@ -0,0 +1 @@
+_release

Diff for: README.md

@@ -1,28 +1,29 @@
 # Code Snippets Collections
 
-This repository will be used to store one or more collections of reusable code snippets, mainly in Pascal.
+This repository is used to store a collection of reusable code snippets, mainly in Pascal.
 
-## Purpose
+> **NOTE:** Further collections may be added in the future.
 
-The collections that **will be** included here are designed, by and large, for use with the _DelphiDabbler [CodeSnip](https://github.com/delphidabbler/codesnip)_ program.
+## Purpose
 
-Having said that, the source code in the collections can be used stand-alone<sup>&dagger;</sup>. Each collection has meta data associated with it that was originally designed for use with _CodeSnip_, but can be used with any other software designed to parse the meta data. The meta data file formats will be documented.
+The purpose of this repository is to provide collections of snippets for use with the _DelphiDabbler [CodeSnip](https://github.com/delphidabbler/codesnip)_ program.
 
-<sup>&dagger;</sup> Note though that some snippets depend on others. The meta data, in part, specifies those relationships.
+However the intent is that other applications will also be able to use the collections by parsing the meta data provided with the collections. It is intended that the meta data will be fully documented.
 
 ## Collections
 
-> Available collections will be described here.
+So far there is just one collection, the _DelphiDabbler Code Snippets Database_. This collection is version 2 of the database. It is designed for use with _CodeSnip_ v4.16 and later.
 
-## Development
+> The collection is not compatible with versions of _CodeSnip_ up to v4.15.1.
 
-The repo uses the [Git Flow](http://nvie.com/posts/a-successful-git-branching-model/) methodology - i.e. development proceeds on the `develop` branch and `feature` branches off it. Only released content appears on the `master` branch.
+The collection can be found in the `csdb` directory. The actual collection is contained in the `collection` sub-directory and it is documented in the `docs` sub-directory - see `collection-format.html` for further information.
 
-## License
+## Development
 
-By default the source code contained in each collection is released under the [MIT License](./LICENSE.md) ***unless either***:
+This repo uses the [Git Flow](http://nvie.com/posts/a-successful-git-branching-model/) methodology - i.e. development proceeds on the `develop` branch and `feature` branches off it. Only released content appears on the `master` branch.
 
-1. The directory containing the collection has its own `LICENSE.md` file - the license specified by such a file then takes precedence; ***or***
+## Licenses
 
-2. The snippet's source code specifies a license. In this case that license applies.
+The license that applies to this project can be found in `LICENSE.md` in the repo's root directory.
 
+Code snippets in collections may have a different license or licenses. See the documentation of each collection for details.

Diff for: csdb/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+This is the change log for the _DelphiDabbler Code Snippets Database_ collection.
+
+From v2.0.0 all notable changes to this project will be documented in this file.
+
+> No change log was kept for version 1 of the collection.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v2.0.0 of 2020/05/02
+
+Initial release of v2 of the collection.
+
+### Changes since last v1 release
+
+* Removed any code that restricted use of the collection to _[DelphiDabbler CodeSnip](https://github.com/delphidabbler/codesnip)_. The collection can now be used by 3rd party applications.
+    * Removed backwards compatibility with _CodeSnip_ v4.15.1 and earlier.
+    * Removed conditionally included code and _CodeSnip_ version dependent code from category .ini files.
+    * Merged multiple versions of category .ini files down into a single file. (These multiple file were used to hide some categories from earlier versions of _CodeSnip_).
+    * Removed duplicated, _CodeSnip_ version dependent, source code files: used a copy of the most recent version and removed version specifiers from the file names.
+* Rationalised and corrected errors in category .ini files:
+    * Condensed two string management categories into one.
+    * Removed `Desc` keys where they duplicated `DescEx` keys.
+    * Removed some duplicate `Credits` and `Comments` keys.
+    * Removed some empty keys.
+    * Fixed or removed some broken web links.
+    * Rephrased some descriptive text.
+* Changed layout of category .ini files and `categories.ini`:
+    * Re-ordered sections of `categories.ini` in alphabetic order.
+    * Removed all explanatory comments: there were inconsistencies.
+    * Added header comments, including copyright and licensing information, to all .ini files.
+* File format changes:
+    * Removed the `StandardFormat` key from the specification of category .ini files.
+    * Added requirements for `LICENSE`, `LICENSE_INFO` and `VERSION` files and added suitable files to the collection.
+    * Changed the required name for the contributors and testers files to `CONTRIBUTORS` and `TESTERS` respectively. Renamed the existing `contrib.txt` and `testers.txt` files accordingly.
+    * Made support for REML v4 an official requirement.
+    * Dropped support for conditional inclusion of code in .ini files.
+* Added documentation:
+    * Of the collection file format.
+    * A read-me file.
+    * This change log.
+* Ensured that all files in the collection use the UTF-8 text file preamble (aka byte order mark).
+* Added a shell script to create releases.
+* Officially adopted the MIT license for source code files.

Diff for: csdb/MakeRelease.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# --------------------------------------------------------------------------
+# DelphiDabbler Code Snippets Database v2
+#
+# Build tool for Windows to package up files ready for release.
+#
+# This file is licensed under the MIT license, copyright © 2020 Peter Johnson,
+# https://gravatar.com/delphidabbler
+#
+#
+# Two packages are made, each in a zip file: one containing the collection and
+# the other containing documentation. Both zip files are written to the
+# _release sub-folder in the collection's home directory.
+#
+# Any pre-existing _release sub-folder is cleared before the zip files are
+# created.
+#
+# Requirements:
+#
+#   - The release version number must be passed to this script as a command
+#     line.
+#
+#   - The zip utility is required to zip up the files.
+#
+# --------------------------------------------------------------------------
+
+
+VERSION=$1
+RELEASE_DIR="./_release"
+RELEASE_FILE_STUB="${RELEASE_DIR}/csdb-v${VERSION}"
+
+COLLECTION_ZIP_FILE="${RELEASE_FILE_STUB}-data.zip"
+DOCS_ZIP_FILE="${RELEASE_FILE_STUB}-docs.zip"
+
+echo Creating CSDB release $1
+echo
+
+rm -rf $RELEASE_DIR || true
+mkdir $RELEASE_DIR
+
+echo Zipping data
+zip -j -q $COLLECTION_ZIP_FILE ./collection/*
+
+echo Zipping documentation
+zip -j -q $DOCS_ZIP_FILE ./docs/*
+
+echo Done

Diff for: csdb/README.md

@@ -0,0 +1,42 @@
+# DelphiDabbler Code Snippets Database v2
+
+This collection is version 2 of the DelphiDabbler Code Snippets Database.
+
+The collection contains over 600 reusable Pascal code snippets. The majority are simple functions and procedures but there are also some constants and type definitions, including some advanced records with methods.
+
+All of the snippets have been tested: some received basic testing while others have been tested more comprehensively. The collection contains details of the level of testing each snippet received.
+
+## History
+
+Version 1 was designed exclusively for use with _DelphiDabbler [CodeSnip](https://github.com/delphidabbler/codesnip)_ (v4.15.1 and earlier) and was downloaded by the program directly from a web service on DelphiDabbler.com.
+
+Version 2 is designed to be able to be used by other applications in addition to _CodeSnip_ (v4.16.0 or later). This version is **not** backwards compatible with version 1.
+
+## Using the Collection
+
+Anyone is welcome to write applications or web pages that access the snippets in the collection, subject to the terms of the license (see below). You should read the collection's documentation which explains the file format in detail.
+
+> **WARNING:** Implementors **must not** read the collection data directly from this GitHub repository - that could generate more than the permitted amount of traffic. Instead you must download a release from the _Releases_ tab and either distribute the collection with the application or host it on a web server.
+
+## Documentation
+
+The collection data format is fully documented in the file `collection-format.html` in the `docs` directory.
+
+## Releases
+
+Releases can be found on the `releases` tab on the GitHub project page.
+
+Each release comprises two zip files, as follows (replace `X.Y.X` in the file names with the release version number):
+
+  * `csdb-vX.Y.Z-data.zip` - Contains all the data in the collection. Required by applications that access the collection.
+  * `csdb-vX.Y.Z-docs.zip` - Contains the documentation developers need to understand the structure of the data.
+
+## Change Log
+
+The project's change log can be found in `CHANGELOG.md` in the collection's base directory.
+
+## License
+
+All snippets in this collection (stored in `.dat` files in the `collections` directory) are licensed under the MIT license and are copyright © 2005-2020, [Peter Johnson](https://gravatar.com/delphidabbler) and Contributors. The full license and a list of contributors can be found in the `LICENSE` and `CONTRIBUTORS` files in the `collection` sub-directory.
+
+All other files in this project are licensed under the MIT license and are copyright © 2020, [Peter Johnson](https://gravatar.com/delphidabbler).

Diff for: csdb/collection/001.dat

@@ -0,0 +1,8 @@
+function WinFileTimeToDOSFileTime(FT: Windows.TFileTime): Integer;
+begin
+  SysUtils.Win32Check(
+    Windows.FileTimeToDosDateTime(
+      FT, SysUtils.LongRec(Result).Hi, SysUtils.LongRec(Result).Lo
+    )
+  );
+end;

Diff for: csdb/collection/002.dat

@@ -0,0 +1,9 @@
+function WinFileTimeToDateTime(FT: Windows.TFileTime): TDateTime;
+var
+  SysTime: Windows.TSystemTime; // stores date/time in system time format
+begin
+  // Convert file time to system time, raising exception on error
+  SysUtils.Win32Check(Windows.FileTimeToSystemTime(FT, SysTime));
+  // Convert system time to Delphi date time, raising excpetion on error
+  Result := SysUtils.SystemTimeToDateTime(SysTime);
+end;

Diff for: csdb/collection/003.dat

@@ -0,0 +1,4 @@
+function WinFileTimeToStr(FT: Windows.TFileTime): string;
+begin
+  Result := SysUtils.DateTimeToStr(WinFileTimeToDateTime(FT));
+end;

Diff for: csdb/collection/004.dat

@@ -0,0 +1,18 @@
+function ParseDelims(const TextLine: string; var StartPos: Integer;
+  const Delims: string): string;
+var
+  StringEnd: Integer;     // tracks end of current string being parsed out
+begin
+  // Find next non-delimiter char - this is where token starts
+  while (StartPos <= Length(TextLine))
+    and SysUtils.IsDelimiter(Delims, TextLine, StartPos) do
+    Inc(StartPos);
+  // Now find next delimiter - this is where token ends
+  StringEnd := StartPos;
+  while (StringEnd <= Length(TextLine))
+    and not SysUtils.IsDelimiter(Delims, TextLine, StringEnd) do
+    Inc(StringEnd);
+  // Copy result out of string
+  Result := Copy(TextLine, StartPos, StringEnd - StartPos);
+  StartPos := StringEnd + 1;
+end;

Diff for: csdb/collection/005.dat

@@ -0,0 +1,17 @@
+procedure CreateURLShortcut(const ShortcutFile, URL: string);
+var
+  F: TextFile;  // text file
+begin
+  {$I+} // ensure file i/o raises exception on error
+  // Open new file for writing (overwrites any existing file)
+  AssignFile(F, ShortcutFile);
+  Rewrite(F);
+  try
+    // Write file contents: this is simplest basic format of shortcut file
+    WriteLn(F, '[InternetShortcut]');
+    WriteLn(F, 'URL=', URL);
+  finally
+    // Close file
+    CloseFile(F);
+  end;
+end;

Diff for: csdb/collection/006.dat

@@ -0,0 +1,17 @@
+function DeleteFileWithUndo(const FileName: string): Boolean;
+var
+  FOS: ShellAPI.TSHFileOpStruct;  // contains info about required file operation
+begin
+  // Set up structure that determines file operation
+  FillChar(FOS, SizeOf(FOS), 0);
+  with FOS do
+  begin
+    wFunc := ShellAPI.FO_DELETE;      // we're deleting
+    pFrom := PChar(FileName + #0);    // this file (#0#0 terminated)
+    fFlags := ShellAPI.FOF_ALLOWUNDO  // with facility to undo op
+      or ShellAPI.FOF_NOCONFIRMATION  // and we don't want any dialogs
+      or ShellAPI.FOF_SILENT;
+  end;
+  // Perform the operation
+  Result := ShellAPI.SHFileOperation(FOS) = 0;
+end;

Diff for: csdb/collection/007.dat

@@ -0,0 +1,7 @@
+function IsDirectory(const DirName: string): Boolean;
+var
+  Attr: Integer;  // directory's file attributes
+begin
+  Attr := SysUtils.FileGetAttr(DirName);
+  Result := (Attr <> -1) and IsFlagSet(Attr, SysUtils.faDirectory);
+end;

Diff for: csdb/collection/008.dat

@@ -0,0 +1,4 @@
+function DOSToUnixPath(const PathName: string): string;
+begin
+  Result := SysUtils.StringReplace(PathName, '\', '/', [SysUtils.rfReplaceAll]);
+end;

Diff for: csdb/collection/009.dat

@@ -0,0 +1,16 @@
+function GetFileDate(const FName: string): Integer;
+var
+  FileH: Integer;   // file handle
+begin
+  // Open file
+  FileH := SysUtils.FileOpen(FName, SysUtils.fmOpenRead);
+  if FileH = -1 then
+    // Couldn't open file - return -1 to indicate can't get date
+    Result := -1
+  else
+  begin
+    // File opened OK - record date and close file
+    Result := SysUtils.FileGetDate(FileH);
+    SysUtils.FileClose(FileH);
+  end;
+end;

Diff for: csdb/collection/010.dat

@@ -0,0 +1,38 @@
+function GetFixedFileVerInfo(const FileName: string;
+  out FFI: Windows.TVSFixedFileInfo): Boolean;
+var
+  VerInfoBuf: Pointer;    // points to memory storing version info
+  VerInfoSize: Integer;   // size of version info memory
+  Dummy: Cardinal;        // unused parameter required by API function
+  PFFI: Pointer;          // points to fixed file info
+  FFISize: Windows.UINT;  // size of file file info returned from API (unused)
+begin
+  // Assume failure: sets zero result
+  FillChar(FFI, SizeOf(FFI), 0);
+  Result := False;
+  // Get size of version info: there is none if this is zero
+  VerInfoSize := Windows.GetFileVersionInfoSize(PChar(FileName), Dummy);
+  if VerInfoSize > 0 then
+  begin
+    // Allocate memory to store ver info
+    GetMem(VerInfoBuf, VerInfoSize);
+    try
+      // Get the version info, filling buffer
+      if Windows.GetFileVersionInfo(
+        PChar(FileName), Dummy, VerInfoSize, VerInfoBuf
+      ) then
+      begin
+        // Get a pointer to fixed file info
+        if Windows.VerQueryValue(VerInfoBuf, '\', PFFI, FFISize) then
+        begin
+          // Got pointer OK: record file version
+          FFI := Windows.PVSFixedFileInfo(PFFI)^;
+          Result := True;
+        end;
+      end;
+    finally
+      // Dispose of ver info storage
+      FreeMem(VerInfoBuf, VerInfoSize);
+    end;
+  end;
+end;

Diff for: csdb/collection/011.dat

@@ -0,0 +1,15 @@
+function SetFileDate(const FName: string; const ADate: Integer): Boolean;
+var
+  FileH: Integer;   // file handle
+begin
+  // Open file (assume failure)
+  Result := False;
+  FileH := SysUtils.FileOpen(FName, SysUtils.fmOpenWrite);
+  if FileH <> -1 then
+  begin
+    // File opened OK - set date and close file
+    SysUtils.FileSetDate(FileH, ADate);
+    SysUtils.FileClose(FileH);
+    Result := True;
+  end;
+end;