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...)
endMake 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 atloc. A namesymwithhasproperty(value, sym)givesgetproperty(value, sym).forward(loc, names...): forward only the named properties of the value atloc.forward(loc; settable)andforward(loc, names...; settable): forward as above, and let a patch ofAccessors.setset the forwarded names. Without the option, the patch refuses a forwarded name. With it, the patch passes the name to the keyword constructor ofTas 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_setpropertiesstates this contract.alias(exposed, loc): give the value atlocthe new nameexposed.compute(exposed, loc; broadcast): giveexposedthrough a dotted locator with two or more hops.broadcastmaps the last hop over a vector value before it.compute(exposed, fn): giveexposedasfn(obj).fnmust be an anonymous function, because the macro cannot tell any other function from a dotted path.swap(field, loc)andswap(field, fn): replace the value of an existing field with the value atloc, or withfn(obj).locis a bare name, such as inswap(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 aRegressionwhoseLparameter isNothing. The locator form reads throughgetfield, so it does not recurse. In the function form, the body must read the swapped field withgetfield(obj, :field), never withobj.field. A dot access of the swapped field callsgetpropertyagain, and the recursion raises aStackOverflowError. The body can use a dot access for every other field.derived(fields...): mark real fields as derived. The inner constructor ofTcomputes a derived field from the other fields, and the keyword constructor does not take it. The patch ofAccessors.setleaves 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_derivedgives the names.
Algorithm
blockis not abegin … endblock: raise an error.- Make six empty vectors:
swap_branches,getprop_branches,source_branches,has_branches,propname_contribsandderived_names. - For each rule of the block, except a
LineNumberNode:- The rule is not a call: raise an error that names it.
- Read
marker, the rule name. Read thebroadcastandsettableoptions andargs, the other arguments, withforward_rule_options. markerisforward: flatten the locator withforward_flatten_path, and buildwalkwithforward_walk_expr. With no more arguments, push a branch that returnsgetproperty(walk, sym)whenhasproperty(walk, sym)istrue, and add all of the names ofpropertynames(walk). With more arguments, check that each is a bare identifier. Then push a branch that matchessymagainst that set of names, and add those names. In both cases, push ontohas_branchesa branch that givestruefor the same names, and push ontosource_branchesa branch that gives the pair of the pathloc.sym, as a tuple of symbols, and thesettableflag for the same names.markerisalias: check the exposed name, and buildwalkfrom the locator. Push a branch that matches the exposed name and returnswalk. Push a source branch that gives the pair of the locator path andfalse. Push a branch ontohas_branchesthat givestruefor the exposed name, and add the name.markeriscompute: check the exposed name. An anonymous-function source pushes a branch that returnsfn(x), and a source branch that gives(nothing, false).broadcastwith that form raises an error. A dotted source buildswalkwith thebroadcastflag, pushes the matching branch, and pushes a source branch that gives the pair of the dotted path andfalse. Any other source raises an error. Push a branch ontohas_branchesthat givestruefor the exposed name, and add the name.markerisswap: do as forcompute, but a bare name is also a valid source, and the branch goes ontoswap_branchesand not ontogetprop_branches.markerisderived: check the field names, and append them toderived_names, withforward_derived_names!.markeris any other name: raise an error that names it.
- Build
Base.getproperty(x::T, sym::Symbol)in this order: theswapbranches, then the own-field check againstfieldnames(S), which returnsgetfield(x, sym), then the other branches in declaration order.Sis the name ofTwithout its type parameters. The last statement isgetfield(x, sym), which raises the standard error for an absent field. - Build
Base.propertynames(x::T)fromfieldnames(S)and then every added name, and return the unique names as a tuple. - Build
Base.hasproperty(x::T, sym::Symbol). It givestruewhensymis infieldnames(S), then runs thehas_branches, and givesfalsewhen no branch matches. - Build
forward_source(x::T, sym::Symbol), which runs thesource_branchesand givesnothingwhen no branch matches. - Build
ConstructionBase.setproperties(x::T, patch::NamedTuple), which callsforward_setpropertieswith one more argument: the name ofTwithout its type parameters, which is its keyword constructor. - Build
forward_derived(::Type{<:T}), which gives the tuple ofderived_names. With noderivedrule, the tuple is empty, the same value as the fallback. - 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