From WikiChip
Difference between revisions of "mirc/identifiers/$zip"
< mirc‎ | identifiers

(add content for new identifier)
 
Line 1: Line 1:
{{mirc title|$zip Identifier}}'''$zip''' creates/tests/extracts zip using optional AES-256 encryption
+
{{mirc title|$zip Identifier}}'''$zip''' creates/tests/extracts/lists zip using optional AES-256 encryption
  
 
== Synopsis ==
 
== Synopsis ==
<pre>$zip(file.zip,<c|e|t>[po],file|dir [,password])
+
<pre>$zip(file.zip,<c|e|t|l>[po],file|dir|N [,password])[.size]
 
$zip(file.zip,c[po],file|dir added [,password])
 
$zip(file.zip,c[po],file|dir added [,password])
 +
$zip(file.zip,l,N)[.size]
 
$zip(file.zip,t[p,password])
 
$zip(file.zip,t[p,password])
 
$zip(file.zip,e[po],ExtractDir [,password])
 
$zip(file.zip,e[po],ExtractDir [,password])
 
</pre>
 
</pre>
 
== Parameters ==
 
== Parameters ==
* file.zip = filename used to create the .zip (or overwrite existing file when using o switch)
+
* '''file.zip''' = filename used to create the .zip (or overwrite existing file when using o switch)
* cetpo = see valid switches below
+
* '''cetpol''' = see valid switches below
* file|dir = when c switch used, if this is a filename, is the 1 file to be added without including path. Wildcards not accepted. If this is a foldername, the contents of that folder and any subfolders are added to file.zip with relative path beginning with "dirname\"
+
* '''file|dir''' = different meaning in different c|e|l contexts:
When e switch used, is the destination FOLDER for extraction of all contents of file.zip.
+
** when c switch used, if this is a filename, this is the 1 file to be added without including path. Wildcards not accepted. If this is a foldername, the contents of that folder and any subfolders are added to file.zip with relative path beginning with "dirname\"
* password = password used to encrypt each file added to zip. Can contain spaces. Valid only when using the 'p' switch
+
** When e switch used, is the destination FOLDER for extraction of all contents of file.zip.
 +
** When l switch is used, this is the filename.zip whose contents are listed (listed items can be filenames or foldernames)
 +
** When 't' switch is used, does not permit using the file|dir parameter
 +
'''N = 0''' lists the total number of items
 +
'''N > 0''' returns the Nth item inside the zip
 +
* password = password used to encrypt each file added to zip. Can contain spaces. Valid only when using the 'p' switch.
 +
Note: when 't' testing the .zip, the file|dir parameter is not present, and 'p' causes the 3rd parameter to be seen as password<br />
 +
Note: the password is valid but ignored when 't' tests or 'e' extracts files which had not been encrypted
  
 
== Switches ==
 
== Switches ==
 
* c = create zip
 
* c = create zip
 +
* l = list zip contents (N=0 is total items, N>0 is the Nth item) .size prop lists filesize instead of filename) items ending with "\" are foldernames whose .size is zero)
 
* e = extract from zip
 
* e = extract from zip
 +
* p = password
 
* t = test zip contents
 
* t = test zip contents
* p = password
 
 
* o = overwrite extraction dir & contents (required if extraction dir exists)
 
* o = overwrite extraction dir & contents (required if extraction dir exists)
  
Returns 1=success 0=fail
+
Returns 1=success 0=fail except when 'l'isting
 +
 
 +
* Warning: Using the 'o' switch when extracting should NOT be used when extracting into $mircdir or any folder having important files in that folder or in any subfolders below it, especially if the zip was not created by YOU. The 'o' switch is required when extracting into an existing foldername, even if empty. However it also results in overwriting extracted contents on top of existing filenames or path\filenames relative to the parent folder of the folder being extracted into.
  
* Warning: Using the 'o' switch when extracting should NOT be used when extracting into $mircdir or any folder having important files in that folder or in any subfolders below it, especially if the zip was not created by you. The 'o' switch is required when extracting into an existing folder, even if empty. However it also results in overwriting extracted contents on top of existing filenames or path\filenames relative to the parent folder of the folder being extracted into.
+
Note: If .zip contains a potentially dangerous filename such as containing '../' then 'e' and 'l' report 0 and refuse to extract or list contents.
 
== Properties ==
 
== Properties ==
 +
.size = alters 'l' output to return the Nth item's filesize instead of its filename (If the Nth item is a foldername, returns 0)
 
None
 
None
 
== Example ==
 
== Example ==
 +
 
These examples assume TESTDIR contains filenames test1.txt and test2.txt and a subfolder named Backup beneath TESTDIR contains test3.bak
 
These examples assume TESTDIR contains filenames test1.txt and test2.txt and a subfolder named Backup beneath TESTDIR contains test3.bak
  
 
<source lang="mIRC">//echo -a $zip(test,cp,testdir\test1.txt,foo bar)</source>
 
<source lang="mIRC">//echo -a $zip(test,cp,testdir\test1.txt,foo bar)</source>
 
returns 1=success:
 
returns 1=success:
Create zip filename "test" without the .zip extension. If you want the filename as test.zip, you must use test.zip as the zipfilename.
+
Creates zip filename "test" without the .zip extension. If you want the filename as test.zip, you must use 'test.zip' instead of 'test'.
The zip contains the filename as test1.txt without the foldername. File is encrypted using the 7-character passphrase "foo bar".<br />
+
The zip contains the filename as test1.txt without the foldername. File is encrypted using the 7-character passphrase "foo bar" including teh space.<br />
  
Error "* Invalid parameters: $zip" if the name "test" exists as a foldername or filename, or if testdir\test1.txt does not exist.
+
Error "* File exists: $zip" -> trying to create a .zip using a string which already exists as filename/foldername<br />
 +
Error "* Invalid parameters: $zip" file/folder being added does not exist.
  
 
<source lang="mIRC">//echo -a $zip(test,cpo,testdir\test1.txt,foo bar)</source>
 
<source lang="mIRC">//echo -a $zip(test,cpo,testdir\test1.txt,foo bar)</source>
Same except overwrites filename "test" if it already exists.
+
Same except creates zip named 'test' by overwriting it if it already exists.
  
 
<source lang="mIRC">//echo -a $zip(test.zip,tp,foo bar)</source>
 
<source lang="mIRC">//echo -a $zip(test.zip,tp,foo bar)</source>
Line 61: Line 75:
 
If this is the test3.zip created above, it extracts test1.txt and test2.txt into F:\ExtractDir\TESTDIR folder and extracts test3.bak into F:\ExtractDir\TESTDIR\Backup folder.<br />
 
If this is the test3.zip created above, it extracts test1.txt and test2.txt into F:\ExtractDir\TESTDIR folder and extracts test3.bak into F:\ExtractDir\TESTDIR\Backup folder.<br />
  
Note: After extraction, you must use
+
Note: After extraction, you can also use
 
<source lang="mIRC">//echo -a $findfile(F:\ExtractDir\,*,0,echo -a $1-)</source>
 
<source lang="mIRC">//echo -a $findfile(F:\ExtractDir\,*,0,echo -a $1-)</source>
to discover which files were extracted from the .zip
+
to discover which files were extracted from the .zip, which does not require repeatedly using $zip() to list the contents.
  
 
Note: If the password is missing/wrong for a file inside the zip, any foldernames in the zip are created.
 
Note: If the password is missing/wrong for a file inside the zip, any foldernames in the zip are created.
 +
 +
Create logs.zip containing contents of logs subfolder beneath $mircdir, returns 1 if successful
 +
//echo -a $zip(logs.zip,c,logs)
 +
 +
<source lang="mIRC">
 +
List contents of logs.zip:
 +
//var %i 1 | while ($zip(logs.zip,l,%i)) { echo -a $ord(%i) item: $v1 | inc %i }
 +
Note that the 1st item was the name of the folder, indicated by the trailing backslash
 
</source>
 
</source>
  

Revision as of 13:47, 12 March 2019

$zip creates/tests/extracts/lists zip using optional AES-256 encryption

Synopsis

$zip(file.zip,<c|e|t|l>[po],file|dir|N [,password])[.size]
$zip(file.zip,c[po],file|dir added [,password])
$zip(file.zip,l,N)[.size]
$zip(file.zip,t[p,password])
$zip(file.zip,e[po],ExtractDir [,password])

Parameters

  • file.zip = filename used to create the .zip (or overwrite existing file when using o switch)
  • cetpol = see valid switches below
  • file|dir = different meaning in different c|e|l contexts:
    • when c switch used, if this is a filename, this is the 1 file to be added without including path. Wildcards not accepted. If this is a foldername, the contents of that folder and any subfolders are added to file.zip with relative path beginning with "dirname\"
    • When e switch used, is the destination FOLDER for extraction of all contents of file.zip.
    • When l switch is used, this is the filename.zip whose contents are listed (listed items can be filenames or foldernames)
    • When 't' switch is used, does not permit using the file|dir parameter

N = 0 lists the total number of items N > 0 returns the Nth item inside the zip

  • password = password used to encrypt each file added to zip. Can contain spaces. Valid only when using the 'p' switch.

Note: when 't' testing the .zip, the file|dir parameter is not present, and 'p' causes the 3rd parameter to be seen as password
Note: the password is valid but ignored when 't' tests or 'e' extracts files which had not been encrypted

Switches

  • c = create zip
  • l = list zip contents (N=0 is total items, N>0 is the Nth item) .size prop lists filesize instead of filename) items ending with "\" are foldernames whose .size is zero)
  • e = extract from zip
  • p = password
  • t = test zip contents
  • o = overwrite extraction dir & contents (required if extraction dir exists)

Returns 1=success 0=fail except when 'l'isting

  • Warning: Using the 'o' switch when extracting should NOT be used when extracting into $mircdir or any folder having important files in that folder or in any subfolders below it, especially if the zip was not created by YOU. The 'o' switch is required when extracting into an existing foldername, even if empty. However it also results in overwriting extracted contents on top of existing filenames or path\filenames relative to the parent folder of the folder being extracted into.

Note: If .zip contains a potentially dangerous filename such as containing '../' then 'e' and 'l' report 0 and refuse to extract or list contents.

Properties

.size = alters 'l' output to return the Nth item's filesize instead of its filename (If the Nth item is a foldername, returns 0) None

Example

These examples assume TESTDIR contains filenames test1.txt and test2.txt and a subfolder named Backup beneath TESTDIR contains test3.bak

//echo -a $zip(test,cp,testdir\test1.txt,foo bar)

returns 1=success: Creates zip filename "test" without the .zip extension. If you want the filename as test.zip, you must use 'test.zip' instead of 'test'. The zip contains the filename as test1.txt without the foldername. File is encrypted using the 7-character passphrase "foo bar" including teh space.

Error "* File exists: $zip" -> trying to create a .zip using a string which already exists as filename/foldername
Error "* Invalid parameters: $zip" file/folder being added does not exist.

//echo -a $zip(test,cpo,testdir\test1.txt,foo bar)

Same except creates zip named 'test' by overwriting it if it already exists.

//echo -a $zip(test.zip,tp,foo bar)

Tests contents of test.zip zipfile
Error "* Invalid parameters: $zip" if test.zip filename does not exist
Returns 1=success: contents of test.zip either use this password or are not encrypted
Returns 0=fail: At least 1 file in test.zip not able to be decrypted, or test.zip is not a valid zip file.

//echo -a $zip(test3.zip,cp,TESTDIR,foo bar)

adds to test3.zip the contents of TESTDIR and all contents of any of its subfolders. In this example, the .zip contains 5 items:

DIR entry for TESTDIR
filename TESTDIR\test1.txt
filename TESTDIR\test2.txt
DIR entry for TESTDIR\Backup
filename TESTDIR\Backup\test3.bak

Note: If TESTDIR uses a different case than the existing folder, the files are added using the spelling as used in the $zip parameter. Foldernames for any empty subfolders beneath TESTDIR are also added.

//echo -a $zip(test.zip3,ep,F:\ExtractDir,foo bar)

extract contents of test.zip to F:\ExtractDir. If no path were listed, subfolder below $mircdir.
Error "* Invalid parameters: $zip" if ExtractDir foldername already exists, even if empty
If this is the test3.zip created above, it extracts test1.txt and test2.txt into F:\ExtractDir\TESTDIR folder and extracts test3.bak into F:\ExtractDir\TESTDIR\Backup folder.

Note: After extraction, you can also use

//echo -a $findfile(F:\ExtractDir\,*,0,echo -a $1-)

to discover which files were extracted from the .zip, which does not require repeatedly using $zip() to list the contents.

Note: If the password is missing/wrong for a file inside the zip, any foldernames in the zip are created.

Create logs.zip containing contents of logs subfolder beneath $mircdir, returns 1 if successful //echo -a $zip(logs.zip,c,logs)

List contents of logs.zip:
//var %i 1 | while ($zip(logs.zip,l,%i)) { echo -a $ord(%i) item: $v1 | inc %i }
Note that the 1st item was the name of the folder, indicated by the trailing backslash

Compatibility

7.55

See Also