Merge branch 'main' of github.com:Josef-Friedrich/mscxyz

README.rst

@@ -33,30 +33,73 @@ Installation
 
 .. code:: Shell
 
-    pip install mscxyz
+    pipx install mscxyz
+
+How to ...
+==========
+
+... specify the MuseScore files to work on.
+-------------------------------------------
+
+To find out which files are selected by the script, the ``-L, --list-files``
+option can be used. The ``--list-files`` option lists as the name suggests
+only the file paths and doesn’t touch the specified *MuseScore* files:
+
+::
+
+    musescore-manager --list-files
+
+Without an option the script lists all MuseScore files in the current directory
+in a recursive way (``musescore-manager`` = ``musescore-manager .``).
+You can pass multiple file paths to the script:
+
+::
+
+    musescore-manager -L score1.mscz score2.mscz score3.mscz
+
+or multiple directories:
+
+::
+
+    musescore-manager -L folder1 folder2 folder3
+
+or use the path expansion of your shell:
+
+::
+
+    musescore-manager -L *.mscz
+
+To apply glob patterns on the file paths, the ``--glob`` option can be used.
+
+::
+
+    musescore-manager -L --glob "*/folder/*.mscz"
+
+To selection only *mscz* oder *mscx* files use the options ``--mscz`` or ``--mscx``.
+Don’t mix the options ``--mscz`` and ``--mscx`` with the option ``--glob``.
 
 CLI Usage
 =========
 
 :: 
 
     usage: musescore-manager [-h] [--print-completion {bash,zsh,tcsh}] [-V] [-b]
-                             [-k] [-C GENERAL_CONFIG_FILE] [-d] [-g GENERAL_GLOB]
-                             [-m] [--diff] [-e FILE_PATH] [-v] [--list-files]
-                             [-E EXPORT_EXTENSION] [-c META_CLEAN] [-D]
-                             [-i SOURCE_FIELDS FORMAT_STRING] [-j]
-                             [-l DESTINATION FORMAT_STRING] [-y]
+                             [-k] [-C GENERAL_CONFIG_FILE] [-d] [-m] [--diff]
+                             [-e FILE_PATH] [-v] [-E EXPORT_EXTENSION]
+                             [-c META_CLEAN] [-D] [-i SOURCE_FIELDS FORMAT_STRING]
+                             [-j] [-l DESTINATION FORMAT_STRING] [-y]
                              [-S DESTINATION_FIELD FORMAT_STRING]
                              [-x LYRICS_EXTRACT] [-r LYRICS_REMAP] [-F]
                              [-f RENAME_FORMAT] [-A] [-a] [-n] [-K FIELDS]
-                             [-t RENAME_TARGET] [-s STYLE VALUE] [-Y STYLE_FILE]
-                             [--s3] [--s4] [--list-fonts]
-                             [path ...]
+                             [-t RENAME_TARGET] [-L]
+                             [-g <glob-pattern> | --mscz | --mscx] [-s STYLE VALUE]
+                             [-Y STYLE_FILE] [--s3] [--s4] [--list-fonts]
+                             [<path> ...]
 
     The next generation command line tool to manipulate the XML based "*.mscX" and "*.mscZ" files of the notation software MuseScore.
 
     positional arguments:
-      path                  Path to a *.msc[zx]" file or a folder which contains
+      <path>                Path to a *.msc[zx]" file or a folder which contains
                             "*.msc[zx]" files. In conjunction with the subcommand "help"
                             this positional parameter accepts the names of all other
                             subcommands or the word "all".
@@ -71,10 +114,6 @@ CLI Usage
       -C GENERAL_CONFIG_FILE, --config-file GENERAL_CONFIG_FILE
                             Specify a configuration file in the INI format.
       -d, --dry-run         Simulate the actions.
-      -g GENERAL_GLOB, --glob GENERAL_GLOB
-                            Handle only files which matches against Unix style glob
-                            patterns (e. g. "*.mscx", "* - *"). If you omit this option,
-                            the standard glob pattern "*.msc[xz]" is used.
       -m, --mscore          Open and save the XML file in MuseScore after manipulating
                             the XML with lxml to avoid differences in the XML structure.
       --diff                Show a diff of the XML file before and after the
@@ -83,7 +122,6 @@ CLI Usage
                             Path of the musescore executable.
       -v, --verbose         Make commands more verbose. You can specifiy multiple
                             arguments (. g.: -vvv) to make the command more verbose.
-      --list-files          Only list files and do nothing else.
 
     clean:
       Clean and reset the formating of the "*.mscx" file
@@ -433,6 +471,17 @@ CLI Usage
       -t RENAME_TARGET, --target RENAME_TARGET
                             Target directory
 
+    selection:
+      The following options affect how the manager selects the MuseScore files.
+
+      -L, --list-files      Only list files and do nothing else.
+      -g <glob-pattern>, --glob <glob-pattern>
+                            Handle only files which matches against Unix style glob
+                            patterns (e. g. "*.mscx", "* - *"). If you omit this option,
+                            the standard glob pattern "*.msc[xz]" is used.
+      --mscz                Take only "*.mscz" files into account.
+      --mscx                Take only "*.mscx" files into account.
+
     style:
       Change the styles.
 
@@ -451,7 +500,7 @@ mscxyz
 .. code-block:: text
 
   usage: mscx-manager [-h] [-V] [-b] [-c] [-C GENERAL_CONFIG_FILE] [-d]
-                      [-g GENERAL_GLOB] [-m] [--diff] [-e FILE_PATH] [-v]
+                      [-g SELECTION_GLOB] [-m] [--diff] [-e FILE_PATH] [-v]
                       {clean,export,help,meta,lyrics,rename,style} ... path
 
   aaaaaaA command line tool to manipulate the XML based "*.mscX" and "*.mscZ" files of the notation software MuseScore.
@@ -470,7 +519,7 @@ mscxyz
     -C GENERAL_CONFIG_FILE, --config-file GENERAL_CONFIG_FILE
                           Specify a configuration file in the INI format.
     -d, --dry-run         Simulate the actions.
-    -g GENERAL_GLOB, --glob GENERAL_GLOB
+    -g SELECTION_GLOB, --glob SELECTION_GLOB
                           Handle only files which matches against Unix style glob
                           patterns (e. g. "*.mscx", "* - *"). If you omit this option,
                           the standard glob pattern "*.msc[xz]" is used.

README_template.rst

@@ -27,7 +27,54 @@ Installation
 
 .. code:: Shell
 
-    pip install mscxyz
+    pipx install mscxyz
+
+
+How to ...
+==========
+
+... specify the MuseScore files to work on.
+-------------------------------------------
+
+
+To find out which files are selected by the script, the ``-L, --list-files``
+option can be used. The ``--list-files`` option lists as the name suggests
+only the file paths and doesn’t touch the specified *MuseScore* files:
+
+::
+
+    musescore-manager --list-files
+
+Without an option the script lists all MuseScore files in the current directory
+in a recursive way (``musescore-manager`` = ``musescore-manager .``).
+You can pass multiple file paths to the script:
+
+::
+
+    musescore-manager -L score1.mscz score2.mscz score3.mscz
+
+or multiple directories:
+
+::
+
+    musescore-manager -L folder1 folder2 folder3
+
+or use the path expansion of your shell:
+
+::
+
+    musescore-manager -L *.mscz
+
+
+To apply glob patterns on the file paths, the ``--glob`` option can be used.
+
+::
+
+    musescore-manager -L --glob "*/folder/*.mscz"
+
+
+To selection only *mscz* oder *mscx* files use the options ``--mscz`` or ``--mscx``.
+Don’t mix the options ``--mscz`` and ``--mscx`` with the option ``--glob``.
 
 CLI Usage
 =========

autocomplete.bash

@@ -2,7 +2,7 @@
 
 
 
-_shtab_musescore_manager_option_strings=('-h' '--help' '--print-completion' '-V' '--version' '-b' '--backup' '-k' '--colorize' '-C' '--config-file' '-d' '--dry-run' '-g' '--glob' '-m' '--mscore' '--diff' '-e' '--executable' '-v' '--verbose' '--list-files' '-E' '--extension' '-c' '--clean' '-D' '--delete-duplicates' '-i' '--distribute-fields' '-j' '--json' '-l' '--log' '-y' '--synchronize' '-S' '--set-field' '-x' '--extract' '--extract-lyrics' '-r' '--remap' '--remap-lyrics' '-F' '--fix' '--fix-lyrics' '-f' '--format' '-A' '--alphanum' '-a' '--ascii' '-n' '--no-whitespace' '-K' '--skip-if-empty' '-t' '--target' '-s' '--style' '-Y' '--style-file' '--s3' '--styles-v3' '--s4' '--styles-v4' '--list-fonts')
+_shtab_musescore_manager_option_strings=('-h' '--help' '--print-completion' '-V' '--version' '-b' '--backup' '-k' '--colorize' '-C' '--config-file' '-d' '--dry-run' '-m' '--mscore' '--diff' '-e' '--executable' '-v' '--verbose' '-E' '--extension' '-c' '--clean' '-D' '--delete-duplicates' '-i' '--distribute-fields' '-j' '--json' '-l' '--log' '-y' '--synchronize' '-S' '--set-field' '-x' '--extract' '--extract-lyrics' '-r' '--remap' '--remap-lyrics' '-F' '--fix' '--fix-lyrics' '-f' '--format' '-A' '--alphanum' '-a' '--ascii' '-n' '--no-whitespace' '-K' '--skip-if-empty' '-t' '--target' '-L' '--list-files' '-g' '--glob' '--mscz' '--mscx' '-s' '--style' '-Y' '--style-file' '--s3' '--styles-v3' '--s4' '--styles-v4' '--list-fonts')
 
 
 
@@ -24,7 +24,6 @@ _shtab_musescore_manager___mscore_nargs=0
 _shtab_musescore_manager___diff_nargs=0
 _shtab_musescore_manager__v_nargs=0
 _shtab_musescore_manager___verbose_nargs=0
-_shtab_musescore_manager___list_files_nargs=0
 _shtab_musescore_manager__D_nargs=0
 _shtab_musescore_manager___delete_duplicates_nargs=0
 _shtab_musescore_manager__i_nargs=2
@@ -46,6 +45,10 @@ _shtab_musescore_manager__a_nargs=0
 _shtab_musescore_manager___ascii_nargs=0
 _shtab_musescore_manager__n_nargs=0
 _shtab_musescore_manager___no_whitespace_nargs=0
+_shtab_musescore_manager__L_nargs=0
+_shtab_musescore_manager___list_files_nargs=0
+_shtab_musescore_manager___mscz_nargs=0
+_shtab_musescore_manager___mscx_nargs=0
 _shtab_musescore_manager__s_nargs=2
 _shtab_musescore_manager___style_nargs=2
 _shtab_musescore_manager___s3_nargs=0

autocomplete.tcsh

@@ -3,7 +3,7 @@
 
 
 complete musescore-manager \
-        'c/--/(alphanum ascii backup clean colorize config-file delete-duplicates diff distribute-fields dry-run executable extension extract extract-lyrics fix fix-lyrics format glob help json list-files list-fonts log mscore no-whitespace print-completion remap remap-lyrics s3 s4 set-field skip-if-empty style style-file styles-v3 styles-v4 synchronize target verbose version)/' \
-        'c/-/(- A C D E F K S V Y a b c d e f g h i j k l m n r s t v x y)/' \
+        'c/--/(alphanum ascii backup clean colorize config-file delete-duplicates diff distribute-fields dry-run executable extension extract extract-lyrics fix fix-lyrics format glob help json list-files list-fonts log mscore mscx mscz no-whitespace print-completion remap remap-lyrics s3 s4 set-field skip-if-empty style style-file styles-v3 styles-v4 synchronize target verbose version)/' \
+        'c/-/(- A C D E F K L S V Y a b c d e f g h i j k l m n r s t v x y)/' \
         'n/--print-completion/(bash zsh tcsh)/' \
         'p/*/()/'

autocomplete.zsh

@@ -18,12 +18,10 @@ _shtab_musescore_manager_options=(
   {-k,--colorize}"[Colorize the command line print statements.]"
   {-C,--config-file}"[Specify a configuration file in the INI format.]:general_config_file:"
   {-d,--dry-run}"[Simulate the actions.]"
-  {-g,--glob}"[Handle only files which matches against Unix style     glob patterns (e. g. \"\*.mscx\", \"\* - \*\"). If you omit this     option, the standard glob pattern \"\*.msc\[xz\]\" is used.]:general_glob:"
   {-m,--mscore}"[Open and save the XML file in MuseScore after manipulating the XML     with lxml to avoid differences in the XML structure.]"
   "--diff[Show a diff of the XML file before and after the manipulation.]"
   {-e,--executable}"[Path of the musescore executable.]:general_executable:"
   "*"{-v,--verbose}"[Make commands more verbose. You can specifiy     multiple arguments (. g.\: -vvv) to make the command more     verbose.]"
-  "--list-files[Only list files and do nothing else.]"
   {-E,--extension}"[Extension to export. If this option     is omitted, then the default extension is \"pdf\".]:export_extension:"
   {-c,--clean}"[Clean the meta data fields. Possible values\: \„all\“ or     \„field_one,field_two\“.]:meta_clean:"
   {-D,--delete-duplicates}"[Deletes combined_lyricist if this field is equal to combined_composer. Deletes combined_subtitle if this field is equal tocombined_title. Move combined_subtitle to combimed_title if combined_title is empty.]"
@@ -41,6 +39,10 @@ _shtab_musescore_manager_options=(
   {-n,--no-whitespace}"[Replace all whitespaces with dashes or     sometimes underlines.]"
   {-K,--skip-if-empty}"[Skip rename action if FIELDS are empty. Separate FIELDS using     commas\: combined_composer,combined_title]:rename_skip:"
   {-t,--target}"[Target directory]:rename_target:"
+  {-L,--list-files}"[Only list files and do nothing else.]"
+  {-g,--glob}"[Handle only files which matches against Unix style     glob patterns (e. g. \"\*.mscx\", \"\* - \*\"). If you omit this     option, the standard glob pattern \"\*.msc\[xz\]\" is used.]:selection_glob:"
+  "--mscz[Take only \"\*.mscz\" files into account.]"
+  "--mscx[Take only \"\*.mscx\" files into account.]"
   "*"{-s,--style}"[Set a single style. For example\: --style pageWidth 8.5]:style_set:"
   {-Y,--style-file}"[Load a \"\*.mss\" style file and include the contents of this file.]:style_file:"
   {--s3,--styles-v3}"[List all possible version 3 styles.]"

docs/cli.rst

@@ -5,22 +5,22 @@ Comande line interface
 :: 
 
     usage: musescore-manager [-h] [--print-completion {bash,zsh,tcsh}] [-V] [-b]
-                             [-k] [-C GENERAL_CONFIG_FILE] [-d] [-g GENERAL_GLOB]
-                             [-m] [--diff] [-e FILE_PATH] [-v] [--list-files]
-                             [-E EXPORT_EXTENSION] [-c META_CLEAN] [-D]
-                             [-i SOURCE_FIELDS FORMAT_STRING] [-j]
-                             [-l DESTINATION FORMAT_STRING] [-y]
+                             [-k] [-C GENERAL_CONFIG_FILE] [-d] [-m] [--diff]
+                             [-e FILE_PATH] [-v] [-E EXPORT_EXTENSION]
+                             [-c META_CLEAN] [-D] [-i SOURCE_FIELDS FORMAT_STRING]
+                             [-j] [-l DESTINATION FORMAT_STRING] [-y]
                              [-S DESTINATION_FIELD FORMAT_STRING]
                              [-x LYRICS_EXTRACT] [-r LYRICS_REMAP] [-F]
                              [-f RENAME_FORMAT] [-A] [-a] [-n] [-K FIELDS]
-                             [-t RENAME_TARGET] [-s STYLE VALUE] [-Y STYLE_FILE]
-                             [--s3] [--s4] [--list-fonts]
-                             [path ...]
+                             [-t RENAME_TARGET] [-L]
+                             [-g <glob-pattern> | --mscz | --mscx] [-s STYLE VALUE]
+                             [-Y STYLE_FILE] [--s3] [--s4] [--list-fonts]
+                             [<path> ...]
 
     The next generation command line tool to manipulate the XML based "*.mscX" and "*.mscZ" files of the notation software MuseScore.
 
     positional arguments:
-      path                  Path to a *.msc[zx]" file or a folder which contains
+      <path>                Path to a *.msc[zx]" file or a folder which contains
                             "*.msc[zx]" files. In conjunction with the subcommand "help"
                             this positional parameter accepts the names of all other
                             subcommands or the word "all".
@@ -35,10 +35,6 @@ Comande line interface
       -C GENERAL_CONFIG_FILE, --config-file GENERAL_CONFIG_FILE
                             Specify a configuration file in the INI format.
       -d, --dry-run         Simulate the actions.
-      -g GENERAL_GLOB, --glob GENERAL_GLOB
-                            Handle only files which matches against Unix style glob
-                            patterns (e. g. "*.mscx", "* - *"). If you omit this option,
-                            the standard glob pattern "*.msc[xz]" is used.
       -m, --mscore          Open and save the XML file in MuseScore after manipulating
                             the XML with lxml to avoid differences in the XML structure.
       --diff                Show a diff of the XML file before and after the
@@ -47,7 +43,6 @@ Comande line interface
                             Path of the musescore executable.
       -v, --verbose         Make commands more verbose. You can specifiy multiple
                             arguments (. g.: -vvv) to make the command more verbose.
-      --list-files          Only list files and do nothing else.
 
     clean:
       Clean and reset the formating of the "*.mscx" file
@@ -397,6 +392,17 @@ Comande line interface
       -t RENAME_TARGET, --target RENAME_TARGET
                             Target directory
 
+    selection:
+      The following options affect how the manager selects the MuseScore files.
+
+      -L, --list-files      Only list files and do nothing else.
+      -g <glob-pattern>, --glob <glob-pattern>
+                            Handle only files which matches against Unix style glob
+                            patterns (e. g. "*.mscx", "* - *"). If you omit this option,
+                            the standard glob pattern "*.msc[xz]" is used.
+      --mscz                Take only "*.mscz" files into account.
+      --mscx                Take only "*.mscx" files into account.
+
     style:
       Change the styles.
 
@@ -415,7 +421,7 @@ mscxyz
 .. code-block:: text
 
   usage: mscx-manager [-h] [-V] [-b] [-c] [-C GENERAL_CONFIG_FILE] [-d]
-                      [-g GENERAL_GLOB] [-m] [--diff] [-e FILE_PATH] [-v]
+                      [-g SELECTION_GLOB] [-m] [--diff] [-e FILE_PATH] [-v]
                       {clean,export,help,meta,lyrics,rename,style} ... path
 
   aaaaaaA command line tool to manipulate the XML based "*.mscX" and "*.mscZ" files of the notation software MuseScore.
@@ -434,7 +440,7 @@ mscxyz
     -C GENERAL_CONFIG_FILE, --config-file GENERAL_CONFIG_FILE
                           Specify a configuration file in the INI format.
     -d, --dry-run         Simulate the actions.
-    -g GENERAL_GLOB, --glob GENERAL_GLOB
+    -g SELECTION_GLOB, --glob SELECTION_GLOB
                           Handle only files which matches against Unix style glob
                           patterns (e. g. "*.mscx", "* - *"). If you omit this option,
                           the standard glob pattern "*.msc[xz]" is used.