From c34d275e1ae7d6f2e017e72e0ff88b5525118640 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Wed, 10 Jan 2024 14:49:22 +0800 Subject: [PATCH] docs: add example to parse reference with digest (#675) Resolves #671 Related to #670 Signed-off-by: Shiwei Zhang --- registry/example_reference_test.go | 47 ++++++++++++++++++++++++++++++ registry/reference.go | 5 ++++ 2 files changed, 52 insertions(+) create mode 100644 registry/example_reference_test.go diff --git a/registry/example_reference_test.go b/registry/example_reference_test.go new file mode 100644 index 00000000..45cb3b7a --- /dev/null +++ b/registry/example_reference_test.go @@ -0,0 +1,47 @@ +/* +Copyright The ORAS Authors. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package registry_test + +import ( + _ "crypto/sha256" // required to parse sha256 digest. See [Reference.Digest] + "fmt" + + "oras.land/oras-go/v2/registry" +) + +// ExampleParseReference_digest demonstrates parsing a reference string with +// digest and print its components. +func ExampleParseReference_digest() { + rawRef := "ghcr.io/oras-project/oras-go@sha256:601d05a48832e7946dab8f49b14953549bebf42e42f4d7973b1a5a287d77ab76" + ref, err := registry.ParseReference(rawRef) + if err != nil { + panic(err) + } + + fmt.Println("Registry:", ref.Registry) + fmt.Println("Repository:", ref.Repository) + + digest, err := ref.Digest() + if err != nil { + panic(err) + } + fmt.Println("Digest:", digest) + + // Output: + // Registry: ghcr.io + // Repository: oras-project/oras-go + // Digest: sha256:601d05a48832e7946dab8f49b14953549bebf42e42f4d7973b1a5a287d77ab76 +} diff --git a/registry/reference.go b/registry/reference.go index a4d2003d..fe5eddf6 100644 --- a/registry/reference.go +++ b/registry/reference.go @@ -64,6 +64,9 @@ type Reference struct { } // ParseReference parses a string (artifact) into an `artifact reference`. +// Corresponding cryptographic hash implementations are required to be imported +// as specified by https://pkg.go.dev/github.com/opencontainers/go-digest#readme-usage +// if the string contains a digest. // // Note: An "image" is an "artifact", however, an "artifact" is not necessarily // an "image". @@ -250,6 +253,8 @@ func (r Reference) ReferenceOrDefault() string { } // Digest returns the reference as a digest. +// Corresponding cryptographic hash implementations are required to be imported +// as specified by https://pkg.go.dev/github.com/opencontainers/go-digest#readme-usage func (r Reference) Digest() (digest.Digest, error) { return digest.Parse(r.Reference) }