hex_tarball (hex_core v0.7.1) View Source

Functions for creating and unpacking Hex tarballs.

Link to this section Summary

Types

checksum/0

contents/0

filename/0

files/0

metadata/0

tarball/0

Functions

create(Metadata, Files)

create(Metadata, Files, Config)

Creates a package tarball.

create_docs(Files)

create_docs(Files, _)

Creates a docs tarball.

format_byte_size(Size)

format_checksum(Checksum)

Returns base16-encoded representation of checksum.

format_error(_)

Converts an error reason term to a human-readable error message string.

unpack(Tarball, Output)

unpack(Tarball, Output, Config)

Unpacks a package tarball.

unpack_docs(Tarball, Output)

unpack_docs(Tarball, Output, Config)

Unpacks a documentation tarball.

Link to this section Types

checksum/0

Specs

checksum() :: binary()

contents/0

Specs

contents() :: %{optional(filename()) => binary()}

filename/0

Specs

filename() :: string()

files/0

Specs

files() :: [{filename(), filename() | binary()}]

metadata/0

Specs

metadata() :: map()

tarball/0

Specs

tarball() :: binary()

Link to this section Functions

create(Metadata, Files)

Specs

create(metadata(), files()) ::
  {:ok,
   %{
     optional(:tarball) => tarball(),
     optional(:outer_checksum) => checksum(),
     optional(:inner_checksum) => tarball()
   }}
  | {:error, term()}

create(Metadata, Files, Config)

Specs

create(metadata(), files(), :hex_core.config()) ::
  {:ok,
   %{
     optional(:tarball) => tarball(),
     optional(:outer_checksum) => checksum(),
     optional(:inner_checksum) => tarball()
   }}
  | {:error, term()}

Creates a package tarball.

Returns the binary of the tarball the "inner checksum" and "outer checksum". The inner checksum is deprecated in favor of the outer checksum.

Examples:

  > Metadata = #{<<"name">> => <<"foo">>, <<"version">> => <<"1.0.0">>},
  > Files = [{"src/foo.erl", <<"-module(foo).">>}],
  > hex_tarball:create(Metadata, Files).
  {ok, #{tarball => <<86,69,...>>,
         outer_checksum => <<40,32,...>>,
         inner_checksum => <<178,12,...>>}}

create_docs(Files)

Specs

create_docs(files()) :: {:ok, tarball()}

create_docs(Files, _)

Specs

create_docs(files(), :hex_core.config()) :: {:ok, tarball()} | {:error, term()}

Creates a docs tarball.

Examples:

  > Files = [{"doc/index.html", <<"Docs">>}],
  > hex_tarball:create_docs(Files).
  {ok, <<86,69,...>>}

format_byte_size(Size)

format_checksum(Checksum)

Specs

format_checksum(checksum()) :: binary()

Returns base16-encoded representation of checksum.

format_error(_)

Specs

format_error(term()) :: string()

Converts an error reason term to a human-readable error message string.

unpack(Tarball, Output)

Specs

unpack(tarball(), :memory) ::
  {:ok,
   %{
     optional(:outer_checksum) => checksum(),
     optional(:inner_checksum) => checksum(),
     optional(:metadata) => metadata(),
     optional(:contents) => contents()
   }}
  | {:error, term()}

unpack(tarball(), filename()) ::
  {:ok,
   %{
     optional(:outer_checksum) => checksum(),
     optional(:inner_checksum) => checksum(),
     optional(:metadata) => metadata()
   }}
  | {:error, term()}

unpack(Tarball, Output, Config)

Specs

unpack(tarball(), :memory, :hex_core.config()) ::
  {:ok,
   %{
     optional(:outer_checksum) => checksum(),
     optional(:inner_checksum) => checksum(),
     optional(:metadata) => metadata(),
     optional(:contents) => contents()
   }}
  | {:error, term()}

unpack(tarball(), filename(), :hex_core.config()) ::
  {:ok,
   %{
     optional(:outer_checksum) => checksum(),
     optional(:inner_checksum) => checksum(),
     optional(:metadata) => metadata()
   }}
  | {:error, term()}

Unpacks a package tarball.

Remember to verify the outer tarball checksum against the registry checksum returned from hex_repo:get_package(Config, Package).

Examples:

  > hex_tarball:unpack(Tarball, memory).
  {ok,#{outer_checksum => <<...>>,
        contents => [{"src/foo.erl",<<"-module(foo).">>}],
        metadata => #{<<"name">> => <<"foo">>, ...}}}
 
  > hex_tarball:unpack(Tarball, "path/to/unpack").
  {ok,#{outer_checksum => <<...>>,
        metadata => #{<<"name">> => <<"foo">>, ...}}}

unpack_docs(Tarball, Output)

Specs

unpack_docs(tarball(), :memory) :: {:ok, contents()} | {:error, term()}

unpack_docs(tarball(), filename()) :: :ok | {:error, term()}

unpack_docs(Tarball, Output, Config)

Specs

unpack_docs(tarball(), :memory, :hex_core.config()) ::
  {:ok, contents()} | {:error, term()}

unpack_docs(tarball(), filename(), :hex_core.config()) :: :ok | {:error, term()}

Unpacks a documentation tarball.

Examples:

  > hex_tarball:unpack_docs(Tarball, memory).
  {ok, [{"index.html", <<"<!doctype>">>}, ...]}
 
  > hex_tarball:unpack_docs(Tarball, "path/to/unpack").
  ok