Scoggle

Scoggle is a Sublime Text ¾ plugin that will allow you to toggle between production and test code. It will allow you to do this in a number of configurable ways.

Installation

Here are a few ways to install Scoggle on your system.

1. The easiest way to install Scoggle is through Package Control.

2. Git clone the Scoggle repository into your Packages directory:

   git clone git@github.com:ssanj/Scoggle.git

3. Download the latest release source code and extract it to the Packages directory.

The Packages directory is located at:

• OS X: ~/Library/Application Support/Sublime Text 3/Packages
• Linux: ~/.config/sublime-text-3/Packages

Configuration

Here is the default Scoggle.sublime-settings file:

{
    "production_srcs" :
    [
        "/src/main/scala"
    ],
    "test_srcs" :
    [
        "/src/test/scala",
    ],
    "test_suffixes" :
    [
        "Spec.scala",
        "IntSpec.scala",
        "Suite.scala",
        "Test.scala",
        "Specification.scala"
    ],
    "log" : false,
    "display_errors_in" : "dialog",
    "default_test_suffix": "Spec.scala"
}

• production_src list the production source directories to search through when switching to a production file.
• test_srcs list the test source directories to search through when switching to test file.
• test_suffixes list the suffixes to search for when switching to a test file.
• log specifies whether to turn on debug logging.
• display_errors_in specifies where to display error messages. By default these are shown in a modal dialog (“dialog”) but this can get annoying. To overcome this we have another two options: “status_bar” and “dont_display”.
• default_test_suffix specifies the default test file name suffix to use when creating a test file.

The plugin settings file can be overridden on a per-project basis. The configuration is as above but it has a namespace of “Scoggle” associated with it.

Here's a sample .sublime-project file with Scoggle settings:

{
    "folders":
    [
        {
            "path": "."
        }
    ],
    "settings": {
        "Scoggle" : {
            "production_srcs" :
            [
                "/app"
            ],
            "test_srcs" :
            [
                "/test"
            ],
            "test_suffixes" :
            [
                "Spec.scala"
            ]
        }
    }
}

Note: any settings not mentioned in the project settings will be sourced from the default settings or user settings if they have been overridden.

Gotcha: remember that project settings are only active when you open the source directory as a Project through Project > Open Project... not through File > Open.

When customising settings for Windows, remember to replace forward slashes with double backslashes.

If you don't want to write your custom settings by hand you can generate a custom configuration for most settings by using scoggle-gen.

Matching Strategies

Scoggle comes bundled with a three main matching strategies. You can also write your own matcher quite easily. The bundled matchers go from very specific matches to more fuzzy matches.

Prefix Suffix

[CMD + SHIFT + E]

The production source filename is used in conjunction with the supplied test_suffixes to find matching test sources.

The test source filename is used minus the largest matching test_suffixes to find the matching production sources.

Example:

Given a production file named Contrast.scala in one of the production_srcs paths, test_suffixes of [“Spec.scala”, “Suite.scala”, “IntSpec.scala”] it will match the following test files in one of the test_srcs paths:

• Contrast Spec.scala
• Contrast Suite.scala
• Contrast IntSpec.scala

When toggling from the test source back to the production source, it does the following:

1. Removes the largest matching suffix from the test filename.
2. Searches the production_srcs for a filename that matches (1)

Example:

Given a test file named ContrastIntSpec.scala in one of the test_srcs paths, test_suffixes of [“Spec.scala”, “Suite.scala”, “IntSpec.scala”] it will match the following production file in one of the production_srcs paths:

• Contrast.scala (Contrast IntSpec)

notice although the Spec suffix would have matched the test filename, we remove the largest matching suffix. In this case that would be IntSpec. If we had a test file named ContrastSpec.scala we would still arrive at the same matching production file: Constrast.scala. This time we would have removed Spec as the largest matching suffix.

Prefix Wildcard Suffix

[CMD + CTRL + SHIFT + E]

The production source filename is used in conjunction a wildcard and ends with the supplied test_suffixes to find matching test sources.

The test source filename is used minus the largest matching test_suffixes to find a production source that matches the start of the match.

Example:

Given a production file named Contrast.scala in one of the production_srcs paths, test_suffixes of [“Spec.scala”, “Suite.scala”, “IntSpec.scala”] it will match the following test files in one of the test_srcs paths:

• Contrast WithinSomeContext Spec.scala
• Contrast WithinAnotherContext IntSpec.scala
• Contrast ThrowingAnException Suite.scala

When toggling from the test source back to the production source, it does the following:

1. Removes the largest matching suffix from the test filename.
2. Searches the production_srcs for a filename that matches the start of (1)

Example:

Given a test file named ContrastThrowingAnExceptionSuite.scala in one of the test_srcs paths, test_suffixes of [“Spec.scala”, “Suite.scala”, “IntSpec.scala”] it will match the following production files in one of the production_srcs paths:

• Contrast.scala (Contrast ThrowingAnException Suite)
• ContrastThrowing.scala (ContrastThrowing AnException Suite)
• ContrastThrowingAn.scala (ContrastThrowingAn Exception Suite)
• ContrastThrowingAnException.scala (ContrastThrowingAnException Suite)

Wildcard Prefix Wildcard Suffix

[CMD + CTRL + SHIFT + X]

A wildcard and the production source filename is used in conjunction a wildcard and ends with the supplied test_suffixes to find matching test sources.

The test source filename is used minus the largest matching test_suffixes to find a production source that matches the any part of the match.

Example:

Given a production file named Contrast.scala in one of the production_srcs paths, test_suffixes of [“Spec.scala”, “Suite.scala”, “IntSpec.scala”] it will match the following test files in one of the test_srcs paths:

• A Contrast WithinSomeContext Spec.scala
• ABeautiful Contrast Context IntSpec.scala
• Some Contrast Context Suite.scala
• ThisCouldBeAnythingHaving Contrast InItsName Spec.scala

When toggling from the test source back to the production source, it does the following:

1. Removes the largest matching suffix from the test filename.
2. Breaks down the remain prefix into words by capitalisation. Example: ABeautifulContrastContext is broken down into [“A”, “Beautiful”, “Contrast”, “Context”].
3. Searches the production_srcs for a filename that contains a combination of words in (2) in order from the left to right. Example: matches ABeautifulContrast and Context but not AContrastContext.

Given a test file named ABeautifulContrastContextIntSpec.scala in one of the test_srcs paths, test_suffixes of [“Spec.scala”, “Suite.scala”, “IntSpec.scala”] it will match the following production files in one of the production_srcs paths:

• Contrast.scala (ABeautiful Contrast Context IntSpec)
• ABeautiful.scala (ABeautiful ContrastContext IntSpec)
• ABeautifulContrast.scala (ABeautifulContrast Context IntSpec)
• ABeautifulContrastContext.scala (ABeautifulContrastContext IntSpec)
• BeautifulContrast.scala (BeautifulContrast Context IntSpec)
• BeautifulContrastContext.scala (A BeautifulContrastContext IntSpec)
• Context.scala (ABeautifulContrast Context IntSpec)
• A.scala (A BeautifulContrastContext IntSpec)

Writing your own Matcher

Before we get into how to write your matcher, lets see how the current matchers work. Matcher shortcuts are defined in .sublime-keymap files. Taking the Prefix Suffix Matcher example:

{ "keys": ["super+shift+e"], "command": "scoggle", "args": {"matcher": "prefix_suffix_matcher"}, "context" : [{"key": "selector", "operator": "equal", "operand": "source.scala", "match_all": true}]}

Notice how the args parameter supplies a matcher argument? The matcher value maps to the matcher to use. The mapping is done like so:

1. Given a matcher of prefix_suffix_matcher, look in the matchers module directory for a python file of the same name: prefix_suffix_matcher.py.
2. Load the class within that file called PrefixSuffixMatcher. Basically convert snake_case to CamelCase. Each matcher class extends scoggle_types.BaseMatcher and provides the definition for three methods:

• constructor (_init_) - that takes in a scoggle_types.MatcherParam instance.
• matchtest_file - called from a production file when a matching test file needs to be found. Files are supplied from the paths specified in __test_srcs_.
• matchprod_file - called from a test file when a matching production file needs to be found. Files are supplied from the paths specified in __production_srcs_.

Both of the above methods are supplied a filename and it's associated path. The methods just have to return True to include the file as match or False to exclude it.

The matcher class is supplied the MatcherParam constructor parameter with the following six fields:

1. root_dir - the first matching directory in the list of production_srcs or test_srcs (Scoggle.sublime-settings) that contains the target file.
2. test_dirs - the list of test directories defined in test_srcs ((Scoggle.sublime-settings)).
3. prefix - the target file (prod or test) without an extension.
4. suffixes - the list of test suffixes defined in test_suffixes (Scoggle.sublime-settings).
5. scoggle - reference to the scoggle module.
6. logger: the logger to use for logging.

To define your own matcher:

1. Create a matcher python filed named yourmatcher_name.py within the __matchers_ module (directory).
2. Within it define a YourMatcherName class that has the following attributes:
   1. Extends the scoggle_types.BaseMatcher class
   2. A constructor that takes in a MatcherParam
   3. An override of match_test_file
   4. An override of match_prod_file
3. Add keybindings to your .sublime-keymap file with a matcher argument of your_matcher_name:

{ "keys": ["your_shortcuts"], "command": "scoggle", "args": {"matcher": "your_matcher_name"}, "context" : [{"key": "selector", "operator": "equal", "operand": "source.scala", "match_all": true}]},

If you want to add it to the command palette, then add an entry in the .sublime-commads file:

{ "caption": "Scoggle: Your matcher description", "command": "scoggle", "args": {"matcher": "your_matcher_name"} }

If you want to add it to the context menu, then add an entry in the Context.sublime-menu file:

{
    "id" : "scoggle",
    "caption" : "Scoggle: Your matcher description",
    "command" : "scoggle",
    "args": {"matcher": "your_matcher_name"}
}

To troubleshoot your matcher, turn on debug logging in your .sublime-settings or .sublime-project:

"log" : true

Open the console with (CTRL + ) to see the debug log.

In addition have a look at the existing matchers to get an idea of how everything hangs together.

Additional Functionality

Insert package

[CMD + SHIFT + G]

Inserts the package declaration at the top of a scala file. The package of the current file is derived from the production_srcs or test_srcs paths depending on which the file is on.

package your.awesome.packagename

Collapse package

[CMD + SHIFT + H]

Collapses the package declaration of the current file into sub packages, when given a prefix. The packages are inserted at the top of a scala file. The package of the current file is derived from the production_srcs or test_srcs paths depending on which the file is on.

Given a package of:

your.awesome.packagename.project.feature

and a prefix of:

your.awesome.packagename

inserts:

package your.awesome.packagename
package project
package feature

Create Test File

[CMD + CTRL + SHIFT + T]

Creates a test file in the required test sources directory matching a file in the production source directory. The name of the test file to be created can be selected by:

• Placing the cursor within a word that makes up the test file name and launching the test file creation feature (selects the word under the cursor)
• Selecting a word and launching the test file creation feature (selects the highlighted word)
• Placing the cursor within an empty line and launching the test file creation feature (selects the current file name)

In the example below, the cursor was placed within the EitherValidations object name.

If there is only a single test source directory, an input is shown with the test file name that will be created including its path. If any adjustments to the test file name need to be made, they can be made here. Notice the default_test_suffix is used to create the file name.

Pressing enter will create the path (if necessary) and the test file. The test file will have the package path and the class name included.

If a test file with the same name already exists at the path specified, you will be given an option to select a new file name.

The default test file suffix used (Spec.scala in the above example) is retrieve from the default_test_suffix key in the settings file.

Show Current Module

[CMD + CTRL + SHIFT + M]

When using a multi-module project, it can get confusing as to which module you're currently working in. Running this command from any production or test file will display the current module.