public abstract class AbstractSyntax extends Object implements Syntax
Syntax
units.Constructor and Description |
---|
AbstractSyntax()
Creates a new instance with no line or number specified (used for dynamically created
Syntax units). |
AbstractSyntax(int line,
int column)
Creates a new instance with the given line and column numbers.
|
Modifier and Type | Method and Description |
---|---|
void |
annotate(CssAnnotation annotation)
Appends the given
CssAnnotation to this unit. |
void |
annotateUnlessPresent(CssAnnotation annotation)
Same as
Syntax.annotate(CssAnnotation) , except only if Syntax.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.
|
protected <T extends Syntax> |
copiedFrom(T original)
This should be called on all copied units.
|
abstract Syntax |
copy()
For implementations: do not copy comments or orphaned comments, instead be sure to call
copiedFrom(Syntax) on the
new copy. |
boolean |
equals(Object obj) |
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.
|
int |
hashCode() |
boolean |
hasSourcePosition()
Gets whether this unit has a source location specified.
|
int |
id()
Gets the unique identifier for this unit.
|
boolean |
isWritable()
Returns whether this unit should actually be written.
|
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.
|
void |
propagateBroadcast(Broadcaster broadcaster,
Status status)
Broadcasts or rebroadcasts all child units using the given
Broadcaster . |
boolean |
shouldBreakBroadcast(SubscriptionPhase phase)
Gets whether an in-progress broadcast should be stopped.
|
Status |
status()
Gets the current broadcast status of this unit.
|
void |
status(Status status)
Sets the current broadcast status.
|
String |
toString() |
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 . |
public AbstractSyntax()
Syntax
units).public AbstractSyntax(int line, int column)
line
- The line number.column
- The column number.public int id()
Syntax
public int line()
Syntax
Syntax
unit was parsed.public int column()
Syntax
Syntax
unit was parsed.public boolean hasSourcePosition()
Syntax
This will be true for units within the original parsed source and false for dynamically created units.
hasSourcePosition
in interface Syntax
public abstract Syntax copy()
copiedFrom(Syntax)
on the
new copy.protected final <T extends Syntax> T copiedFrom(T original)
Examples:
Rule copy = new Rule().copiedFrom(original);
T
- Syntax type.original
- The original, copied unit.public Syntax comment(String comment)
Syntax
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.
public Syntax comment(Comment comment)
Syntax
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.
public Syntax comments(Collection<String> comments)
Syntax
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.
public Syntax comments(Syntax copyFrom)
Syntax
public com.google.common.collect.ImmutableList<Comment> comments()
Syntax
public Syntax orphanedComments(Collection<String> comments)
Syntax
orphanedComments
in interface Syntax
comments
- The comments to add.public Syntax orphanedComments(Syntax copyFrom)
Syntax
orphanedComments
in interface Syntax
copyFrom
- Copy orphaned comments from this unit.public com.google.common.collect.ImmutableList<Comment> orphanedComments()
Syntax
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.
orphanedComments
in interface Syntax
public boolean hasAnnotation(String name)
Syntax
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.
hasAnnotation
in interface Syntax
name
- Check for an annotation with this name.CssAnnotation
was found with the given name in Comment
s associated with this unit.public boolean hasAnnotation(CssAnnotation annotation)
Syntax
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 Syntax.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.
hasAnnotation
in interface Syntax
annotation
- Check for a CssAnnotation
that equals this one.CssAnnotation
was found that equals the given one.public Optional<CssAnnotation> annotation(String name)
Syntax
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.
annotation
in interface Syntax
name
- Get the annotation with this name.CssAnnotation
, or an empty Optional
if not found.public List<CssAnnotation> annotations()
Syntax
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.
annotations
in interface Syntax
CssAnnotation
s.public void annotate(CssAnnotation annotation)
Syntax
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 Syntax.comments()
.
You can subsequently check for this annotation again using the Syntax.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.
public void annotateUnlessPresent(CssAnnotation annotation)
Syntax
Syntax.annotate(CssAnnotation)
, except only if Syntax.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.
annotateUnlessPresent
in interface Syntax
annotation
- Add this annotation.public void status(Status status)
Broadcastable
status
in interface Broadcastable
status
- The new status.public Status status()
Broadcastable
This primarily determines whether this unit should be broadcasted again.
status
in interface Broadcastable
public void propagateBroadcast(Broadcaster broadcaster, Status status)
Broadcastable
Broadcaster
.
The broadcast will only occur for a unit if its Status
matches the given Status
.
Implementers should call this on child units and SyntaxCollection
s first, then use the broadcaster to broadcast
itself. All of this should be wrapped in a check to ensure the Status
matches.
propagateBroadcast
in interface Broadcastable
broadcaster
- Use this Broadcaster
to broadcast all unbroadcasted child units.status
- Broadcast units that have this status.public boolean shouldBreakBroadcast(SubscriptionPhase phase)
Broadcastable
This might be true if a change of state or conditions of the unit result in the broadcast no longer being necessary during
the given SubscriptionPhase
.
shouldBreakBroadcast
in interface Broadcastable
phase
- The current SubscriptionPhase
.public boolean isWritable()
Writable
Usually this should just return true, however some units that are detachable or otherwise potentially invalid should first check their state and respond appropriately.
isWritable
in interface Writable
public boolean writesOwnComments()
Syntax
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.
writesOwnComments
in interface Syntax
public boolean writesOwnOrphanedComments()
Syntax
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.
writesOwnOrphanedComments
in interface Syntax
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.