1# Copyright 2023 The Bazel Authors. All rights reserved. 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14"""# StructSubject 15 16A subject for arbitrary structs. This is most useful when wrapping an ad-hoc 17struct (e.g. a struct specific to a particular function). Such ad-hoc structs 18are usually just plain data objects, so they don't need special functionality 19that writing a full custom subject allows. If a struct would benefit from 20custom accessors or asserts, write a custom subject instead. 21 22This subject is usually used as a helper to a more formally defined subject that 23knows the shape of the struct it needs to wrap. For example, a `FooInfoSubject` 24implementation might use it to handle `FooInfo.struct_with_a_couple_fields`. 25 26Note the resulting subject object is not a direct replacement for the struct 27being wrapped: 28 * Structs wrapped by this subject have the attributes exposed as functions, 29 not as plain attributes. This matches the other subject classes and defers 30 converting an attribute to a subject unless necessary. 31 * The attribute name `actual` is reserved. 32 33 34## Example usages 35 36To use it as part of a custom subject returning a sub-value, construct it using 37`subjects.struct()` like so: 38 39```starlark 40load("@rules_testing//lib:truth.bzl", "subjects") 41 42def _my_subject_foo(self): 43 return subjects.struct( 44 self.actual.foo, 45 meta = self.meta.derive("foo()"), 46 attrs = dict(a=subjects.int, b=subjects.str), 47 ) 48``` 49 50If you're checking a struct directly in a test, then you can use 51`Expect.that_struct`. You'll still have to pass the `attrs` arg so it knows how 52to map the attributes to the matching subject factories. 53 54```starlark 55def _foo_test(env): 56 actual = env.expect.that_struct( 57 struct(a=1, b="x"), 58 attrs = dict(a=subjects.int, b=subjects.str) 59 ) 60 actual.a().equals(1) 61 actual.b().equals("x") 62``` 63""" 64 65def _struct_subject_new(actual, *, meta, attrs): 66 """Creates a `StructSubject`, which is a thin wrapper around a [`struct`]. 67 68 Args: 69 actual: ([`struct`]) the struct to wrap. 70 meta: ([`ExpectMeta`]) object of call context information. 71 attrs: ([`dict`] of [`str`] to [`callable`]) the functions to convert 72 attributes to subjects. The keys are attribute names that must 73 exist on `actual`. The values are functions with the signature 74 `def factory(value, *, meta)`, where `value` is the actual attribute 75 value of the struct, and `meta` is an [`ExpectMeta`] object. 76 77 Returns: 78 [`StructSubject`] object, which is a struct with the following shape: 79 * `actual` attribute, the underlying struct that was wrapped. 80 * A callable attribute for each `attrs` entry; it takes no args 81 and returns what the corresponding factory from `attrs` returns. 82 """ 83 attr_accessors = {} 84 for name, factory in attrs.items(): 85 if not hasattr(actual, name): 86 fail("Struct missing attribute: '{}' (from expression {})".format( 87 name, 88 meta.current_expr(), 89 )) 90 attr_accessors[name] = _make_attr_accessor(actual, name, factory, meta) 91 92 public = struct(actual = actual, **attr_accessors) 93 return public 94 95def _make_attr_accessor(actual, name, factory, meta): 96 # A named function is used instead of a lambda so stack traces are easier to 97 # grok. 98 def attr_accessor(): 99 return factory(getattr(actual, name), meta = meta.derive(name + "()")) 100 101 return attr_accessor 102 103# buildifier: disable=name-conventions 104StructSubject = struct( 105 # keep sorted start 106 new = _struct_subject_new, 107 # keep sorted end 108) 109