Using UnPack.jl (#112)

Author: mauro3

Project.toml

@@ -5,10 +5,12 @@ version = "0.12.0"
 
 [deps]
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
+UnPack = "3a884ed6-31ef-47d7-9d2a-63182c4928ed"
 
 [compat]
-OrderedCollections = "≥ 0.1.0"
-julia = "≥ 1.0.0"
+OrderedCollections = "1"
+UnPack = "0.1"
+julia = "1"
 
 [extras]
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"

docs/src/manual.md

@@ -180,14 +180,19 @@ Since the macro operates on a single tuple expression (as opposed to a tuple of
 
 # (Un)pack macros
 
+## `@unpack` and `@pack` re-exported from UnPack.jl
+
 When working with parameters, or otherwise, it is often convenient to
 unpack (and pack, in the case of mutable datatypes) some or all of the
 fields of a type.  This is often the case when passed into a function.
 
-The preferred to do this is using the [`@unpack`](@ref) and [`@pack!`](@ref) macros
-which are generic and also work with non-`@with_kw` types, modules, and
-dictionaries (and can be customized for other types too, see next section). Continuing
-with the `Para` type defined above:
+The preferred to do this is using the `@unpack` and
+`@pack!` macros from the package
+[UnPack.jl](https://github.com/mauro3/UnPack.jl).  These are generic
+and also work with non-`@with_kw` stucts, named-tuples, modules, and
+dictionaries.
+Here one example is given, for more see the README of
+UnPack. Continuing with the `Para` struct defined above:
 
 ```julia
 function fn2(var, pa::Para)
@@ -201,64 +206,14 @@ end
 out, pa = fn2(7, pa)
 ```
 
-Example with a dictionary:
-
-```julia
-d = Dict{Symbol,Any}(:a=>5.0,:b=>2,:c=>"Hi!")
-@unpack a, c = d
-a == 5.0 #true
-c == "Hi!" #true
-
-d = Dict{String,Any}()
-@pack! d = a, c
-d # Dict{String,Any}("a"=>5.0,"a"=>"Hi!")
-```
-
-## Customization of `@unpack` and `@pack!`
-
-What happens during the (un-)packing of a particular datatype is
-determined by the functions [`Parameters.unpack`](@ref) and
-[`Parameters.pack!`](@ref).
-
-The `Parameters.unpack` function is invoked to unpack one entity of some
-`DataType` and has signature:
-
-`unpack(dt::Any, ::Val{property}) -> value of property`
-
-Note that `unpack` (and `pack!`) works with `Base.getproperty`.  By
-default this means that all the fields of a type are unpacked but if
-`getproperty` is overloaded, then it will unpack accordingly.
-
-Two definitions are included in the package to unpack a composite type/module
-or a dictionary with Symbol or string keys:
-
-```
-@inline unpack{f}(x, ::Val{f}) = getproperty(x, f)
-@inline unpack{k}(x::Associative{Symbol}, ::Val{k}) = x[k]
-@inline unpack{S<:AbstractString,k}(x::Associative{S}, ::Val{k}) = x[string(k)]
-```
-
-The `Parameters.pack!` function is invoked to pack one entity into some
-`DataType` and has signature:
-
-`pack!(dt::Any, ::Val{field}, value) -> value`
-
-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) = setproperty!(x, f, val)
-@inline pack!{k}(x::Associative{Symbol}, ::Val{k}, val) = x[k]=val
-@inline pack!{S<:AbstractString,k}(x::Associative{S}, ::Val{k}, val) = x[string(k)]=val
-```
-
-More methods can be added to `unpack` and `pack!` to allow for
-specialized packing of datatypes.
+Note that `@unpack` and `@pack!` can be customized on types,
+see [UnPack.jl](https://github.com/mauro3/UnPack.jl).
 
-## The type-specific (un)pack macros (somewhat dangerous)
+## The type-specific (un)pack-all macros (somewhat dangerous)
 
 The `@with_kw` macro automatically produces type-specific (un-)pack
-macros of form `@unpack_TypeName`, `@pack_TypeName!`, and `@pack_TypeName` which unpack/pack all fields:
+macros of form `@unpack_TypeName`, `@pack_TypeName!`, and
+`@pack_TypeName` which unpack/pack all fields:
 
 ```julia
 function fn(var, pa::Para)

src/Parameters.jl

@@ -43,6 +43,7 @@ c = BB.c
 module Parameters
 import Base: @__doc__
 import OrderedCollections: OrderedDict
+using UnPack: @unpack, @pack!
 
 export @with_kw, @with_kw_noshow, type2dict, reconstruct, @unpack, @pack!, @pack
 
@@ -656,154 +657,4 @@ macro with_kw_noshow(typedef)
     return esc(with_kw(typedef, __module__, false))
 end
 
-
-###########################
-# Packing and unpacking @unpack, @pack!
-##########################
-# Below code slightly adapted from Simon Danisch's GLVisualize via PR
-# https://github.com/mauro3/Parameters.jl/pull/13
-
-"""
-This function is invoked to unpack one field/entry of some DataType
-`dt` and has signature:
-
-`unpack(dt::Any, ::Val{property}) -> value of property`
-
-The `property` 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} = getproperty(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!`.
-"""
-function unpack end
-@inline unpack(x, ::Val{f}) where {f} = getproperty(x, f)
-@inline unpack(x::AbstractDict{Symbol}, ::Val{k}) where {k} = x[k]
-@inline unpack(x::AbstractDict{<:AbstractString}, ::Val{k}) where {k} = x[string(k)]
-
-"""
-This function is invoked to pack one entity into some DataType and has
-signature:
-
-`pack!(dt::Any, ::Val{property}, value) -> value`
-
-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} = setproperty!(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`.
-"""
-function pack! end
-@inline pack!(x, ::Val{f}, val) where {f} = setproperty!(x, f, val)
-@inline pack!(x::AbstractDict{Symbol}, ::Val{k}, val) where {k} = x[k]=val
-@inline pack!(x::AbstractDict{<:AbstractString}, ::Val{k}, val) where {k} = x[string(k)]=val
-
-"""
-Unpacks fields/properties/keys from a composite type, a `Dict{Symbol}`, a `Dict{String}`,
-or a module into variables
-```julia_skip
-@unpack a, b, c = dict_or_typeinstance
-```
-
-Example with dict:
-```julia
-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:
-```julia
-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 unpack(args)
-    args.head!=:(=) && error("Expression needs to be of form `a, b = c`")
-    items, suitecase = args.args
-    items = isa(items, Symbol) ? [items] : items.args
-    suitecase_instance = gensym()
-    kd = [:( $key = $Parameters.unpack($suitecase_instance, Val{$(Expr(:quote, key))}()) ) for key in items]
-    kdblock = Expr(:block, kd...)
-    expr = quote
-        $suitecase_instance = $suitecase # handles if suitecase is not a variable but an expression
-        $kdblock
-        $suitecase_instance # return RHS of `=` as standard in Julia
-    end
-    esc(expr)
-end
-
-
-"""
-Packs variables into a mutable, composite type, a `Dict{Symbol}`, or a `Dict{String}`
-```julia_skip
-@pack! dict_or_typeinstance = a, b, c
-```
-
-Example with dict:
-```julia
-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:
-```julia
-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.
-"""
-macro pack!(args)
-    esc(_pack_bang(args))
-end
-
-function _pack_bang(args)
-    args.head!=:(=) && error("Expression needs to be in the form of an assignment.")
-    suitecase, items = args.args
-    items = isa(items, Symbol) ? [items] : items.args
-    suitecase_instance = gensym()
-    kd = [:( $Parameters.pack!($suitecase_instance, Val{$(Expr(:quote, key))}(), $key) ) for key in items]
-    kdblock = Expr(:block, kd...)
-    return quote
-        $suitecase_instance = $suitecase # handles if suitecase is not a variable but an expression
-        $kdblock
-        ($(items...),)
-    end
-end
-
-# TODO: maybe add @pack_new for packing into a new instance.  Could be
-# used with immutables also.
-
 end # module