Put z -b foo bar in command summary, add regex docs

Author: ilyagr

README.md

@@ -42,16 +42,17 @@ From people using z.lua:
 ## Examples
 
 ```bash
-z foo       # cd to most frecent dir matching foo
-z foo bar   # cd to most frecent dir matching foo and bar
-z -r foo    # cd to the highest ranked dir matching foo
-z -t foo    # cd to most recently accessed dir matching foo
-z -l foo    # list matches instead of cd
-z -c foo    # restrict matches to subdirs of $PWD
-z -e foo    # echo the best match, don't cd
-z -i foo    # cd with interactive selection
-z -I foo    # cd with interactive selection using fzf
-z -b foo    # cd to the parent directory starting with foo
+z foo        # cd to most frecent dir matching foo
+z foo bar    # cd to most frecent dir matching foo and bar
+z -r foo     # cd to the highest ranked dir matching foo
+z -t foo     # cd to most recently accessed dir matching foo
+z -l foo     # list matches instead of cd
+z -c foo     # restrict matches to subdirs of $PWD
+z -e foo     # echo the best match, don't cd
+z -i foo     # cd with interactive selection
+z -I foo     # cd with interactive selection using fzf
+z -b foo     # cd to the parent directory starting with foo
+z -b foo bar # replace foo with bar in cwd and cd there
 ```
 
 
@@ -176,16 +177,12 @@ To z.lua, a directory that has low ranking but has been accessed recently will q
 
 ## Default Matching
 
-By default, z.lua uses default matching algorithm similar to the original z.sh. Paths must be match all of the regexes in order.
+By default, `z.lua` uses default matching algorithm similar to the original `z.sh`. Paths must be match all of the regexes in order.
 
 - cd to a directory contains foo:
 
       z foo
 
-- cd to a directory ends with foo:
-
-      z foo$
-
 - use multiple arguments:
 
   Assuming the following database:
@@ -195,6 +192,15 @@ By default, z.lua uses default matching algorithm similar to the original z.sh.
 
   `"z in"` would cd into `/home/user/mail/inbox` as the higher weighted entry. However you can pass multiple arguments to z.lua to prefer a different entry. In the above example, `"z w in"` would then change directory to `/home/user/work/inbox`.
 
+- use regexes:
+
+  ```bash
+  z foo$   # cd to a directory ends with foo
+  z %d     # cd to a directory that contains a digit
+  ```
+
+  Unlike `z.sh`, `z.lua` uses the [Lua regular expression syntax](https://www.lua.org/pil/20.2.html).
+
 ## Enhanced Matching
 
 Enhanced matching can be enabled by exporting the environment:

z.lua

@@ -12,17 +12,18 @@
 -- * compatible with lua 5.1, 5.2 and 5.3+
 --
 -- USE:
---     * z foo      # cd to most frecent dir matching foo
---     * z foo bar  # cd to most frecent dir matching foo and bar
---     * z -r foo   # cd to highest ranked dir matching foo
---     * z -t foo   # cd to most recently accessed dir matching foo
---     * z -l foo   # list matches instead of cd
---     * z -c foo   # restrict matches to subdirs of $PWD
---     * z -e foo   # echo the best match, don't cd
---     * z -x path  # remove path from history
---     * z -i foo   # cd with interactive selection
---     * z -I foo   # cd with interactive selection using fzf
---     * z -b foo   # cd to the parent directory starting with foo
+--     * z foo        # cd to most frecent dir matching foo
+--     * z foo bar    # cd to most frecent dir matching foo and bar
+--     * z -r foo     # cd to highest ranked dir matching foo
+--     * z -t foo     # cd to most recently accessed dir matching foo
+--     * z -l foo     # list matches instead of cd
+--     * z -c foo     # restrict matches to subdirs of $PWD
+--     * z -e foo     # echo the best match, don't cd
+--     * z -x path    # remove path from history
+--     * z -i foo     # cd with interactive selection
+--     * z -I foo     # cd with interactive selection using fzf
+--     * z -b foo     # cd to the parent directory starting with foo
+--     * z -b foo bar # replace foo with bar in cwd and cd there
 --
 -- Bash Install:
 --     * put something like this in your .bashrc:
@@ -46,7 +47,7 @@
 --
 -- Fish Shell Install:
 --     * put something like this in your config file:
---         source (lua /path/to/z.lua --init fish | psub)
+--         lua /path/to/z.lua --init fish | source
 --
 -- Power Shell Install:
 --     * put something like this in your config file:
@@ -2714,17 +2715,18 @@ end
 -----------------------------------------------------------------------
 function z_help()
 	local cmd = Z_CMD .. ' '
-	print(cmd .. 'foo       # cd to most frecent dir matching foo')
-	print(cmd .. 'foo bar   # cd to most frecent dir matching foo and bar')
-	print(cmd .. '-r foo    # cd to highest ranked dir matching foo')
-	print(cmd .. '-t foo    # cd to most recently accessed dir matching foo')
-	print(cmd .. '-l foo    # list matches instead of cd')
-	print(cmd .. '-c foo    # restrict matches to subdirs of $PWD')
-	print(cmd .. '-e foo    # echo the best match, don\'t cd')
-	print(cmd .. '-x path   # remove path from history')
-	print(cmd .. '-i foo    # cd with interactive selection')
-	print(cmd .. '-I foo    # cd with interactive selection using fzf')
-	print(cmd .. '-b foo    # cd to the parent directory starting with foo')
+	print(cmd .. 'foo        # cd to most frecent dir matching foo')
+	print(cmd .. 'foo bar    # cd to most frecent dir matching foo and bar')
+	print(cmd .. '-r foo     # cd to highest ranked dir matching foo')
+	print(cmd .. '-t foo     # cd to most recently accessed dir matching foo')
+	print(cmd .. '-l foo     # list matches instead of cd')
+	print(cmd .. '-c foo     # restrict matches to subdirs of $PWD')
+	print(cmd .. '-e foo     # echo the best match, don\'t cd')
+	print(cmd .. '-x path    # remove path from history')
+	print(cmd .. '-i foo     # cd with interactive selection')
+	print(cmd .. '-I foo     # cd with interactive selection using fzf')
+	print(cmd .. '-b foo     # cd to the parent directory starting with foo')
+	print(cmd .. '-b foo bar # replace foo with bar in cwd and cd there')
 end