← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to lib/stdlib/doc/src/zip.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/stdlib/doc/src/zip.xml
4
4
<erlref>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>2006</year><year>2009</year>
 
7
      <year>2006</year><year>2010</year>
8
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
9
    </copyright>
10
10
    <legalnotice>
13
13
      compliance with the License. You should have received a copy of the
14
14
      Erlang Public License along with this software. If not, it can be
15
15
      retrieved online at http://www.erlang.org/.
16
 
    
 
16
 
17
17
      Software distributed under the License is distributed on an "AS IS"
18
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
19
      the License for the specific language governing rights and limitations
20
20
      under the License.
21
 
    
 
21
 
22
22
    </legalnotice>
23
23
 
24
24
    <title>zip</title>
42
42
    <p>By convention, the name of a zip file should end in "<c>.zip</c>".
43
43
      To abide to the convention, you'll need to add "<c>.zip</c>" yourself
44
44
      to the name.</p>
45
 
    <p>Zip archives are created with the 
46
 
      <seealso marker="#zip_2">zip/2</seealso> or the 
 
45
    <p>Zip archives are created with the
 
46
      <seealso marker="#zip_2">zip/2</seealso> or the
47
47
      <seealso marker="#zip_2">zip/3</seealso> function. (They are
48
48
      also available as <c>create</c>, to resemble the <c>erl_tar</c>
49
49
      module.)</p>
50
 
    <p>To extract files from a zip archive, use the 
51
 
      <seealso marker="#unzip_1">unzip/1</seealso> or the 
 
50
    <p>To extract files from a zip archive, use the
 
51
      <seealso marker="#unzip_1">unzip/1</seealso> or the
52
52
      <seealso marker="#unzip_2">unzip/2</seealso> function. (They are
53
53
      also available as <c>extract</c>.)</p>
54
 
    <p>To return a list of the files in a zip archive, use the 
 
54
    <p>To fold a function over all files in a zip archive, use the
 
55
      <seealso marker="#foldl_3">foldl_3</seealso>.</p>
 
56
    <p>To return a list of the files in a zip archive, use the
55
57
      <seealso marker="#list_dir_1">list_dir/1</seealso> or the
56
58
      <seealso marker="#list_dir_2">list_dir/2</seealso> function. (They
57
59
      are also available as <c>table</c>.)</p>
132
134
      <type>
133
135
        <v>Name = filename()</v>
134
136
        <v>FileList = [FileSpec]</v>
135
 
        <v>FileSpec = filename() | {filename(), binary()}</v>
 
137
        <v>FileSpec = filename() | {filename(), binary()} | {filename(), binary(), #file_info{}}</v>
136
138
        <v>Options = [Option]</v>
137
139
        <v>Option = memory | cooked | verbose | {comment, Comment} | {cwd, CWD} | {compress, What} | {uncompress, What}</v>
138
140
        <v>What = all | [Extension] | {add, [Extension]} | {del, [Extension]}</v>
212
214
              <taglist>
213
215
                    <tag><c>all</c></tag>
214
216
                    <item><p> means that all files will be compressed (as long
215
 
                       as they pass the <c>uncompress</c> condition).</p></item>  
 
217
                       as they pass the <c>uncompress</c> condition).</p></item>
216
218
                    <tag><c>[Extension]</c></tag>
217
219
                    <item><p>means that only files with exactly these extensions
218
 
                     will be compressed.</p></item>  
 
220
                     will be compressed.</p></item>
219
221
                    <tag><c>{add,[Extension]}</c></tag>
220
222
                    <item><p>adds these extensions to the list of compress
221
 
                     extensions.</p></item>  
 
223
                     extensions.</p></item>
222
224
                    <tag><c>{del,[Extension]}</c></tag>
223
225
                    <item><p>deletes these extensions from the list of compress
224
 
                     extensions.</p></item>  
 
226
                     extensions.</p></item>
225
227
              </taglist>
226
228
          </item>
227
229
          <tag><c>{uncompress, What}</c></tag>
231
233
            The following values of <c>What</c> are allowed:</p>
232
234
              <taglist>
233
235
                    <tag><c>all</c></tag>
234
 
                    <item><p> means that no files will be compressed.</p></item>  
 
236
                    <item><p> means that no files will be compressed.</p></item>
235
237
                    <tag><c>[Extension]</c></tag>
236
238
                    <item><p>means that files with these extensions will be
237
 
                    uncompressed.</p></item>  
 
239
                    uncompressed.</p></item>
238
240
                    <tag><c>{add,[Extension]}</c></tag>
239
241
                    <item><p>adds these extensions to the list of uncompress
240
 
                     extensions.</p></item>  
 
242
                     extensions.</p></item>
241
243
                    <tag><c>{del,[Extension]}</c></tag>
242
244
                    <item><p>deletes these extensions from the list of uncompress
243
 
                     extensions.</p></item>  
 
245
                     extensions.</p></item>
244
246
              </taglist>
245
247
          </item>
246
248
        </taglist>
283
285
              the <c>unzip/2</c> function will only extract the files
284
286
              whose names are included in <c>FileList</c>. The full
285
287
              paths, including the names of all sub directories within
286
 
              the zip archive, must be specified.</p>  
 
288
              the zip archive, must be specified.</p>
287
289
          </item>
288
290
          <tag><c>cooked</c></tag>
289
291
          <item>
327
329
      </desc>
328
330
    </func>
329
331
    <func>
 
332
      <name>foldl(Fun, Acc0, Archive) -> {ok, Acc1} | {error, Reason}</name>
 
333
      <fsummary>Fold a function over all files in a zip archive</fsummary>
 
334
      <type>
 
335
        <v>Fun = fun(FileInArchive, GetInfo, GetBin, AccIn) -> AccOut</v>
 
336
        <v>FileInArchive = filename()</v>
 
337
        <v>GetInfo = fun() -> #file_info{}</v>
 
338
        <v>GetBin = fun() -> binary()</v>
 
339
        <v>Acc0 = Acc1 = AccIn = AccOut = term()</v>
 
340
        <v>Archive = filename() | {filename(), binary()}</v>
 
341
      </type>
 
342
      <desc>
 
343
        <p>The <marker id="foldl_3"></marker> <c>foldl/3</c> function
 
344
        calls <c>Fun(FileInArchive, GetInfo, GetBin, AccIn)</c> on
 
345
        successive files in the <c>Archive</c>, starting with <c>AccIn
 
346
        == Acc0</c>. <c>FileInArchive</c> is the name that the file
 
347
        has in the archive. <c>GetInfo</c> is a fun that returns info
 
348
        about the the file. <c>GetBin</c> returns the contents of the
 
349
        file. Both <c>GetInfo</c> and <c>GetBin</c> must be called
 
350
        within the <c>Fun</c>. Their behavior is undefined if they are
 
351
        called outside the context of the <c>Fun</c>. The <c>Fun</c>
 
352
        must return a new accumulator which is passed to the next
 
353
        call. <c>foldl/3</c> returns the final value of the
 
354
        accumulator. <c>Acc0</c> is returned if the archive is
 
355
        empty. It is not necessary to iterate over all files in the
 
356
        archive. The iteration may be ended prematurely in a
 
357
        controlled manner by throwing an exception.</p>
 
358
 
 
359
        <p>For example:</p>
 
360
        <pre>
 
361
&gt; <input>Name = "dummy.zip".</input>
 
362
"dummy.zip"
 
363
&gt; <input>{ok, {Name, Bin}} = zip:create(Name, [{"foo", &lt;&lt;"FOO"&gt;&gt;}, {"bar", &lt;&lt;"BAR"&gt;&gt;}], [memory]).</input>
 
364
{ok,{"dummy.zip",
 
365
     &lt;&lt;80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0,
 
366
       0,0,3,0,0,...&gt;&gt;}}
 
367
&gt; <input>{ok, FileSpec} = zip:foldl(fun(N, I, B, Acc) -> [{N, B(), I()} | Acc] end, [], {Name, Bin}).</input>
 
368
{ok,[{"bar",&lt;&lt;"BAR"&gt;&gt;,
 
369
      {file_info,3,regular,read_write,
 
370
                 {{2010,3,1},{19,2,10}},
 
371
                 {{2010,3,1},{19,2,10}},
 
372
                 {{2010,3,1},{19,2,10}},
 
373
                 54,1,0,0,0,0,0}},
 
374
     {"foo",&lt;&lt;"FOO"&gt;&gt;,
 
375
      {file_info,3,regular,read_write,
 
376
                 {{2010,3,1},{19,2,10}},
 
377
                 {{2010,3,1},{19,2,10}},
 
378
                 {{2010,3,1},{19,2,10}},
 
379
                 54,1,0,0,0,0,0}}]}
 
380
&gt; <input>{ok, {Name, Bin}} = zip:create(Name, lists:reverse(FileSpec), [memory]).</input>
 
381
{ok,{"dummy.zip",
 
382
     &lt;&lt;80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0,
 
383
       0,0,3,0,0,...&gt;&gt;}}
 
384
&gt; <input>catch zip:foldl(fun("foo", _, B, _) -> throw(B()); (_, _, _, Acc) -> Acc end, [], {Name, Bin}). </input>
 
385
&lt;&lt;"FOO"&gt;&gt;
 
386
</pre>
 
387
      </desc>
 
388
    </func>
 
389
    <func>
330
390
      <name>list_dir(Archive) -> RetValue</name>
331
391
      <name>list_dir(Archive, Options)</name>
332
392
      <name>table(Archive) -> RetValue</name>