diff options
author | Johanna Larsson <johanna.a.m.larsson@gmail.com> | 2019-09-08 13:55:01 +0200 |
---|---|---|
committer | Johanna Larsson <johanna.a.m.larsson@gmail.com> | 2019-09-19 21:41:25 +0200 |
commit | 3407e53742534f8b16121f4a4d48c58d08776133 (patch) | |
tree | 18a299e89718649dd1e8f442cba03d3bc8c39350 | |
parent | a02bc2774c0e9b984cb46e49efe039faa6965c13 (diff) | |
download | erlang-3407e53742534f8b16121f4a4d48c58d08776133.tar.gz |
erl_tar: Fix typespec for create
The first argument for `create/3` and `create/4` can be either a `string()` or `binary()` but the typespec says `file:filename()` which is only `string()`. This switches it to `file:filename_all()`.
-rw-r--r-- | lib/stdlib/doc/src/erl_tar.xml | 176 | ||||
-rw-r--r-- | lib/stdlib/src/erl_tar.erl | 17 |
2 files changed, 47 insertions, 146 deletions
diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml index ea8173748a..9be3594724 100644 --- a/lib/stdlib/doc/src/erl_tar.xml +++ b/lib/stdlib/doc/src/erl_tar.xml @@ -125,24 +125,25 @@ </list> </section> + <datatypes> + <datatype> + <name name="name_in_archive"/> + </datatype> + <datatype> + <name name="open_handle"/> + </datatype> + <datatype> + <name name="reader"/> + </datatype> + </datatypes> + <funcs> <func> - <name since="">add(TarDescriptor, Filename, Options) -> RetValue</name> + <name name="add" arity="3" since=""/> + <name name="add" arity="4" since=""/> <fsummary>Add a file to an open tar file.</fsummary> - <type> - <v>TarDescriptor = term()</v> - <v>FilenameOrBin = filename()|binary()</v> - <v>NameInArchive = filename()</v> - <v>Filename = filename()|{NameInArchive,FilenameOrBin}</v> - <v>Options = [Option]</v> - <v>Option = dereference|verbose|{chunks,ChunkSize}</v> - <v>|{atime,non_neg_integer()}|{mtime,non_neg_integer()}</v> - <v>|{ctime,non_neg_integer()}|{uid,non_neg_integer()}</v> - <v>|{gid,non_neg_integer()}</v> - <v>ChunkSize = positive_integer()</v> - <v>RetValue = ok|{error,{Filename,Reason}}</v> - <v>Reason = term()</v> - </type> + <type name="add_type"/> + <type name="add_opt"/> <desc> <p>Adds a file to a tar file that has been opened for writing by <seealso marker="#open/2"><c>open/1</c></seealso>.</p> @@ -211,33 +212,8 @@ </func> <func> - <name since="">add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> - RetValue </name> - <fsummary>Add a file to an open tar file.</fsummary> - <type> - <v>TarDescriptor = term()</v> - <v>FilenameOrBin = filename()|binary()</v> - <v>Filename = filename()</v> - <v>NameInArchive = filename()</v> - <v>Options = [Option]</v> - <v>Option = dereference|verbose</v> - <v>RetValue = ok|{error,{Filename,Reason}}</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Adds a file to a tar file that has been opened for writing by - <seealso marker="#open/2"><c>open/2</c></seealso>. This function - accepts the same options as - <seealso marker="#add/3"><c>add/3</c></seealso>.</p> - </desc> - </func> - - <func> - <name since="">close(TarDescriptor)</name> + <name name="close" arity="1" since=""/> <fsummary>Close an open tar file.</fsummary> - <type> - <v>TarDescriptor = term()</v> - </type> <desc> <p>Closes a tar file opened by <seealso marker="#open/2"><c>open/2</c></seealso>.</p> @@ -245,17 +221,9 @@ </func> <func> - <name since="">create(Name, FileList) ->RetValue </name> + <name name="create" arity="2" since=""/> <fsummary>Create a tar archive.</fsummary> - <type> - <v>Name = filename()</v> - <v>FileList = [Filename|{NameInArchive, FilenameOrBin}]</v> - <v>FilenameOrBin = filename()|binary()</v> - <v>Filename = filename()</v> - <v>NameInArchive = filename()</v> - <v>RetValue = ok|{error,{Name,Reason}}</v> - <v>Reason = term()</v> - </type> + <type name="filelist"/> <desc> <p>Creates a tar file and archives the files whose names are specified in <c>FileList</c> into it. The files can either be read from disk @@ -264,19 +232,10 @@ </func> <func> - <name since="">create(Name, FileList, OptionList)</name> + <name name="create" arity="3" since=""/> <fsummary>Create a tar archive with options.</fsummary> - <type> - <v>Name = filename()</v> - <v>FileList = [Filename|{NameInArchive, FilenameOrBin}]</v> - <v>FilenameOrBin = filename()|binary()</v> - <v>Filename = filename()</v> - <v>NameInArchive = filename()</v> - <v>OptionList = [Option]</v> - <v>Option = compressed|cooked|dereference|verbose</v> - <v>RetValue = ok|{error,{Name,Reason}}</v> - <v>Reason = term()</v> - </type> + <type name="filelist"/> + <type name="create_opt"/> <desc> <p>Creates a tar file and archives the files whose names are specified in <c>FileList</c> into it. The files can either be read from disk @@ -315,14 +274,8 @@ </func> <func> - <name since="">extract(Name) -> RetValue</name> + <name name="extract" arity="1" since=""/> <fsummary>Extract all files from a tar file.</fsummary> - <type> - <v>Name = filename() | {binary,binary()} | {file,Fd}</v> - <v>Fd = file_descriptor()</v> - <v>RetValue = ok|{error,{Name,Reason}}</v> - <v>Reason = term()</v> - </type> <desc> <p>Extracts all files from a tar archive.</p> <p>If argument <c>Name</c> is specified as <c>{binary,Binary}</c>, @@ -339,20 +292,9 @@ </func> <func> - <name since="">extract(Name, OptionList)</name> + <name name="extract" arity="2" since=""/> <fsummary>Extract files from a tar file.</fsummary> - <type> - <v>Name = filename() | {binary,binary()} | {file,Fd}</v> - <v>Fd = file_descriptor()</v> - <v>OptionList = [Option]</v> - <v>Option = {cwd,Cwd}|{files,FileList}|keep_old_files|verbose|memory</v> - <v>Cwd = [dirname()]</v> - <v>FileList = [filename()]</v> - <v>RetValue = ok|MemoryRetValue|{error,{Name,Reason}}</v> - <v>MemoryRetValue = {ok, [{NameInArchive,binary()}]}</v> - <v>NameInArchive = filename()</v> - <v>Reason = term()</v> - </type> + <type name="extract_opt"/> <desc> <p>Extracts files from a tar archive.</p> <p>If argument <c>Name</c> is specified as <c>{binary,Binary}</c>, @@ -411,11 +353,8 @@ </func> <func> - <name since="">format_error(Reason) -> string()</name> + <name name="format_error" arity="1" since=""/> <fsummary>Convert error term to a readable string.</fsummary> - <type> - <v>Reason = term()</v> - </type> <desc> <p>Converts an error reason term to a human-readable error message string.</p> @@ -423,24 +362,11 @@ </func> <func> - <name since="OTP 17.4">init(UserPrivate, AccessMode, Fun) -> - {ok,TarDescriptor} | {error,Reason}</name> + <name name="init" arity="3" since="OTP 17.4"/> <fsummary>Create a <c>TarDescriptor</c> used in subsequent tar operations when defining own low-level storage access functions.</fsummary> - <type> - <v>UserPrivate = term()</v> - <v>AccessMode = [write] | [read]</v> - <v>Fun when AccessMode is [write] = - fun(write, {UserPrivate,DataToWrite})->...; - (position,{UserPrivate,Position})->...; - (close, UserPrivate)->... end</v> - <v>Fun when AccessMode is [read] = - fun(read2, {UserPrivate,Size})->...; - (position,{UserPrivate,Position})->...; - (close, UserPrivate)->... end</v> - <v>TarDescriptor = term()</v> - <v>Reason = term()</v> - </type> + <type name="handle"/> + <type name="file_op"/> <desc> <p>The <c>Fun</c> is the definition of what to do when the different storage operations functions are to be called from the higher tar @@ -518,16 +444,8 @@ erl_tar:close(TarDesc)</code> </func> <func> - <name since="">open(Name, OpenModeList) -> RetValue</name> + <name name="open" arity="2" since=""/> <fsummary>Open a tar file for writing.</fsummary> - <type> - <v>Name = filename()</v> - <v>OpenModeList = [OpenMode]</v> - <v>Mode = write|compressed|cooked</v> - <v>RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}</v> - <v>TarDescriptor = term()</v> - <v>Reason = term()</v> - </type> <desc> <p>Creates a tar file for writing (any existing file with the same name is truncated).</p> @@ -565,36 +483,23 @@ erl_tar:close(TarDesc)</code> </func> <func> - <name since="">table(Name) -> RetValue</name> - <fsummary>Retrieve the name of all files in a tar file.</fsummary> - <type> - <v>Name = filename()|{binary,binary()}|{file,file_descriptor()}</v> - <v>RetValue = {ok,[string()]}|{error,{Name,Reason}}</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Retrieves the names of all files in the tar file <c>Name</c>.</p> - </desc> - </func> - - <func> - <name since="">table(Name, Options)</name> + <name name="table" arity="1" since=""/> + <name name="table" arity="2" since=""/> <fsummary>Retrieve name and information of all files in a tar file. </fsummary> - <type> - <v>Name = filename()|{binary,binary()}|{file,file_descriptor()}</v> - </type> + <type name="tar_entry"/> + <type name="typeflag"/> + <type name="mode"/> + <type name="uid"/> + <type name="gid"/> <desc> <p>Retrieves the names of all files in the tar file <c>Name</c>.</p> </desc> </func> <func> - <name since="">t(Name)</name> + <name name="t" arity="1" since=""/> <fsummary>Print the name of each file in a tar file.</fsummary> - <type> - <v>Name = filename()|{binary,binary()}|{file,file_descriptor()}</v> - </type> <desc> <p>Prints the names of all files in the tar file <c>Name</c> to the Erlang shell (similar to "<c>tar t</c>").</p> @@ -602,12 +507,9 @@ erl_tar:close(TarDesc)</code> </func> <func> - <name since="">tt(Name)</name> + <name name="tt" arity="1" since=""/> <fsummary>Print name and information for each file in a tar file. </fsummary> - <type> - <v>Name = filename()|{binary,binary()}|{file,file_descriptor()}</v> - </type> <desc> <p>Prints names and information about all files in the tar file <c>Name</c> to the Erlang shell (similar to "<c>tar tv</c>").</p> diff --git a/lib/stdlib/src/erl_tar.erl b/lib/stdlib/src/erl_tar.erl index 7064fcacfa..2dddee632a 100644 --- a/lib/stdlib/src/erl_tar.erl +++ b/lib/stdlib/src/erl_tar.erl @@ -165,7 +165,7 @@ check_extract(Name, #read_opts{files=Files}) -> %%%================================================================ %% The following table functions produce a list of information about %% the files contained in the archive. --type filename() :: string(). +-type name_in_archive() :: string(). -type typeflag() :: regular | link | symlink | char | block | directory | fifo | reserved | unknown. @@ -173,7 +173,7 @@ check_extract(Name, #read_opts{files=Files}) -> -type uid() :: non_neg_integer(). -type gid() :: non_neg_integer(). --type tar_entry() :: {filename(), +-type tar_entry() :: {name_in_archive(), typeflag(), non_neg_integer(), tar_time(), @@ -301,7 +301,7 @@ month(12) -> "Dec". %%%================================================================ %% The open function with friends is to keep the file and binary api of this module --type open_handle() :: file:filename() +-type open_handle() :: file:filename_all() | {binary, binary()} | {file, term()}. -spec open(open_handle(), [write | compressed | cooked]) -> @@ -396,13 +396,13 @@ pad_file(#reader{pos=Pos}=Reader) -> %% Creation/modification of tar archives %% Creates a tar file Name containing the given files. --spec create(file:filename(), filelist()) -> ok | {error, {string(), term()}}. +-spec create(file:filename_all(), filelist()) -> ok | {error, {string(), term()}}. create(Name, FileList) when is_list(Name); is_binary(Name) -> create(Name, FileList, []). %% Creates a tar archive Name containing the given files. %% Accepted options: verbose, compressed, cooked --spec create(file:filename(), filelist(), [create_opt()]) -> +-spec create(file:filename_all(), filelist(), [create_opt()]) -> ok | {error, term()} | {error, {string(), term()}}. create(Name, FileList, Options) when is_list(Name); is_binary(Name) -> Mode = lists:filter(fun(X) -> (X=:=compressed) or (X=:=cooked) @@ -434,9 +434,8 @@ do_create(TarFile, [Name|Rest], Opts) -> end. %% Adds a file to a tape archive. --type add_type() :: string() - | {string(), string()} - | {string(), binary()}. +-type add_type() :: name_in_archive() + | {name_in_archive(), string()|binary()}. -spec add(reader(), add_type(), [add_opt()]) -> ok | {error, term()}. add(Reader, {NameInArchive, Name}, Opts) when is_list(NameInArchive), is_list(Name) -> @@ -448,7 +447,7 @@ add(Reader, Name, Opts) when is_list(Name) -> do_add(Reader, Name, Name, Opts). --spec add(reader(), string() | binary(), string(), [add_opt()]) -> +-spec add(reader(), file:filename_all(), name_in_archive(), [add_opt()]) -> ok | {error, term()}. add(Reader, NameOrBin, NameInArchive, Options) when is_list(NameOrBin); is_binary(NameOrBin), |