API

This is a package I use to handle numerical-model parameters, thus the name. However, it should be useful otherwise too. It has two main features:

• keyword type constructors with default values, and
• unpacking and packing of composite types and dicts.

The macro @with_kw which decorates a type definition to allow default values and a keyword constructor:

julia> using Parameters

julia> @with_kw struct A
           a::Int = 6
           b::Float64 = -1.1
           c::UInt8
       end

julia> A(c=4)
A
  a: 6
  b: -1.1
  c: 4

Unpacking is done with @unpack (@pack! is similar):

struct B
    a
    b
    c
end
@unpack a, c = B(4,5,6)
# is equivalent to
BB = B(4,5,6)
a = BB.a
c = BB.c

Make a new instance of a type with the same values as the input type except for the fields given in the AbstractDict second argument or as keywords. Works for types, Dicts, and NamedTuples.

Note: this is not very performant. Check Setfield.jl for a faster & nicer implementation.

julia> using Parameters

julia> struct A
           a
           b
       end

julia> a = A(3,4)
A(3, 4)

julia> b = reconstruct(a, b=99)
A(3, 99)

Transforms a type-instance into a dictionary.

julia> type T
           a
           b
       end

julia> type2dict(T(4,5))
Dict{Symbol,Any} with 2 entries:
  :a => 4
  :b => 5

Packs variables into a mutable, composite type, a Dict{Symbol}, or a Dict{String}

@pack! dict_or_typeinstance = a, b, c

Example with dict:

a = 5.0
c = "Hi!"
d = Dict{Symbol,Any}()
@pack! d = a, c
d # Dict{Symbol,Any}(:a=>5.0,:c=>"Hi!")

Example with type:

a = 99
c = "HaHa"
mutable struct A; a; b; c; end
d = A(4,7.0,"Hi")
@pack! d = a, c
d.a == 99 #true
d.c == "HaHa" #true

Note that its functionality can be extende by adding methods to the Parameters.pack! function.

Unpacks fields/keys from a composite type, a Dict{Symbol}, a Dict{String}, or a module into variables

@unpack a, b, c = dict_or_typeinstance

Example with dict:

d = Dict{Symbol,Any}(:a=>5.0,:b=>2,:c=>"Hi!")
@unpack a, c = d
a == 5.0 #true
c == "Hi!" #true

Example with type:

struct A; a; b; c; end
d = A(4,7.0,"Hi")
@unpack a, c = d
a == 4 #true
c == "Hi" #true

Note that its functionality can be extende by adding methods to the Parameters.unpack function.

Macro which allows default values for field types and a few other features.

Basic usage:

@with_kw struct MM{R}
    r::R = 1000.
    a::Int = 4
end

For more details see manual.

As @with_kw but does not define a show method to avoid annoying redefinition warnings.

@with_kw_noshow struct MM{R}
    r::R = 1000.
    a::Int = 4
end

For more details see manual.

This function is invoked to pack one entity into some DataType and has signature:

pack!(dt::Any, ::Val{field}, value) -> value

Note that this means the only symbols or immutable field-descriptors are allowed, as they are used as type parameter in Val.

Two definitions are included in the package to pack into a composite type or into a dictionary with Symbol or string keys:

@inline pack!(x, ::Val{f}, val) where {f} = setfield!(x, f, val)
@inline pack!(x::AbstractDict{Symbol}, ::Val{k}, val) where {k} = x[k]=val
@inline pack!(x::AbstractDict{S}, ::Val{k}, val) where {S<:AbstractString,k} = x[string(k)]=val

More methods can be added to allow for specialized packing of other datatypes.

See also unpack.

This function is invoked to unpack one field/entry of some DataType dt and has signature:

unpack(dt::Any, ::Val{field}) -> value of field

The field is the symbol of the assigned variable.

Three definitions are included in the package to unpack a composite type or a dictionary with Symbol or string keys:

@inline unpack(x, ::Val{f}) where {f} = getfield(x, f)
@inline unpack(x::AbstractDict{Symbol}, ::Val{k}) where {k} = x[k]
@inline unpack(x::AbstractDict{S}, ::Val{k}) where {S<:AbstractString,k} = x[string(k)]

More methods can be added to allow for specialized unpacking of other datatypes.

See also pack!.

This function is called by the @with_kw macro and does the syntax transformation from:

@with_kw struct MM{R}
    r::R = 1000.
    a::R
end

into

struct MM{R}
    r::R
    a::R
    MM{R}(r,a) where {R} = new(r,a)
    MM{R}(;r=1000., a=error("no default for a")) where {R} = MM{R}(r,a) # inner kw, type-paras are required when calling
end
MM(r::R,a::R) where {R} = MM{R}(r,a) # default outer positional constructor
MM(;r=1000,a=error("no default for a")) =  MM(r,a) # outer kw, so no type-paras are needed when calling
MM(m::MM; kws...) = reconstruct(mm,kws)
MM(m::MM, di::Union{AbstractDict, Tuple{Symbol,Any}}) = reconstruct(mm, di)
macro unpack_MM(varname)
    esc(quote
    r = varname.r
    a = varname.a
    end)
end
macro pack_MM(varname)
    esc(quote
    varname = Parameters.reconstruct(varname,r=r,a=a)
    end)
end

Do the with-kw stuff for named tuples.