scspell3k


Namescspell3k JSON
Version 2.1 PyPI version JSON
download
home_pagehttps://github.com/myint/scspell
SummaryA conservative interactive spell checker for source code.
upload_time2017-01-14 16:48:20
maintainer
docs_urlNone
author
requires_python
licenseGPL 2
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI
coveralls test coverage
            scspell
=======

.. image:: https://travis-ci.org/myint/scspell.svg?branch=master
    :target: https://travis-ci.org/myint/scspell
    :alt: Build status

**scspell** is a spell checker for source code. This is an unofficial fork (of
https://launchpad.net/scspell) that runs on both Python 2 and 3.

**scspell** does not try to be particularly smart--rather, it does the simplest
thing that can possibly work:

    1. All alphanumeric strings (strings of letters, numbers, and
       underscores) are spell-checked tokens.
    2. Each token is split into one or more subtokens. Underscores and digits
       always divide tokens, and capital letters will begin new subtokens. In
       other words, ``some_variable`` and ``someVariable`` will both generate
       the subtoken list {``some``, ``variable``}.
    3. All subtokens longer than three characters are matched against a set of
       dictionaries, and a match failure prompts the user for action. When
       matching against the included English dictionary, *prefix matching* is
       employed; this choice permits the use of truncated words like ``dict``
       as valid subtokens.

When applied to code written in most popular programming languages while using
typical naming conventions, this algorithm will usually catch many errors
without an annoying false positive rate.

In an effort to catch more spelling errors, **scspell** is able to check each
file against a set of dictionary words selected *specifically for that file*. Up
to three different sub-dictionaries may be searched for any given file:

    1. A natural language dictionary. (**scspell** provides an American
       English dictionary as the default.)
    2. A programming language-specific dictionary, intended to contain
       oddly-spelled keywords and APIs associated with that language.
       (**scspell** provides small default dictionaries for a number of popular
       programming languages.)
    3. A file-specific dictionary, intended to contain uncommon strings which
       are not likely to be found in more than a handful of unique files.

Usage
-----

To begin the spell checker, run ::

    $ scspell source_file1 source_file2 ...

For each spell check failure, you will see output much like this::

    filename.c:27: Unmatched 'someMispeldVaraible' -> {mispeld, varaible}

In other words, the token "``someMispeldVaraible``" was found on line 27
of ``filename.c``, and it contains subtokens "``mispeld``" and
"``varaible``" which both failed the spell-checking algorithm. You will
be prompted for an action to take:

    (i)gnore
        Skip to the next unmatched token, without taking any action.

    (I)gnore all
        Skip over this token every time it is encountered, for the
        remainder of this spell check session.

    (r)eplace
        Enter some text to use as a replacement for this token, and replace
        only the token at this point in the file.

    (R)eplace all
        Enter some text to use as a replacement for this token, and replace
        every occurrence of the token until the end of the current file.

    (a)dd to dictionary
        Add one or more tokens to one of the dictionaries (see below).

    show (c)ontext
        Print out some lines of context surrounding the unmatched token.

If you accidentally select a replacement operation, enter an empty
string to cancel.

If you select the ``(a)dd to dictionary`` option, then you will be
prompted with the following options for every subtoken:

    (b)ack
        Return to the previous menu, without taking any action.

    (i)gnore
        Skip to the next subtoken, without taking any action.

    add to (p)rogramming language dictionary
        Add this subtoken to the dictionary associated with the
        programming language of the current file. **scspell** uses the
        file extension to determine the language, so you will only
        see this option for files which have an extension.

    add to (f)ile-specific dictionary
        Add this subtoken to the dictionary associated with the
        current file. You will see this option only for files which
        have such an embedded ID or which have an entry in the file ID
        mapping.  See `Creating File IDs`_ for details.

    add to (N)ew file-specific dictionary
        Create a new file ID for the current file, record the new
        file ID in the file ID mapping, and add this subtoken to a new
        file-specific dictionary associated with that file ID.  You will
        see this option only for files which have neither an embedded ID nor
        an entry in the file ID mapping, and only if the ``--relative-to``
	option is given.  See `Creating File IDs`_ for details.

    add to (n)atural language dictionary
        Add this subtoken to the natural language dictionary.

If scspell finds no unknown tokens, it exits with exit status 0.  If
there were unknown tokens, it exits with exit status 1.  If it
terminates in response to a (handled) signal such as a SIGINT from ^C,
it exits with exit status 2.


Spell-checking Options
----------------------

--report-only\ 
 This option causes **scspell** to report to stderr a report of the
 subtokens that it considers to be in error, instead of offering the
 interactive menu described above.  For each subtoken, the report
 includes the filename, line number, and full token.  **scspell** will
 exit with an exit code of 1 if any errors are found, or 0 if the run
 was clean.

 The format of the reported errors is different than the interactive
 mode reports them.  With ``--report-only``, the above one would appear
 like this::

    filename.c:27: 'mispeld', 'varaible' were not found in the dictionary (from token 'someMispeldVaraible')


--no-c-escapes\ 
 By default, **scspell** treats files as if they contain C-style
 character escapes.  That is, given ``printf("Hello\nworld.")``, it will
 consider the tokens "``hello``" and "``world``", not "``nworld``".

 The ``--no-c-escapes`` option causes **scspell** to not treat ``\`` as a
 special character, for e.g. LaTeX files where you might write
 ``\Alpha\beta\gamma\delta``.  Without this option, **scspell** would
 see the tokens "``lpha``", "``eta``", "``amma``", and "``elta``".


Creating File IDs
-----------------

If you would like **scspell** to be able to uniquely identify a file,
thus enabling the creation of a file-specific dictionary, then
**scspell** must be able to find a file ID to identify both the file
an the file-specific dictionary.  There are two ways **scspell** can
find the file ID:

1. The file ID may be embedded directly in the file, using a string of
   the following form::

      scspell-id: <unique ID>

2. An entry in the file ID mapping file ties a filename to a file ID.

The unique ID must consist only of letters, numbers, underscores, and dashes.
**scspell** can generate suitable unique ID strings using the ``--gen-id`` option::

    $ scspell --gen-id
    scspell-id: e497803c-523a-11de-ae42-0017f2ee0f37

(Most likely you will want to place a file's unique ID inside a source code comment.)

During interactive use, the ``(a)dd to dictionary`` -> ``add to (N)ew
file-specific dictionary`` option will create a new File ID for the
current file, and add it to the file ID mapping file.


--relative-to RELATIVE_TO\ 
 The filenames stored in the file ID mapping are relative paths.  This
 option specifies what they're relative to.  If this option is not
 specified, the file ID mapping will not be consulted, and the ``add to (N)ew
 file-specific dictionary`` option will not be offered.



Managing File IDs
-----------------

These options direct **scspell** to manipulate the file ID mapping.
(These can all be accomplished by editing the file ID mapping
manually).  These have no effect on file IDs embedded in files.

--rename-file FROM_FILE TO_FILE
   Changes the filename that a File ID maps to.  After renaming a file
   that has a file-specific dictionary and an entry in the file ID
   mapping, you can use this option to have the entry "follow" the file.

--delete-files\ 
   Remove filenames from the file ID mapping.  If it was the only
   filename for a given File ID, removes the File ID from the mapping and
   its wordlist from the dictionary.

--merge-file-ids FROM_ID TO_ID
  Combines the file-specific dictionaries referenced by the two File
  IDs.  All words from FROM_IDs list are moved to TO_IDs.  The FROM_ID
  File ID is removed from the mapping, and any files using it are
  changed to use TO_ID.  Either FROM_ID or TO_ID may be given as a filename
  instead, in which case that file's File ID is used for that parameter.


Sharing a Dictionary
--------------------

A team of developers working on the same source tree may wish to share a common
dictionary. You can permanently set the location of a shared dictionary by
executing ::

    $ scspell --set-dictionary=/path/to/dictionary_file.txt

The dictionary is formatted as a simple newline-separated list of words, so it
can easily be managed by a version control system if desired.

The current dictionary can be saved to a file by executing ::

    $ scspell --export-dictionary=/path/to/output_file.txt

You can also override the dictionary location for a single spell check session,
by using the ``--override-dictionary`` option::

    $ scspell --override-dictionary=/path/to/dictionary_file.txt source_file1 ...

--base-dict BASE_DICT\
   A *base dictionary* is consulted for its words, but is not modified
   at runtime.  By using

    $ scspell --base-dict ~/.dict --override-dictionary proj/.dict source...

   words added at runtime will be added to ``proj/.dict``, and
   ``~/.dict`` will be left alone.  This way ``proj/.dict`` may be
   limited only to the words added for ``proj/``.  This may be more
   convenient when ``proj/.dict`` is committed to source control and
   shared by many users.

--use-builtin-base-dict\
   Use the dictionary file shipped with scspell as a base dictionary.

--filter-out-base-dicts\
   Read the dictionary specified by the normal dictionary selection
   options, called the ``project dict`` here.  Read the base
   dictionaries specified by the base-dict options.  Remove from the
   project dict all the words from the base dicts, and write the
   project dict back out.

   This may be useful when a project dict has been generated with an
   older version of **scspell** that did not support base dicts.


Installation
------------

Install **scspell** via pip::

    $ pip install scspell3k

Alternatively, download and unpack the source archive, switch to the
archive root directory, and run the installation script::

    $ python setup.py install

On a UNIX-like system, you may need to use ``sudo`` if installing to a
directory that requires root privileges::

    $ sudo python setup.py install

License
-------

**scspell** is Free Software, licensed under Version 2 of the GNU General
Public License; see ``COPYING.txt`` for details.

The English dictionary distributed with scspell is derived from the
`SCOWL word lists <http://wordlist.sourceforge.net>`_ . See
``SCOWL-LICENSE.txt`` for the myriad licenses that apply to that dictionary.
            

Raw data

            {
    "_id": null,
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "cheesecake_code_kwalitee_id": null,
    "keywords": "",
    "upload_time": "2017-01-14 16:48:20",
    "author": "",
    "home_page": "https://github.com/myint/scspell",
    "github_user": "myint",
    "download_url": "https://pypi.python.org/packages/fe/0a/38e98cce6114542c7b2ef887767c2f9a0bff031a3f21e14927be1fbc2203/scspell3k-2.1.tar.gz",
    "platform": "any",
    "version": "2.1",
    "cheesecake_documentation_id": null,
    "description": "scspell\n=======\n\n.. image:: https://travis-ci.org/myint/scspell.svg?branch=master\n    :target: https://travis-ci.org/myint/scspell\n    :alt: Build status\n\n**scspell** is a spell checker for source code. This is an unofficial fork (of\nhttps://launchpad.net/scspell) that runs on both Python 2 and 3.\n\n**scspell** does not try to be particularly smart--rather, it does the simplest\nthing that can possibly work:\n\n    1. All alphanumeric strings (strings of letters, numbers, and\n       underscores) are spell-checked tokens.\n    2. Each token is split into one or more subtokens. Underscores and digits\n       always divide tokens, and capital letters will begin new subtokens. In\n       other words, ``some_variable`` and ``someVariable`` will both generate\n       the subtoken list {``some``, ``variable``}.\n    3. All subtokens longer than three characters are matched against a set of\n       dictionaries, and a match failure prompts the user for action. When\n       matching against the included English dictionary, *prefix matching* is\n       employed; this choice permits the use of truncated words like ``dict``\n       as valid subtokens.\n\nWhen applied to code written in most popular programming languages while using\ntypical naming conventions, this algorithm will usually catch many errors\nwithout an annoying false positive rate.\n\nIn an effort to catch more spelling errors, **scspell** is able to check each\nfile against a set of dictionary words selected *specifically for that file*. Up\nto three different sub-dictionaries may be searched for any given file:\n\n    1. A natural language dictionary. (**scspell** provides an American\n       English dictionary as the default.)\n    2. A programming language-specific dictionary, intended to contain\n       oddly-spelled keywords and APIs associated with that language.\n       (**scspell** provides small default dictionaries for a number of popular\n       programming languages.)\n    3. A file-specific dictionary, intended to contain uncommon strings which\n       are not likely to be found in more than a handful of unique files.\n\nUsage\n-----\n\nTo begin the spell checker, run ::\n\n    $ scspell source_file1 source_file2 ...\n\nFor each spell check failure, you will see output much like this::\n\n    filename.c:27: Unmatched 'someMispeldVaraible' -> {mispeld, varaible}\n\nIn other words, the token \"``someMispeldVaraible``\" was found on line 27\nof ``filename.c``, and it contains subtokens \"``mispeld``\" and\n\"``varaible``\" which both failed the spell-checking algorithm. You will\nbe prompted for an action to take:\n\n    (i)gnore\n        Skip to the next unmatched token, without taking any action.\n\n    (I)gnore all\n        Skip over this token every time it is encountered, for the\n        remainder of this spell check session.\n\n    (r)eplace\n        Enter some text to use as a replacement for this token, and replace\n        only the token at this point in the file.\n\n    (R)eplace all\n        Enter some text to use as a replacement for this token, and replace\n        every occurrence of the token until the end of the current file.\n\n    (a)dd to dictionary\n        Add one or more tokens to one of the dictionaries (see below).\n\n    show (c)ontext\n        Print out some lines of context surrounding the unmatched token.\n\nIf you accidentally select a replacement operation, enter an empty\nstring to cancel.\n\nIf you select the ``(a)dd to dictionary`` option, then you will be\nprompted with the following options for every subtoken:\n\n    (b)ack\n        Return to the previous menu, without taking any action.\n\n    (i)gnore\n        Skip to the next subtoken, without taking any action.\n\n    add to (p)rogramming language dictionary\n        Add this subtoken to the dictionary associated with the\n        programming language of the current file. **scspell** uses the\n        file extension to determine the language, so you will only\n        see this option for files which have an extension.\n\n    add to (f)ile-specific dictionary\n        Add this subtoken to the dictionary associated with the\n        current file. You will see this option only for files which\n        have such an embedded ID or which have an entry in the file ID\n        mapping.  See `Creating File IDs`_ for details.\n\n    add to (N)ew file-specific dictionary\n        Create a new file ID for the current file, record the new\n        file ID in the file ID mapping, and add this subtoken to a new\n        file-specific dictionary associated with that file ID.  You will\n        see this option only for files which have neither an embedded ID nor\n        an entry in the file ID mapping, and only if the ``--relative-to``\n\toption is given.  See `Creating File IDs`_ for details.\n\n    add to (n)atural language dictionary\n        Add this subtoken to the natural language dictionary.\n\nIf scspell finds no unknown tokens, it exits with exit status 0.  If\nthere were unknown tokens, it exits with exit status 1.  If it\nterminates in response to a (handled) signal such as a SIGINT from ^C,\nit exits with exit status 2.\n\n\nSpell-checking Options\n----------------------\n\n--report-only\\ \n This option causes **scspell** to report to stderr a report of the\n subtokens that it considers to be in error, instead of offering the\n interactive menu described above.  For each subtoken, the report\n includes the filename, line number, and full token.  **scspell** will\n exit with an exit code of 1 if any errors are found, or 0 if the run\n was clean.\n\n The format of the reported errors is different than the interactive\n mode reports them.  With ``--report-only``, the above one would appear\n like this::\n\n    filename.c:27: 'mispeld', 'varaible' were not found in the dictionary (from token 'someMispeldVaraible')\n\n\n--no-c-escapes\\ \n By default, **scspell** treats files as if they contain C-style\n character escapes.  That is, given ``printf(\"Hello\\nworld.\")``, it will\n consider the tokens \"``hello``\" and \"``world``\", not \"``nworld``\".\n\n The ``--no-c-escapes`` option causes **scspell** to not treat ``\\`` as a\n special character, for e.g. LaTeX files where you might write\n ``\\Alpha\\beta\\gamma\\delta``.  Without this option, **scspell** would\n see the tokens \"``lpha``\", \"``eta``\", \"``amma``\", and \"``elta``\".\n\n\nCreating File IDs\n-----------------\n\nIf you would like **scspell** to be able to uniquely identify a file,\nthus enabling the creation of a file-specific dictionary, then\n**scspell** must be able to find a file ID to identify both the file\nan the file-specific dictionary.  There are two ways **scspell** can\nfind the file ID:\n\n1. The file ID may be embedded directly in the file, using a string of\n   the following form::\n\n      scspell-id: <unique ID>\n\n2. An entry in the file ID mapping file ties a filename to a file ID.\n\nThe unique ID must consist only of letters, numbers, underscores, and dashes.\n**scspell** can generate suitable unique ID strings using the ``--gen-id`` option::\n\n    $ scspell --gen-id\n    scspell-id: e497803c-523a-11de-ae42-0017f2ee0f37\n\n(Most likely you will want to place a file's unique ID inside a source code comment.)\n\nDuring interactive use, the ``(a)dd to dictionary`` -> ``add to (N)ew\nfile-specific dictionary`` option will create a new File ID for the\ncurrent file, and add it to the file ID mapping file.\n\n\n--relative-to RELATIVE_TO\\ \n The filenames stored in the file ID mapping are relative paths.  This\n option specifies what they're relative to.  If this option is not\n specified, the file ID mapping will not be consulted, and the ``add to (N)ew\n file-specific dictionary`` option will not be offered.\n\n\n\nManaging File IDs\n-----------------\n\nThese options direct **scspell** to manipulate the file ID mapping.\n(These can all be accomplished by editing the file ID mapping\nmanually).  These have no effect on file IDs embedded in files.\n\n--rename-file FROM_FILE TO_FILE\n   Changes the filename that a File ID maps to.  After renaming a file\n   that has a file-specific dictionary and an entry in the file ID\n   mapping, you can use this option to have the entry \"follow\" the file.\n\n--delete-files\\ \n   Remove filenames from the file ID mapping.  If it was the only\n   filename for a given File ID, removes the File ID from the mapping and\n   its wordlist from the dictionary.\n\n--merge-file-ids FROM_ID TO_ID\n  Combines the file-specific dictionaries referenced by the two File\n  IDs.  All words from FROM_IDs list are moved to TO_IDs.  The FROM_ID\n  File ID is removed from the mapping, and any files using it are\n  changed to use TO_ID.  Either FROM_ID or TO_ID may be given as a filename\n  instead, in which case that file's File ID is used for that parameter.\n\n\nSharing a Dictionary\n--------------------\n\nA team of developers working on the same source tree may wish to share a common\ndictionary. You can permanently set the location of a shared dictionary by\nexecuting ::\n\n    $ scspell --set-dictionary=/path/to/dictionary_file.txt\n\nThe dictionary is formatted as a simple newline-separated list of words, so it\ncan easily be managed by a version control system if desired.\n\nThe current dictionary can be saved to a file by executing ::\n\n    $ scspell --export-dictionary=/path/to/output_file.txt\n\nYou can also override the dictionary location for a single spell check session,\nby using the ``--override-dictionary`` option::\n\n    $ scspell --override-dictionary=/path/to/dictionary_file.txt source_file1 ...\n\n--base-dict BASE_DICT\\\n   A *base dictionary* is consulted for its words, but is not modified\n   at runtime.  By using\n\n    $ scspell --base-dict ~/.dict --override-dictionary proj/.dict source...\n\n   words added at runtime will be added to ``proj/.dict``, and\n   ``~/.dict`` will be left alone.  This way ``proj/.dict`` may be\n   limited only to the words added for ``proj/``.  This may be more\n   convenient when ``proj/.dict`` is committed to source control and\n   shared by many users.\n\n--use-builtin-base-dict\\\n   Use the dictionary file shipped with scspell as a base dictionary.\n\n--filter-out-base-dicts\\\n   Read the dictionary specified by the normal dictionary selection\n   options, called the ``project dict`` here.  Read the base\n   dictionaries specified by the base-dict options.  Remove from the\n   project dict all the words from the base dicts, and write the\n   project dict back out.\n\n   This may be useful when a project dict has been generated with an\n   older version of **scspell** that did not support base dicts.\n\n\nInstallation\n------------\n\nInstall **scspell** via pip::\n\n    $ pip install scspell3k\n\nAlternatively, download and unpack the source archive, switch to the\narchive root directory, and run the installation script::\n\n    $ python setup.py install\n\nOn a UNIX-like system, you may need to use ``sudo`` if installing to a\ndirectory that requires root privileges::\n\n    $ sudo python setup.py install\n\nLicense\n-------\n\n**scspell** is Free Software, licensed under Version 2 of the GNU General\nPublic License; see ``COPYING.txt`` for details.\n\nThe English dictionary distributed with scspell is derived from the\n`SCOWL word lists <http://wordlist.sourceforge.net>`_ . See\n``SCOWL-LICENSE.txt`` for the myriad licenses that apply to that dictionary.",
    "tox": true,
    "lcname": "scspell3k",
    "name": "scspell3k",
    "github": true,
    "bugtrack_url": null,
    "license": "GPL 2",
    "travis_ci": true,
    "github_project": "scspell",
    "summary": "A conservative interactive spell checker for source code.",
    "split_keywords": [],
    "author_email": "",
    "urls": [
        {
            "has_sig": false,
            "upload_time": "2017-01-14T16:48:20",
            "comment_text": "",
            "python_version": "source",
            "url": "https://pypi.python.org/packages/fe/0a/38e98cce6114542c7b2ef887767c2f9a0bff031a3f21e14927be1fbc2203/scspell3k-2.1.tar.gz",
            "md5_digest": "f03ad0aab9c8dfce17adc4b0aabe766e",
            "downloads": 0,
            "filename": "scspell3k-2.1.tar.gz",
            "packagetype": "sdist",
            "path": "fe/0a/38e98cce6114542c7b2ef887767c2f9a0bff031a3f21e14927be1fbc2203/scspell3k-2.1.tar.gz",
            "size": 272336
        }
    ],
    "cheesecake_installability_id": null,
    "coveralls": true
}
        
Elapsed time: 0.02844s