Reference

XAMAuxData.AuxTag — Type

AuxTag(::Union{String, SubString{String}})
AuxTag(::Char, ::Char)
AuxTag(::UInt8, ::UInt8)

The type of a key of Auxiliary. This type is lightweight, and validates that the key is of appropriate format. Auxiliary can also be modified using strings as keys, which will be converted to AuxTag, but this may cause a needless allocation of the string.

To construct an AuxTag of value "AB", you can use:

AuxTag("AB")
AuxTag('A', 'B')
AuxTag(UInt8('A'), UInt8('B'))
try_auxtag(UInt8('A'), UInt8('B'))

Throw an AuxException if the resulting AuxTag does not conform to the regex r"^[A-Za-z][A-Za-z0-9]$(Expr(:incomplete, Base.Meta.ParseError("ParseError:\n# Error @ none:1:3\n\".\n# └ ── unterminated string literal", Base.JuliaSyntax.ParseError(Base.JuliaSyntax.SourceFile("\".", 0, "none", 1, [1, 3]), Base.JuliaSyntax.Diagnostic[Base.JuliaSyntax.Diagnostic(3, 2, :error, "unterminated string literal")], :string))))

Examples

julia> AuxTag("AC")
AuxTag("AC")

julia> AuxTag('k', 'w')
AuxTag("kw")

julia> AuxTag("1C") # invalid tag
ERROR: Invalid AuxTag. Tags must conform to r"^[A-Za-z][A-Za-z0-9]$".
[...]

XAMAuxData.try_auxtag — Function

try_augtag(a::UInt8, b::UInt8)::Union{Nothing, AuxTag}

Like AuxTag(a, b), but return nothing instead of throwing an exception if the tag is invalid.

See also: AuxTag

Examples

julia> try_auxtag(UInt8('k'), UInt8('9'))
AuxTag("k9")

julia> try_auxtag(UInt8('A'), UInt8('B'))
AuxTag("AB")

julia> try_auxtag(UInt8('1'), UInt8('Z')) === nothing
true

XAMAuxData.Hex — Type

Hex(v::AbstractVector{UInt8})

Wrapper type around a byte vector. When this type is assigned to an Auxiliary, it is encoded as a hex value (type tag H) as opposed to a raw byte array ( type tag B).

julia> aux = SAM.Auxiliary(UInt8[], 1);

julia> aux["AB"] = Hex([0xae, 0xf8, 0x6c]);

julia> String(MemoryView(aux))
"AB:H:AEF86C"

julia> aux = BAM.Auxiliary(UInt8[], 1);

julia> aux["AB"] = Hex([0xae, 0xf8, 0x6c]);

julia> String(MemoryView(aux))
"ABHAEF86C\0"

XAMAuxData.Errors.Error — Type

Error

Enum type representing errors returned when loading invalid auxiliary data values. The errors are nonexhausitve - more might be added in a non-breaking release.

The following errors may contained in AbstractAuxiliary instead of the real value:

InvalidTypeTag (SAM only): An aux value with an unknown type
InvalidArrayEltype (SAM only): A B value with an unknown element type
InvalidInt (SAM only): An integer that can't be parsed to an Int32
InvalidFloat (SAM only): A float that can't be parsed to a Float32
InvalidChar: Loading a Char not in '!':'~'
InvalidString: A string that contains a character not in re"[ !-~]"
InvalidHex: a H value with an odd number of symbols, or symbol not in re"[0-9A-F]"
InvalidArray: A malformed B value

See also: Error

XAMAuxData.SAM.Auxiliary — Type

SAM.Auxiliary{T <: AbstractVector{UInt8}} <: AbstractDict{AuxTag, Any}

Lazily loaded AbstractDict representing the auxiliary data fields of a SAM record. Immutable aux's can be constructed with Auxiliary(x) for any x with MemoryView(x) defined. Mutable aux data is constructed with Auxiliary(x::Vector{UInt8}, start::Int), where start gives the first index of the used data in x - all data before start will be ignored and never modified.

Examples

julia> immut = SAM.Auxiliary("KJ:i:-1	AB:Z:abc");

julia> immut["KJ"]
-1

julia> haskey(immut, "AB")
true

Extended help

Since fields of Auxiliary are lazily loaded, auxiliaries may contain invalid data even after successful construction. Auxiliary operates with two distinct notions of invalid data - malformedness and invalidness. See is_well_formed for their definitions.

XAMAuxData.BAM.Auxiliary — Type

BAM.Auxiliary{T <: AbstractVector{UInt8}} <: AbstractDict{AuxTag, Any}

Lazily loaded AbstractDict representing the auxiliary data fields of a BAM record. Immutable aux's can be constructed with Auxiliary(x) for any x with MemoryView(x) defined. Mutable aux data is constructed with Auxiliary(x::Vector{UInt8}, start::Int), where start gives the first index of the used data in x - all data before start will be ignored and never modified.

Examples

julia> immut = BAM.Auxiliary("KJS\0ABZabc\0");

julia> immut["KJ"]
0x0007

julia> haskey(immut, "AB")
true

Extended help

XAMAuxData.is_well_formed — Function

is_well_formed(aux::AbstractAuxiliary) -> Bool

Check if the auxiliary is well formed. AbstractAuxiliary distinguishes two ways their data can be incorrect: If the data is corrupted such that it is not possible to identify the key, or start/end of the encoded data of the value for a key/value pair, we say the auxiliary is malformed. Accessing values, or iterating such an auxiliary may or may not throw an exception. This notion of malformedness is what this function checks for.

Alternatively, if the keys and encoded values can be identified, but the encoded values are corrupt and the value cannot be loaded, we say the auxiliary is invalid. Such auxiliaries can be iterated over, and the values can be loaded, although the loaded value will be of type XAMAuxData.Error. This can be checked for with isvalid. Valid auxiliaries are always well-formed.

Examples

julia> aux = SAM.Auxiliary("KM:i:252\tAK::C"); # bad key

julia> is_well_formed(aux)
false

julia> aux["KM"] # loading a value may error
252

julia> aux["AK"] # loading a value may error
ERROR: Invalid SAM tag header. Expected <AuxTag>:<type tag>:, but found no colons.
[...]

julia> aux = SAM.Auxiliary("AB:Z:αβγδ\tCD:f:-1.2"); # bad value encoding

julia> (is_well_formed(aux), isvalid(aux))
(true, false)

julia> aux["AB"] # note: numerical value of enum is not API
InvalidString::Error = 9

Base.isvalid — Method

isvalid(aux::AbstractAuxiliary) -> Bool

Check if the auxiliary is well formed, and that all the values can be loaded without returning an XAMAuxData.Error.

Examples

julia> aux = SAM.Auxiliary("AB:i:not an integer");

julia> is_well_formed(aux)
true

julia> isvalid(aux)
false