feat(developer): add relatedPackages metadata

Adds relatedPackages support to:
* .kps schema
* .kps file format for Typescript
* kmp.json file format for Typescript
* kmc-package compiler
* Package Editor

Author: mcdurdin

common/schemas/kps/kps.xsd

@@ -97,6 +97,19 @@
         </xs:complexType>
       </xs:element>
 
+      <xs:element minOccurs="0" maxOccurs="1" name="RelatedPackages">
+        <xs:complexType>
+          <xs:sequence>
+            <xs:element minOccurs="0" maxOccurs="unbounded" name="RelatedPackage">
+              <xs:complexType>
+                <xs:attribute name="ID" type="xs:string" />
+                <!-- "deprecates" is only valid value, if not present then means "related" -->
+                <xs:attribute name="Relationship" type="km-package-relationship" />
+              </xs:complexType>
+            </xs:element>
+          </xs:sequence>
+        </xs:complexType>
+      </xs:element>
 
       <xs:element minOccurs="0" maxOccurs="1" name="Keyboards">
         <xs:complexType>
@@ -137,6 +150,7 @@
         </xs:complexType>
       </xs:element>
 
+      <!-- Deprecated elements: we won't validate as processors ignore them -->
 
       <xs:element minOccurs="0" maxOccurs="1" name="Strings">
         <xs:complexType>
@@ -151,8 +165,6 @@
         </xs:complexType>
       </xs:element>
 
-      <!-- Deprecated elements: we won't validate as processors ignore them -->
-
       <xs:element minOccurs="0" maxOccurs="1" name="Buttons" type="km-any" />
       <xs:element minOccurs="0" maxOccurs="1" name="Registry" type="km-any" />
 
@@ -191,6 +203,12 @@
   </xs:restriction>
 </xs:simpleType>
 
+<xs:simpleType name="km-package-relationship">
+  <xs:restriction base="xs:string">
+    <xs:pattern value="deprecates" />
+  </xs:restriction>
+</xs:simpleType>
+
 <xs:simpleType name="km-start-menu-location">
   <xs:restriction base="xs:string">
     <xs:pattern value="psmelStartMenu|psmelDesktop"></xs:pattern>

common/web/types/src/package/kmp-json-file.ts

@@ -6,6 +6,7 @@ export interface KmpJsonFile {
   lexicalModels?: KmpJsonFileLexicalModel[];
   startMenu?: KmpJsonFileStartMenu;
   keyboards?: KmpJsonFileKeyboard[];
+  relatedPackages?: KmpJsonRelatedPackage[];
 }
 
 export interface KmpJsonFileSystem {
@@ -103,4 +104,9 @@ export interface KmpJsonFileExample {
    * A short description of what the text means or represents
    */
   note?: string;
-}
+}
+
+export interface KmpJsonRelatedPackage {
+  id: string;
+  relationship: "deprecates" | "related";
+}

common/web/types/src/package/kps-file.ts

@@ -29,6 +29,7 @@ export interface KpsFile {
   lexicalModels?: KpsFileLexicalModels;
   startMenu?: KpsFileStartMenu;
   strings?: KpsFileStrings;
+  relatedPackages?: KpsFileRelatedPackages;
 }
 
 export interface KpsFileSystem {
@@ -92,6 +93,20 @@ export interface KpsFileLanguage {
   $: { ID: string }
 }
 
+export interface KpsFileRelatedPackages {
+  relatedPackage: KpsFileRelatedPackage | KpsFileRelatedPackage[];
+}
+
+export interface KpsFileRelatedPackage {
+  $: {
+    ID: string;
+    /**
+     * relationship between this package and the related package, "related" is default if not specified
+     */
+    Relationship?: "deprecates";
+  }
+}
+
 export interface KpsFileKeyboard {
   name: string;     /// the descriptive name of the keyboard
   iD: string;       /// the keyboard identifier, equal to the basename of the keyboard file sans extension

common/windows/delphi/packages/PackageInfo.pas

@@ -404,6 +404,24 @@   TPackageLexicalModelList = class(TPackageObjectList<TPackageLexicalModel>)
     function ItemByID(id: string): TPackageLexicalModel;
   end;
 
+  TPackageRelatedPackage = class(TPackageBaseObject)
+  private
+    FID: string;
+    FRelationship: string;
+  public
+    procedure Assign(Source: TPackageRelatedPackage); virtual;
+    property ID: string read FID write FID;
+    property Relationship: string read FRelationship write FRelationship;
+  end;
+
+  TPackageRelatedPackageList = class(TPackageObjectList<TPackageRelatedPackage>)
+    procedure Assign(Source: TPackageRelatedPackageList); virtual;
+    procedure LoadXML(ARoot: IXMLNode); virtual;
+    procedure SaveXML(ARoot: IXMLNode); virtual;
+    procedure LoadJSON(ARoot: TJSONObject); virtual;
+    procedure SaveJSON(ARoot: TJSONObject); virtual;
+  end;
+
   { TPackage }
 
   TPackage = class
@@ -428,6 +446,7 @@   TPackage = class
     Info: TPackageInfoEntryList;
     Keyboards: TPackageKeyboardList;
     LexicalModels: TPackageLexicalModelList;
+    RelatedPackages: TPackageRelatedPackageList;
 
     property FileName: WideString read FFileName write FFileName;
     procedure Assign(Source: TPackage); virtual;
@@ -455,6 +474,9 @@   TPackage = class
 const
   PackageStartMenuEntryLocationName: array[TPackageStartMenuEntryLocation] of WideString = ('Start Menu', 'Desktop'); //, 'Quick Launch Toolbar');
 
+const
+  S_RelatedPackage_Deprecates = 'deprecates';
+
 implementation
 
 uses
@@ -475,9 +497,6 @@ implementation
   SDisplayFontNotOwnedCorrectly = 'The display font file ''%s'' referred to is not part of the package.';
   SOSKFontNotOwnedCorrectly = 'The OSK font file ''%s'' referred to is not part of the package.';
 
-
-
-
 const
   SXML_PackageKeyboards = 'Keyboards';
   SXML_PackageKeyboard = 'Keyboard';
@@ -507,6 +526,11 @@ implementation
   SXML_PackageLexicalModel_RTL = 'RTL';
   SXML_PackageLexicalModel_Languages = 'Languages';
 
+  SXML_PackageRelatedPackages = 'RelatedPackages';
+  SXML_PackageRelatedPackage = 'RelatedPackage';
+  SXML_PackageRelatedPackage_ID = 'ID';
+  SXML_PackageRelatedPackage_Relationship = 'Relationship';
+
 const
   SJSON_System = 'system';
   SJSON_System_KeymanDeveloperVersion = 'keymanDeveloperVersion';
@@ -584,6 +608,10 @@ implementation
   SJSON_LexicalModel_RTL = 'rtl';
   SJSON_LexicalModel_Languages = 'languages';
 
+  SJSON_RelatedPackages = 'relatedPackages';
+  SJSON_RelatedPackage_ID = 'id';
+  SJSON_RelatedPackage_Relationship = 'relationship';
+
 function XmlVarToStr(v: OleVariant): string;
 begin
   Result := ReplaceStr(ReplaceStr(Trim(VarToStr(v)), #$D#$A, #$A), #$A, #$D#$A);
@@ -1479,6 +1507,7 @@ procedure TPackage.Assign(Source: TPackage);
   Info.Assign(Source.Info);
   Keyboards.Assign(Source.Keyboards);
   LexicalModels.Assign(Source.LexicalModels);
+  RelatedPackages.Assign(Source.RelatedPackages);
 end;
 
 constructor TPackage.Create;
@@ -1491,6 +1520,7 @@ constructor TPackage.Create;
   if not Assigned(Info)      then Info      := TPackageInfoEntryList.Create(Self);
   if not Assigned(Keyboards) then Keyboards := TPackageKeyboardList.Create(Self);
   if not Assigned(LexicalModels) then LexicalModels := TPackageLexicalModelList.Create(Self);
+  if not Assigned(RelatedPackages) then RelatedPackages := TPackageRelatedPackageList.Create(Self);
 end;
 
 destructor TPackage.Destroy;
@@ -1501,6 +1531,7 @@ destructor TPackage.Destroy;
   Info.Free;
   Keyboards.Free;
   LexicalModels.Free;
+  RelatedPackages.Free;
   inherited Destroy;
 end;
 
@@ -1534,6 +1565,7 @@ procedure TPackage.DoLoadIni(ini: TIniFile);
   Options.LoadIni(ini);
   Keyboards.LoadIni(ini);
   //LexicalModels not supported in ini
+  //RelatedPackages not supported in ini
 end;
 
 procedure TPackage.LoadJSON;
@@ -1652,8 +1684,9 @@ procedure TPackage.DoLoadJSON(ARoot: TJSONObject);
   Files.LoadJSON(ARoot);
   Options.LoadJSON(ARoot);
   Keyboards.LoadJSON(ARoot);
-  if Options.FileVersion = SKeymanVersion120 then
+  if CompareVersions(Options.FileVersion, SKeymanVersion120) >= 0 then
     LexicalModels.LoadJSON(ARoot);
+  RelatedPackages.LoadJSON(ARoot);
 end;
 
 procedure TPackage.DoLoadXML(ARoot: IXMLNode);
@@ -1672,8 +1705,9 @@ procedure TPackage.DoLoadXML(ARoot: IXMLNode);
   Files.LoadXML(ARoot);
   Options.LoadXML(ARoot);
   Keyboards.LoadXML(ARoot);
-  if FVersion = SKeymanVersion120 then
+  if CompareVersions(FVersion, SKeymanVersion120) >= 0 then
     LexicalModels.LoadXML(ARoot);
+  RelatedPackages.LoadXML(ARoot);
 end;
 
 procedure TPackage.DoSaveIni(ini: TIniFile);
@@ -1685,6 +1719,7 @@ procedure TPackage.DoSaveIni(ini: TIniFile);
   Files.SaveIni(ini);
   Keyboards.SaveIni(ini);
   // Lexical models not supported in ini
+  // RelatedPackages not supported in ini
 end;
 
 procedure TPackage.FixupFileVersion;
@@ -1706,6 +1741,7 @@ procedure TPackage.DoSaveJSON(ARoot: TJSONObject);
   Keyboards.SaveJSON(ARoot);
   if LexicalModels.Count > 0 then
     LexicalModels.SaveJSON(ARoot);
+  RelatedPackages.SaveJSON(ARoot);
 end;
 
 procedure TPackage.DoSaveXML(ARoot: IXMLNode);
@@ -1719,6 +1755,7 @@ procedure TPackage.DoSaveXML(ARoot: IXMLNode);
   Keyboards.SaveXML(ARoot);
   if LexicalModels.Count > 0 then
     LexicalModels.SaveXML(ARoot);
+  RelatedPackages.SaveXML(ARoot);
 end;
 
 procedure TPackage.SaveIni;
@@ -2530,5 +2567,110 @@ procedure TPackageKeyboardExampleList.SaveXML(ARoot: IXMLNode);
   end;
 end;
 
+{ TPackageRelatedPackage }
+
+procedure TPackageRelatedPackage.Assign(Source: TPackageRelatedPackage);
+begin
+  FID := Source.ID;
+  FRelationship := Source.Relationship;
+end;
+
+{ TPackageRelatedPackageList }
+
+procedure TPackageRelatedPackageList.Assign(Source: TPackageRelatedPackageList);
+var
+  i: Integer;
+  rp: TPackageRelatedPackage;
+begin
+  Clear;
+  for i := 0 to Source.Count - 1 do
+  begin
+    rp := TPackageRelatedPackage.Create(Package);
+    rp.Assign(Source[i]);
+    Add(rp);
+  end;
+end;
+
+procedure TPackageRelatedPackageList.LoadJSON(ARoot: TJSONObject);
+var
+  rp: TPackageRelatedPackage;
+  i: Integer;
+  ANode: TJSONArray;
+  ARelatedPackage: TJSONObject;
+begin
+  Clear;
+
+  ANode := ARoot.Values[SJSON_RelatedPackages] as TJSONArray;
+  if not Assigned(ANode) then
+    Exit;
+
+  for i := 0 to ANode.Count - 1 do
+  begin
+    ARelatedPackage := ANode.Items[i] as TJSONObject;
+
+    rp := TPackageRelatedPackage.Create(Package);
+    rp.ID := GetJsonValueString(ARelatedPackage,SJSON_RelatedPackage_ID);
+    rp.Relationship := GetJsonValueString(ARelatedPackage, SJSON_RelatedPackage_Relationship);
+    Add(rp);
+  end;
+end;
+
+procedure TPackageRelatedPackageList.LoadXML(ARoot: IXMLNode);
+var
+  rp: TPackageRelatedPackage;
+  i: Integer;
+  ARelatedPackage, ANode: IXMLNode;
+begin
+  Clear;
+
+  ANode := ARoot.ChildNodes[SXML_PackageRelatedPackages];
+  for i := 0 to ANode.ChildNodes.Count - 1 do
+  begin
+    ARelatedPackage := ANode.ChildNodes[i];
+
+    rp := TPackageRelatedPackage.Create(Package);
+    rp.ID := XmlVarToStr(ARelatedPackage.Attributes[SXML_PackageRelatedPackage_ID]);
+    rp.Relationship := XmlVarToStr(ARelatedPackage.Attributes[SXML_PackageRelatedPackage_Relationship]);
+    Add(rp);
+  end;
+end;
+
+procedure TPackageRelatedPackageList.SaveJSON(ARoot: TJSONObject);
+var
+  i: Integer;
+  ARelatedPackage: TJSONObject;
+  ARelatedPackages: TJSONArray;
+begin
+  if Count = 0 then
+    Exit;
+
+  ARelatedPackages := TJSONArray.Create;
+  ARoot.AddPair(SJSON_RelatedPackages, ARelatedPackages);
+
+  for i := 0 to Count - 1 do
+  begin
+    ARelatedPackage := TJSONObject.Create;
+    ARelatedPackages.Add(ARelatedPackage);
+
+    ARelatedPackage.AddPair(SJSON_RelatedPackage_ID, Items[i].ID);
+    ARelatedPackage.AddPair(SJSON_RelatedPackage_Relationship, Items[i].Relationship);
+  end;
+end;
+
+procedure TPackageRelatedPackageList.SaveXML(ARoot: IXMLNode);
+var
+  i: Integer;
+  ARelatedPackage, ANode: IXMLNode;
+begin
+  ANode := ARoot.AddChild(SXML_PackageRelatedPackages);
+  for i := 0 to Count - 1 do
+  begin
+    ARelatedPackage := ANode.AddChild(SXML_PackageRelatedPackage);
+
+    ARelatedPackage.Attributes[SXML_PackageRelatedPackage_ID] := Items[i].ID;
+    ARelatedPackage.Attributes[SXML_PackageRelatedPackage_Relationship] := Items[i].Relationship;
+  end;
+end;
+
 end.
 

developer/src/kmc-package/src/compiler/kmp-compiler.ts

@@ -89,6 +89,16 @@ export class KmpCompiler {
       kmp.info = this.kpsInfoToKmpInfo(kps.info);
     }
 
+    //
+    // Add related package metadata
+    //
+
+    if(kps.relatedPackages) {
+      kmp.relatedPackages = (this.arrayWrap(kps.relatedPackages.relatedPackage) as KpsFile.KpsFileRelatedPackage[]).map(p =>
+        ({id: p.$.ID, relationship: p.$.Relationship || "related"})
+      );
+    }
+
     //
     // Add file metadata
     //

developer/src/kmc-package/test/fixtures/kmp_2.0/khmer_angkor.kps

@@ -123,6 +123,10 @@ Khmer Unicode keyboard layout based on the NiDA keyboard layout. Automatically c
       <FileType>.gif</FileType>
     </File>
   </Files>
+  <RelatedPackages>
+    <RelatedPackage ID="modern_khmer" Relationship="deprecates" />
+    <RelatedPackage ID="khmer_nida" />
+  </RelatedPackages>
   <Keyboards>
     <Keyboard>
       <Name>Khmer Angkor</Name>