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

  1. v is nothing: throw a PropertyPathError whose message names pathstr, the type T and the node nodestr.
  2. v is any other value: return v.

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

source
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

  1. expr is a Symbol: return the one-element vector that holds it.
  2. expr is an Expr with head :. and two arguments:
    1. Read leaf, its second argument, and unwrap a QuoteNode to its value.
    2. leaf is not a Symbol: raise an error that names the leaf.
    3. Call this function again on the first argument, and append leaf to the result.
  3. expr is 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

source
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

  1. The path holds one name: return getfield(x, name) and stop. The walk uses getfield and not getproperty, so the generated Base.getproperty never calls itself.
  2. Build pathstr, the whole path joined by dots, for the error message.
  3. Start stmts with __v = getfield(x, first_name).
  4. For each further hop k of the path:
    1. Push __v = forward_nonnothing(__v, struct_name, pathstr, nodestr), where nodestr names the part of the path walked so far.
    2. k is the last hop and broadcast is true: push an assignment that reads the leaf with getproperty. when __v is an AbstractVector, and with getproperty otherwise.
    3. Otherwise: push __v = getproperty(__v, leaf).
  5. Push __v as the value of the block.
  6. Return the statements wrapped in a let block, so __v never 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

source
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

  1. args is empty, or its first argument is not a :parameters node: return (false, false, args).
  2. For each option p of the node:
    1. p is broadcast and marker is compute or swap: set broadcast to true.
    2. p is settable and marker is forward: set settable to true.
    3. p is broadcast or settable: raise an error that names the rules it applies to.
    4. Otherwise: raise an error that names the two options.
  3. Return (broadcast, settable, args[2:end]).

Related

source
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

  1. args is empty: raise an error.
  2. For each argument n of args:
    1. n is not a Symbol: raise an error that names it.
    2. Otherwise: push n onto names.
  3. Return names.

Related

source
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

source
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

  1. Start hops empty, and start v at x.
  2. For each hop s of path:
    1. s is a field of v, or forward_source of v gives nothing for it, or the rule that reads it is settable: push s onto hops.
    2. The rule that reads s has no path: push s onto hops, and return (hops, typeof(v)).
    3. Otherwise: follow the path of the rule from v with this function, and append its hops. Its owner is not nothing: return (hops, owner).
    4. s is not the last hop, and v is not nothing: set v to getproperty(v, s).
  3. 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

source
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

source
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 patch is in forward_derived(T). Raises an ArgumentError that names the derived field and the fields that the keyword constructor takes.

Returns

  • nothing.

Related

source
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

  1. Refuse a patch that names a derived field of T, with assert_not_derived.
  2. For each key sym of patch that is not a field of T:
    1. forward_source of sym is nothing: refuse it as a name that T does not have, and name the fields.
    2. The pair is settable: keep sym in the patch.
    3. The pair has no path: refuse it as a computed value, and name the fields.
    4. Otherwise: follow its path with forward_storage_path. The path ends at a stored value: refuse sym, and name that path as the one to set.
    5. 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.
  3. Read every field of x with getfield into a NamedTuple, in declaration order.
  4. Merge patch over it, and remove the derived fields that forward_derived names.
  5. Call ctor, the keyword constructor of T, 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

source