Mention delimiter_split() in CannotSplit docstring

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index 61498b2abfa1aca5c099a15d1b872ed75dddf94b..6ec8dd8d79de45dfe6acb38e6489b86054aa90e8 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # black
 
 # black
 

-[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black)
+[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black) ![License: MIT](https://img.shields.io/github/license/ambv/black.svg) ![PyPI](https://img.shields.io/pypi/v/black.svg) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)

 
 > Any color you like.
 
 
 > Any color you like.
 


@@ -54,6 +54,12 @@ Options:
   --help                      Show this message and exit.
 ```
 
   --help                      Show this message and exit.
 ```
 

+`Black` is a well-behaved Unix-style command-line tool:
+* it does nothing if no sources are passed to it;
+* it will read from standard input and write to standard output if `-`
+  is used as the filename;
+* it only outputs messages to users on standard error.
+

 
 ## The philosophy behind *Black*
 
 
 ## The philosophy behind *Black*
 


@@ -76,12 +82,14 @@ or simple statement per line.  If this fits the allotted line length,
 great.
 ```py3
 # in:
 great.
 ```py3
 # in:

+

 l = [1,
      2,
      3,
 ]
 
 # out:
 l = [1,
      2,
      3,
 ]
 
 # out:

+

 l = [1, 2, 3]
 ```
 
 l = [1, 2, 3]
 ```
 


@@ -89,9 +97,11 @@ If not, *Black* will look at the contents of the first outer matching
 brackets and put that in a separate indented line.
 ```py3
 # in:
 brackets and put that in a separate indented line.
 ```py3
 # in:

+

 l = [[n for n in list_bosses()], [n for n in list_employees()]]
 
 # out:
 l = [[n for n in list_bosses()], [n for n in list_employees()]]
 
 # out:

+

 l = [
     [n for n in list_bosses()], [n for n in list_employees()]
 ]
 l = [
     [n for n in list_bosses()], [n for n in list_employees()]
 ]


@@ -106,16 +116,17 @@ matching brackets.  If that doesn't work, it will put all of them in
 separate lines.
 ```py3
 # in:
 separate lines.
 ```py3
 # in:

-def very_important_function(template: str, *variables, *, file: os.PathLike, debug: bool = False):
+
+def very_important_function(template: str, *variables, file: os.PathLike, debug: bool = False):

     """Applies `variables` to the `template` and writes to `file`."""
     with open(file, 'w') as f:
         ...
 
 # out:
     """Applies `variables` to the `template` and writes to `file`."""
     with open(file, 'w') as f:
         ...
 
 # out:

+

 def very_important_function(
     template: str,
     *variables,
 def very_important_function(
     template: str,
     *variables,

-    *,

     file: os.PathLike,
     debug: bool = False,
 ):
     file: os.PathLike,
     debug: bool = False,
 ):


@@ -184,9 +195,33 @@ explains it.  The tl;dr is "it's like highway speed limits, we won't
 bother you if you overdo it by a few km/h".
 
 
 bother you if you overdo it by a few km/h".
 
 

+### Empty lines
+
+*Black* will allow single empty lines left by the original editors,
+except when they're added within parenthesized expressions.  Since such
+expressions are always reformatted to fit minimal space, this whitespace
+is lost.
+
+It will also insert proper spacing before and after function definitions.
+It's one line before and after inner functions and two lines before and
+after module-level functions.  *Black* will put those empty lines also
+between the function definition and any standalone comments that
+immediately precede the given function.  If you want to comment on the
+entire function, use a docstring or put a leading comment in the function
+body.
+
+

 ### Editor integration
 
 ### Editor integration
 

-There is currently no integration with any text editors. Vim and
+* Visual Studio Code: [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode)
+
+Any tool that can pipe code through *Black* using its stdio mode (just
+[use `-` as the file name](http://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
+The formatted code will be returned on stdout (unless `--check` was
+passed).  *Black* will still emit messages on stderr but that shouldn't
+affect your use case.
+
+There is currently no integration with any other text editors. Vim and

 Atom/Nuclide integration is planned by the author, others will require
 external contributions.
 
 Atom/Nuclide integration is planned by the author, others will require
 external contributions.
 


@@ -214,6 +249,18 @@ and [`pipenv`](https://docs.pipenv.org/):
 > This vastly improves the formatting of our code. Thanks a ton!
 
 
 > This vastly improves the formatting of our code. Thanks a ton!
 
 

+## Show your style
+
+Use the badge in your project's README.md:
+
+```markdown
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+```
+
+Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+
+
+

 ## Tests
 
 Just run:
 ## Tests
 
 Just run:


@@ -258,7 +305,31 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
 
 ## Change Log
 

-### 18.3a2 (unreleased)
+### 18.3a4 (unreleased)
+
+* don't remove single trailing commas from square bracket indexing
+  (#59)
+
+* don't omit whitespace if the previous factor leaf wasn't a math
+  operator (#55)
+
+* omit extra space in kwarg unpacking if it's the first argument (#46)
+
+
+### 18.3a3
+
+* don't remove single empty lines outside of bracketed expressions
+  (#19)
+
+* added ability to pipe formatting from stdin to stdin (#25)
+
+* restored ability to format code with legacy usage of `async` as
+  a name (#20, #42)
+
+* even better handling of numpy-style array indexing (#33, again)
+
+
+### 18.3a2

 
 * changed positioning of binary operators to occur at beginning of lines
   instead of at the end, following [a recent change to PEP8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)
 
 * changed positioning of binary operators to occur at beginning of lines
   instead of at the end, following [a recent change to PEP8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)


@@ -269,6 +340,14 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 * remove a trailing comma if there is a single argument to a call
 
 
 * remove a trailing comma if there is a single argument to a call
 

+* if top level functions were separated by a comment, don't put four
+  empty lines after the upper function
+
+* fixed unstable formatting of newlines with imports
+
+* fixed unintentional folding of post scriptum standalone comments
+  into last statement if it was a simple statement (#18, #28)
+

 * fixed missing space in numpy-style array indexing (#33)
 
 * fixed spurious space after star-based unary expressions (#31)
 * fixed missing space in numpy-style array indexing (#33)
 
 * fixed spurious space after star-based unary expressions (#31)