github.com/kovansky/hugo@v0.92.3-0.20220224232819-63076e4ff19f/resources/resource/resourcetypes.go (about)

     1  // Copyright 2019 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 resource
    15  
    16  import (
    17  	"image"
    18  
    19  	"github.com/gohugoio/hugo/common/maps"
    20  	"github.com/gohugoio/hugo/langs"
    21  	"github.com/gohugoio/hugo/media"
    22  	"github.com/gohugoio/hugo/resources/images/exif"
    23  
    24  	"github.com/gohugoio/hugo/common/hugio"
    25  )
    26  
    27  // Cloner is an internal template and not meant for use in the templates. It
    28  // may change without notice.
    29  type Cloner interface {
    30  	Clone() Resource
    31  }
    32  
    33  // OriginProvider provides the original Resource if this is wrapped.
    34  // This is an internal Hugo interface and not meant for use in the templates.
    35  type OriginProvider interface {
    36  	Origin() Resource
    37  	GetFieldString(pattern string) (string, bool)
    38  }
    39  
    40  // ErrProvider provides an Err.
    41  type ErrProvider interface {
    42  	Err() error
    43  }
    44  
    45  // Resource represents a linkable resource, i.e. a content page, image etc.
    46  type Resource interface {
    47  	ResourceTypeProvider
    48  	MediaTypeProvider
    49  	ResourceLinksProvider
    50  	ResourceMetaProvider
    51  	ResourceParamsProvider
    52  	ResourceDataProvider
    53  	ErrProvider
    54  }
    55  
    56  // Image represents an image resource.
    57  type Image interface {
    58  	Resource
    59  	ImageOps
    60  }
    61  
    62  type ImageOps interface {
    63  	Height() int
    64  	Width() int
    65  	Crop(spec string) (Image, error)
    66  	Fill(spec string) (Image, error)
    67  	Fit(spec string) (Image, error)
    68  	Resize(spec string) (Image, error)
    69  	Filter(filters ...interface{}) (Image, error)
    70  	Exif() *exif.Exif
    71  
    72  	// Internal
    73  	DecodeImage() (image.Image, error)
    74  }
    75  
    76  type ResourceTypeProvider interface {
    77  	// ResourceType is the resource type. For most file types, this is the main
    78  	// part of the MIME type, e.g. "image", "application", "text" etc.
    79  	// For content pages, this value is "page".
    80  	ResourceType() string
    81  }
    82  
    83  type ResourceTypesProvider interface {
    84  	ResourceTypeProvider
    85  	MediaTypeProvider
    86  }
    87  
    88  type MediaTypeProvider interface {
    89  	// MediaType is this resource's MIME type.
    90  	MediaType() media.Type
    91  }
    92  
    93  type ResourceLinksProvider interface {
    94  	// Permalink represents the absolute link to this resource.
    95  	Permalink() string
    96  
    97  	// RelPermalink represents the host relative link to this resource.
    98  	RelPermalink() string
    99  }
   100  
   101  type ResourceMetaProvider interface {
   102  	// Name is the logical name of this resource. This can be set in the front matter
   103  	// metadata for this resource. If not set, Hugo will assign a value.
   104  	// This will in most cases be the base filename.
   105  	// So, for the image "/some/path/sunset.jpg" this will be "sunset.jpg".
   106  	// The value returned by this method will be used in the GetByPrefix and ByPrefix methods
   107  	// on Resources.
   108  	Name() string
   109  
   110  	// Title returns the title if set in front matter. For content pages, this will be the expected value.
   111  	Title() string
   112  }
   113  
   114  type ResourceParamsProvider interface {
   115  	// Params set in front matter for this resource.
   116  	Params() maps.Params
   117  }
   118  
   119  type ResourceDataProvider interface {
   120  	// Resource specific data set by Hugo.
   121  	// One example would be.Data.Digest for fingerprinted resources.
   122  	Data() interface{}
   123  }
   124  
   125  // ResourcesLanguageMerger describes an interface for merging resources from a
   126  // different language.
   127  type ResourcesLanguageMerger interface {
   128  	MergeByLanguage(other Resources) Resources
   129  	// Needed for integration with the tpl package.
   130  	MergeByLanguageInterface(other interface{}) (interface{}, error)
   131  }
   132  
   133  // Identifier identifies a resource.
   134  type Identifier interface {
   135  	Key() string
   136  }
   137  
   138  // ContentResource represents a Resource that provides a way to get to its content.
   139  // Most Resource types in Hugo implements this interface, including Page.
   140  type ContentResource interface {
   141  	MediaType() media.Type
   142  	ContentProvider
   143  }
   144  
   145  // ContentProvider provides Content.
   146  // This should be used with care, as it will read the file content into memory, but it
   147  // should be cached as effectively as possible by the implementation.
   148  type ContentProvider interface {
   149  	// Content returns this resource's content. It will be equivalent to reading the content
   150  	// that RelPermalink points to in the published folder.
   151  	// The return type will be contextual, and should be what you would expect:
   152  	// * Page: template.HTML
   153  	// * JSON: String
   154  	// * Etc.
   155  	Content() (interface{}, error)
   156  }
   157  
   158  // OpenReadSeekCloser allows setting some other way (than reading from a filesystem)
   159  // to open or create a ReadSeekCloser.
   160  type OpenReadSeekCloser func() (hugio.ReadSeekCloser, error)
   161  
   162  // ReadSeekCloserResource is a Resource that supports loading its content.
   163  type ReadSeekCloserResource interface {
   164  	MediaType() media.Type
   165  	hugio.ReadSeekCloserProvider
   166  }
   167  
   168  // LengthProvider is a Resource that provides a length
   169  // (typically the length of the content).
   170  type LengthProvider interface {
   171  	Len() int
   172  }
   173  
   174  // LanguageProvider is a Resource in a language.
   175  type LanguageProvider interface {
   176  	Language() *langs.Language
   177  }
   178  
   179  // TranslationKeyProvider connects translations of the same Resource.
   180  type TranslationKeyProvider interface {
   181  	TranslationKey() string
   182  }
   183  
   184  // UnmarshableResource represents a Resource that can be unmarshaled to some other format.
   185  type UnmarshableResource interface {
   186  	ReadSeekCloserResource
   187  	Identifier
   188  }
   189  
   190  type resourceTypesHolder struct {
   191  	mediaType    media.Type
   192  	resourceType string
   193  }
   194  
   195  func (r resourceTypesHolder) MediaType() media.Type {
   196  	return r.mediaType
   197  }
   198  
   199  func (r resourceTypesHolder) ResourceType() string {
   200  	return r.resourceType
   201  }
   202  
   203  func NewResourceTypesProvider(mediaType media.Type, resourceType string) ResourceTypesProvider {
   204  	return resourceTypesHolder{mediaType: mediaType, resourceType: resourceType}
   205  }
   206  
   207  type languageHolder struct {
   208  	lang *langs.Language
   209  }
   210  
   211  func (l languageHolder) Language() *langs.Language {
   212  	return l.lang
   213  }
   214  
   215  func NewLanguageProvider(lang *langs.Language) LanguageProvider {
   216  	return languageHolder{lang: lang}
   217  }