adif 317.0.0

Amateur Data Interchange Format (ADIF) parser for Dart.

Dart_adif

Amateur Data Interchange Format (ADIF) parser for Dart.

There are three parts among the version. The first part is the version of the related ADIF file, for example 317 refers to ADIF 3.1.7. The second and third part are the version of this library that is compatiple to the corresponding ADIF version. This library supports both ADI and ADX formats.

Note:

• Submodes are considered as strings, but please use the submodes enumeration for interoperability.
• This library rejects to generate non-standard ADIF texts. All the fields are checked strictly (eg. non-ASCII characters are not allowed in non-international fields). However, as many programs actually puts non-ASCII UTF-8 characters in ADI files (as there is no international field for ADI), you can configure whether to recognize the characters and try to transfer them to their international versions.

When you want to upgrade the library for better functionality, please check the possible breaking changes in the CHANGELOG.

Usage

Import an ADIF object

To parse an ADI string, use the method provided in the extension AdifOperations:

final adifObj = AdifOperations.parseAdiString(adiString);

To parse more smoothly, you may want to ignore data that illegal to ADIF:

final adifObj = AdifOperations.parseAdiString(
  adiString,
  ignoreIllegals: true,
  nonAsciiParse: NonAsciiParseOption.parseByCharacter
);

When your ADI string contains non-ASCII characters generated by non-standard programs, you may choose one of the following nonAsciiParseOption:

• throwError: Refuses to parse ADI texts if non-ASCII characters are found.
• parseByCharacter: Regard each non-ASCII character as a single character for ADI.
• parseByByte: Regard each byte as a single character for ADI.

For ADX strings, use the method provided in the extension AdifOperations:

final adifObj = AdifOperations.parseAdxString(adxString);

Also you may want to ignore data that illegal to ADIF:

final adifObj = AdifOperations.parseAdxString(adxString, ignoreIllegals: true);

Build an ADIF object manually and export it to ADI/ADX

First let's see the data structure of a QSO:

class Qso {
  /// The QSO's ADIF-defined fields.
  List<AdifField> adifdefs;

  /// The application-defined fields.
  List<Appdef> appdefs;

  /// The user-defined fields.
  List<Userdef> userdefs;
}

You can generate a QSO like this:

// Use ADIF-defined fields.
final call = adifFieldFactory('CALL', 'BA1ABC');
final date = adifFieldFactory('DATE', '20250505');

// Use app-defined fields.
final myRig = Appdef.generate(
  'dart-adif.test_suites', // Program ID
  'PHONE_NUMBER', // Field name
  'S', // Type
  '[phone]' // Value in string
);
final gender = Appdef.generate(
  'dart-adif.test_suites',
  'GENDER',
  'E', // Enumerations.
  'M',
  enums: ['M', 'F', 'X'], // When use enumerations, this field should be provided.
);

// Use user-defined fields.
final opNumber = Userdef.generate(
  'OP_NUMBER', // Field name
  'N', // Type
  '3', // Value in string
  range: (1, 10), // optional allowed range (min, max) for numbers
)

final qso = Qso([call, date], [myRig, gender], [opNumber]);

For the available types, see ADIF types. The fields enums and range are available for both App and user defined fields to specify the type more clearly. And here is the structure of an ADIF object:

class Adif {
  /// The ADIF version. Generally defined by this library.
  String adifVer = adifVersion;

  /// Created timestamp, shall be converted to string when converting.
  /// Generated automatically.
  DateTime? createdTimestamp = DateTime.now().toUtc();

  /// The program's name.
  final String? programid;

  /// The program's version.
  final String? programversion;

  /// The QSO data.
  List<Qso> data;

  Adif(this.programid, this.programversion, this.userdef, this.data);
}

Give the fields of your program, leave the userdef as empty, and put the QSOs together as a list, you can get an ADIF object:

// Generate an ADIF log.
final adif = Adif(
  "dart-adif.test_suites",
  "315.2.0",
  [qso1, qso2, qso3]);

You can export it into an ADI string:

final String adiString = adif.buildAdiString(nonAsciiBuildOption: NonAsciiBuildOption.throwError);

As ADI texts are not allowed to contain non-ASCII characters, when your QSOs contain international fields, you may use one of the following nonAsciiBuildOption:

• throwError: Refuses to generate texts if international fields are found.
• removeCharacters: Remove non-ASCII characters directly from the strings and try to transfer them to their non-international versions. If the process fails, throw an exception.
• removeFields: Ignore all international fields.

Also you may export it into an ADX string:

final String adxString = adif.buildAdxString();

Roadmap

Supported ADIF Data types

• ✅ AwardList
• ✅ Boolean
• ✅ Character
• ✅ CreditList
• ✅ Date
• ✅ Digit
• ✅ Enumeration
• ✅ GridSquare
• ✅ GridSquareExt
• ✅ GridSquareList
• ✅ Integer
• ✅ IntlCharacter
• ✅ IntlMultilineString
• ✅ IntlString
• ✅ IOTARefNo
• ✅ Location
• ✅ MultilineString
• ✅ Number
• ✅ PositiveInteger
• ✅ POTARef
• ✅ POTARefList
• ✅ SecondarySubdivisionList (Secondary_Administrative_Subdivision_Alt items are treated as strings)
• ❌ SecondaryAdministrativeSubdivisionListAlt
• ✅ SOTARef
• ❌ SponsoredAwardList
• ✅ String
• ✅ Time
• ✅ WWFFRef

Supported operations

• ✅ Import from ADI
• ✅ Export to ADI
• ✅ Import from ADX
• ✅ Export to ADX

ADIF-defined fields unsupported yet

• AWARD_SUBMITTED
• AWARD_GRANTED
• CNTY
• CNTY_ALT
• DARK_DOK
• MY_CNTY
• MY_CNTY_ALT
• MY_DARK_DOK
• MY_STATE
• STATE