public interface Syntax extends Writable, Broadcastable
Syntax
objects are used to represent the individual pieces of content of the parsed CSS source, and are the primary
objects used to construct the AST (Abstract Syntax Tree). Not all Syntax
objects have content directly associated with
them. Some are used to represent the logical grouping of content, such as the Rule
.
Each unit has a particular line and column indicating where it was parsed within the source, except for dynamically created
units. You can check hasSourcePosition()
to see if a unit is dynamically created.
It's important to remember that in certain parsing configurations some high level units may be in an unrefined state.
This means that only the raw content is available (and may potentially be invalid/inappropriate). You can enforce refinement by
using AutoRefine
, custom refiners, or in other ways. See the main readme file for more information.
Modifier and Type | Method and Description |
---|---|
void |
annotate(CssAnnotation annotation)
Appends the given
CssAnnotation to this unit. |
void |
annotateUnlessPresent(CssAnnotation annotation)
Same as
annotate(CssAnnotation) , except only if hasAnnotation(CssAnnotation) is false for the given
annotation. |
Optional<CssAnnotation> |
annotation(String name)
Gets the
CssAnnotation with the given name from the comments associated with this unit, if there is one. |
List<CssAnnotation> |
annotations()
Gets all
CssAnnotation s from the comments associated with this unit. |
int |
column()
The column number within the source where this
Syntax unit was parsed. |
Syntax |
comment(Comment comment)
Adds the given
Comment to this unit. |
Syntax |
comment(String comment)
Adds the given comment to this unit.
|
com.google.common.collect.ImmutableList<Comment> |
comments()
Gets all comments associated with this
Syntax unit. |
Syntax |
comments(Collection<String> comments)
Adds the given comments to this unit.
|
Syntax |
comments(Syntax copyFrom)
Copies all comments from the given syntax unit.
|
Syntax |
copy()
Performs a deep copy of the instance.
|
boolean |
hasAnnotation(CssAnnotation annotation)
Checks if this unit has a CSS comment with a
CssAnnotation that equals the given one. |
boolean |
hasAnnotation(String name)
Checks if this unit has a CSS comment annotation with the given name.
|
boolean |
hasSourcePosition()
Gets whether this unit has a source location specified.
|
int |
id()
Gets the unique identifier for this unit.
|
int |
line()
The line number within the source where this
Syntax unit was parsed. |
com.google.common.collect.ImmutableList<Comment> |
orphanedComments()
Gets all orphaned comments (comments that appear after or at the end of the unit).
|
Syntax |
orphanedComments(Collection<String> comments)
Adds orphaned comments (comments that appears after or at the end of the unit).
|
Syntax |
orphanedComments(Syntax copyFrom)
Copies all orphaned comments from the given syntax unit.
|
String |
toString(boolean includeUnitType)
Returns a string representation of this object.
|
boolean |
writesOwnComments()
Specifies whether this object will handle writing its own comments, instead of the automatic behavior of the
StyleWriter . |
boolean |
writesOwnOrphanedComments()
Specifies whether this object will handle writing its own orphaned comments, instead of the automatic behavior of the
StyleWriter . |
isWritable, write
propagateBroadcast, shouldBreakBroadcast, status, status
int id()
int line()
Syntax
unit was parsed.int column()
Syntax
unit was parsed.boolean hasSourcePosition()
This will be true for units within the original parsed source and false for dynamically created units.
Syntax copy()
This includes any inner syntax units, for example the selectors inside of a rule. This also carries over the comments and orphaned comments.
Keep in mind that copying is generally not preferred. Particularly, it is generally better to parse the source again than
to copy a Stylesheet
. Copying a specific syntax unit may be appropriate when duplicating the terms in a declaration
or the selector parts in a selector.
String toString(boolean includeUnitType)
includeUnitType
- Specify true to append in parenthesis the syntax type (e.g., 'pseudo-element-selector').Syntax comment(String comment)
Note that in the case of Selector
s, it is preferred to add comments to the Selector
object itself instead
of the individual SimpleSelector
s inside of it. Likewise, it is preferred to add a comment to the Declaration
itself instead of the property name or value inside of it.
comment
- The comment to add.Syntax comment(Comment comment)
Comment
to this unit.
Note that in the case of Selector
s, it is preferred to add comments to the Selector
object itself instead
of the individual SimpleSelector
s inside of it. Likewise, it is preferred to add a comment to the Declaration
itself instead of the property name or value inside of it.
comment
- The comment to add.Syntax comments(Collection<String> comments)
Note that in the case of Selector
s, it is preferred to add comments to the Selector
object itself instead
of the individual SimpleSelector
s inside of it. Likewise, it is preferred to add a comment to the Declaration
itself instead of the property name or value inside of it.
comments
- The comments to add.Syntax comments(Syntax copyFrom)
copyFrom
- Copy comments from this unit.com.google.common.collect.ImmutableList<Comment> comments()
Syntax
unit.
A unit is associated with all comments that directly precede it. However in the case of comments at the start of a Rule
, the first Selector
will contain the comment, not the Rule or the SimpleSelector
. For more info, see
the main readme file.
Syntax orphanedComments(Collection<String> comments)
comments
- The comments to add.Syntax orphanedComments(Syntax copyFrom)
copyFrom
- Copy orphaned comments from this unit.com.google.common.collect.ImmutableList<Comment> orphanedComments()
A comment is considered orphaned if it does not appear before a logically associated unit. For example, comments at the end of a stylesheet or declaration block.
boolean hasAnnotation(String name)
CSS comment annotations are CSS comments that contain an annotation in the format of "@annotationName [optionalArgs]", for example "@noparse", "@browser ie7", etc...
Only one annotation per comment block is allowed.
A unit is associated with all comments that directly precede it. However in the case of comments at the start of a Rule
, the first Selector
will contain the comment, not the Rule or the SimpleSelector
. For convenience,
the Rule will check the comments on the first Selector for annotation getter methods (which includes this method).
For more info, see the main readme file.
name
- Check for an annotation with this name.CssAnnotation
was found with the given name in Comment
s associated with this unit.boolean hasAnnotation(CssAnnotation annotation)
CssAnnotation
that equals the given one.
A unit is associated with all comments that directly precede it. However in the case of comments at the start of a Rule
, the first Selector
will contain the comment, not the Rule or the SimpleSelector
. For convenience,
the Rule will check the comments on the first Selector for annotation getter methods though, including this
method. For more info, see the main readme file.
This is most useful in tangent with the annotate(CssAnnotation)
method. You can annotate many syntax units using
that method and then subsequently check for the annotation using this method, reusing the same instance in all cases for
efficiency.
The annotation must match according to the rules defined in CssAnnotation.equals(Object)
.
A unit is associated with all comments that directly precede it. However in the case of comments at the start of a Rule
, the first Selector
will contain the comment, not the Rule or the SimpleSelector
. For convenience,
the Rule will check the comments on the first Selector for annotation getter methods (which includes this method).
For more info, see the main readme file.
annotation
- Check for a CssAnnotation
that equals this one.CssAnnotation
was found that equals the given one.Optional<CssAnnotation> annotation(String name)
CssAnnotation
with the given name from the comments associated with this unit, if there is one.
CSS comment annotations are CSS comments that contain an annotation in the format of "@annotationName [optionalArgs]", for example "@noparse", "@browser ie7", etc...
Only one annotation per comment block is allowed.
A unit is associated with all comments that directly precede it. However in the case of comments at the start of a Rule
, the first Selector
will contain the comment, not the Rule or the SimpleSelector
. For convenience,
the Rule will check the comments on the first Selector for annotation getter methods (which includes this method).
For more info, see the main readme file.
name
- Get the annotation with this name.CssAnnotation
, or an empty Optional
if not found.List<CssAnnotation> annotations()
CssAnnotation
s from the comments associated with this unit.
CSS comment annotations are CSS comments that contain an annotation in the format of "@annotationName [optionalArgs]", for example "@noparse", "@browser ie7", etc...
Only one annotation per comment block is allowed.
A unit is associated with all comments that directly precede it. However in the case of comments at the start of a Rule
, the first Selector
will contain the comment, not the Rule or the SimpleSelector
. For convenience,
the Rule will check the comments on the first Selector for annotation getter methods (which includes this method).
For more info, see the main readme file.
CssAnnotation
s.void annotate(CssAnnotation annotation)
CssAnnotation
to this unit.
A Comment
will be created and appended to this unit using the normal CSS comment annotation syntax. This means if
CSS comments are written out then they will include this annotation. The comment will also be returned by normal comment
retrieval methods such as comments()
.
You can subsequently check for this annotation again using the hasAnnotation(CssAnnotation)
method. This might be
useful in plugins that dynamically annotate syntax units and then subsequently check for the annotation later on, as using
both of these methods can efficiently reuse the same CssAnnotation
instance.
annotation
- Append this annotation.void annotateUnlessPresent(CssAnnotation annotation)
annotate(CssAnnotation)
, except only if hasAnnotation(CssAnnotation)
is false for the given
annotation.
Note that if using this method on a Rule
that comments at the start of a Rule are usually associated with the
Selector
, and this method will not check the Selector when determining if the annotation is present. Thus you
should only call this method on a Rule if you are sure the annotation was manually added to the Rule.
annotation
- Add this annotation.boolean writesOwnComments()
StyleWriter
.
If returning true, be sure to check StyleWriter#shouldWriteAllComments()
to determine if comments should actually
be written out or not. The StyleWriter#appendComments(Iterable, StyleAppendable)
utility method contains this logic
and is the preferable way to handle it.
boolean writesOwnOrphanedComments()
StyleWriter
.
If returning true, be sure to check StyleWriter#shouldWriteAllComments()
to determine if comments should actually
be written out or not. The StyleWriter#appendComments(Iterable, StyleAppendable)
utility method contains this logic
and is the preferable way to handle it.
Copyright (c) 2019, Salesforce.com, Inc. All rights reserved. Licensed under the BSD 3-Clause license. For full license text, see the LICENSE file in the repository.