Add inline documentation for new syntax; See: websharks/zencache#191

[kristineds]

Add inline documentation for new syntax;

• Add on the following relevant configuration settings: URI Exclusion Patterns, HTTP Referrer Exclusion Patterns, User - Agent Exclusion Patterns, CSS and JS Exclusion Patterns

See: wpsharks/comet-cache#191

[kristineds]

@raamdev @jaswsinc Submitting PR for step 2. Please refer to the latest commit for the updated version. Would love to hear your feedback on this and how to proceed. Thanks

[jaswrks]

In this paragraph...

A wildcard character can also be used when necessary; e.g., xy-framework; (where = anything, 0 or more characters in length). These other special characters can also be used: ^ = beginning of line, when not used inside square brackets; * = anything, 0 or more characters in length including all subdirectories; $ = end of the line.

Note that ZenCache is not parsing true Regular Expression syntax in any of these fields. Instead, we are using a watered-down version of regex, where only those specific characters that you listed are treated a different way.

Therefore, saying, "when not used inside square brackets" is unnecessary (i.e., incorrect in this case), because square brackets have no special meaning in our watered-down version of regex. You can simply say that ^ equals the beginning of the line. That will always be the case in our watered-down parser.

---

So I suggest changing it to the following:

A wildcard * character can also be used when necessary; e.g., /xy*-framework/ (where * = 0 or more characters that are NOT a slash /). Other special characters include: ** = 0 or more characters of any kind, including / slashes; ^ = beginning of the string; $ = end of the string. To learn more about this syntax, please see this KB article.

---

Then, you can draft a KB article that goes over this in greater detail to help clarify how this works; and perhaps show more examples that would help others understand how these can be used.

---

For instance, if I want to exclude only the home page URI, I can do that now!

^/$

---

To exclude a URI that begins with /members/, and only that specific URI:

^/members/$

---

You can also show the difference between * and **. To exclude URIs that start with /members/ and anything beneath that slug, infinitely deep:

^/members/**

Excludes: /members/, /members/jason/, /members/jason/profile/, /members/groups/a/, /members/groups/b/c/a/edit, etc.

---

To exclude /members/ and anything beneath that slug, one level deep:

^/members/$
^/members/*/$

Excludes: /members/, /members/jason/, /members/groups/; but NOT /members/groups/a/

---

To exclude any URI that simply contains /members/ in it anywhere:

/members/

---

To exclude any URI that simply contains /member/or /members/ or /member[SOMETHING]/ in it anywhere:

/member*/

Excludes: /member/, /members/, /member-groups/, /member-info/, and /member/groups/ too, because there is no ^ or $ specified.

[raamdev]

@kristineds I'm noting two more things @jaswsinc mentioned in #163 that should go in the KB Article regarding the special syntax:

• Feature/191 Step 3 #163 (comment)
• Feature/191 Step 3 #163 (comment)

[raamdev]

@jaswsinc @kristineds Hmm, it looks like this was auto-closed when I merged #163. However, the inline documentation does still need to be updated.

@kristineds Could you please open another PR that updates the inline documentation to include mention of the new syntax Jason describes above?

[jaswrks]

@raamdev writes...

@kristineds Could you please open another PR that updates the inline documentation to include mention of the new syntax Jason describes above?

@kristineds I just wanted to note that Raam's latest merge included the changes you opened this PR for. So you can just start a new feature branch called: feature/191-step-4 (based on 000000-dev) and resume your work to improve the inline documentation regarding these changes.

$ git checkout 000000-dev
$ git pull
$ git checkout -b feature/191-step-4

Whenever you create the link (in the Dashboard) which leads to the KBA that you write to help explain this new syntax, please use this redirection link. Once the article is published, Raam can update this so it points to the live KBA: http://zencache.com/r/watered-down-regex-syntax/