public final class Rule extends AbstractGroupable<StatementIterable,Statement> implements Statement
You might be looking for a "DeclarationBlock" class. Currently such a class serves no purpose, and all ordered declarations are
contained inside of a SyntaxCollection
within this class instead.
Note that if a Rule
does not have any selectors or declarations (or all of it's selectors and declarations are
detached) then the rule will not be printed out.
Comments that appear in the original CSS source "before" the rule are actually going to be added to the first Selector
instead of the rule. However, for convenience, the getter annotation-related methods will include results from the first
selector (getter methods for pure comments will not do this).
Any comments that appear after the semi-colon of the last rule are considered orphaned comments and can be retrieved via AbstractSyntax.orphanedComments()
. Note that any comments before the semi-colon (or if the last declaration does not end with a semi-colon)
are attributed as orphaned comments on the Declaration
instead.
Example of a dynamically created rule:
Rule rule = new Rule();
rule.selectors().append(new Selector(new ClassSelector("class")));
rule.selectors().append(new Selector(new IdSelector("id")));
rule.declarations().append(new Declaration(Property.DISPLAY, KeywordValue.of(Keyword.NONE)));
rule.declarations().append(new Declaration(Property.MARGIN, NumericalValue.of(5, "px")));
Constructor and Description |
---|
Rule()
Creates a new instance with no line or number specified (used for dynamically created
Syntax units). |
Rule(int line,
int column)
Creates a new
Rule instance with the given line and column numbers. |
Modifier and Type | Method and Description |
---|---|
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. |
Rule |
copy()
For implementations: do not copy comments or orphaned comments, instead be sure to call
AbstractSyntax.copiedFrom(Syntax) on the
new copy. |
SyntaxCollection<Rule,Declaration> |
declarations()
Gets the collection of declarations for this
Rule . |
void |
destroy()
Removes this unit from its collection.
|
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 |
isWritable()
Returns whether this unit should actually be written.
|
void |
propagateBroadcast(Broadcaster broadcaster,
Status status)
Broadcasts or rebroadcasts all child units using the given
Broadcaster . |
SyntaxCollection<Rule,Selector> |
selectors()
Gets the collection of selectors for this
Rule . |
protected Rule |
self()
Should return "this".
|
void |
write(StyleWriter writer,
StyleAppendable appendable)
Outputs this
Writable 's string representation. |
boolean |
writesOwnOrphanedComments()
Specifies whether this object will handle writing its own orphaned comments, instead of the automatic behavior of the
StyleWriter . |
append, group, group, isDestroyed, isFirst, isLast, next, parent, prepend, previous, replaceWith, unlink
annotate, annotateUnlessPresent, column, comment, comment, comments, comments, comments, copiedFrom, equals, hashCode, hasSourcePosition, id, line, orphanedComments, orphanedComments, orphanedComments, shouldBreakBroadcast, status, status, toString, toString, writesOwnComments
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
append, group, group, isDestroyed, isFirst, isLast, next, parent, prepend, previous, replaceWith, unlink
annotate, annotateUnlessPresent, column, comment, comment, comments, comments, comments, hasSourcePosition, id, line, orphanedComments, orphanedComments, orphanedComments, toString, writesOwnComments
shouldBreakBroadcast, status, status
public Rule()
Syntax
units).public Rule(int line, int column)
Rule
instance with the given line and column numbers.line
- The line number.column
- The column number.public SyntaxCollection<Rule,Selector> selectors()
Rule
. You can append, prepend, etc... additional Selector
s to
this collection. New Selector
s will automatically be broadcasted.public SyntaxCollection<Rule,Declaration> declarations()
Rule
. You can append, prepend, etc... additional Declaration
s
to this collection. New Declaration
s will be automatically broadcasted.protected Rule self()
AbstractGroupable
AbstractGroupable
class.self
in class AbstractGroupable<StatementIterable,Statement>
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
hasAnnotation
in class AbstractSyntax
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
hasAnnotation
in class AbstractSyntax
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
annotation
in class AbstractSyntax
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
annotations
in class AbstractSyntax
CssAnnotation
s.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
propagateBroadcast
in class AbstractSyntax
broadcaster
- Use this Broadcaster
to broadcast all unbroadcasted child units.status
- Broadcast units that have this status.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
isWritable
in class AbstractGroupable<StatementIterable,Statement>
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
writesOwnOrphanedComments
in class AbstractSyntax
public void write(StyleWriter writer, StyleAppendable appendable) throws IOException
Writable
Writable
's string representation.
Important notes for implementation:
Do not use the StyleWriter
in an attempt to write direct content (Strings, chars, etc...). Use the StyleAppendable
.
The StyleWriter
should be used to make decisions based on writer settings (e.g., compressed vs. verbose output
mode), as well as for writing inner or child Writable
s. Do not call the this method method directly on inner
or child Writable
s! That would bypass any overrides that are set on the StyleWriter
. Use StyleWriter.writeInner(Writable, StyleAppendable)
instead.
write
in interface Writable
writer
- Writer to use for output settings and for writing inner Writable
s.appendable
- Append direct content to this StyleAppendable
.IOException
- If an I/O error occurs.public Rule copy()
AbstractSyntax
AbstractSyntax.copiedFrom(Syntax)
on the
new copy.public void destroy()
Groupable
Once removed, the unit cannot be re-added to any collection, however it can still be copied. Destroyed units will no longer be broadcasted to any subsequent plugins.
destroy
in interface Groupable<StatementIterable,Statement>
destroy
in class AbstractGroupable<StatementIterable,Statement>
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.