From d3cef97ad38fb027262a905bd82e1d3d2549aec7 Mon Sep 17 00:00:00 2001 From: wm4 Date: Tue, 7 Jan 2020 23:08:45 +0100 Subject: options: change option parsing when using a single dash Addresses dumb things like accidentally overwriting a media file with e.g. "mpv --log-file test.mkv" (when the user thought that --log-file was a flag option, when it actually takes a filename). This example will now print an error. It still works with "-log-file overwritten.mkv", but prints a warning. Not sure if I'm being too careful or not "radical" enough. In any case, both the syntax that stops working and the syntax that produces a warning now have been discouraged and were called legacy for almost a decade. --- DOCS/interface-changes.rst | 8 ++++++++ DOCS/man/mpv.rst | 14 ++++++++++---- 2 files changed, 18 insertions(+), 4 deletions(-) (limited to 'DOCS') diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index e6e1eb317c..2c3cae76de 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -24,6 +24,14 @@ Interface changes :: + --- mpv 0.31.1 --- + - change behavior when using legacy option syntax with options that start + with two dashes (``--`` instead of a ``-``). Now, using the recommended + syntax is required for options starting with ``--``, which means an option + value must be strictly passed after a ``=``, instead of as separate + argument. For example, ``--log-file f.txt`` was previously accepted and + behaved like ``--log-file=f.txt``, but now causes an error. Use of legacy + syntax that is still supported now prints a deprecation warning. --- mpv 0.31.0 --- - add `--resume-playback-check-mtime` to check consistent mtime when restoring playback state. diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index a014388877..676cd1897f 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -314,7 +314,7 @@ Legacy option syntax -------------------- The ``--option=value`` syntax is not strictly enforced, and the alternative -legacy syntax ``-option value`` and ``--option value`` will also work. This is +legacy syntax ``-option value`` and ``-option=value`` will also work. This is mostly for compatibility with MPlayer. Using these should be avoided. Their semantics can change any time in the future. @@ -324,9 +324,15 @@ because ``--fs`` is a flag option that requires no parameter. If an option changes and its parameter becomes optional, then a command line using the alternative syntax will break. -Currently, the parser makes no difference whether an option starts with ``--`` -or a single ``-``. This might also change in the future, and ``--option value`` -might always interpret ``value`` as filename in order to reduce ambiguities. +Until mpv 0.31.0, there was no difference whether an option started with ``--`` +or a single ``-``. Newer mpv releases strictly expect that you pass the option +value after a ``=``. For example, before ``mpv --log-file f.txt`` would write +a log to ``f.txt``, but now this command line fails, as ``--log-file`` expects +an option value, and ``f.txt`` is simply considered a normal file to be played +(as in ``mpv f.txt``). + +The future plan is that ``-option value`` will not work anymore, and options +with a single ``-`` behave the same as ``--`` options. Escaping spaces and other special characters -------------------------------------------- -- cgit v1.2.3