Debian Codegraph @

hugolib/sitesmatrix/dimensions.go

raw
1 // Copyright 2025 The Hugo 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 // http://www.apache.org/licenses/LICENSE-2.0
7 //
8 // Unless required by applicable law or agreed to in writing, software
9 // distributed under the License is distributed on an "AS IS" BASIS,
10 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 // See the License for the specific language governing permissions and
12 // limitations under the License.
13
14 package sitesmatrix
15
16 import (
17 "fmt"
18 )
19
20 const (
21 // Dimensions in the Hugo build matrix.
22 // These can be used as indices into the Vector type.
23 Language int = iota
24 Version
25 Role
26 )
27
28 // Vector represents a site vector in the Hugo sites matrix from the three dimensions:
29 // Language, Version and Role.
30 // This is a fixed-size array for performance reasons (for one, it can be used as map key).
31 type Vector [3]int
32
33 // Compare returns -1 if v1 is less than v2, 0 if they are equal, and 1 if v1 is greater than v2.
34 // This adds a implicit weighting to the dimensions, where the first dimension is the most important,
35 // but this is just used for sorting to get stable output.
36 func (v1 Vector) Compare(v2 Vector) int {
37 // note that a and b will never be equal.
38 minusOneOrOne := func(a, b int) int {
39 if a < b {
40 return -1
41 }
42 return 1
43 }
44 if v1[0] != v2[0] {
45 return minusOneOrOne(v1[0], v2[0])
46 }
47 if v1[1] != v2[1] {
48 return minusOneOrOne(v1[1], v2[1])
49 }
50 if v1[2] != v2[2] {
51 return minusOneOrOne(v1[2], v2[2])
52 }
53 // They are equal.
54 return 0
55 }
56
57 // Distance returns the distance between v1 and v2
58 // using the first dimension that is different.
59 func (v1 Vector) Distance(v2 Vector) int {
60 if v1[0] != v2[0] {
61 return v1[0] - v2[0]
62 }
63 if v1[1] != v2[1] {
64 return v1[1] - v2[1]
65 }
66 if v1[2] != v2[2] {
67 return v1[2] - v2[2]
68 }
69 return 0
70 }
71
72 // EuclideanDistanceSquared returns the Euclidean distance between two vectors as the sum of the squared differences.
73
74 func (v1 Vector) HasVector(v2 Vector) bool {
75 return v1 == v2
76 }
77
78 func (v1 Vector) HasAnyVector(vp VectorProvider) bool {
79 n := vp.LenVectors()
80 if n == 0 {
81 return false
82 }
83 if n == 1 {
84 return v1 == vp.VectorSample()
85 }
86
87 return !vp.ForEachVector(func(v2 Vector) bool {
88 if v1 == v2 {
89 return false // stop iteration
90 }
91 return true // continue iteration
92 })
93 }
94
95 func (v1 Vector) LenVectors() int {
96 return 1
97 }
98
99 func (v1 Vector) VectorSample() Vector {
100 return v1
101 }
102
103 func (v1 Vector) EqualsVector(other VectorProvider) bool {
104 if other.LenVectors() != 1 {
105 return false
106 }
107 return other.VectorSample() == v1
108 }
109
110 func (v1 Vector) ForEachVector(yield func(v Vector) bool) bool {
111 return yield(v1)
112 }
113
114 // Language returns the language dimension.
115 func (v1 Vector) Language() int {
116 return v1[Language]
117 }
118
119 // Version returns the version dimension.
120 func (v1 Vector) Version() int {
121 return v1[Version]
122 }
123
124 // IsFirst returns true if this is the first vector in the matrix, i.e. all dimensions are 0.
125 func (v1 Vector) IsFirst() bool {
126 return v1[Language] == 0 && v1[Version] == 0 && v1[Role] == 0
127 }
128
129 // Role returns the role dimension.
130 func (v1 Vector) Role() int {
131 return v1[Role]
132 }
133
134 func (v1 Vector) Weight() int {
135 return 0
136 }
137
138 var _ ToVectorStoreProvider = Vectors{}
139
140 type Vectors map[Vector]struct{}
141
142 func (vs Vectors) ForEachVector(yield func(v Vector) bool) bool {
143 for v := range vs {
144 if !yield(v) {
145 return false
146 }
147 }
148 return true
149 }
150
151 func (vs Vectors) LenVectors() int {
152 return len(vs)
153 }
154
155 func (vs Vectors) ToVectorStore() VectorStore {
156 return newVectorStoreMapFromVectors(vs)
157 }
158
159 // VectorSample returns one of the vectors in the set.
160 func (vs Vectors) VectorSample() Vector {
161 for v := range vs {
162 return v
163 }
164 panic("no vectors")
165 }
166
167 type (
168 VectorIterator interface {
169 // ForEachVector iterates over all vectors in the provider.
170 // It returns false if the iteration was stopped early.
171 ForEachVector(func(v Vector) bool) bool
172
173 // LenVectors returns the number of vectors in the provider.
174 LenVectors() int
175
176 // VectorSample returns one of the vectors in the provider, usually the first or the only one.
177 // This will panic if the provider is empty.
178 VectorSample() Vector
179 }
180 )
181
182 // Bools holds boolean values for each dimension in the Hugo build matrix.
183 type Bools [3]bool
184
185 func (d Bools) Language() bool {
186 return d[Language]
187 }
188
189 func (d Bools) Version() bool {
190 return d[Version]
191 }
192
193 func (d Bools) Role() bool {
194 return d[Role]
195 }
196
197 func (d Bools) IsZero() bool {
198 return !d[0] && !d[1] && !d[2]
199 }
200
201 type VectorProvider interface {
202 VectorIterator
203 // HasVector returns true if the given vector is contained in the provider.
204 // Used for membership testing of files, resources and pages.
205 HasVector(HasAnyVectorv Vector) bool
206
207 // HasAnyVector returns true if any of the vectors in the provider matches any of the vectors in v.
208 HasAnyVector(v VectorProvider) bool
209
210 // Equals returns true if this provider is equal to the other provider.
211 EqualsVector(other VectorProvider) bool
212 }
213
214 type VectorStore interface {
215 VectorProvider
216 Complement(...VectorProvider) VectorStore
217 WithLanguageIndices(i ...int) VectorStore
218 WithVersionIndices(i ...int) VectorStore
219 WithRoleIndices(i ...int) VectorStore
220 HasLanguage(lang int) bool
221 HasVersion(version int) bool
222 HasRole(role int) bool
223 MustHash() uint64
224
225 // Used in tests.
226 KeysSorted() ([]int, []int, []int)
227 Vectors() []Vector
228 }
229
230 type ToVectorStoreProvider interface {
231 ToVectorStore() VectorStore
232 }
233
234 // CoarseSiteVectorMatcher is implemented by types that can match a site vector in a coarse way, i.e. it first checks for a
235 // sites matrix match and then falls back to checking the sites complements.
236 type CoarseSiteVectorMatcher interface {
237 MatchSiteVectorCoarse(Vector) bool
238 MatchSiteVectorCoarseExcludeLanguage(Vector) bool
239 }
240
241 func VectorIteratorToStore(vi VectorIterator) VectorStore {
242 switch v := vi.(type) {
243 case VectorStore:
244 return v
245 case ToVectorStoreProvider:
246 return v.ToVectorStore()
247 }
248
249 vectors := make(Vectors)
250 vi.ForEachVector(func(v Vector) bool {
251 vectors[v] = struct{}{}
252 return true
253 })
254 return vectors.ToVectorStore()
255 }
256
257 type weightedVectorStore struct {
258 VectorStore
259 weight int
260 }
261
262 func (w weightedVectorStore) Weight() int {
263 return w.weight
264 }
265
266 func NewWeightedVectorStore(vs VectorStore, weight int) VectorStore {
267 if vs == nil {
268 return nil
269 }
270 return weightedVectorStore{VectorStore: vs, weight: weight}
271 }
272
273 // Dimension is a dimension in the Hugo build matrix.
274 type Dimension int8
275
276 func ParseDimension(s string) (int, error) {
277 switch s {
278 case "language":
279 return Language, nil
280 case "version":
281 return Version, nil
282 case "role":
283 return Role, nil
284 default:
285 return 0, fmt.Errorf("unknown dimension %q", s)
286 }
287 }
288
289 func DimensionName(d int) string {
290 switch d {
291 case Language:
292 return "language"
293 case Version:
294 return "version"
295 case Role:
296 return "role"
297 default:
298 panic("unknown dimension")
299 }
300 }
301
302 // Common information provided by all of language, version and role.
303 type DimensionInfo interface {
304 // The name. This corresponds to the key in the config, e.g. "en", "v1.2.3", "guest".
305 Name() string
306
307 // Whether this is the default value for this dimension.
308 IsDefault() bool
309 }