hex_core v0.10.0

View Source hex_tarball (hex_core v0.10.0)

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_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)
Unpacks a package tarball.

See also: unpack/3.

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

Link to this type

checksum/0

View Source 
-type checksum() :: binary().
Link to this type

contents/0

View Source 
-type contents() :: #{filename() => binary()}.
Link to this type

filename/0

View Source 
-type filename() :: string().
Link to this type

files/0

View Source 
-type files() :: [{filename(), filename() | binary()}].
Link to this type

metadata/0

View Source 
-type metadata() :: map().
Link to this type

tarball/0

View Source 
-type tarball() :: binary().

Link to this section Functions

Link to this function

create(Metadata, Files)

View Source 
-spec create(metadata(), files()) ->
          {ok, #{tarball => tarball(), outer_checksum => checksum(), inner_checksum => tarball()}} |
          {error, term()}.
Link to this function

create(Metadata, Files, Config)

View Source 
-spec create(metadata(), files(), hex_core:config()) ->
          {ok, #{tarball => tarball(), outer_checksum => checksum(), 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,...>>}}
Link to this function

create_docs(Files)

View Source 
-spec create_docs(files()) -> {ok, tarball()}.
Link to this function

create_docs(Files, _)

View Source 
-spec 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,...>>}
Link to this function

format_checksum(Checksum)

View Source 
-spec format_checksum(checksum()) -> binary().
Returns base16-encoded representation of checksum.
Link to this function

format_error(_)

View Source 
-spec format_error(term()) -> string().
Converts an error reason term to a human-readable error message string.
Link to this function

unpack(Tarball, Output)

View Source 
-spec unpack(tarball(), memory) ->
          {ok,
           #{outer_checksum => checksum(),
             inner_checksum => checksum(),
             metadata => metadata(),
             contents => contents()}} |
          {error, term()};
      (tarball(), filename()) ->
          {ok,
           #{outer_checksum => checksum(), inner_checksum => checksum(), metadata => metadata()}} |
          {error, term()}.
Unpacks a package tarball.

See also: unpack/3.

Link to this function

unpack(Tarball, Output, Config)

View Source 
-spec unpack(tarball(), memory, hex_core:config()) ->
          {ok,
           #{outer_checksum => checksum(),
             inner_checksum => checksum(),
             metadata => metadata(),
             contents => contents()}} |
          {error, term()};
      (tarball(), filename(), hex_core:config()) ->
          {ok,
           #{outer_checksum => checksum(), inner_checksum => checksum(), 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">>, ...}}}
Link to this function

unpack_docs(Tarball, Output)

View Source 
-spec unpack_docs(tarball(), memory) -> {ok, contents()} | {error, term()};
           (tarball(), filename()) -> ok | {error, term()}.
Link to this function

unpack_docs(Tarball, Output, Config)

View Source 
-spec unpack_docs(tarball(), memory, hex_core:config()) -> {ok, contents()} | {error, term()};
           (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