Add support for URL protocol and file type association (all OS)

.github/workflows/tests.yml

@@ -6,13 +6,13 @@ on:
       - main
       - cep-devel
     paths-ignore:
-      - 'docs/**'
+      - "docs/**"
   pull_request:
     branches:
       - main
       - cep-devel
     paths-ignore:
-      - 'docs/**'
+      - "docs/**"
 
 concurrency:
   # Concurrency group that uses the workflow name and PR number if available
@@ -27,20 +27,28 @@ jobs:
   run_test_suite:
     name: ${{ matrix.os }}-py${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}-latest
-    timeout-minutes: 30
+    timeout-minutes: 60
     env:
       CONDA_NUMBER_CHANNEL_NOTICES: 0
+      PYTHONUNBUFFERED: 1
     strategy:
       fail-fast: false
       matrix:
         os: [windows, ubuntu, macos]
-        python-version: ["3.8", "3.9", "3.10",] # "3.11"]
+        python-version: ["3.8", "3.9", "3.10"] # "3.11"]
 
     steps:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0
 
+      - name: Add Linux dependencies
+        if: matrix.os == 'ubuntu'
+        run: |
+          sudo apt-get install libfile-mimeinfo-perl desktop-file-utils
+          echo "XDG_UTILS_DEBUG_LEVEL=2" >> $GITHUB_ENV
+          echo "XDG_CURRENT_DESKTOP=GNOME" >> $GITHUB_ENV
+
       - name: Install dependencies
         uses: mamba-org/provision-with-micromamba@main
         with:

.gitignore

@@ -139,6 +139,7 @@ cython_debug/
 
 # MacOS
 .DS_Store
+.build
 
 # setuptools-scm
 menuinst/_version.py

docs/source/defining-shortcuts.md

@@ -1,15 +1,19 @@
 # Define your own shortcuts
 
-`menuinst` takes JSON configuration files as its input.
-The minimal structure is a dictionary with four keys
+`menuinst` takes JSON configuration files as its input. The minimal structure is a dictionary with
+four keys
 
 - `$schema`: The JSON-schema standard version
 - `$id`: The version of the menuinst configuration, as a JSON schema URL
 - `menu_name`: The name for this group of menu items
-- `menu_items`: A list of dictionaries, each defining the settings for one shortcut / menu item. Each menu item must define, at least, the following keys (see {class}`MenuItem schema <menuinst._schema.MenuItem>` for more details):
+- `menu_items`: A list of dictionaries, each defining the settings for one shortcut / menu item.
+  Each menu item must define, at least, the following keys (see {class}`MenuItem schema <menuinst._schema.MenuItem>`
+  for more details):
     - `name`: The name for this specific shortcut.
     - `command`: A list of strings detailing how to launch the application.
-    - `platforms`: A dictionary with up to three keys. All of them are optional but you must at least define one. The presence of a key with a non-`null` value enables the shortcut for that platform. If you don't include any, shortcuts will not be created. Available keys are:
+    - `platforms`: A dictionary with up to three keys. All of them are optional but you must at
+      least define one. The presence of a key with a non-`null` value enables the shortcut for that
+      platform. If you don't include any, shortcuts will not be created. Available keys are:
         - `linux` - see {class}`Linux schema <menuinst._schema.Linux>`
         - `osx`- see {class}`MacOS schema <menuinst._schema.MacOS>`
         - `win`- see {class}`Windows schema <menuinst._schema.Windows>`
@@ -25,20 +29,20 @@ A minimal example to launch Python's `turtle` module would be:
 
 ```json
 {
-    "$schema": "https://json-schema.org/draft-07/schema",
-    "$id": "https://schemas.conda.io/menuinst-1.schema.json",
-    "menu_name": "Python {{ PY_VER }}",
-    "menu_items": [
-        {
-            "name": "Launch Turtle",
-            "command": ["python", "-m", "turtle"],
-            "platforms": {
-                "linux": {},
-                "osx": {},
-                "win": {},
-            }
-        }
-    ]
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://schemas.conda.io/menuinst-1.schema.json",
+  "menu_name": "Python {{ PY_VER }}",
+  "menu_items": [
+    {
+      "name": "Launch Turtle",
+      "command": ["python", "-m", "turtle"],
+      "platforms": {
+        "linux": {},
+        "osx": {},
+        "win": {}
+      }
+    }
+  ]
 }
 ```
 
@@ -48,8 +52,8 @@ Note how the `menu_name` is using a placeholder `{{ PY_VER }}`.
 The full list of available placeholders is available at {ref}`placeholders`.
 ```
 
-This is not using any customization options or advanced features.
-It's the bare minimum to make it work: a name, the command, and the target platforms.
+This is not using any customization options or advanced features. It's the bare minimum to make it
+work: a name, the command, and the target platforms.
 
 ## Associate your shortcut with file types and URL protocols
 
@@ -58,98 +62,125 @@ It's the bare minimum to make it work: a name, the command, and the target platf
 Each operating system has a slightly different way of associating a file type to a given shortcut.
 Unix systems have the notion of MIME types, while Windows relies more on file name extensions.
 
-* On Linux, use the `MimeType` option.
-  Remember to add the `%f` (single file) or `%F` (several files) placeholders to your command
-  so the URLs are passed adequately.
-* On macOS, use `CFBundleDocumentTypes`. Requires no placeholder. The opened document will be automatically passed as an argument.
-* On Windows, use `file_extensions`. Remember to add the `%1` or `%*` placeholders to your command
+- On Linux, use the `MimeType` option. Remember to add the `%f` (single file) or `%F` (several
+  files) placeholders to your command so the paths are passed adequately. If you are defining a new
+  MIME type, you must fill the `glob_patterns` field by mapping the new MIME type to the file
+  extensions you want to associate with it.
+- On macOS, use `CFBundleDocumentTypes`. Requires no placeholder. The opened document will be
+  automatically passed as a regular command-line argument. The file will be dispatched via events.
+  You need to define the `event_handler` field to define a logic that will forward the caught files
+  to your application (via sockets, API calls, inotify or any other inter-process communication
+  mechanism) The association happens via UTI strings (Uniform Type Identifiers). If you need UTIs
+  not defined by Apple, use the `UTImportedTypeDeclarations` field if they are provided by other
+  apps, or `UTExportedTypeDeclarations` if you are defining them yourself.
+- On Windows, use `file_extensions`. Remember to add the `%1` or `%*` placeholders to your command
   so the path of the opened file(s) is passed adequately.
 
-
 A multi-platform example:
 
 ```json
 {
-    "$schema": "https://json-schema.org/draft-07/schema",
-    "$id": "https://schemas.conda.io/menuinst-1.schema.json",
-    "menu_name": "File type handler example",
-    "menu_items": [
-        {
-            "name": "My CSV Reader",
-            "activate": true,
-            "command": ["{{ PREFIX }}/bin/my_csv_reader.py"],
-            "icon": "{{ MENU_DIR }}/my_csv_reader.{{ ICON_EXT }}",
-            "platforms": {
-                "linux": {
-                    "command": ["{{ PREFIX }}/bin/my_csv_reader.py", "%f"],
-                    "MimeType": ["text/csv"]
-                },
-                "macos": {
-                    "CFBundleDocumentTypes": [
-                        {
-                            "CFBundleTypeIconFile": "{{ MENU_DIR }}/my_csv_reader",
-                            "CFBundleTypeName": "my-csv-reader.csv",
-                            "CFBundleTypeRole": "Viewer",
-                            "LSItemContentTypes": ["public.comma-separated-values-text"],
-                            "LSHandlerRank": "Default"
-                        }
-                    ]
-                },
-                "windows": {
-                    "command": ["{{ SCRIPTS_DIR }}/my_csv_reader.py", "%1"],
-                    "file_extensions": [".csv"]
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://schemas.conda.io/menuinst-1.schema.json",
+  "menu_name": "File type handler example",
+  "menu_items": [
+    {
+      "name": "My CSV Reader",
+      "activate": true,
+      "command": ["{{ PREFIX }}/bin/open_menuinst_files.py"],
+      "icon": "{{ MENU_DIR }}/open_menuinst_files.{{ ICON_EXT }}",
+      "platforms": {
+        "linux": {
+          "command": ["{{ PREFIX }}/bin/open_menuinst_files.py", "%f"],
+          "MimeType": ["application/x-menuinst"],
+          "glob_patterns": {
+            "application/x-menuinst": ["*.menuinst"]
+          }
+        },
+        "osx": {
+          "CFBundleDocumentTypes": [
+            {
+              "CFBundleTypeName": "org.conda.menuinst.opener",
+              "CFBundleTypeRole": "Viewer",
+              "LSItemContentTypes": ["org.conda.menuinst.main-file-uti"],
+              "LSHandlerRank": "Default"
+            }
+          ],
+          "UTExportedTypeDeclarations": [
+            {
+              "UTTypeConformsTo": ["public.data", "public.content"],
+              "UTTypeIdentifier": "org.conda.menuinst.main-file-uti",
+              "UTTypeTagSpecification": [
+                {
+                  "public.filename-extension": ["menuinst"]
                 }
+              ]
             }
+          ]
+        },
+        "windows": {
+          "command": ["{{ SCRIPTS_DIR }}/open_menuinst_files.py", "%1"],
+          "file_extensions": [".csv"]
         }
-    ]
+      }
+    }
+  ]
 }
 ```
 
 ### URL protocols
 
-Each operating system has a slightly different way of associating a URL protocol to a given shortcut.
+Each operating system has a slightly different way of associating a URL protocol to a given
+shortcut.
 
-* On Linux, you must use the `MimeType` option too.
-  Use the `x-scheme-handler/your-protocol-here` syntax.
-  Remember to add the `%u` (single URL) or `%U` (several URLs) placeholders to your command
-  so the URLs are passed adequately.
-* On macOS, use `CFBundleURLTypes`. Requires no placeholder. The URL will be dispatched via events. Right now, the .app launcher/forwarder doesn't know about the Apple events involved in this, so **it will not work**. WIP.
-* On Windows, use `url_protocols`. Remember to add the `%1` or `%*` placeholders to your command
+- On Linux, you must use the `MimeType` option too. Use the `x-scheme-handler/your-protocol-here`
+  syntax. Remember to add the `%u` (single URL) or `%U` (several URLs) placeholders to your command
   so the URLs are passed adequately.
-
+- On Windows, use `url_protocols`. Remember to add the `%1` or `%*` placeholders to your command so
+  the URLs are passed adequately.
+- On macOS, use `CFBundleURLTypes`. Requires no placeholders. The URL will be dispatched via
+  events. You need to define the `event_handler` field to define a logic that will forward the
+  caught URLs to your application (via sockets, API calls, inotify or any other inter-process
+  communication mechanism). Note that setting `CFBundleTypeRole` will make the wrapper blip in the
+  dock when the URL is opened. If you don't want that, do not set it.
 
 ```json
 {
-    "$schema": "https://json-schema.org/draft-07/schema",
-    "$id": "https://schemas.conda.io/menuinst-1.schema.json",
-    "menu_name": "Protocol handler example",
-    "menu_items": [
-        {
-            "name": "My custom menuinst:// handler",
-            "activate": true,
-            "command": ["{{ PREFIX }}/bin/my_protocol_handler.py"],
-            "icon": "{{ MENU_DIR }}/my_protocol_handler.{{ ICON_EXT }}",
-            "platforms": {
-                "linux": {
-                    "command": ["{{ PREFIX }}/bin/my_protocol_handler.py", "%u"],
-                    "MimeType": ["x-scheme-handler/menuinst"]
-                },
-                "macos": {
-                    "CFBundleURLTypes": [
-                        {
-                            "CFBundleURLIconFile": "{{ MENU_DIR }}/my_protocol_handler",
-                            "CFBundleURLName": "my-protocol-handler.menuinst.does-not-work-yet",
-                            "CFBundleTypeRole": "Viewer",
-                            "CFBundleURLSchemes": ["menuinst"]
-                        }
-                    ]
-                },
-                "windows": {
-                    "command": ["{{ SCRIPTS_DIR }}/my_protocol_handler.py", "%1"],
-                    "url_protocols": ["menuinst"]
-                }
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://schemas.conda.io/menuinst-1.schema.json",
+  "menu_name": "Protocol handler example",
+  "menu_items": [
+    {
+      "name": "My custom menuinst:// handler",
+      "activate": true,
+      "command": ["{{ PREFIX }}/bin/my_protocol_handler.py"],
+      "icon": "{{ MENU_DIR }}/my_protocol_handler.{{ ICON_EXT }}",
+      "platforms": {
+        "linux": {
+          "command": ["{{ PREFIX }}/bin/my_protocol_handler.py", "%u"],
+          "MimeType": ["x-scheme-handler/menuinst"]
+        },
+        "osx": {
+          "command": [
+            "{{ PREFIX }}/bin/my_protocol_handler.py",
+            "--listen",
+            "4444"
+          ],
+          "CFBundleURLTypes": [
+            {
+              "CFBundleURLIconFile": "{{ MENU_DIR }}/my_protocol_handler",
+              "CFBundleURLName": "my-protocol-handler.menuinst.does-not-work-yet",
+              "CFBundleURLSchemes": ["menuinst"]
             }
+          ],
+          "event_handler": "for i in 1 2 3 4 5; do echo \"$*\" | nc localhost 4444 && break || sleep 1; done"
+        },
+        "windows": {
+          "command": ["{{ SCRIPTS_DIR }}/my_protocol_handler.py", "%1"],
+          "url_protocols": ["menuinst"]
         }
-    ]
+      }
+    }
+  ]
 }
 ```