API

Parameters — Module.

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

source

Parameters.reconstruct — Method.

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> struct A
           a
           b
       end

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

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

source

Parameters.type2dict — Method.

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

source

Parameters.with_kw — Function.

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

source

Parameters.@pack — Macro.

Packs variables into a composite type or a Dict{Symbol}

@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

source

Parameters.@unpack — Macro.

Unpacks fields/keys from a composite type or a Dict{Symbol} 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

source

Parameters.@with_kw — Macro.

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.

source

Parameters.@with_kw_noshow — Macro.

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.

source

Parameters.pack! — Function.

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!{f}(x, ::Val{f}, val) = setfield!(x, f, val)
@inline pack!{k}(x::AbstractDict{Symbol}, ::Val{k}, val) = x[k]=val
@inline pack!{S<:AbstractString,k}(x::AbstractDict{S}, ::Val{k}, val) = x[string(k)]=val

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