Forward properties

Utility functions

PortfolioOptimisers.@forward_properties — Macro
@forward_properties T begin
    forward(loc; settable)
    forward(loc, names...; settable)
    alias(exposed, loc)
    compute(exposed, loc; broadcast)
    compute(exposed, fn)
    swap(field, loc)
    swap(field, fn)
    derived(fields...)
end

Make the Base.getproperty, Base.propertynames and Base.hasproperty methods of the type T from a block of declared forwarding rules. The forwarding of properties is then in one declaration, not in a hand-written getproperty body. The hasproperty method answers without the list of names, so a read through a forward rule allocates nothing. The macro also makes the ConstructionBase.setproperties method that Accessors.set needs to build T again on a lens path. The default method refuses a type whose propertynames differ from its fieldnames. The method of forward_source that the macro makes tells that method which rule reads a name. T can be a bare type name or a parametric or UnionAll signature, such as Foo{<:Any, Nothing, <:Any}, so a swap can apply to one value of a type parameter.

Write all names as bare identifiers. Every rule names its source through a locator. A locator is a bare name a, which is the field a of the receiver, or a dotted path a.b.c of any depth, which is the path obj.a.b.c from the receiver. A deeper path has more dots. A path with two or more hops checks each intermediate node, and it throws a PropertyPathError that names the path when a node is nothing.

forward, alias and compute only add new virtual names, so they resolve after the fields of the receiver. swap replaces the value of an existing field, so it resolves before the field check.

Rules

  • forward(loc): forward all properties of the value at loc. A name sym with hasproperty(value, sym) gives getproperty(value, sym).
  • forward(loc, names...): forward only the named properties of the value at loc.
  • forward(loc; settable) and forward(loc, names...; settable): forward as above, and let a patch of Accessors.set set the forwarded names. Without the option, the patch refuses a forwarded name. With it, the patch passes the name to the keyword constructor of T as a keyword, so the constructor must take each such name. The keyword replaces that slot of the nested part, and its default leaves the slot as it is. forward_setproperties states this contract.
  • alias(exposed, loc): give the value at loc the new name exposed.
  • compute(exposed, loc; broadcast): give exposed through a dotted locator with two or more hops. broadcast maps the last hop over a vector value before it.
  • compute(exposed, fn): give exposed as fn(obj). fn must be an anonymous function, because the macro cannot tell any other function from a dotted path.
  • swap(field, loc) and swap(field, fn): replace the value of an existing field with the value at loc, or with fn(obj). loc is a bare name, such as in swap(L, M), or a dotted path. This rule runs before the own-field check, and it is the only rule that can name a real field. It usually applies to one value of a type parameter. For example, swap(L, M) applies to a Regression whose L parameter is Nothing. The locator form reads through getfield, so it does not recurse. In the function form, the body must read the swapped field with getfield(obj, :field), never with obj.field. A dot access of the swapped field calls getproperty again, and the recursion raises a StackOverflowError. The body can use a dot access for every other field.
  • derived(fields...): mark real fields as derived. The inner constructor of T computes a derived field from the other fields, and the keyword constructor does not take it. The patch of Accessors.set leaves a derived field out of the call of the keyword constructor, and it refuses a patch that names one. The rule adds no name, and it does not change a read. forward_derived gives the names.

Algorithm

  1. block is not a begin … end block: raise an error.
  2. Make six empty vectors: swap_branches, getprop_branches, source_branches, has_branches, propname_contribs and derived_names.
  3. For each rule of the block, except a LineNumberNode:
    1. The rule is not a call: raise an error that names it.
    2. Read marker, the rule name. Read the broadcast and settable options and args, the other arguments, with forward_rule_options.
    3. marker is forward: flatten the locator with forward_flatten_path, and build walk with forward_walk_expr. With no more arguments, push a branch that returns getproperty(walk, sym) when hasproperty(walk, sym) is true, and add all of the names of propertynames(walk). With more arguments, check that each is a bare identifier. Then push a branch that matches sym against that set of names, and add those names. In both cases, push onto has_branches a branch that gives true for the same names, and push onto source_branches a branch that gives the pair of the path loc.sym, as a tuple of symbols, and the settable flag for the same names.
    4. marker is alias: check the exposed name, and build walk from the locator. Push a branch that matches the exposed name and returns walk. Push a source branch that gives the pair of the locator path and false. Push a branch onto has_branches that gives true for the exposed name, and add the name.
    5. marker is compute: check the exposed name. An anonymous-function source pushes a branch that returns fn(x), and a source branch that gives (nothing, false). broadcast with that form raises an error. A dotted source builds walk with the broadcast flag, pushes the matching branch, and pushes a source branch that gives the pair of the dotted path and false. Any other source raises an error. Push a branch onto has_branches that gives true for the exposed name, and add the name.
    6. marker is swap: do as for compute, but a bare name is also a valid source, and the branch goes onto swap_branches and not onto getprop_branches.
    7. marker is derived: check the field names, and append them to derived_names, with forward_derived_names!.
    8. marker is any other name: raise an error that names it.
  4. Build Base.getproperty(x::T, sym::Symbol) in this order: the swap branches, then the own-field check against fieldnames(S), which returns getfield(x, sym), then the other branches in declaration order. S is the name of T without its type parameters. The last statement is getfield(x, sym), which raises the standard error for an absent field.
  5. Build Base.propertynames(x::T) from fieldnames(S) and then every added name, and return the unique names as a tuple.
  6. Build Base.hasproperty(x::T, sym::Symbol). It gives true when sym is in fieldnames(S), then runs the has_branches, and gives false when no branch matches.
  7. Build forward_source(x::T, sym::Symbol), which runs the source_branches and gives nothing when no branch matches.
  8. Build ConstructionBase.setproperties(x::T, patch::NamedTuple), which calls forward_setproperties with one more argument: the name of T without its type parameters, which is its keyword constructor.
  9. Build forward_derived(::Type{<:T}), which gives the tuple of derived_names. With no derived rule, the tuple is empty, the same value as the fallback.
  10. Return the definitions in one escaped block.

Step 4 gives the two orders of the first paragraph. A swap runs before the own-field check, so it replaces a real field. Every other rule runs after that check, so it can only add a name. In each group, the first branch that matches wins, and the branches are in the declaration order of the rules.

Step 6 gives the same set of names as step 5, without the tuple of step 5. That tuple removes the duplicate names with unique, which allocates on each call. A forward rule asks hasproperty of the child, so a read through a chain of forward rules runs one generated hasproperty method for each link, and none of them allocates. A child that @forward_properties does not decorate answers through the method of Base, sym in propertynames(x). Steps 4 to 6 read the field names of S, not of T. A signature such as Foo{<:Any, Nothing, <:Any} is an expression that builds a new UnionAll on each call, and that construction allocates. S is a constant with the same field names, so the compiler folds the field check.

Step 7 gives no source for a swap, because a swap names a real field, and the patch sets it as a field. Every other rule pushes a source branch, in the same order as its getproperty branch. So the rule that reads a name also decides whether a patch can set it. A name that a settable rule forwards, but that an earlier rule reads, stays refused. Step 7 makes a method and not a closure inside step 8, so forward_storage_path can ask the source of a name of a nested value, and the refusal of a patch names the path that stores the value.

Related

source