Forward properties: private API
Utility functions
PortfolioOptimisers.forward_nonnothing — Function
forward_nonnothing(v, _::Type{T}, pathstr, nodestr) -> Any
Check one intermediate node of a nested path of @forward_properties.
Return v with no change when it is not nothing. Otherwise, throw a PropertyPathError that names the receiver type T, the full declared path pathstr, and the node nodestr that resolved to nothing. The generated walk of a locator with two or more hops calls it once for each intermediate hop.
Algorithm
visnothing: throw aPropertyPathErrorwhose message namespathstr, the typeTand the nodenodestr.vis any other value: returnv.
The check runs on the intermediate hops only. A path whose last hop gives nothing returns that nothing, and raises no error. This is by design. An absent leaf is a value, but an absent intermediate node is a path that the walk cannot follow.
Related
PortfolioOptimisers.forward_flatten_path — Function
forward_flatten_path(expr) -> Vector{Symbol}
Change a locator of @forward_properties into its path of field symbols.
A bare identifier a becomes [:a]. A dotted expression a.b.c becomes [:a, :b, :c]. Any other expression raises an error.
Algorithm
expris aSymbol: return the one-element vector that holds it.expris anExprwith head:.and two arguments:- Read
leaf, its second argument, and unwrap aQuoteNodeto its value. leafis not aSymbol: raise an error that names the leaf.- Call this function again on the first argument, and append
leafto the result.
- Read
expris any other expression: raise an error that names the expression.
The recursion of step 2.3 lets the path have any depth. a.b.c parses as (a.b).c, so the walk goes down to the bare name and builds the path again from the left.
Related
PortfolioOptimisers.forward_walk_expr — Function
forward_walk_expr(
path,
struct_name,
broadcast::Bool
) -> Expr
Build the expression that walks a path of @forward_properties on the receiver x, and returns the value at the end of the path. path is a vector of field symbols.
A path with one hop is one getfield. A path with two or more hops goes one hop at a time. It checks every intermediate node with forward_nonnothing, which takes the receiver type struct_name. A nothing node then throws a PropertyPathError that names the path. When broadcast is true, the last hop maps over the value before it if that value is an AbstractVector. This is the case of a solution that is a scalar or a vector. Otherwise, the last hop is a plain access.
Algorithm
- The path holds one name: return
getfield(x, name)and stop. The walk usesgetfieldand notgetproperty, so the generatedBase.getpropertynever calls itself. - Build
pathstr, the whole path joined by dots, for the error message. - Start
stmtswith__v = getfield(x, first_name). - For each further hop
kof the path:- Push
__v = forward_nonnothing(__v, struct_name, pathstr, nodestr), wherenodestrnames the part of the path walked so far. kis the last hop andbroadcastistrue: push an assignment that reads the leaf withgetproperty.when__vis anAbstractVector, and withgetpropertyotherwise.- Otherwise: push
__v = getproperty(__v, leaf).
- Push
- Push
__vas the value of the block. - Return the statements wrapped in a
letblock, so__vnever escapes into the caller.
Step 4.1 runs before every hop after the first, so the check reads each intermediate node one time and never reads the leaf. Only the leaf of step 4.2 broadcasts. So an intermediate vector raises an error at the next hop, and the walk does not map over it.
Related
PortfolioOptimisers.forward_rule_options — Function
forward_rule_options(marker, args) -> Tuple{Bool, Bool, Any}
Read the options of one rule of @forward_properties, and return (broadcast, settable, args).
args are the arguments of the rule marker. When the first of them is a :parameters node, it holds the options of the rule, and the returned args drop it. Each option applies to some rules only. broadcast applies to compute and swap, and settable applies to forward. An option on any other rule raises an error, so a rule never ignores an option that it was given.
Algorithm
argsis empty, or its first argument is not a:parametersnode: return(false, false, args).- For each option
pof the node:pisbroadcastandmarkeriscomputeorswap: setbroadcasttotrue.pissettableandmarkerisforward: setsettabletotrue.pisbroadcastorsettable: raise an error that names the rules it applies to.- Otherwise: raise an error that names the two options.
- Return
(broadcast, settable, args[2:end]).
Related
PortfolioOptimisers.forward_derived_names! — Function
forward_derived_names!(
names::Vector{Symbol},
args
) -> Vector{Symbol}
Check the arguments args of a derived rule of @forward_properties, and append them to names.
Each argument is the name of a field that the inner constructor computes. The macro cannot see the fields of the type when it expands, so the census of test/test_05_tools.jl checks that each name is a field.
Algorithm
argsis empty: raise an error.- For each argument
nofargs:nis not aSymbol: raise an error that names it.- Otherwise: push
nontonames.
- Return
names.
Related
PortfolioOptimisers.forward_source — Function
forward_source(
x,
sym::Symbol
) -> Union{Nothing, Tuple{Tuple{Symbol, Symbol}, Bool}}
Give the source of the property sym of x, for a type that @forward_properties does not decorate: nothing.
The macro adds a method of this function for each type that it decorates. That method gives nothing when no rule names sym. Otherwise it gives the pair (path, settable) of the first rule that names sym, in the order in which getproperty reads the rules. path is the tuple of the field symbols of the path that holds the value, from x. It is nothing for the function form of compute. settable is true for a name of a settable forward rule.
forward_setproperties reads the pair to decide whether a patch can set sym. forward_storage_path reads it for each hop of a path, so it follows a chain of rules to the value that stores the property. A value of a type that the macro does not decorate stores each of its properties, as far as this function can tell, so this method ends the chain.
Related
PortfolioOptimisers.forward_storage_path — Function
forward_storage_path(
x,
path
) -> Union{Tuple{Vector{Symbol}, DataType}, Tuple{Vector{Symbol}, Nothing}}
Follow the path of field symbols from x to the path that stores its value, and return (hops, owner).
A forward rule of @forward_properties names the path that it reads, from the receiver. A hop of that path can be a forwarded or computed property of the value before it, with no storage either. This function asks forward_source of the value at each hop, and it puts the path of the rule in place of a hop that a rule reads. hops is the path that results, from x. owner is nothing when the value at hops is stored or settable. Otherwise, owner is the type that computes the last hop with the function form of compute, and hops ends at that hop.
Algorithm
- Start
hopsempty, and startvatx. - For each hop
sofpath:sis a field ofv, orforward_sourceofvgivesnothingfor it, or the rule that reads it is settable: pushsontohops.- The rule that reads
shas no path: pushsontohops, and return(hops, typeof(v)). - Otherwise: follow the path of the rule from
vwith this function, and append its hops. Its owner is notnothing: return(hops, owner). sis not the last hop, andvis notnothing: setvtogetproperty(v, s).
- Return
(hops, nothing).
Step 2.4 reads no value after the last hop, and it reads nothing through a nothing node. So the walk never raises the PropertyPathError of a node that is nothing. A hop after such a node is a field that the walk cannot see, and step 2.1 keeps it as it is.
Related
PortfolioOptimisers.forward_derived — Function
forward_derived(_::Type{T}) -> Tuple{}
Give the names of the derived fields of the type T, for a type that @forward_properties does not decorate: ().
A derived field is a field that the inner constructor of its type computes from the other fields. The keyword constructor of the type does not take it. The macro adds a method of this function for each type that it decorates. That method gives the tuple of the names of the derived rules of the block, and () when the block has none. The function takes the type and not a value, because a derived field is a property of the type, and a census can read it with no instance.
forward_setproperties and rebuild_struct leave these fields out of the call of the keyword constructor, so the constructor computes them again from the new values. assert_not_derived refuses a patch that names one of them.
Related
PortfolioOptimisers.assert_not_derived — Function
assert_not_derived(x, patch::NamedTuple)
Refuse a patch that names a derived field of x.
A derived field has no value of its own to set, because the inner constructor computes it from the other fields. A patch that carries a value for it would give a value that the constructor does not compute. forward_derived gives the names of the derived fields of T, the type of x.
Validation
- No key of
patchis inforward_derived(T). Raises anArgumentErrorthat names the derived field and the fields that the keyword constructor takes.
Returns
nothing.
Related
PortfolioOptimisers.forward_setproperties — Function
forward_setproperties(x, patch::NamedTuple, ctor) -> Any
Rebuild x with the names in patch replaced, for a type that @forward_properties decorates.
This function is the body of the ConstructionBase.setproperties method that the macro makes. Accessors.set and Accessors.@set call that method to build again every struct on a lens path. The default method refuses a type whose propertynames differ from its fieldnames. It also reads every field through getproperty, so with a swap(L, M) rule it writes M into an unset L. This function reads the fields with getfield, and it patches a field. A forwarded or computed property is a view of a nested value, with no storage of its own. The function refuses a patch that names one, and it names the path to set. forward_storage_path follows the path of the rule to the path that stores the value, so the path that the message names does not refuse the patch too.
A forward rule with the settable option is the one exception. The function passes a name of that rule to ctor as a flat keyword, beside the fields. So Accessors.set(x, @optic(_.w), v) works on a type that forwards w from a nested part.
forward_source gives the pair (path, settable) of the rule that reads sym, or nothing when no rule names sym.
Algorithm
- Refuse a patch that names a derived field of
T, withassert_not_derived. - For each key
symofpatchthat is not a field ofT:forward_sourceofsymisnothing: refuse it as a name thatTdoes not have, and name the fields.- The pair is settable: keep
symin the patch. - The pair has no path: refuse it as a computed value, and name the fields.
- Otherwise: follow its path with
forward_storage_path. The path ends at a stored value: refusesym, and name that path as the one to set. - The path ends at a computed property: refuse
sym. Name the property, the type that computes it, and the fields of that type as the ones to set.
- Read every field of
xwithgetfieldinto aNamedTuple, in declaration order. - Merge
patchover it, and remove the derived fields thatforward_derivednames. - Call
ctor, the keyword constructor ofT, with the result. Every check of the constructor runs on the new value, and the constructor computes each derived field again.
The macro passes ctor as the name of T without its type parameters. So step 5 calls the ordinary keyword constructor, and it needs no reflection to find it. A patch that changes a type parameter, such as a value for an unset L, gives the specialisation that the constructor selects.
The keyword constructor of T must take every field of T by its field name, except a field that a derived rule names. A type that marks a name as settable must also take that name as a keyword of its keyword constructor. The keyword replaces that slot of the nested part that the constructor is given, and the default of the keyword must leave that slot as it is. Step 5 passes the old nested part and the new value of the slot in one call. rebuild_struct calls the constructor in the same way, so the two give the same value.
Related