docs(all): support custom filename func

iyear · Feb 18, 2023 · a8db280 · a8db280
1 parent 9c2b882
commit a8db280
Show file tree

Hide file tree

Showing 3 changed files with 55 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -230,16 +230,7 @@ tdl dl -u https://t.me/tdl/1 -e mp4,flv
 
 - Download with custom file name template:
 
-Following the [go template syntax](https://pkg.go.dev/text/template), you can use the variables:
-
-|     Var      |                 Desc                 |
-|:------------:|:------------------------------------:|
-|   DialogID   |          Telegram dialog id          |
-|  MessageID   |         Telegram message id          |
-| MessageDate  |      Telegram message date(ts)       |
-|   FileName   |          Telegram file name          |
-|   FileSize   | Human-readable file size, like `1GB` |
-| DownloadDate |          Download date(ts)           |
+Please refer to [template guide](docs/template.md) for more details.
 
 ```shell
 tdl dl -u https://t.me/tdl/1 \

diff --git a/docs/command/tdl_dl.md b/docs/command/tdl_dl.md
@@ -9,16 +9,18 @@ tdl dl [flags]
 ### Options
 
 ```
+      --continue          continue the last download directly
       --desc              download files from the newest to the oldest ones (may affect resume download)
   -d, --dir string        specify the download directory. If the directory does not exist, it will be created automatically (default "downloads")
   -e, --exclude strings   exclude the specified file extensions, and only judge by file name, not file MIME. Example: -e png,jpg
   -f, --file strings      official client exported files
   -h, --help              help for dl
   -i, --include strings   include the specified file extensions, and only judge by file name, not file MIME. Example: -i mp4,mp3
       --pool int          specify the size of the DC pool (default 3)
+      --restart           restart the last download directly
       --rewrite-ext       rewrite file extension according to file header MIME
       --skip-same         skip files with the same name(without extension) and size
-      --template string   download file name template (default "{{ .DialogID }}_{{ .MessageID }}_{{ .FileName }}")
+      --template string   download file name template (default "{{ .DialogID }}_{{ .MessageID }}_{{ replace .FileName `/` `_` `\\` `_` `:` `_` `*` `_` `?` `_` `<` `_` `>` `_` `|` `_` ` ` `_`  }}")
   -u, --url strings       telegram message links
 ```
 

diff --git a/docs/template.md b/docs/template.md
@@ -0,0 +1,51 @@
+## Template Guide
+
+This guide is intended to introduce variables and functions that are available in the tdl template.
+
+Template syntax is based on [Go's text/template](https://golang.org/pkg/text/template/) package.
+
+### Download
+
+Variables: (beta)
+
+|      Var       |                 Desc                 |
+|:--------------:|:------------------------------------:|
+|   `DialogID`   |          Telegram dialog id          |
+|  `MessageID`   |         Telegram message id          |
+| `MessageDate`  |   Telegram message date(timestamp)   |
+|   `FileName`   |          Telegram file name          |
+|   `FileSize`   | Human-readable file size, like `1GB` |
+| `DownloadDate` |       Download date(timestamp)       |
+
+Functions: (beta)
+
+|     Func     |                         Desc                         |           Usage           |                Example                 |
+|:------------:|:----------------------------------------------------:|:-------------------------:|:--------------------------------------:|
+|   `repeat`   |              Repeat `STRING` `N` times               |     `repeat STRING N`     |        `{{ repeat "test" 3 }}`         |
+|  `replace`   |     Perform replacement on `STRING` with `PAIRS`     | `replace STRING PAIRS...` | `{{ replace "Test" "t" "T" "e" "E" }}` |
+|   `upper`    |            Convert `STRING` to uppercase             |      `upper STRING`       |          `{{ upper "Test" }}`          |
+|   `lower`    |            Convert `STRING` to lowercase             |      `lower STRING`       |          `{{ lower "Test" }}`          |
+| `snakecase`  |            Convert `STRING` to snake_case            |    `snakecase STRING`     |        `{{ snakecase "Test" }}`        |
+| `camelcase`  |            Convert `STRING` to camelCase             |    `camelcase STRING`     |        `{{ camelcase "Test" }}`        |
+| `kebabcase`  |            Convert `STRING` to kebab-case            |    `kebabcase STRING`     |        `{{ kebabcase "Test" }}`        |
+|    `rand`    |    Generate random number in range `MIN` to `MAX`    |      `rand MIN MAX`       |           `{{ rand 1 10 }}`            |
+|    `now`     |                Get current timestamp                 |           `now`           |              `{{ now }}`               |
+| `formatDate` | Format `TIMESTAMP` with `2006-01-02 15:04:05` format |  `formatDate TIMESTAMP`   |     `{{ formatDate 1600000000 }}`      |
+
+Examples:
+
+```gotemplate
+{{ .DialogID }}_{{ .MessageID }}_{{ replace .FileName `/` `_` `\` `_` `:` `_` `*` `_` `?` `_` `<` `_` `>` `_` `|` `_` ` ` `_`  }}
+
+{{ .FileName }}_{{ formatDate .DownloadDate }}_{{ .FileSize }}
+
+{{ lower (replace .FileName ` ` `_`) }}
+
+{{ formatDate (now) }}
+```
+
+Default template:
+
+```gotemplate
+{{ .DialogID }}_{{ .MessageID }}_{{ replace .FileName `/` `_` `\` `_` `:` `_` `*` `_` `?` `_` `<` `_` `>` `_` `|` `_` ` ` `_`  }}
+```