Reference

FieldProperties.jl

FieldProperties provides an interface for creating method/property based APIs that can be flexibly incorporated into Julia structures. This is predominantly accomplished through the use of @defprop and @properties. These macros help in the creation of methods and mapping them to the fields of a concrete type.

AbstractProperty{name}

A AbstractProperty serves as a common reference point for accessing methods related to name, where name is the dot accessed field (as in x.<name>).

See @defprop, @properties

AbstractPropertyList{M <: AbstractDict{Symbol,Any}} <: AbstractDict{Symbol,Any}

Abstract type for storing metadata.

NoopPropertyList

Empty dictionary that indicates there is no metadata.

PropertyList{D}

Subtype of AbstractPropertyList that provides getproperty syntax for accessing the values of a dictionary.

Examples

julia> using FieldProperties

julia> m = PropertyList(; a = 1, b= 2)
PropertyList{Dict{Symbol,Any}} with 2 entries
    a: 1
    b: 2

julia> getindex(m, :a)
1

julia> get(m, :a, 3)
1

julia> get!(m, :a, 3)
1

julia> m.a
1

julia> m[:a] = 2
2

julia> m.a
2

julia> m.b
2

julia> m.b = 3
3

julia> m.b
3

julia> m.name = "ridiculously long name that we don't want to print everytime the other properties are printed.";


julia> m.suppress = (:name,)
(:name,)

julia> m
PropertyList{Dict{Symbol,Any}} with 4 entries
    a: 2
    b: 3
    name: <suppressed>
    suppress: (:name,)

calmax(x)
calmax!(x, val)

Specifies maximum element for display purposes. If not specified returns the maximum value in the collection.

Examples

julia> using FieldProperties

julia> x = reshape(1:16, 4, 4);

julia> calmax(x)
16

julia> struct ArrayMaxThresh{T,N}
           a::AbstractArray{T,N}
           calmax::T
       end

julia> calmax(ArrayMaxThresh(x, 10))
10

calmax(x)
calmax!(x, val)

Specifies maximum element for display purposes. If not specified returns the maximum value in the collection.

Examples

julia> using FieldProperties

julia> x = reshape(1:16, 4, 4);

julia> calmax(x)
16

julia> struct ArrayMaxThresh{T,N}
           a::AbstractArray{T,N}
           calmax::T
       end

julia> calmax(ArrayMaxThresh(x, 10))
10

calmin(x)
calmin!(x, val)

Specifies minimum element for display purposes. If not specified returns the minimum value in the collection.

Examples

julia> using FieldProperties

julia> x = reshape(1:16, 4, 4);

julia> calmin(x)
1

julia> struct ArrayMinThresh{T,N}
           a::AbstractArray{T,N}
           calmin::T
       end

julia> calmin(ArrayMinThresh(x, 5))
5

calmin(x)
calmin!(x, val)

Specifies minimum element for display purposes. If not specified returns the minimum value in the collection.

Examples

julia> using FieldProperties

julia> x = reshape(1:16, 4, 4);

julia> calmin(x)
1

julia> struct ArrayMinThresh{T,N}
           a::AbstractArray{T,N}
           calmin::T
       end

julia> calmin(ArrayMinThresh(x, 5))
5

description(x) -> String

Description that may say whatever you like.

description(x::AbstractProperty) -> String

Returns description for property x.

Examples

julia> using FieldProperties

julia> description(description)
"Description that may say whatever you like.\n"

description(x) -> String

Description that may say whatever you like.

description(x::AbstractProperty) -> String

Returns description for property x.

Examples

julia> using FieldProperties

julia> description(description)
"Description that may say whatever you like.\n"

description_list(ps...) -> String

Returns a markdown list where eache element of ps is formatted as:

* name(ps[i]): description(ps[i]).

Examples

julia> using FieldProperties

julia> description_list(description, calmax)
"* `description`: Description that may say whatever you like.\n* `calmax`: Specifies maximum element for display purposes. If not specified returns the maximum value in the collection.\n"

Property providing label for parent structure.

Property providing label for parent structure.

name(x) -> Symbol
name!(x, val)

Property providing name for parent structure.

name(x) -> Symbol
name!(x, val)

Property providing name for parent structure.

name(x::AbstractProperty) -> Symbol

Returns the symbolic name of the property.

propconvert(p, context, v)

Ensures the value v is the appropriate type for property p given context. If v isn't the appropriate type then propconvert attempts to convert to the "correct type".

No documentation found.

FieldProperties.Status is of type UnionAll.

Summary

struct UnionAll <: Type{T}

Fields

var  :: TypeVar
body :: Any

Supertype Hierarchy

UnionAll <: Type{T} <: Any

No documentation found.

FieldProperties.Status is of type UnionAll.

Summary

struct UnionAll <: Type{T}

Fields

var  :: TypeVar
body :: Any

Supertype Hierarchy

UnionAll <: Type{T} <: Any

@defprop Property{name}::Type block

Convient way of creating properties that wrap getproperty and setproperty! methods.

Examples

The simplest form simply creates a getter and setter.

julia> using FieldProperties

julia> @defprop Property1{:prop1}

julia> name(prop1)
:prop1

julia> prop1_type(:any_type)
Any

Define the propertie's type

julia> @defprop Property2{:prop2}::Int

julia> name(prop2)
:prop2

julia> prop2_type(:any_type)
Int64

Define type requirement and default value.

julia> @defprop Property3{:prop3}::Int begin
           @getproperty x -> 1
       end

julia> name(prop3)
:prop3

julia> prop3_type(:any_type)
Int64

julia> prop3(3)
1

Define a default value but no enforced return type but multiple getproperty methods.

julia> @defprop Property4{:prop4} begin
           @getproperty x::Int -> 1
           @getproperty x::String -> "1"
       end

julia> name(prop4)
:prop4

julia> prop4_type(:any_type)
Any

julia> prop4(1)
1

@properties T block

Syntactic sugar for custom getproperty, setproperty!, and propertynames methods. For any type T passed to @properties these methods will be rewritten from their default.

Examples

The following syntax assigns property names to function calls.

julia> using FieldProperties

julia> mutable struct MyType
           x::Int
       end

julia> @properties MyType begin
           xint(self) = getfield(self, :x)
           xint!(self, val) = setfield!(self, :x, val)
           hello(self) = "hello"
       end

julia> mt = MyType(1)
MyType(1)

julia> mt.xint
1

julia> mt.xint = 2
2

julia> mt.xint
2

julia> mt.hello
"hello"

julia> propertynames(mt)
(:xint, :hello)

julia> mt.x
ERROR: Property x not found
[...]

There are three things you should take away from this:

1. getproperty, setproperty!, and propertynames are completely overwritten here
2. Any property assignment that ends with ! is used to assign a setproperty!
3. MyType not longer can access the x field via mt.x (because of the first point).

It can be somewhat tedious to write out every getfield and setfield method, so let's redo this using => to assign fields

julia> @properties MyType begin
           xint(self) => :x
           xint!(self, val) => :x
           hello(self) = "hello"
       end

julia> mt = MyType(1)
MyType(1)

julia> mt.xint
1

julia> mt.xint = 2
2

julia> mt.xint
2

julia> mt.hello
"hello"

julia> propertynames(mt)
(:xint, :hello)

julia> mt.x
ERROR: Property x not found
[...]

Sometimes we want to use a modular approach to constructing a type. The following example requires users to know where to find the x1, x2, and x3 fields.

julia> mutable struct PropList1
           x2::Int
       end

julia> mutable struct PropList2
           x3::Int
       end

julia> mutable struct MyProperties
           x1::Int
           l1::PropList1
           l2::PropList2
       end

julia> mp = MyProperties(1, PropList1(2), PropList2(3))
MyProperties(1, PropList1(2), PropList2(3))

julia> mp.x1
1

julia> mp.l1.x2  # obnoxious for users
2

julia> mp.l2.x3  # also obnoxious for users
3

The following syntax tells our property methods to search through nested fields.

julia> @properties MyProperties begin
           x1(self) => :x1
           x1!(self, val) => :x1
           Any(self) => (:l1, :l2)
           Any!(self, val) => (:l1, :l2)
       end

julia> propertynames(mp)
(:x1, :x2, :x3)

julia> mp.x1
1

julia> mp.x2
2

julia> mp.x3
3

The last two methods (Any(x) and Any!(x, val)) tell the getproperty and setproperty! methods search the l1 and l2 fields for any property that isn't :x1.

The lowered code is:

julia> @macroexpand @properties MyProperties begin
                  x1(self) => :x1
                  x1!(self, val) => :x1
                  Any(self) => (:l1, :l2)
                  Any!(self, val) => (:l1, :l2)
              end
quote
    function Base.getproperty(self::MyProperties, p::Symbol)
        if p === :x1
            getfield(self, :x1)
        else
            if hasproperty(getfield(self, :l1), p)
                getproperty(getfield(self, :l1), p)
            else
                getproperty(getfield(self, :l2), p)
            end
        end
    end
    function Base.setproperty!(self::MyProperties, p::Symbol, val)
        if p === :x1
            setfield!(self, :x1, val)
        else
            if hasproperty(getfield(self, :l1), p)
                setproperty!(getfield(self, :l1), p, val)
            else
                setproperty!(getfield(self, :l2), p, val)
            end
        end
    end
    function Base.propertynames(self::MyProperties)
        (:x1, propertynames(getfield(self, :l1))..., propertynames(getfield(self, :l2))...)
    end
end

Note that the the :l1 and l2 fields are searched in the same order they are called inside the macro (e.g., Any(x) => (:l1, :l2) results in searching :l1 then :l2).

calmax(x)
calmax!(x, val)

Specifies maximum element for display purposes. If not specified returns the maximum value in the collection.

Examples

julia> using FieldProperties

julia> x = reshape(1:16, 4, 4);

julia> calmax(x)
16

julia> struct ArrayMaxThresh{T,N}
           a::AbstractArray{T,N}
           calmax::T
       end

julia> calmax(ArrayMaxThresh(x, 10))
10

calmin(x)
calmin!(x, val)

Specifies minimum element for display purposes. If not specified returns the minimum value in the collection.

Examples

julia> using FieldProperties

julia> x = reshape(1:16, 4, 4);

julia> calmin(x)
1

julia> struct ArrayMinThresh{T,N}
           a::AbstractArray{T,N}
           calmin::T
       end

julia> calmin(ArrayMinThresh(x, 5))
5

description(x) -> String

Description that may say whatever you like.

description(x::AbstractProperty) -> String

Returns description for property x.

Examples

julia> using FieldProperties

julia> description(description)
"Description that may say whatever you like.\n"

Property providing label for parent structure.

name(x) -> Symbol
name!(x, val)

Property providing name for parent structure.