1 // Copyright 2018 Google LLC 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 15 package name 16 17 import ( 18 "fmt" 19 ) 20 21 // Reference defines the interface that consumers use when they can 22 // take either a tag or a digest. 23 type Reference interface { 24 fmt.Stringer 25 26 // Context accesses the Repository context of the reference. 27 Context() Repository 28 29 // Identifier accesses the type-specific portion of the reference. 30 Identifier() string 31 32 // Name is the fully-qualified reference name. 33 Name() string 34 35 // Scope is the scope needed to access this reference. 36 Scope(string) string 37 } 38 39 // ParseReference parses the string as a reference, either by tag or digest. 40 func ParseReference(s string, opts ...Option) (Reference, error) { 41 if t, err := NewTag(s, opts...); err == nil { 42 return t, nil 43 } 44 if d, err := NewDigest(s, opts...); err == nil { 45 return d, nil 46 } 47 return nil, newErrBadName("could not parse reference: " + s) 48 } 49 50 type stringConst string 51 52 // MustParseReference behaves like ParseReference, but panics instead of 53 // returning an error. It's intended for use in tests, or when a value is 54 // expected to be valid at code authoring time. 55 // 56 // To discourage its use in scenarios where the value is not known at code 57 // authoring time, it must be passed a string constant: 58 // 59 // const str = "valid/string" 60 // MustParseReference(str) 61 // MustParseReference("another/valid/string") 62 // MustParseReference(str + "/and/more") 63 // 64 // These will not compile: 65 // 66 // var str = "valid/string" 67 // MustParseReference(str) 68 // MustParseReference(strings.Join([]string{"valid", "string"}, "/")) 69 func MustParseReference(s stringConst, opts ...Option) Reference { 70 ref, err := ParseReference(string(s), opts...) 71 if err != nil { 72 panic(err) 73 } 74 return ref 75 } 76