PyCharm 2017.3 Help

Using Language Injections

The following is only valid when IntelliLang Plugin is installed and enabled!

You can inject a language (such as HTML, CSS, XML, SQL, RegExp, etc.) into a string literal in your code and, as a result, get comprehensive coding assistance when editing that literal.

Prerequisite

For language injection features to be available, the IntelliLang plugin must be enabled. (This plugin is bundled with the IDE and enabled by default.)

Example: Injecting HTML. Opening a fragment editor

To get an impression of how language injections work:

  1. In the editor, add a code fragment containing a string literal.
  2. Place the cursor within the literal (between the quotation marks).
  3. Click quick fix large or press Alt+Enter, select Inject language or reference, and then select HTML (HTML files).
  4. Type:
    <body><h1>Hello, World!</h1></body>

    When typing, note that auto-completion for HTML tags is now available. Also note how the HTML code is highlighted.

  5. Let's now open a fragment editor for the injected HTML code: press Alt+Enter and select Edit HTML Fragment.

    You can use the fragment editor as an alternative (or in addition) to editing injected string literals in the "main editor".

  6. To complete the example, let's cancel the injection: switch to the main editor, press Alt+Enter and select Un-inject Language/Reference.

    Note that the text between the quotation marks has become green which is the default color for string values. This indicates that the value in the quotation marks is now treated simply as text.

    Don't close the editor yet. Later in this topic, we'll use our code for showing other language injection features.

Accessing language injection functions

Most of the functions related to language injections are accessed through a "light bulb menu" (quick fix large or Alt+Enter).

Ways to inject a language

You can inject a language by using:

Using language injection comments

To inject a language by means of an injection comment, on a separate line preceding the one that contains the target string literal, add:

# language=<language_ID>

e.g.

# language=HTML

NOTE: The syntax of comments should be appropriate for the language that you are using. So you may want to use // language=... or -- language=... rather than # language=....

Example

  1. On the line preceding the one that contains your string literal, depending on the language, type // language=HTML or # language=HTML.
  2. Check the light bulb menu (Alt+Enter).

    The Edit HTML Fragment command is available which means that HTML has been injected into the string literal.

  3. Remove the commented line (e.g. Ctrl+Y) to come back to the previous state.

Language IDs

The language IDs, generally, are intuitive, e.g. MySQL, RegExp, XML, HTML. If not sure about the language ID, use the suggestion list for the Inject language or reference command. What precedes the opening parentheses there is the language IDs.

See also, Using language injection prefixes and suffixes.

Accessing injection settings

To access the language injection settings:

  1. Open the Settings / Preferences dialog (e.g. Ctrl+Alt+S).
  2. Go to the Language Injections page: Editor | Language Injections.

For more info, see Language Injections page.

Using language injection prefixes and suffixes

A language fragment may be combined with a prefix and a suffix which together act as a wrapper, thereby turning the fragment into a syntactically complete language unit. When editing your code, you can see the prefix and the suffix only in the fragment editor. They are not shown in the main editor.

The prefix and the suffix can be included in the injection comment as follows:

# language=<language_ID> prefix=<prefix> suffix=<suffix>

The prefix and suffix attributes are optional.

Example

In this example, we'll remove the opening and closing <body> tags from the injected code fragment and add these tags to the injection comment as the prefix and suffix.

  1. Remove the opening and closing <body> tags: e.g. place the cursor within the injected fragment, press Ctrl+Shift+Delete and select Remove Enclosing Tag body.
  2. On the line preceding the one that contains your string literal, depending on the language, type // language=HTML prefix=<body> suffix=</body> or # language=HTML prefix=<body> suffix=</body>.
  3. For the injected fragment, open the fragment editor.

    Compare the fragments shown in the main and in the fragment editors.

Last modified: 28 March 2018

See Also