[DFDL-WG] proposal: add fn:error function and dfdl:hex function to DFDL

[Mike Beckerle]

Proposal revised for dfdl:hex, and clarification added on fn:error when
used inside assert.

Revised language below:

Proposed: add fn:error function and add dfdl:hexBinary function.

DFDL only needs one of the several variations of fn:error.

fn:error($error as xs:QName?, $description as xs:string) as none

The behavior of fn:error in DFDL expressions is the same as described in
XPath 2.0, an example is given below.

dfdl:hexBinary($arg as xs:anyAtomicType?) as xs:hexBinary?

This function provides an extension to the behavior of the xs:hexBinary
constructor. The argument can be a string, in which case the behavior is as
the xs:hexBinary constructor. The argument can also be a long,
unsignedLong, or any subtype thereof, and in that case a string containing
hexadecimal digits is produced. The hexadecimal digits produced that are
letters are always uppercase. The number of hex digits in the resulting
string is a function of the input type. If byte or unsigned byte, exactly 2
hex digits are produced, for short and unsignedShort, 4 hex digits, and so
on. The hex digits correspond to a big-endian representation of a
twos-complement binary representation of the argument value. So:

dfdl:short(xs:concat('x', dfdl:hexBinary(xs:short(208)))) eq xs:short(208)

is true, and a corresponding tautology holds for all the other DFDL
functions that construct integers from hexadecimal, if you replace the 208
above with a value in range for the corresponding numeric type.

If the argument is a numeric literal, then the smallest signed integer type
(long, int, short, byte) is selected that can contain the value, and the
number of hexadecimal digits produced corresponds to that type. So:

dfdl:hexBinary(208) eq 'D0'
dfdl:hexBinary(-2084) eq 'F7FF'

Example of fn:error and dfdl:hexBinary:

This expression allows a meaningful error message that includes the
offending parts of data.

fn:error(ex:magic_number, fn:concat("The magic number: 0x",
dfdl:hexBinary(.), " was not 0xA1B2C3D4 (for bigEndian) or 0xD4C3B2A1 (for
littleEndian)."))

The $error argument (of type QName) is used in an implementation-dependent
manner to provide the context of the error. So for example, if namespace
prefix 'ex' is bound to 'http://example.com' then the above call might
produce:

"Error: {http://example.com}magic_number - The magic number: 0xFEFF0000 was
not 0xA1B2C3D4 (for bigEndian) or 0xD4C3B2A1 (for littleEndian)."

Only the part of the above string after the hyphen is standardized. The
hyphen and part before the hyphen is implementation dependent.

fn:error, if called from inside an assert or discriminator, causes the
assert or discriminator to fail (as with any processing error that occurs
during evaluation of the assert or discriminator expression).  If the
assert or discriminator has a message property, then it is implementation
dependent how that message string is combined with the description string
argument provided to the fn:error function.



On Thu, Jun 20, 2013 at 1:09 PM, Mike Beckerle <mbeckerle.dfdl at gmail.com>wrote:

>
> Proposed: add fn:error function and add dfdl:hex function.
>
> DFDL only needs one of the several variations of fn:error
>
> fn:error($error as xs:QName?, $description as xs:string) as none
>
> dfdl:hex($num as xs:integer) as string
>
> The dfdl:hex function inverts the behavior of the dfdl:byte, and related
> functions (currently also proposed) which take a string specification of a
> hex value. The argument to dfdl:hex can be a long, unsignedLong, or any
> subtype thereof. The number of hex digits in the resulting string is a
> function of the input type. If byte or unsigned byte, exactly 2 hex digits
> are produced, for short and unsignedShort, 4 hex digits, and so on. The
> resulting value contains a prefix 'x' character as its first character. So:
>
> dfdl:short(dfdl:hex(xs:short(208))) eq xs:short(208)
>
> is true, and a corresponding tautology holds for all the other DFDL
> functions that construct integers from hexadecimal, if you replace the 208
> above with a value in range for the corresponding numeric type.
>
> Example:
>
> This allows a meaningful error message that includes the offending parts
> of data.
>
> fn:error(ex:magic_number, fn:concat("The magic number: 0", dfdl:hex(.), "
> was not 0xA1B2C3D4 (for bigEndian) or 0xD4C3B2A1 (for littleEndian)."))
>
> The $error argument (of type QName) is used in an implementation-dependent
> manner to provide the context of the error. So for example, if namespace
> prefix 'ex' is bound to 'http://example.com' then the above call might
> produce:
>
> "Error: {http://example.com}magic_number - The magic number: 0xFEFF0000
> was not 0xA1B2C3D4 (for bigEndian) or 0xD4C3B2A1 (for littleEndian)."
>
> Only the part of the above string after the hyphen is standardized. The
> hyphen and part before the hyphen is implementation dependent.
>
>


-- 
Mike Beckerle | OGF DFDL Workgroup Co-Chair | Tresys Technology |
www.tresys.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.ogf.org/pipermail/dfdl-wg/attachments/20130709/d8905449/attachment.html>