一般用法
该插件的使用简单明了,但非常灵活。将提供的注释集添加到您的项目并开始使用它们,将插件配置为使用自定义注释集或简单地使用 UI 配置使 PhpStorm 了解例如 String 参数Pattern.compile()
应该被视为正则表达式。
使用注释
IntelliLang 使用三个基本注释@Language
:@Pattern
和@Subst
.
@Language
负责语言注入功能。@Pattern
用于根据特定的正则表达式模式验证字符串。@Subst
用于用固定值替换非编译时常量表达式。这允许您验证模式并构建注入语言的前缀/后缀(见下文),即使对于已知在运行时包含某些类型的值的非常量表达式也是如此。
IntelliLang 提供的注释位于文件annotations.jar中,该文件可在%product_home%/plugins/IntelliLang/lib中找到。
@语言
@Language
注解可用于对String字段、局部变量、方法参数和返回String的方法进行注解。这将导致分配给字段/变量、作为参数传递或用作方法的返回值的字符串文字被解释为指定的语言。
此外,当分配字段/变量或从方法返回值时,语言不匹配检查会检查预期语言与实际语言之间的冲突。
该插件支持直接和间接注释,即您可以像这样直接使用注释:
或像这样注释另一个注释类:
然后可以简单地用于将元素注释为@XPath
.
language-id
获取必须作为注释的 value 属性提供的 非常容易:IntelliLang 通过常规代码完成操作提供可用语言的列表。只需从 ctrl-space 弹出窗口中选择适当的语言:
@图案
@Pattern
注释负责标记必须符合某个正则表达式的字符串,并且可以以与注释相同的方式使用@Language
。这意味着,可以创建派生注释,例如@Number
要求字符串由一个或多个数字组成的注释:
事实上,预定义的注解已经包含两个这样的派生注解:第一个,@PrintFormat
,匹配使用的类似 printf 的模式java.util.Formatter
,另一个,@Identifier
,描述一个有效的 Java 标识符。这些无需指定任何其他模式即可使用。
@Subst
@Subst
注释用于替换不是编译时常量的引用,这使插件能够基于替换值与运行时预期值兼容的假设进行模式验证。如果值与预期的模式不匹配,插件会抱怨。
它还有助于为语言注入功能构建有效的前缀/后缀上下文(请参阅下一节)。考虑这个例子:
如果不将变量的值替换为font
值Tahoma
(实际上它在这里可能只是单个字符),注入的片段在语法上会不正确,从而导致错误是预期在“ font:
”指令之后显示的术语。
提供上下文:前缀和后缀
注释元素时,可以提供在解析语言片段时应添加/添加的前缀和后缀。这可用于提供上下文信息,即如果 JavaScript 注入的前缀是“var someContextVariable;”,PhpStorm 将知道变量someContextVariable已声明,并且在使用时不会警告它未声明。
除了手动提供前缀和后缀的能力之外,IntelliLang 还可以根据使用字符串文字的上下文动态确定这些值:
在此示例中,JavaScript 语言将被注入到三个 String 文字中的每一个中,并且每个人的前缀和后缀都将根据前后表达式计算,以便解析的结果文本是有效的 JavaScript 语法:
不会显示“缺少'}'”错误:右大括号是第一个文字后缀的一部分。
x
将声明使用的变量doSomethingElse(a);
:它的声明是第二个文字前缀的一部分。该函数
doSomethingElse()
也将是已知的:它在静态提供的前缀中定义。
重要笔记
PhpStorm 语言注入 API 存在一些问题,这些问题对注入的语言片段的前缀/后缀施加了某些限制。例如,不允许语言的标记跨越元素的前缀/后缀。例如,如果前缀以空格字符结尾并且片段以空格开头,则可能会发生这种情况。
该插件通过修剪前缀/后缀并恰好插入一个空格字符作为分隔符来处理这种特殊情况。但是,如果空格字符不是标记分隔符,这将不起作用,例如适用于 JavaScript 字符串文字。
这种情况无法自动处理,PhpStorm 核心会产生断言。
尽管动态前缀/后缀计算为语言片段提供了适当的上下文,但有些事情可能无法按预期工作。最值得注意的是重构(重命名)和导航功能。