Updated Definition format (markdown)

2023-04-30 18:02:37 -05:00 · 2023-04-30 18:02:37 -05:00 · 56bf44dd44
parent 4a191e4489
commit 56bf44dd44
1 changed files with 59 additions and 52 deletions
--- a/Definition-format.md
+++ b/Definition-format.md
@ -49,13 +49,13 @@ description: "Pirate Bay (TPB) is the galaxy’s most resilient Public BitTorren
 # [REQUIRED] Language code of the main language used on the tracker
 # See http://www.lingoes.net/en/translator/langcode.htm
 # usually you load this with the value from the sites <html lang="en_US"> tag.
-language: en-US 
+language: en-US

 # [REQUIRED] Indexer type:
 # public (no registration required)
 # semi-private (registration required, but always open)
 # private (registration required. Invite/application needed)
-type: public 
+type: public

 # [REQUIRED] Website encoding used by the tracker
 # usually you get this from the sites html <meta charset=utf-8"> tag.
@ -77,14 +77,14 @@ requestDelay: 2.5

 # [REQUIRED] List of known domains
 # (the first one is the default, must end with /)
-links: 
+links:
  - https://thepiratebay.org/
  - https://thepiratesbay.pw/
  - https://tproxy.pro/

 # [OPTIONAL] List of old domains which no longer work
 # If one of these URLs is configured it will be automatically replaced with the default one
-legacylinks: 
+legacylinks:
  - https://thepiratebay.sw/

 # [OPTIONAL] If the tracker uses untrusted HTTPS certificates (self-signed, expired, etc)
@ -361,12 +361,12 @@ search:
      followredirect: false
      # [OPTIONAL] list of tracker categories
      # If specified the path will be only used if at least one category from the list is included in
-      # the search categories list. A "!" as first entry negates the matching logic (include the path 
+      # the search categories list. A "!" as first entry negates the matching logic (include the path
      # in any other than the specified categories is in the search categories list)
      categories: ["!", 901, 902]
      # [OPTIONAL] list of (extra) arguments which should be added for this path
      inputs:
-        scene: 0 
+        scene: 0
      # [OPTIONAL] boolean option to disable input inheritance from the search level inputs list.
      # If set to true the "inputs" from the search level list will be used as the base for the path specific inputs
      # Default is true
@ -379,20 +379,14 @@ search:
    - path: xxx.php
      # only use it if we're searching for porn
      categories: [901, 902]
-  # [OPTIONAL] By default Cardigann removes any keys whose values resolve to Empty (or Null).
-  # This means that the key is not placed in the query string sent to the web site.
-  # However should the web site require that the empty key be present regardless, then set this parameter to true.
-  # Note that this does not apply to the special $Raw key, which is to say that keys built via $Raw are sent as is.
-  # Default is false.
-  allowEmptyInputs: true
  # list of HTTP arguments which are used by all paths
-  inputs: 
+  inputs:
    # Generate the category[] arguments list
    # The $raw input is special, the result will be included in the HTTP arguments list
    # without further escaping (only variables are escaped).
-    $raw: "{{ range .Categories }}category[]={{.}}&{{end}}" 
+    $raw: "{{ range .Categories }}category[]={{.}}&{{end}}"
    # If an IMDB ID has been specified use it. Otherwise use the search keywords.
-    search: "{{ if .Query.IMDBID }}{{ .Query.IMDBID }}{{ else }}{{ .Keywords }}{{ end }}" 
+    search: "{{ if .Query.IMDBID }}{{ .Query.IMDBID }}{{ else }}{{ .Keywords }}{{ end }}"
    imdb_search: "{{ if .Query.IMDBID }}yes{{ else }}{{ end }}"
    searchin: title
    incldead: 1
@ -425,10 +419,10 @@ search:
    filters:
      # The andmatch filter will make sure that only torrents which contain all words from the search string are
      # returned. This is helpful if the tracker returns a lot of unrelated search results.
-      - name: andmatch 
+      - name: andmatch
        # [OPTIONAL] argument, the maximum length of the search string which should be compared. Specify this if the
        # trackers cuts of the torrent name after a certain amount of characters.
-        args: 66 
+        args: 66
      # [OPTIONAL] dump the HTML of each row to the log (for debugging purposes)
      - name: strdump
    # [OPTIONAL] selector for rows containing dates.
@ -499,7 +493,7 @@ search:
        # replace dummy image with empty string
        - name: replace
          args: ["./pic/noposter.jpg", ""]
-    # [OPTIONAL] id for imdb.com if a link is returned then the number is extracted automatically
+    # [OPTIONAL] id for imdb.com if e.g. a link is returned then the number is extracted automatically
    # An alias named imdb is also valid here.
    # If the selector does not match it is ignored.
    imdbid:
@ -535,7 +529,7 @@ search:
    doubanid:
      selector: a[href*="movie.douban.com/subject/"]
      attribute: href
-    # [OPTIONAL] publish date (if the site does not provide a date for all results, then "now" is preferred)
+    # [OPTIONAL] publish date (if the site does not provide a date for all results, then a default of "now" is preferred)
    date:
      selector: td:nth-child(4) > span[title]
      attribute: title
@ -562,7 +556,7 @@ search:
          # get the first number from the result
          args: (\d+)
    # [OPTIONAL] number of seeders (if the site does not provide seeders for all results,
-    # then a default of "1" is preferred). 
+    # then a default of "1" is preferred).
    seeders:
      selector: td:nth-child(9)
    # [OPTIONAL] number of leechers (if the site does not provide leechers for all results,
@ -619,7 +613,7 @@ After that the selector specified in the `remove` keyword is applied. With this,
 Now it's possible to set the value based on the existence of elements using the `case` keyword. If the corresponding selector matches the field value is set to the specified case value. Processing ends after the first case selector matches. This is commonly used for `downloadvolumefactor` and `uploadvolumefactor`.
 Finally, the resulting value will be processed by the template engine and filter engine (see below).

-#### Providing fields with a default value
+### Providing the category field with a default value

 In the event that a field might not be reliably present from the site results, you can use the `default` statement, as shown in these examples:

@ -701,7 +695,7 @@ search:
      method: "{{ if .Keywords }}post{{ else }}get{{ end }}"
      # [REQUIRED] The response block is necessary to define parsing of a JSON response
      response:
-        # [REQUIRED] indicates that a JSON response is expected
+        # [REQUIRED] "json" indicates that a JSON response is expected
        type: json
        # [OPTIONAL] In the event that a server does not return an empty JSON object or a Count set to 0
        # in response to a query-no-found state, you can code the exception here.
@ -869,7 +863,7 @@ search:
      selector: genres
    # [OPTIONAL] Factor for the download volume. In most cases it should be set to "1"
    # Set to "0" if a torrent is freeleech, "0.5" if only 50% is counted, "0.75" if only 75% is counted.
-    # if a site states that the download is 75% free then the DLVF is 0.25 (only 25% is counted).
+    # if a site states that the download is 75% free then the DLVF is 0.25 (only 25% is counted). 
    downloadvolumefactor:
      selector: freeleech
      # in this example the freeleech provided by the API is 0=false, 1=true
@ -894,8 +888,11 @@ search:
      # 7 day (as seconds = 7 x 24 x 60 x 60)
      text: 604800
 ```
+
+### Search Row Selectors
+
 The use of `:has()`, `:not()` and `:contains()` are supported by the rows selector and fields selectors.
-Examples:
+
 ```yaml
 rows:
    selector: data:has(attributes.size):has(attributes.name:contains(1080)):has(attributes.poster:contains(.jpg)):not(attributes.fake_att):not(attributes.uploader:contains(DarkSwan2001))
@ -939,7 +936,7 @@ Example of the download block explaining all options:
 ```yaml
 download:
  # [OPTIONAL] use HTTP POST instead of GET to download the torrent file (default is get)
-  method: post 
+  method: post
  # [OPTIONAL] HTTP request which needs to be done before downloading the file
  before:
    # request target
@ -967,7 +964,7 @@ download:
        - name: querystring
          args: url
        - name: urldecode
-    # [OPTIONAL] As many other selectors as you need, to be used as fallback for when the prior selector fails to download.
+    # [OPTIONAL] As many other selectors as you need, to be used as a fallback for when the prior selector fails to download.
    - selector: a[href^="magnet:?xt="]
      attribute: href
      # [OPTIONAL] a list of filters which should be applied to the result of this selector
@ -975,7 +972,7 @@ download:
        - name: toupper
 ```

-### example of a download block using the infohash method
+### Download Block Infohash Example

 ```yaml
 download:
@ -1003,7 +1000,7 @@ download:
      filters:
        - name: regexp
          args: ([A-F|a-f|0-9]{40})
-    # [REQUIRED] Use this selector to provide the title for the &dn parameter of the magnet URI 
+    # [REQUIRED] Use this selector to provide the title for the &dn parameter of the magnet URI
    title:
      # [REQUIRED] The selector used to find the title
      selector: meta[property="og:title"]
@ -1014,7 +1011,7 @@ download:
        - name: validfilename
 ```

-### example of a download block using the before pathselector
+### Download Block "before" Pathselector Example

 ```yaml
 download:
@ -1029,7 +1026,7 @@ download:
      attribute: href
 ```

-# Template engine
+# Template Engine

 The template engine is very basic, and supports the following statements.

@ -1041,8 +1038,8 @@ Syntax: `{{ re_replace .Variable "regex-term" "replace-term"}}`

 Example:

-```none
-# Replace any non-alphanumeric character in the keywords with the wildcard character
+```yaml
+# Replace any non alphanumeric character in the keywords with the wildcard character
 "{{ re_replace .Keywords \"[^a-zA-Z0-9]+\" \"*\" }}"
 ```

@ -1065,9 +1062,9 @@ search:

 ## if or/and ... else ... end

-The implementation is based on: <https://golang.org/pkg/text/template/#hdr-Functions>
+The implementation is based on: [go hdr functions](https://golang.org/pkg/text/template/#hdr-Functions)
 These are not true logical OR and AND operators in that they operate on variables that contain a value or are empty.
-The use of round brackets is entirely optional.
+Note that the use of round brackets is entirely optional.

 Example of: if or ... else ... end

@ -1098,7 +1095,7 @@ Example of: if and ... else ... end

 ## if eq/ne ... else ... end

-The implementation is based on: <https://golang.org/pkg/text/template/#hdr-Functions>
+The implementation is based on: [go hdr functions](https://golang.org/pkg/text/template/#hdr-Functions)
 This is a string comparison only.
 Supports the use of both variables and strings.

@ -1128,13 +1125,13 @@ Special variables .True and .False are available

 ## join

-A simple loop over a list variable building a concatenated string with items joined by a delimiter.  
+A simple loop over a list variable building a concatenated string with items joined by a delimiter.

 Syntax: `{{ join .Variable "<delimiter>"}}`

 Example:

-```none
+```yaml
 # build a query string by concatenating all the categories with a comma
 # input: [101,201,301]
 "{{join .Categories \",\"}}"
@ -1143,13 +1140,13 @@ Example:

 ## range

-A simple loop over a list variable building a concatenated string.  
+A simple loop over a list variable building a concatenated string.

 Syntax: `{{ range .Variable }}<prefix>{{.}}<suffix>{{end}}`

 Example:

-```none
+```yaml
 # build a query string argument list for the selected categories
 # input: [101,201,301]
 "{{ range .Categories }}&cat{{.}}=1{{end}}"
@ -1173,31 +1170,36 @@ Example:

 ## Variable substitution

-The basic variable substitution operation.  
+The basic variable substitution operation.

 Syntax: `{{ .Variable }}`

-# Variables
+## Variables

 TODO: more explanation

-## Config variables (always available)
+## Config Variables

+Note that these are always available.
 Generated based on the settings section

-```none
+```yaml
 .Config.$Name # for example .Config.username , .Config.password , .Config.sitelink
 ```

-## Special variables (always available)
+## Special Variables

-```none
+Note that these are always available.
+
+```yaml
 .True contains "True" (which represents a non-empty variable)
 .False contains null (which represents an empty variable)
 .Today.Year contains "2022" (or whatever the current year is)
 ```

-## Variables available during search queries
+## Search Query Variables
+
+Note that these are only available during search queries.

 ```yaml
 .Query.Type
@ -1232,7 +1234,7 @@ Generated based on the settings section
 .Keywords          # keywords after applying the keywordsfilters
 ```

-note: variables that are not supported are provided by Cardigann for compatibility with the Torznab specifications. These variables will always return null.
+Note: There are several variables that are not supported are provided by Cardigann for compatibility with the Torznab specifications. These variables will always return null.

 All field results are available to the following fields via the `.Result.$FieldName` variables too.
 For example:
@ -1251,11 +1253,12 @@ For example:
      text: "{{ .Result._subcat }} {{ .Result.year }} {{ .Result._quality }}"
 ```
 Temporary variables used to help build release results should contain an underscore in their variable names, such as `title_phase1` or `_quality`.
-## Variables available in the download block
+
+## Download Variables

 Based on the download search field result the following variables are available:

-```none
+```yaml
 .DownloadUri.AbsoluteUri        example: https://domain.to/torrent/1234567/A-Torrent-Name-1080p/
 .DownloadUri.AbsolutePath       example: /torrent/1234567/A-Torrent-Name-1080p/
 .DownloadUri.Scheme             example: https
@ -1565,7 +1568,7 @@ Converts a fuzzy-time *string* into a DateTime object ("ddd, dd MMM yyyy HH:mm:s
 By default fuzzytime renders a USA_Date. But if you supply an argument containing "UK" then it will return a UK_Date.
 Fuzzytime can handle a fuzzy-time *string* such as:

-```none
+```yaml
 now
 4 years ago (or any other timeago values)
 Today
@ -1739,7 +1742,11 @@ fields:
      # result in the log: MM-dd hh:mm:ss Debug CardigannIndexer (trackername): strdump(dl_href_out): http://tracker.btnext.com/download.php/?id=123456
 ```

-# Proposed changes
+## Proposed changes

 - Add support for a more powerful and cross platform template engine (JavaScript?)
- Add support for multi row parsing as described in <https://github.com/cardigann/cardigann/pull/336#issuecomment-277645749>
+- Add support for multi row parsing as described in <https://github.com/cardigann/cardigann/pull/336#issuecomment-277645749>
+
+## Credit
+- [Jackett Wiki Contributors](https://github.com/Jackett/Jackett/wiki/Definition-format)
+- [Prowlarr Wiki Contributors](https://wiki.servarr.com/prowlarr/cardigann-yml-definition)