Readme no docker & allow using platform default version (#66)

* readme about docker-less usage & tidy config file

* change punctuation a bit

* proofreading example

* add example of multi-lined CLI args

* more proofreading

* add macos-latest details

* final proofreading

* update pylintrc; allow version to be blank

* revert docker's default version

* pleasing pylint

* force operator resolution order

Author: 2bndy5

.pylintrc

@@ -52,7 +52,7 @@ confidence=
 # no Warning level messages displayed, use"--disable=all --enable=classes
 # --disable=W"
 # disable=print-statement,parameter-unpacking,unpacking-in-except,backtick,long-suffix,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,bad-whitespace
-disable=invalid-sequence-index,anomalous-backslash-in-string,print-statement,too-few-public-methods,consider-using-f-string,subprocess-run-check
+disable=invalid-sequence-index,anomalous-backslash-in-string,too-few-public-methods,consider-using-f-string,subprocess-run-check
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option
@@ -222,12 +222,6 @@ max-line-length=88
 # Maximum number of lines in a module
 max-module-lines=1000
 
-# List of optional constructs for which whitespace checking is disabled. `dict-
-# separator` is used to allow tabulation in dicts, etc.: {1  : 1,\n222: 2}.
-# `trailing-comma` allows a space between comma and closing bracket: (a, ).
-# `empty-line` allows space-only lines.
-no-space-check=trailing-comma,dict-separator
-
 # Allow the body of a class to be on the same line as the declaration if body
 # contains single statement.
 single-line-class-stmt=no
@@ -254,48 +248,29 @@ min-similarity-lines=4
 
 [BASIC]
 
-# Naming hint for argument names
-argument-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
 # Regular expression matching correct argument names
 argument-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
 
-# Naming hint for attribute names
-attr-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
 # Regular expression matching correct attribute names
 attr-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
 
 # Bad variable names which should always be refused, separated by a comma
 bad-names=foo,bar,baz,toto,tutu,tata
 
-# Naming hint for class attribute names
-class-attribute-name-hint=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
-
 # Regular expression matching correct class attribute names
 class-attribute-rgx=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
 
-# Naming hint for class names
-# class-name-hint=[A-Z_][a-zA-Z0-9]+$
-class-name-hint=[A-Z_][a-zA-Z0-9_]+$
-
 # Regular expression matching correct class names
 # class-rgx=[A-Z_][a-zA-Z0-9]+$
 class-rgx=[A-Z_][a-zA-Z0-9_]+$
 
-# Naming hint for constant names
-const-name-hint=(([A-Z_][A-Z0-9_]*)|(__.*__))$
-
 # Regular expression matching correct constant names
 const-rgx=(([A-Z_][A-Z0-9_]*)|(__.*__))$
 
 # Minimum line length for functions/classes that require docstrings, shorter
 # ones are exempt.
 docstring-min-length=-1
 
-# Naming hint for function names
-function-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
 # Regular expression matching correct function names
 function-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
 
@@ -306,21 +281,12 @@ good-names=r,g,b,w,i,j,k,n,x,y,z,ex,ok,Run,_
 # Include a hint for the correct naming format with invalid-name
 include-naming-hint=no
 
-# Naming hint for inline iteration names
-inlinevar-name-hint=[A-Za-z_][A-Za-z0-9_]*$
-
 # Regular expression matching correct inline iteration names
 inlinevar-rgx=[A-Za-z_][A-Za-z0-9_]*$
 
-# Naming hint for method names
-method-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
 # Regular expression matching correct method names
 method-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
 
-# Naming hint for module names
-module-name-hint=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
-
 # Regular expression matching correct module names
 module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
 
@@ -336,9 +302,6 @@ no-docstring-rgx=^_
 # to this list to register other decorators that produce valid properties.
 property-classes=abc.abstractproperty
 
-# Naming hint for variable names
-variable-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
 # Regular expression matching correct variable names
 variable-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
 

README.md

@@ -66,6 +66,7 @@ jobs:
 
 - **Description**: Comma-separated list of globs with optional '-' prefix. Globs are processed in order of appearance in the list. Globs without '-' prefix add checks with matching names to the set, globs with the '-' prefix remove checks with matching names from the set of enabled checks. This option's value is appended to the value of the 'Checks' option in a .clang-tidy file (if any).
     - It is possible to disable clang-tidy entirely by setting this option to '-\*'. This allows using only clang-format to lint your source files.
+    - It is also possible to rely solely on a .clang-tidy config file by specifying this option as a blank string ('').
 - Default: 'boost-\*,bugprone-\*,performance-\*,readability-\*,portability-\*,modernize-\*,clang-analyzer-\*,cppcoreguidelines-\*'
 
 #### `repo-root`
@@ -76,6 +77,7 @@ jobs:
 #### `version`
 
 - **Description**: The desired version of the [clang-tools](https://hub.docker.com/r/xianpengshen/clang-tools) to use. Accepted options are strings which can be 14, 13, 12, 11, 10, 9, or 8.
+    - Set this option to a blank string ('') to use the platform's default installed version.
 - Default: '10'
 
 #### `verbosity`
@@ -132,11 +134,25 @@ jobs:
 
 This action creates 1 output variable named `checks-failed`. Even if the linting checks fail for source files this action will still pass, but users' CI workflows can use this action's output to exit the workflow early if that is desired.
 
-## Using a Windows-based runner
+## Running without the docker container
 
-This action can only be run on a runner using the Ubuntu Operating System. However, this action's source code (essentially a python package) can be used on a runner using the Windows Operating System.
+Some Continuous Integration environments require access to non-default compilers
+and/or non-standard libraries. To do this properly, the docker container should
+not be used due to it's isolated file system. Instead, you should use this action's
+python source code as an installed python package (see below).
 
-Note: MacOS-based runners have not been tested, but the same approach applies.
+### Using the python source code
+
+This action was originally designed to only be used on a runner with the Ubuntu
+Operating System. However, this action's source code (essentially a python package)
+can be used on any runner using the Windows, Ubuntu, or possibly even MacOS (untested)
+virtual environments.
+
+Note, some runners already ship with clang-format and/or clang-tidy. As of this writing, the following versions of clang-format and clang-tidy are already available:
+
+- `ubuntu-latest` ships with v10, v11, and v12. [More details](https://github.com/actions/virtual-environments/blob/ubuntu20/20220508.1/images/linux/Ubuntu2004-Readme.md).
+- `windows-latest` ships with v13. [More details](https://github.com/actions/virtual-environments/blob/win22/20220511.2/images/win/Windows2022-Readme.md).
+- `macos-latest` ships with v13. [More details](https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11-Readme.md).
 
 This example makes use of another action
 ([KyleMayes/install-llvm-action](https://github.com/KyleMayes/install-llvm-action))
@@ -156,22 +172,27 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v3
 
+      # this step can be skipped if the desired
+      # version already comes with the runner's OS
       - name: Install clang-tools
         uses: KyleMayes/install-llvm-action@v1
         with:
-          # v12 is the recommended minimum for the Visual Studio compiler
-          version: 12
-          # specifying an install path is required because
-          # Windows runners already have a certain version of LLVM installed
+          # v12 is the recommended minimum for the Visual Studio compiler (on Windows)
+          version: 14
+          # specifying an install path is required (on Windows) because installing
+          # multiple versions on Windows runners needs non-default install paths.
           directory: ${{ runner.temp }}/llvm
 
       - name: Install linter python package
         run: python3 -m pip install git+https://github.com/cpp-linter/cpp-linter-action@v1
 
       - name: run linter as a python package
         id: linter
-        # pass the installed path to the '--version' argument
-        run: cpp-linter --version=${{ runner.temp }}/llvm
+        # pass the installed path to the '--version' argument (Windows only).
+        # Any other OS-based runners only take the version number.
+        #     Example. run: cpp-linter --version=14
+        # Omit the version option if using the default version available in the OS.
+        run: cpp-linter --version=${{ runner.temp }}/llvm 
 
       - name: Fail fast?!
         if: steps.linter.outputs.checks-failed > 0
@@ -180,7 +201,31 @@ jobs:
         # run: exit 1
 ```
 
-All input options listed above are specified by pre-pending a `--`. You can also install this repo locally and run `cpp-linter -h` for more detail.
+All input options listed above are specified by pre-pending a `--`. You can also install this repo locally and run `cpp-linter -h` for more detail. For example:
+
+```yaml
+      - uses: cpp-linter/cpp-linter-action@v1
+        with:
+          style: file
+          tidy-checks: '-*'
+          files-changed-only: false
+          ignore: 'dist/third-party-lib'
+```
+
+is equivalent to
+
+```yaml
+      - name: Install linter python package
+        run: python3 -m pip install git+https://github.com/cpp-linter/cpp-linter-action@v1
+
+      - name: run linter as a python package
+        run: |
+          cpp-linter \
+          --style=file \
+          --tidy-checks='-*' \
+          --files-changed-only=false \
+          --ignore='dist/third-party-lib'
+```
 
 ## Example
 

cpp_linter/run.py

@@ -82,7 +82,7 @@
 cli_arg_parser.add_argument(
     "-V",
     "--version",
-    default="10",
+    default="",
     help="The desired version of the clang tools to use. Accepted options are strings "
     "which can be 8, 9, 10, 11, 12, 13, 14. Defaults to %(default)s. On Windows, this "
     "can also be a path to the install location of LLVM",
@@ -403,18 +403,17 @@ def run_clang_tidy(
         # clear the clang-tidy output file and exit function
         with open("clang_tidy_report.txt", "wb") as f_out:
             return
-    cmds = [f"clang-tidy-{version}"]
-    if sys.platform.startswith("win32"):
-        cmds = ["clang-tidy"]
-        if os.path.exists(version + os.sep + "bin"):
-            cmds = [f"{version}\\bin\\clang-tidy.exe"]
-    elif not version.isdigit():
+    cmds = [
+        "clang-tidy" + ("" if not version else f"-{version}"),
+        "--export-fixes=clang_tidy_output.yml",
+    ]
+    if sys.platform.startswith("win32") and os.path.exists(version + os.sep + "bin"):
+        cmds[0] = f"{version + os.sep}bin\\clang-tidy.exe"
+    elif not sys.platform.startswith("win32") and not version.isdigit():
         logger.warning("ignoring invalid version number %s.", version)
-        cmds = ["clang-tidy"]
+        cmds[0] = "clang-tidy"
     if checks:
         cmds.append(f"-checks={checks}")
-    cmds.append("--export-fixes=clang_tidy_output.yml")
-    # cmds.append(f"--format-style={style}")
     if database:
         cmds.append("-p")
         if RUNNER_WORKSPACE:
@@ -459,7 +458,7 @@ def run_clang_format(
     """
     is_on_windows = sys.platform.startswith("win32")
     cmds = [
-        "clang-format" + ("" if is_on_windows else f"-{version}"),
+        "clang-format" + ("" if not version else f"-{version}"),
         f"-style={style}",
         "--output-replacements-xml",
     ]
@@ -614,7 +613,7 @@ def post_diff_comments(base_url: str, user_id: int) -> bool:
             if (
                 int(comment["user"]["id"]) == user_id
                 and comment["line"] == body["line"]
-                and comment["path"] == payload[i]["path"]
+                and comment["path"] == body["path"]
             ):
                 already_posted = True
                 if comment["body"] != body["body"]: