diff options
Diffstat (limited to 'docs/shell.rst')
-rw-r--r-- | docs/shell.rst | 152 |
1 files changed, 2 insertions, 150 deletions
diff --git a/docs/shell.rst b/docs/shell.rst index 0d7d3c9..bf40874 100644 --- a/docs/shell.rst +++ b/docs/shell.rst @@ -6,153 +6,5 @@ Shell Script ============ -The ``natsort`` shell script is automatically installed when you install -:mod:`natsort` with pip. - -Below is the usage and some usage examples for the ``natsort`` shell script. - -Usage ------ - -.. code-block:: - - usage: natsort [-h] [--version] [-p] [-f LOW HIGH] [-F LOW HIGH] [-e EXCLUDE] - [-r] [-t {digit,int,float,version,ver}] [--nosign] [--noexp] - [--locale] - [entries [entries ...]] - - Performs a natural sort on entries given on the command-line. - A natural sort sorts numerically then alphabetically, and will sort - by numbers in the middle of an entry. - - positional arguments: - entries The entries to sort. Taken from stdin if nothing is - given on the command line. - - optional arguments: - -h, --help show this help message and exit - --version show program's version number and exit - -p, --paths Interpret the input as file paths. This is not - strictly necessary to sort all file paths, but in - cases where there are OS-generated file paths like - "Folder/" and "Folder (1)/", this option is needed to - make the paths sorted in the order you expect - ("Folder/" before "Folder (1)/"). - -f LOW HIGH, --filter LOW HIGH - Used for keeping only the entries that have a number - falling in the given range. - -F LOW HIGH, --reverse-filter LOW HIGH - Used for excluding the entries that have a number - falling in the given range. - -e EXCLUDE, --exclude EXCLUDE - Used to exclude an entry that contains a specific - number. - -r, --reverse Returns in reversed order. - -t {digit,int,float,version,ver,real,f,i,r,d}, - --number-type {digit,int,float,version,ver,real,f,i,r,d}, - --number_type {digit,int,float,version,ver,real,f,i,r,d} - Choose the type of number to search for. "float" will - search for floating-point numbers. "int" will only - search for integers. "digit", "version", and "ver" are - synonyms for "int"."real" is a shortcut for "float" - with --sign. "i" and "d" are synonyms for "int", "f" - is a synonym for "float", and "r" is a synonym for - "real".The default is int. - --nosign Do not consider "+" or "-" as part of a number, i.e. - do not take sign into consideration. This is the - default. - -s, --sign Consider "+" or "-" as part of a number, i.e. take - sign into consideration. The default is unsigned. - --noexp Do not consider an exponential as part of a number, - i.e. 1e4, would be considered as 1, "e", and 4, not as - 10000. This only effects the --number-type=float. - -l, --locale Causes natsort to use locale-aware sorting. You will - get the best results if you install PyICU. - -Description ------------ - -``natsort`` was originally written to aid in computational chemistry -research so that it would be easy to analyze large sets of output files -named after the parameter used: - -.. code-block:: console - - $ ls *.out - mode1000.35.out mode1243.34.out mode744.43.out mode943.54.out - -(Obviously, in reality there would be more files, but you get the idea.) Notice -that the shell sorts in lexicographical order. This is the behavior of programs like -``find`` as well as ``ls``. The problem is passing these files to an -analysis program causes them not to appear in numerical order, which can lead -to bad analysis. To remedy this, use ``natsort``: - -.. code-block:: console - - $ natsort *.out - mode744.43.out - mode943.54.out - mode1000.35.out - mode1243.34.out - $ natsort -t r *.out | xargs your_program - -``-t r`` is short for ``--number-type real``. You can also place natsort in -the middle of a pipe: - -.. code-block:: console - - $ find . -name "*.out" | natsort -t r | xargs your_program - -To sort version numbers, use the default ``--number-type``: - -.. code-block:: console - - $ ls * - prog-1.10.zip prog-1.9.zip prog-2.0.zip - $ natsort * - prog-1.9.zip - prog-1.10.zip - prog-2.0.zip - -In general, all ``natsort`` shell script options mirror the :func:`~natsorted` -API, with notable exception of the ``--filter``, ``--reverse-filter``, and ``--exclude`` -options. These three options are used as follows: - -.. code-block:: console - - $ ls *.out - mode1000.35.out mode1243.34.out mode744.43.out mode943.54.out - $ natsort -t r *.out -f 900 1100 # Select only numbers between 900-1100 - mode943.54.out - mode1000.35.out - $ natsort -t r *.out -F 900 1100 # Select only numbers NOT between 900-1100 - mode744.43.out - mode1243.34.out - $ natsort -t r *.out -e 1000.35 # Exclude 1000.35 from search - mode744.43.out - mode943.54.out - mode1243.34.out - -If you are sorting paths with OS-generated filenames, you may require the -``--paths``/``-p`` option: - -.. code-block:: console - - $ find . ! -path . -type f - ./folder/file (1).txt - ./folder/file.txt - ./folder (1)/file.txt - ./folder (10)/file.txt - ./folder (2)/file.txt - $ find . ! -path . -type f | natsort - ./folder (1)/file.txt - ./folder (2)/file.txt - ./folder (10)/file.txt - ./folder/file (1).txt - ./folder/file.txt - $ find . ! -path . -type f | natsort -p - ./folder/file.txt - ./folder/file (1).txt - ./folder (1)/file.txt - ./folder (2)/file.txt - ./folder (10)/file.txt +This page has been moved to the +`natsort wiki <https://github.com/SethMMorton/natsort/wiki/Shell-Script>`_. |