Page History

...

Much of the code does not follow these guidelines. As it evolves the goal is to make new code follow these guidelines, and to evolve existing code toward them.

See also Code Style Guidelines

64-bit vs. 32-bit

Our goal is all-64-bit capabilities. Unfortunately, many Java and Scala libraries do not allow offsets or positions larger than a signed 32-bit Int can hold.

Someday, maybe those libraries will be updated so that, for example, a byte array can hold an entire video, which is bigger than 2GBytes. For now we're stuck.

Our code should be written to use type Long for all offsets and positions, and only when we must deal with an underlying library that has only an Int-based API do we then cast to Int. This should be done with an explicit check, as x.toInt doesn't cause overflow errors. E.g., Long.MaxValue.toInt produces -1. No error is thrown.

Coding for Performance

Formatting

We use the standard Scala formatting as implemented by the unmodified defaults of the Scalariform tool.

Note: If you are coding using ScalaIDE (or other Eclipse configuration), the default indentation settings for Scala are not correct (as of 2019-05-21).

You must explicitly uncheck two options that they enable by default:

• Align parameters on different lines in the same column
• Align the arrows of consecutive single-line case statements

Likewise, if you are coding using IntelliJ IDEA, you must explicitly check two options that are disabled by default (File→Settings, Editor Scala, Spaces tab):

• Import braces
• Around '@' in pattern bindings

64-bit vs. 32-bit

Our goal is all-64-bit capabilities. Unfortunately, many Java and Scala libraries do not allow offsets or positions larger than a signed 32-bit Int can hold.

Someday, maybe those libraries will be updated so that, for example, a byte array can hold an entire video, which is bigger than 2GBytes. For now we're stuck.

Our code should be written to use type Long for all offsets and positions, and only when we must deal with an underlying library that has only an Int-based API do we then cast to Int. This should be done with an explicit check, as x.toInt doesn't cause overflow errors. E.g., Long.MaxValue.toInt produces -1. No error is thrown.

So, when you must have So, when you must have an Int to cope with a library, code should do this:

...

• bitPosition0b : ULong - means position, measured in bits, first bit is at position 0, type unsigned long.
• mCharWidthInBits: MaybeInt - measured in bits, but note that sizes, lengths, widths, don't have 0 or 1 base stuff. Note also use of MaybeInt type.
• childIndex1b - child index, first child is at index 1.

var bitPosition0b = ZeroBased[ULong]

var bitPosInByte1b = OneBased[UInt]

Identifier Naming Conventions

...

import org.apache.daffodil.equality._

...

There are two operators:

• a =:= b provides "Type Equality" for use when a and b have a subtype relationship, including the most obvious case of a and b both being of the same type.
• a =#= b provides "View Equality" for use when a and b are convertible, that is, a can be implicitly converted to b's type, or b can be implicitly converted to a's type. Numbers and number-like types are common cases for this so the "#" in the operator is suggestive of  "number"

...

There are some "supposedly" standard libraries that we're not using, basically because we tried and they didn't work out. Details on these efforts are below. Some day in the future this may be worth revisiting, but only if either the libraries have improved or we have someone with maintenance-level experience with them join the Daffodil project, that is, someone who knows how to make them work properlydecide to enhance them.

Apache XML Schema

This library has been tried and is inadequate to our needs currently (20122022-0212-2406). It lacks support for non-native attributes, the support for appinfo and annotations in general is difficult to use (if it works at all), and it has no escape-mechanism by which one can bypass, get back to the XML objects themselves, and overcome its limitations. It has no notion of a schema component having a location within a file, such as file, line number, and column number (It inherits this from w3c DOM Document class). It also lacks a first class notion of a schema document (corresponding to the xs:schema object defined by one file). This makes it impossible to implement DFDL's schema-file lexical scoping. 

XSOM - XML Schema Object Model

...