Class: QB::Package

Inherits:
Util::Resource show all
Defined in:
lib/qb/package.rb,
lib/qb/package/version.rb

Overview

Common properties and methods of package resources, aimed at packages represented as directories in projects.

Direct Known Subclasses

Gem

Defined Under Namespace

Classes: Gem, Version

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(repo: NRSER::NO_ARG, **props) ⇒ Package

Constructor



98
99
100
101
 
# File 'lib/qb/package.rb', line 98

def initialize repo: NRSER::NO_ARG, **props
  @repo = repo
  super **props
end

Instance Attribute Details

#name ⇒ String (readonly)

The string name the package goes by.

Returns:

  • (String) —

    Non-empty string.



82
 
# File 'lib/qb/package.rb', line 82

prop  :name, type: t.non_empty_str

#ref_path ⇒ String | Pathname? (readonly)

User-provided path value used to construct the resource instance, if any.

This may not be the same as a root path for the resource, such as with resource classes that can be constructed from any path inside the directory, like a Repo::Git.

Returns:

  • (String | Pathname) —

    If the resource instance was constructed based on a path argument.

  • (nil) —

    If the resource instance was not constructed based on a path argument.



57
 
# File 'lib/qb/package.rb', line 57

prop  :ref_path, type: t.maybe( t.dir_path )

#repo_rel_path ⇒ Pathname (readonly)

Relative path from the #repo root to the #root_path.

Used as the version tag prefix (unless it's . - when the repo root is the root path).

Returns:

  • (Pathname) 


90
91
92
 
# File 'lib/qb/package.rb', line 90

prop  :repo_rel_path,
type: t.maybe( t.dir_path ),
source: :repo_rel_path

#root_path ⇒ Pathname (readonly)

Absolute path to the gem's root directory.

Returns:

  • (Pathname) 


65
 
# File 'lib/qb/package.rb', line 65

prop  :root_path, type: t.dir_path

#version ⇒ QB::Package::Version (readonly)

Version of the package.

Returns:



73
 
# File 'lib/qb/package.rb', line 73

prop  :version, type: QB::Package::Version

Instance Method Details

#in_repo? ⇒ Boolean

Returns true if #root_path is in a repo type we recognize.

Returns:

  • (Boolean) —

    true if #root_path is in a repo type we recognize.



130
131
132
 
# File 'lib/qb/package.rb', line 130

def in_repo?
  !!repo
end

#repo ⇒ return_type

TODO:

Document repo method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



118
119
120
121
122
123
124
 
# File 'lib/qb/package.rb', line 118

def repo
  if @repo == NRSER::NO_ARG
    @repo = QB::Repo.from_path root_path
  end
  
  @repo
end

#version_tag ⇒ String

Returns:

  • (String) 


198
199
200
 
# File 'lib/qb/package.rb', line 198

def version_tag
  version_tag_prefix + version.semver
end

#version_tag_prefix ⇒ String

Get the string prefix for tagging versions of this package.

Only makes any sense if the package is in a recognized repo, and will error out if that's not the case.

The most basic prefix is "v" for packages located at the root of the repository.

To support "multi-package" repos - which is a way of dealing with apps that are composed of multiple versioned services without having to create a new submodule for every micro-service - packages that do not share the same root of the repo are prefixed by the relative path from the repo root to the package root.

This creates a unique and intuitive namespace scheme for supporting multiple independent package versions in a single repo, which has proved handy for container-ized apps.

Unless, of course, you change the package's path. Then it will get wonky. We'll burn that bridge when we come to it.

Examples:

repo_root = '.'
package_root = repo_root
QB::Package.from_path( package_root ).version_tag_prefix
# => 'v'
# (an actual tag would look like 'v0.1.2')
repo_root = Pathname.new '.'
package_root = repo_root / 'services' / 'some-service'
QB::Package.from_path( package_root ).version_tag_prefix
# => 'services/some-service/v'
# (an actual tag would look like 'services/some-service/v0.1.2')

Returns:

  • (String) 


184
185
186
187
188
189
190
 
# File 'lib/qb/package.rb', line 184

def version_tag_prefix
  if root_path == repo.root_path
    'v'
  else
    (repo_rel_path / 'v').to_s
  end
end

#versions ⇒ return_type

TODO:

Document versions method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



211
212
213
 
# File 'lib/qb/package.rb', line 211

def versions
  # method body...
end