new API

README.md

@@ -1,7 +1,23 @@
 # kpmatch - Path patterns
 
+## Features and limitations
+
+* **Bash-style pathname patterns**
+* **Curly braces syntax:** `a{/b/c,bc}` expands into `a/b/c` and `abc`
+* **Pattern specificity ranking:** patterns can be sorted to test
+  a path against the more specific patterns first
+* **Pure paths:** This library does not access the filesystem. It does
+  not check if a path exists and does not differentiate between files
+  and directories.
+* Ranges `[0-9]`, character classes `[:space:]` are
+  not supported.
+* The extended operators `?(...)`, `*(...)`, `+(...)`, `@(...)`
+  and `!(...)` are not supported.
+
 ## Pattern Syntax
 
+Braced sections `{ , }` are expanded.
+
 Path patterns should always use forward slashes `/` between segments.
 The actual separator used when matching paths depends on the system.
 
@@ -17,48 +33,3 @@ separator.
 Square brackets `[ ]` can match one of the characters between the brackets.
 If the first character is an exclamation point `[! ]`, it will match one
 character that does NOT appear between the brackets.
-
-Curly braces `{ , }` can match one of the sub-expressions separated by commas.
-
-## API
-
-### Function `kpmatch.kpmatch(path: str | PathLike[str], pattern: str) -> bool`
-
-### Method `kpmatch.Pattern.match(path: str | PathLike[str]) -> bool`
-
-Tests if a path matches a pattern.
-
-<dl>
-    <dt>Parameters</dt>
-    <dd>
-        <strong>path</strong> — A relative or absolute file path.<br/>
-        <strong>pattern</strong> — A path pattern (see above for the syntax of patterns).
-    </dd>
-    <dt>Returns</dt>
-    <dd>True if the path matches the pattern.</dd>
-</dl>
-
-```
-function kpmatch.specificity(pattern: str) -> float
-property kpmatch.Pattern.specificity: bool
-```
-
-Computes the specificity of a pattern. The higher the number, the more
-specific it is.
-:param pattern: The path pattern to evaluate.
-:return: A positive integer.
-
-```python
-def compile(pattern: str) -> Pattern
-```
-
-Compiles a pattern into a Pattern object that can be reused multiple times.
-:param pattern: The path pattern to compile.
-
-```python
-def is_valid_pattern(pattern: str) -> bool
-```
-
-Verifies the syntax of a pattern.
-:param pattern: The path pattern to check.
-:return: True if the pattern is well-formed.