Merge pull request #65 from marcelmamula/sort

software_center_download: Update fuzzy search logic and deduplicate sorting

Author: marcelmamula

docs/module_software_center_download.md

@@ -3,6 +3,7 @@
 ## Description
 The Ansible Module `software_center_download` automates downloading files from the SAP Software Center.
 - It can find a file using a search query or download it directly using a specific download link and filename.
+- Supports wildcard search to find and download specific versions (oldest/newest) from multiple available versions.
 - If a file is not found via search, it can look for alternative versions.
 - It supports checksum validation to ensure file integrity and avoid re-downloading valid files.
 - The module can also perform a dry run to check for file availability without downloading.
@@ -18,6 +19,39 @@ This module requires the following Python modules to be installed on the target
 
 ## Execution
 
+### Wildcard Search Format
+The module supports wildcard search to find files across multiple versions. This is useful when you want to download the latest (or oldest) version of a software package without knowing the exact version number.
+
+**Format:** `PREFIX*-ID.EXT`
+
+Where:
+
+- `PREFIX`: The software name prefix (e.g., `SAPEXE`, `SAPHOSTAGENT`).
+- `*`: Single wildcard representing the version number.
+- `-`: Dash separator (required).
+- `ID`: File ID number (e.g., `80002630`).
+- `.EXT`: File extension (e.g., `.SAR`, `.EXE`).
+
+> **NOTE:** File ID is unique number that represents combination of component and platform version. 
+
+**Requirements:**
+- The parameter `search_alternatives: true` must be enabled.
+- Only one wildcard (`*`) is allowed per query.
+- File format must include both dash and extension according to pattern above.
+- Use `deduplicate` parameter to select oldest (`first`) or newest (`last`) version.
+
+**Examples:**
+- `SWPM20SP2*-80003424.SAR` - Matches all available SWPM20 versions starting with `2` (SWPM20SP23, SWPM20SP24, etc.) for `Linux on x86_64 64bit` (80003424).
+- `SAPEXE_10*-80002630.SAR` - Matches all available SAPEXE_10 versions starting with `10` (SAPEXE_10, SAPEXE_100, SAPEXE_1000, etc.) for `Linux on Power LE 64bit` (80002630).
+- `SAPHOSTAGENT*-80004822.SAR` - Matches all available SAPHOSTAGENT versions for `Linux on x86_64 64bit` (80004822).
+
+**Special Files:**
+Some SAP media files don't follow the standard naming pattern and require exact filenames:
+
+- `S4CORE107_INST_EXPORT_1.zip`
+- `KD75783.SAR`
+- `19118000000000009032` (SAP Media downloaded with ID instead of Title).
+
 ### Execution Flow
 The module follows a sophisticated logic flow to determine whether to download, skip, or fail. Here is a simplified breakdown of the decision-making process:
 
@@ -88,6 +122,31 @@ Download SAP Software file using download_link and download_filename
         dest: "Enter download path (e.g. /software)"
 ```
 
+Download latest version of SAP Software using wildcard search
+```yaml
+---
+- name: Example play for Ansible Module software_center_download
+  hosts: all
+  tasks:
+    - name: Download latest SAPEXE version using wildcard
+      community.sap_launchpad.software_center_download:
+        suser_id: "Enter SAP S-User ID"
+        suser_password: "Enter SAP S-User Password"
+        search_query: "SAPEXE*-80002630.SAR"
+        dest: "Enter download path (e.g. /software)"
+        search_alternatives: true
+        deduplicate: "last"
+    
+    - name: Download oldest SAPHOSTAGENT version using wildcard
+      community.sap_launchpad.software_center_download:
+        suser_id: "Enter SAP S-User ID"
+        suser_password: "Enter SAP S-User Password"
+        search_query: "SAPHOSTAGENT*-80004822.SAR"
+        dest: "Enter download path (e.g. /software)"
+        search_alternatives: true
+        deduplicate: "first"
+```
+
 Download list of SAP Software files, but search for alternatives if not found
 ```yaml
 ---
@@ -129,7 +188,7 @@ Download SAP Software file using Python Virtual Environment `/tmp/venv`
         PYTHONPATH: "/tmp/venv/lib/python3.11/site-packages" 
         VIRTUAL_ENV: "/tmp/venv" 
       vars:
-        ansible_python_interpreter: "/tmp/venv/bin/python3.11 }}"
+        ansible_python_interpreter: "/tmp/venv/bin/python3.11"
 ```
 
 Install prerequisites and download SAP Software file using existing System Python.</br>
@@ -199,7 +258,7 @@ Install prerequisites and download SAP Software file using existing Python Virtu
         PYTHONPATH: "/tmp/python_venv/lib/python3.11/site-packages" 
         VIRTUAL_ENV: "/tmp/python_venv" 
       vars:
-        ansible_python_interpreter: "/tmp/python_venv/bin/python3.11 }}"
+        ansible_python_interpreter: "/tmp/python_venv/bin/python3.11"
 ```
 
 ### Output format
@@ -230,7 +289,15 @@ The password for the SAP S-User specified in `suser_id`.
 ### search_query
 - _Type:_ `string`<br>
 
-The SAP software file name to download.
+The SAP software file name to download.<br>
+Supports wildcard format for version matching when `search_alternatives` is enabled.<br>
+
+**Wildcard Format:** `PREFIX*-ID.EXT`<br>
+- Only one wildcard (`*`) is allowed per query<br>
+- Example: `SAPEXE*-80002630.SAR` matches all SAPEXE versions<br>
+
+**Exact Filename:** Use the complete filename without wildcards for specific files.<br>
+- Example: `SAPCAR_1324-80000936.EXE`
 
 ### download_link
 - _Type:_ `string`<br>
@@ -252,16 +319,30 @@ The directory where downloaded SAP software files will be stored.
 
 ### deduplicate
 - _Type:_ `string`<br>
+- _Choices:_ `first`, `last`, `` (empty)<br>
+- _Default:_ `last`<br>
+
+Specifies how to handle multiple search results.<br>
+Only applies when `search_alternatives` is enabled and multiple versions are found.<br>
 
-Specifies how to handle multiple search results for the same filename.<br>
-If multiple files with the same name are found, this setting determines which one to download.<br>
-- `first`: Download the first file found (oldest).<br>
-- `last`: Download the last file found (newest).<br>
+**Options:**<br>
+- `first`: Download the oldest version<br>
+- `last`: Download the newest version<br>
+- `` (empty): If multiple results are found, display all available versions and fail with an error<br>
+
+Files are sorted numerically by version number, ensuring correct ordering (e.g., version 7 < 10 < 100 < 1500).<br>
 
 ### search_alternatives
 - _Type:_ `boolean`<br>
+- _Default:_ `false`<br>
 
 Enables searching for alternative files if the requested file is not found.<br>
+**Required** when using wildcard queries in `search_query`.<br>
+
+**Requirements:**<br>
+- Only works for files following the format `PREFIX-ID.EXT` (with dash and extension)<br>
+- Special media files without this pattern (e.g., `S4CORE107_INST_EXPORT_1.zip`) must use exact filenames<br>
+- Wildcard searches are not supported for files without dashes or extensions<br>
 
 ### dry_run
 - _Type:_ `boolean