| 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 |
} |