CSS4J User Guide
This project is an implementation of W3C's CSS Object Model API in the Java™ language, and also adds CSS support to the DOM4J package. It targets several different use cases, with functionalities from style sheet error detection to style computation.
Overview
This implementation can be used in several ways: with stand-alone style sheets, with its own DOM implementation, combined with DOM4J, or by wrapping a pre-existing DOM tree.
You can play with independent style sheets created with the createStyleSheet("title", "media")
method of the
CSSStyleSheetFactory
interface.
There are three implementations of that interface:
CSSDOMImplementation
, the native DOM implementation.DOMCSSStyleSheetFactory
for the DOM Wrapper.- If you use DOM4J, get it through
XHTMLDocumentFactory.getStyleSheetFactory()
.
The document back-end is only important if you plan to use the sheets inside a document.
The resulting style sheets are empty, but you can load a style sheet with the AbstractCSSStyleSheet.parseStyleSheet(reader)
method (see Parsing a Style Sheet).
One of the most important functionalities in the library is the ability to compute styles for a given element:
In practice, to obtain the 'computed' or 'used' values required for actual rendering a box model implementation is needed, and also device information. The library provides a simple box model that could be used, but the details of the rendering device can be more difficult.Depending on the use case, the target device may not be the same one where the library is running (and some exact details hence not available).
To help in the computation, the library defines the DeviceFactory
interface to supply device and media-specific data (also provides
the objects required by media queries to work).
Modules
The library is organized in several modules:
css4j
core module, which depends on the next two:carte-util
, a very small collection of interfaces and utility classes.tokenproducer
, the low-level parser at the core of css4j.css4j-agent
, a collection of agent-related classes that makes the processing of remote documents a bit easier.css4j-awt
, a small set of AWT-related utility classes.css4j-dom4j
: to use css4j together with dom4j.xml-dtd
is a small set of classes to aid in the processing of XML DTDs, including the usefulDefaultEntityResolver
.
If you use Apache Maven, you may want to look at each module's POM files to check for the specific dependencies.
Using css4j's native DOM implementation
You can create a DOM document from scratch and use the related DOM methods to programatically build a document: just use the provided DOM implementation
(io.sf.carte.doc.dom.CSSDOMImplementation
). But if you want to parse an existing document, the procedure depends on the type of document: to parse
an XML document (including XHTML documents), you can use this library's XMLDocumentBuilder
, while to parse an HTML one (or an
XHTML document that does not use namespace prefixes) you can use the validator.nu
HTML5 parser (be sure to use the latest version from the nu.validator
Maven group id).
An example with that parser follows:
import java.io.Reader;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import io.sf.carte.doc.dom.CSSDOMImplementation;
import io.sf.carte.doc.dom.DOMElement;
import io.sf.carte.doc.dom.HTMLDocument;
import io.sf.carte.doc.style.css.CSSComputedProperties;
import io.sf.carte.doc.style.css.CSSTypedValue;
import io.sf.carte.doc.style.css.RGBAColor;
import io.sf.carte.doc.xml.dtd.DefaultEntityResolver;
import nu.validator.htmlparser.dom.HtmlDocumentBuilder;
[...]
// Instantiate DOM implementation (with default settings: no IE hacks accepted)
// and configure it
CSSDOMImplementation impl = new CSSDOMImplementation();
// Alternatively, impl = new CSSDOMImplementation(flags);
// Now load default HTML user agent sheets
impl.setDefaultHTMLUserAgentSheet();
// Prepare builder
HtmlDocumentBuilder builder = new HtmlDocumentBuilder(impl);
builder.setIgnoringComments(false);
// Read the document to parse, and prepare source object
Reader re = ... [reader for HTML document]
InputSource source = new InputSource(re);
// Parse. If the document is not HTML, you want to use DOMDocument instead
HTMLDocument document = (HTMLDocument) builder.parse(source);
re.close();
// Set document URI
document.setDocumentURI("http://www.example.com/mydocument.html");
Then you have a CSS-enabled document. To compute styles, use getComputedStyle:
DOMElement element = document.getElementById("someId");
CSSComputedProperties style = element.getComputedStyle(null);
// Next line could be 'String display = style.getDisplay();'
String display = style.getPropertyValue("display");
// If you use a factory that has been set to setLenientSystemValues(false), next
// line may throw an exception if the 'color' property was not specified.
// The default value for lenientSystemValues is TRUE.
RGBAColor color = ((CSSTypedValue) style.getPropertyCSSValue("color")).toRGBColorValue();
// Suppose that the linked style sheet located at 'css/sheet.css' declares:
// background-image: url('foo.png');
String image_css = style.getPropertyValue("background-image");
String image_uri = ((CSSTypedValue) style.getPropertyCSSValue("background-image")).getStringValue();
// Then, because we already set the document URI to "http://www.example.com/mydocument.html",
// image_css will be set to "url('http://www.example.com/css/foo.png')",
// and image_uri to "http://www.example.com/css/foo.png"
The CSSComputedProperties
interface extends W3C's CSSStyleDeclaration
for computed styles, adding methods like getComputedFontSize()
or getComputedLineHeight()
.
If you are computing styles for a specific medium, tell the document about it (see "Media Handling"):
document.setTargetMedium("print");
Conformance with the DOM specification
This library's native DOM implementation has some minor behavior differences with what is written in the DOM
Level 3 Core Specification. For example, on elements and attributes the Node.getLocalName()
method returns the tag name instead of
null
when the node was created with a DOM Level 1 method such as Document.createElement()
. Read the
io.sf.carte.doc.dom package
description for additional information.
Short example with DOM4J
To use the library with dom4j (using dom4j-like documents, elements and factory) you need the css4j-dom4j module in addition to the core module. The -dom4j module optionally depends on the -agent module, so you do not need the latter unless you plan to use the DOM4J agent.
This is the easiest way to use this package with DOM4J, using that library's SAXReader
:
Reader re = ... [reader for XHTML document]
InputSource source = new InputSource(re);
SAXReader reader = new SAXReader(XHTMLDocumentFactory.getInstance());
reader.setEntityResolver(new DefaultEntityResolver());
XHTMLDocument document = (XHTMLDocument) reader.read(source);
And once you got the element you want the computed style for (see, for example, the DOM4J Quick Start Guide), just get it with a procedure analogous to the
ViewCSS
interface:
CSSComputedProperties style = ((CSSStylableElement) element).getComputedStyle(null);
String display = style.getPropertyValue("display");
Be careful to have the XHTMLDocumentFactory
loaded with the desired defaults, like the user agent style sheet
which was loaded by default in 1.0 but not in 2.0.
It is also possible to parse an HTML5 document into a css4j-dom4j tree with the aforementioned validator.nu HTML5 parser:
XHTMLDocumentFactory factory = XHTMLDocumentFactory.getInstance();
// Next line is optional: default is TRUE, and is probably what you want
// factory.getStyleSheetFactory().setLenientSystemValues(false);
HtmlDocumentBuilder builder = new HtmlDocumentBuilder(factory);
builder.setIgnoringComments(false);
// We do not set the EntityResolver, the HtmlDocumentBuilder does not need it
Reader re = ... [reader for HTML document]
InputSource source = new InputSource(re);
XHTMLDocument document = (XHTMLDocument) builder.parse(source);
Or use a SAX parser to parse an XML document into a css4j-dom4j tree, with
XMLDocumentBuilder
instead of dom4j's SAXReader
:
XHTMLDocumentFactory factory = XHTMLDocumentFactory.getInstance();
// Next line is optional: default is TRUE, and is probably what you want
// factory.getStyleSheetFactory().setLenientSystemValues(false);
XMLDocumentBuilder builder = new XMLDocumentBuilder(factory);
builder.setEntityResolver(new DefaultEntityResolver());
Reader re = ... [reader for XML document]
InputSource source = new InputSource(re);
XHTMLDocument document = (XHTMLDocument) builder.parse(source);
re.close();
The code above uses the default JAXP SAX parser. You could use a different SAXParserFactory
:
SAXParserFactory parserFactory = ...
XMLDocumentBuilder builder = new XMLDocumentBuilder(factory, parserFactory);
Usage with the DOM wrapper
If you choose to build your document with your favorite DOM implementation instead of the CSS4J one or the DOM4J back-end, you can use the DOMCSSStyleSheetFactory.createCSSDocument(document) method to wrap a pre-existing DOM Document. Example:
DOMCSSStyleSheetFactory cssFactory = new DOMCSSStyleSheetFactory();
CSSDocument document = cssFactory.createCSSDocument(otherDOMdocument);
Unlike the native DOM or the DOM4J back-end, the DOM resulting from the DOM wrapper is read-only, although you can change the values of some nodes.
Consistency of different DOM implementations
Beware that the computed styles found by each method (native DOM, DOM4J back-end or DOM wrapper) may not be completely identical, due to differences in the underlying document DOM implementations. For example, XML-oriented DOM implementations do not implement the case sensitivity subtleties of HTML (although this library attempts to emulate the basics).
If you find a difference in styles computed from different back-ends that you believe to be a bug, please report.
Configuring the cascade
Depending on your use case, you may need to set the user agent (UA) style sheet.
The library supports two different UA sheets, one for STRICT
('standards') mode and another for QUIRKS
.
To set either of those sheets, first obtain an instance of the factory that you are using:
// Instantiate the new factory or get it from an object that you are already using.
AbstractCSSStyleSheetFactory cssFactory = ...
If you are using the DOM4J classes, you may want to do:
AbstractCSSStyleSheetFactory cssFactory = XHTMLDocumentFactory.getInstance().getStyleSheetFactory();
If you are processing HTML, css4j's default HTML5 UA sheet (based on W3C/WHATWG recommendations) should be appropriate for you:
cssFactory.setDefaultHTMLUserAgentSheet();
But if you want to set your own UA sheet, first obtain a reference to the sheet:
BaseCSSStyleSheet sheet = cssFactory.getUserAgentStyleSheet(CSSDocument.ComplianceMode.STRICT);
This is assuming the STRICT
mode, i.e. that you use documents with a DOCTYPE
, otherwise use QUIRKS
(or you may want to set both UA sheets).
If the UA sheet already contains rules (it is empty by default), clean it:
sheet.getCssRules().clear();
And now load the new sheet:
Reader reader = ... [reads the UA sheet]
sheet.parseStyleSheet(reader, CSSStyleSheet.COMMENTS_IGNORE);
reader.close();
As the UA sheet's comments are rarely of interest at the OM level, they were ignored during the parse
process (notice the COMMENTS_IGNORE
flag).
Note: this implementation does not support important
style declarations in the UA sheet.
Setting the user style sheet
There is also the possibility to set a user style sheet (with 'user' origin) via setUserStyleSheet:
Reader reader = ... [reads the user sheet]
cssFactory.setUserStyleSheet(reader);
reader.close();
Both important
and normal declarations are supported in the user style sheet.
Media handling
By default, computed styles only take into account generic styles that are common to all media. If you want to target a more specific medium,
you have to use the CSSDocument.setTargetMedium("medium")
method. For example, if your document has the following style sheets linked:
<link href="http://www.example.com/css/sheet.css" rel="stylesheet" type="text/css" />
<link href="http://www.example.com/css/sheet_for_print.css" rel="stylesheet" media="print" type="text/css" />
Computed styles will initially take into account only the "sheet.css" style sheet. However, if you execute the following method:
document.setTargetMedium("print");
Then all subsequently computed styles will account for the merged style sheet from "sheet.css" and "sheet_for_print.css".
This way to tie a document with a medium is not totally standard, as the W3C APIs would probably expect a DeviceFactory
-related object implementing the
ViewCSS
interface and referencing the document,
but this approach allows to isolate DOM logic inside DOM objects and keep the DeviceFactory
for media-specific information only.
Style sheet sets
The library supports alternative style sheets: see CSSDocument's methods enableStyleSheetsForSet, getStyleSheetSets, getSelectedStyleSheetSet and setSelectedStyleSheetSet. For example, if you have a document with these linked sheets:
<link href="http://www.example.com/commonsheet.css" rel="stylesheet" type="text/css" />
<link href="http://www.example.com/alter1.css" rel="alternate stylesheet" type="text/css" title="Alter 1" />
<link href="http://www.example.com/alter2.css" rel="alternate stylesheet" type="text/css" title="Alter 2" />
<link href="http://www.example.com/default.css" rel="stylesheet" type="text/css" title="Default" />
Initially, sheets 'alter1.css' and 'alter2.css' will not be used to compute styles. But then you can write code like the following:
String defset = document.getSelectedStyleSheetSet(); // Sets 'defset' to "Default"
document.setSelectedStyleSheetSet("Alter 1"); // Selects the set with title "Alter 1"
document.setSelectedStyleSheetSet("Alter 2"); // Selects the set with title "Alter 2"
These methods have been removed from the DOM standard unfortunately, but you can still read the specification at the CSSOM 5 December 2013 Working Draft.
Style sheet error checking
You can check for errors and warnings in the document's sheets using the non-standard getErrorHandler method. Example:
if (document.getStyleSheets().item(0).getErrorHandler().hasSacErrors())
... error processing / reporting
The merged style sheet obtained from the getStyleSheet
method has the merged error/warning state from the document's active sheets.
A typical source of errors are the non-compliant IE hacks, like prefixing property names with an asterisk (you may want to use the proper NSAC flags when creating the factory, see Compatibility with legacy browsers), or charset rules found in the wrong place.
Override styles
Override styles, that come after the author style sheet in the cascade algorithm, are not part of the formal standard
but are supported by this library; use CSSElement
's getOverrideStyle.
For example:
element.getOverrideStyle(null).setCssText("padding: 6pt;");
Override styles are defined at the DocumentCSS interface description.
Parsing a style sheet
Although document's style sheet fetching and parsing is automatic with this library (for sheets referenced from a document), it is possible to manually parse rules
from a source stream with the CSSStyleSheet.parseStyleSheet(Reader, short)
method:
Reader re = ...
sheet.parseStyleSheet(re, CSSStyleSheet.COMMENTS_AUTO);
When the second argument is COMMENTS_IGNORE
, the comments in the source stream are ignored when parsing
(see Accessing Style Sheet Comments).
The new CSS rules found in the source stream are added to the already present ones, i.e. the sheet is not reset by this method (although the error handler is), so if you want to refill a sheet you need to clear the rules before parsing:
sheet.getCssRules().clear();
Compatibility with legacy browsers
Today's style sheets often contain non-conformant styles that target specific versions of old web browsers, like Internet Explorer. Several web sites contain information about that, including:
Although it could be argued whether those hacks should be used or not, the point is that actual style sheets do contain them, so this library supports them.
By default, a factory is configured to use a flagless NSAC parser which would produce an error on any of those non-standard constructs, but a set of compatibility flags can be specified in the constructors for the factory implementations. The different flags are documented in the NSAC javadocs.
The flags available at the time of this guide's update are the following:
STARHACK
. When set, the parser will handle asterisk-prefixed property names as accepted, normal names.IEVALUES
supports values ending with\9
or\0
, as well as progid filters and IE expressions.IEPRIO
allows values ending with the'!ie'
priority hack.IEPRIOCHAR
accepts values with an'!important!'
priority hack (note the'!'
at the end).
The object model manages these compatibility values in parallel to standard ones. For example, after parsing this declaration
with IEVALUES
set:
width: 900px; width: 890px\9;
its serialization would be identical (if the flag was set correctly):
width: 900px; width: 890px\9;
but the declaration's length shall be only 1
. And computed styles only use the standard values unless there are
no alternatives (no standard value was set). The workings are similar for IEPRIO
and IEPRIOCHAR
:
width: 890px !ie;
width: 890px !important!;
with the last one being handled as of important
priority. Values created by IEPRIOCHAR
are never used
in computed styles.
Instead, declarations including asterisk-prefixed property names (created by STARHACK
) always increase the declaration's
length. For example, the length of the following declaration would be 2
:
width: 900px;
*width: 890px;
If you want to use these flags at the NSAC level (instead of the Object Model), you may want to read the 'Parser Flags' section in the
NSAC package description, as well as the documentation for the individual flags in
Parser.Flag
.
CSS style formatting
The serialization of the cssText
attribute in rules and
style declarations can be customized with an implementation
of the StyleFormattingContext interface.
You can set your StyleFormattingFactory
(which produces your customized formatting context) to the sheet factory with the CSSStyleSheetFactory.setStyleFormattingFactory
method, or subclass your style sheet factory and override the createDefaultStyleFormattingFactory method.
Look at the DefaultStyleFormattingContext class for an example of a formatting context implementation.
There is also the possibility to customize the default serialization of string values, with the CSSStyleSheetFactory.setFactoryFlag(byte) method. You can set two flags that govern which quotation you prefer, or keep the default behaviour:
- Default: Try to keep the original quotation (single or double quotes), unless the alternative is more efficient.
- STRING_DOUBLE_QUOTE: Use double quotes unless single quotes are more efficient (when the string contains more double quotes than single).
- STRING_SINGLE_QUOTE: Use single quotes unless double quotes are more efficient (when the string contains more single quotes than double).
Accessing style sheet comments
CSS style sheets often have comments, like:
/* This is a preceding comment */
p {color: blue; } /* This is a trailing comment */
(XML-style comments can also be present in a style sheet, but both NSAC and the CSSOM skip them.)
There is no standard CSSOM API for accessing comments in style sheets, but the CSSRule.getPrecedingComments()
and CSSRule.getTrailingComments()
methods are provided for that:
StringList pcomments = document.getStyleSheets().item(0).getCssRules().item(3).getPrecedingComments();
StringList tcomments = document.getStyleSheets().item(0).getCssRules().item(3).getTrailingComments();
Other API models were considered for object-model comments, like having a special type of comment rule, but stylesheet-level comments are often related to a rule and if that rule is moved or deleted, those stand-alone comments would have the potential to create a lot of confusion.
By default, comments are parsed with the COMMENTS_AUTO
mode, which should be appropriate for human-readable sheets like the one shown above. But a lot of sheets are serialized
in a way that there are no newline characters (or only a few). For these cases,
COMMENTS_PRECEDING
could be used in
parseStyleSheet(Reader,short)
,
and all the comments will be considered as belonging to the next rule. With COMMENTS_IGNORE
,
all comments found while parsing the sheet will be ignored.
The comments preceding/trailing any rule will be included in the text returned by the sheet's AbstractCSSStyleSheet.toString()
and
toStyleString()
methods,
while other comments (located at places that cannot be easily related to a rule) are lost.
In css4j version 1.0, comments that were intended to apply to the previous rule may be assigned to the next one, but this is addressed in version 2.0 where NSAC 2.0 allows a more accurate approach.
Comments in the default HTML UA style sheet are not available, as the parser is instructed to ignore them when parsing.
Create an AWT font/color from a computed style (css4j-awt module)
Once you have a computed style, on systems where AWT is available you can create an AWT font or color with the createFont
and getAWTColor
static methods in the AWTHelper
class:
CSSComputedProperties style = ...
java.awt.Font font = AWTHelper.createFont(style);
CSSTypedValue cssColor = (CSSTypedValue) style.getPropertyCSSValue("color");
java.awt.Color color = AWTHelper.getAWTColor(cssColor);
Note that the AWTHelper.getAWTColor
method can create colors from a value coming from just a style declaration (the getPropertyCSSValue
used above does not require the style to be computed).
These classes and methods belong to the css4j-awt module (the other css4j modules have no dependencies on AWT).
CSS3 support
CSS3 (defined as "all CSS after CSS2.1") is partially supported by the library; the following table summarizes the basic support for setting/retrieving the main CSS features:
| CSS3 Spec Name | Support | Observations |
|---|---|---|
| Background / Border | Yes | |
| Color | Partial | Some level 4 color functions are not implemented yet; they can be parsed and serialized, but do not convert to RGB in computed styles. |
| Media Queries | Partial | Event handling with addListener/removeListener is not supported. Relies on CSSCanvas implementations to match/unmatch media features. |
| Selectors | Yes | |
| Transitions | Yes | |
| Values | Yes | |
| Variables | Yes | |
| Grid / Template / Alignment | Partial | Legacy gap properties (grid-row-gap ,
grid-column-gap , and grid-gap ) are not supported, although the longhands can be used if declared explicitly). |
Pseudo-classes
The following pseudo-classes are supported by the library:
first-child
, last-child
, only-child
, nth-child()
, nth-last-child()
, first-of-type
,
last-of-type
, only-of-type
, nth-of-type()
, nth-last-of-type()
, link
, visited
,
target
, root
, empty
, blank
, disabled
, enabled
, read-write
,
read-only
, is
, where
, has
, not
, placeholder-shown
, default
,
checked
and indeterminate
.
State pseudo-classes like hover
are supported through the
CSSCanvas.isActivePseudoClass(CSSElement, String) method.
Rendering-oriented interfaces
To help with the determination of 'used' values and the actual rendering, this library provides a few helper interfaces. The most important are:
- DeviceFactory. Delivers the relevant abstractions for a
requested medium:
StyleDatabase
andCSSCanvas
.
- StyleDatabase. Provides medium-specific information like available fonts and colors.
- CSSCanvas. Has knowledge of medium-specific information that depends (or may depend) on a specific viewport, like supported media features. It is linked to a viewport, if there is any. This interface is used to determine the state of active pseudo-classes.
- Viewport. It represents a viewport defined as per the CSS specifications.
The differences between style databases and canvases can be subtle, and for some media features it could be argued that they belong to one or the other. The basic idea is that style databases should be relatively easy to implement for a given medium, while canvases are probably only going to exist if there is an actual rendering engine implemented.
Java™ Runtime Environment requirements
The classes in the binary packages have been compiled with a Java compiler with 1.8 compiler compliance level,
except for the module-info
file which targets Java 11. If you are stuck with Java 7, you may want to use css4j 1.0.


GREP
Section: User Commands (1)Updated:
Index Return to Main Contents
NAME
grep, egrep, fgrep - print lines matching a patternSYNOPSIS
grep [OPTIONS] PATTERN [FILE...]grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]
DESCRIPTION
grep searches the named input FILEs (or standard input if no files are named, or if a single hyphen-minus (-) is given as file name) for lines containing a match to the given PATTERN. By default, grep prints the matching lines.In addition, two variant programs egrep and fgrep are available. egrep is the same as grep -E. fgrep is the same as grep -F. Direct invocation as either egrep or fgrep is deprecated, but is provided to allow historical applications that rely on them to run unmodified.
OPTIONS
Generic Program Information
- --help
- Print a usage message briefly summarizing these command-line options and the bug-reporting address, then exit.
- -V, --version
- Print the version number of grep to the standard output stream. This version number should be included in all bug reports (see below).
Matcher Selection
- -E, --extended-regexp
- Interpret PATTERN as an extended regular expression (ERE, see below). (-E is specified by POSIX.)
- -F, --fixed-strings
- Interpret PATTERN as a list of fixed strings, separated by newlines, any of which is to be matched. (-F is specified by POSIX.)
- -G, --basic-regexp
- Interpret PATTERN as a basic regular expression (BRE, see below). This is the default.
- -P, --perl-regexp
- Interpret PATTERN as a Perl regular expression. This is highly experimental and grep -P may warn of unimplemented features.
Matching Control
- -e PATTERN, --regexp=PATTERN
- Use PATTERN as the pattern. This can be used to specify multiple search patterns, or to protect a pattern beginning with a hyphen (-). (-e is specified by POSIX.)
- -f FILE, --file=FILE
- Obtain patterns from FILE, one per line. The empty file contains zero patterns, and therefore matches nothing. (-f is specified by POSIX.)
- -i, --ignore-case
- Ignore case distinctions in both the PATTERN and the input files. (-i is specified by POSIX.)
- -v, --invert-match
- Invert the sense of matching, to select non-matching lines. (-v is specified by POSIX.)
- -w, --word-regexp
- Select only those lines containing matches that form whole words. The test is that the matching substring must either be at the beginning of the line, or preceded by a non-word constituent character. Similarly, it must be either at the end of the line or followed by a non-word constituent character. Word-constituent characters are letters, digits, and the underscore.
- -x, --line-regexp
- Select only those matches that exactly match the whole line. (-x is specified by POSIX.)
- -y
- Obsolete synonym for -i.
General Output Control
- -c, --count
- Suppress normal output; instead print a count of matching lines for each input file. With the -v, --invert-match option (see below), count non-matching lines. (-c is specified by POSIX.)
- --color[=WHEN], --colour[=WHEN]
- Surround the matched (non-empty) strings, matching lines, context lines, file names, line numbers, byte offsets, and separators (for fields and groups of context lines) with escape sequences to display them in color on the terminal. The colors are defined by the environment variable GREP_COLORS. The deprecated environment variable GREP_COLOR is still supported, but its setting does not have priority. WHEN is never, always, or auto.
- -L, --files-without-match
- Suppress normal output; instead print the name of each input file from which no output would normally have been printed. The scanning will stop on the first match.
- -l, --files-with-matches
- Suppress normal output; instead print the name of each input file from which output would normally have been printed. The scanning will stop on the first match. (-l is specified by POSIX.)
- -m NUM, --max-count=NUM
- Stop reading a file after NUM matching lines. If the input is standard input from a regular file, and NUM matching lines are output, grep ensures that the standard input is positioned to just after the last matching line before exiting, regardless of the presence of trailing context lines. This enables a calling process to resume a search. When grep stops after NUM matching lines, it outputs any trailing context lines. When the -c or --count option is also used, grep does not output a count greater than NUM. When the -v or --invert-match option is also used, grep stops after outputting NUM non-matching lines.
- -o, --only-matching
- Print only the matched (non-empty) parts of a matching line, with each such part on a separate output line.
- -q, --quiet, --silent
- Quiet; do not write anything to standard output. Exit immediately with zero status if any match is found, even if an error was detected. Also see the -s or --no-messages option. (-q is specified by POSIX.)
- -s, --no-messages
- Suppress error messages about nonexistent or unreadable files. Portability note: unlike GNU grep, 7th Edition Unix grep did not conform to POSIX, because it lacked -q and its -s option behaved like GNU grep's -q option. USG-style grep also lacked -q but its -s option behaved like GNU grep. Portable shell scripts should avoid both -q and -s and should redirect standard and error output to /dev/null instead. (-s is specified by POSIX.)
Output Line Prefix Control
- -b, --byte-offset
- Print the 0-based byte offset within the input file before each line of output. If -o (--only-matching) is specified, print the offset of the matching part itself.
- -H, --with-filename
- Print the file name for each match. This is the default when there is more than one file to search.
- -h, --no-filename
- Suppress the prefixing of file names on output. This is the default when there is only one file (or only standard input) to search.
- --label=LABEL
- Display input actually coming from standard input as input coming from file LABEL. This is especially useful when implementing tools like zgrep, e.g., gzip -cd foo.gz | grep --label=foo -H something. See also the -H option.
- -n, --line-number
- Prefix each line of output with the 1-based line number within its input file. (-n is specified by POSIX.)
- -T, --initial-tab
- Make sure that the first character of actual line content lies on a tab stop, so that the alignment of tabs looks normal. This is useful with options that prefix their output to the actual content: -H,-n, and -b. In order to improve the probability that lines from a single file will all start at the same column, this also causes the line number and byte offset (if present) to be printed in a minimum size field width.
- -u, --unix-byte-offsets
- Report Unix-style byte offsets. This switch causes grep to report byte offsets as if the file were a Unix-style text file, i.e., with CR characters stripped off. This will produce results identical to running grep on a Unix machine. This option has no effect unless -b option is also used; it has no effect on platforms other than MS-DOS and MS-Windows.
- -Z, --null
- Output a zero byte (the ASCII NUL character) instead of the character that normally follows a file name. For example, grep -lZ outputs a zero byte after each file name instead of the usual newline. This option makes the output unambiguous, even in the presence of file names containing unusual characters like newlines. This option can be used with commands like find -print0, perl -0, sort -z, and xargs -0 to process arbitrary file names, even those that contain newline characters.
Context Line Control
- -A NUM, --after-context=NUM
- Print NUM lines of trailing context after matching lines. Places a line containing a group separator (--) between contiguous groups of matches. With the -o or --only-matching option, this has no effect and a warning is given.
- -B NUM, --before-context=NUM
- Print NUM lines of leading context before matching lines. Places a line containing a group separator (--) between contiguous groups of matches. With the -o or --only-matching option, this has no effect and a warning is given.
- -C NUM, -NUM, --context=NUM
- Print NUM lines of output context. Places a line containing a group separator (--) between contiguous groups of matches. With the -o or --only-matching option, this has no effect and a warning is given.
File and Directory Selection
- -a, --text
- Process a binary file as if it were text; this is equivalent to the --binary-files=text option.
- --binary-files=TYPE
- If the first few bytes of a file indicate that the file contains binary data, assume that the file is of type TYPE. By default, TYPE is binary, and grep normally outputs either a one-line message saying that a binary file matches, or no message if there is no match. If TYPE is without-match, grep assumes that a binary file does not match; this is equivalent to the -I option. If TYPE is text, grep processes a binary file as if it were text; this is equivalent to the -a option. Warning: grep --binary-files=text might output binary garbage, which can have nasty side effects if the output is a terminal and if the terminal driver interprets some of it as commands.
- -D ACTION, --devices=ACTION
- If an input file is a device, FIFO or socket, use ACTION to process it. By default, ACTION is read, which means that devices are read just as if they were ordinary files. If ACTION is skip, devices are silently skipped.
- -d ACTION, --directories=ACTION
- If an input file is a directory, use ACTION to process it. By default, ACTION is read, which means that directories are read just as if they were ordinary files. If ACTION is skip, directories are silently skipped. If ACTION is recurse, grep reads all files under each directory, recursively; this is equivalent to the -r option.
- --exclude=GLOB
- Skip files whose base name matches GLOB (using wildcard matching). A file-name glob can use *, ?, and [...] as wildcards, and \ to quote a wildcard or backslash character literally.
- --exclude-from=FILE
- Skip files whose base name matches any of the file-name globs read from FILE (using wildcard matching as described under --exclude).
- --exclude-dir=DIR
- Exclude directories matching the pattern DIR from recursive searches.
- -I
- Process a binary file as if it did not contain matching data; this is equivalent to the --binary-files=without-match option.
- --include=GLOB
- Search only files whose base name matches GLOB (using wildcard matching as described under --exclude).
- -R, -r, --recursive
- Read all files under each directory, recursively; this is equivalent to the -d recurse option.
Other Options
- --line-buffered
- Use line buffering on output. This can cause a performance penalty.
- --mmap
- If possible, use the mmap(2) system call to read input, instead of the default read(2) system call. In some situations, --mmap yields better performance. However, --mmap can cause undefined behavior (including core dumps) if an input file shrinks while grep is operating, or if an I/O error occurs.
- -U, --binary
- Treat the file(s) as binary. By default, under MS-DOS and MS-Windows, grep guesses the file type by looking at the contents of the first 32KB read from the file. If grep decides the file is a text file, it strips the CR characters from the original file contents (to make regular expressions with ^ and $ work correctly). Specifying -U overrules this guesswork, causing all files to be read and passed to the matching mechanism verbatim; if the file is a text file with CR/LF pairs at the end of each line, this will cause some regular expressions to fail. This option has no effect on platforms other than MS-DOS and MS-Windows.
- -z, --null-data
- Treat the input as a set of lines, each terminated by a zero byte (the ASCII NUL character) instead of a newline. Like the -Z or --null option, this option can be used with commands like sort -z to process arbitrary file names.
REGULAR EXPRESSIONS
A regular expression is a pattern that describes a set of strings. Regular expressions are constructed analogously to arithmetic expressions, by using various operators to combine smaller expressions.grep understands three different versions of regular expression syntax: ``basic,'' ``extended'' and ``perl.'' In GNU grep, there is no difference in available functionality between basic and extended syntaxes. In other implementations, basic regular expressions are less powerful. The following description applies to extended regular expressions; differences for basic regular expressions are summarized afterwards. Perl regular expressions give additional functionality, and are documented in pcresyntax(3) and pcrepattern(3), but may not be available on every system.
The fundamental building blocks are the regular expressions that match a single character. Most characters, including all letters and digits, are regular expressions that match themselves. Any meta-character with special meaning may be quoted by preceding it with a backslash.
The period . matches any single character.
Character Classes and Bracket Expressions
A bracket expression is a list of characters enclosed by [ and ]. It matches any single character in that list; if the first character of the list is the caret ^ then it matches any character not in the list. For example, the regular expression [0123456789] matches any single digit.Within a bracket expression, a range expression consists of two characters separated by a hyphen. It matches any single character that sorts between the two characters, inclusive, using the locale's collating sequence and character set. For example, in the default C locale, [a-d] is equivalent to [abcd]. Many locales sort characters in dictionary order, and in these locales [a-d] is typically not equivalent to [abcd]; it might be equivalent to [aBbCcDd], for example. To obtain the traditional interpretation of bracket expressions, you can use the C locale by setting the LC_ALL environment variable to the value C.
Finally, certain named classes of characters are predefined within bracket expressions, as follows. Their names are self explanatory, and they are [:alnum:], [:alpha:], [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:], [:space:], [:upper:], and [:xdigit:]. For example, [[:alnum:]] means [0-9A-Za-z], except the latter form depends upon the C locale and the ASCII character encoding, whereas the former is independent of locale and character set. (Note that the brackets in these class names are part of the symbolic names, and must be included in addition to the brackets delimiting the bracket expression.) Most meta-characters lose their special meaning inside bracket expressions. To include a literal ] place it first in the list. Similarly, to include a literal ^ place it anywhere but first. Finally, to include a literal - place it last.
Anchoring
The caret ^ and the dollar sign $ are meta-characters that respectively match the empty string at the beginning and end of a line.The Backslash Character and Special Expressions
The symbols \< and \> respectively match the empty string at the beginning and end of a word. The symbol \b matches the empty string at the edge of a word, and \B matches the empty string provided it's not at the edge of a word. The symbol \w is a synonym for [[:alnum:]] and \W is a synonym for [^[:alnum:]].Repetition
A regular expression may be followed by one of several repetition operators:- ?
- The preceding item is optional and matched at most once.
- *
- The preceding item will be matched zero or more times.
- +
- The preceding item will be matched one or more times.
- {n}
- The preceding item is matched exactly n times.
- {n,}
- The preceding item is matched n or more times.
- {,m}
- The preceding item is matched at most m times.
- {n,m}
- The preceding item is matched at least n times, but not more than m times.
Concatenation
Two regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating two substrings that respectively match the concatenated expressions.Alternation
Two regular expressions may be joined by the infix operator |; the resulting regular expression matches any string matching either alternate expression.Precedence
Repetition takes precedence over concatenation, which in turn takes precedence over alternation. A whole expression may be enclosed in parentheses to override these precedence rules and form a subexpression.Back References and Subexpressions
The back-reference \n, where n is a single digit, matches the substring previously matched by the nth parenthesized subexpression of the regular expression.Basic vs Extended Regular Expressions
In basic regular expressions the meta-characters ?, +, {, |, (, and ) lose their special meaning; instead use the backslashed versions \?, \+, \{, \|, \(, and \).Traditional egrep did not support the { meta-character, and some egrep implementations support \{ instead, so portable scripts should avoid { in grep -E patterns and should use [{] to match a literal {.
GNU grep -E attempts to support traditional usage by assuming that { is not special if it would be the start of an invalid interval specification. For example, the command grep -E '{1' searches for the two-character string {1 instead of reporting a syntax error in the regular expression. POSIX.2 allows this behavior as an extension, but portable scripts should avoid it.
ENVIRONMENT VARIABLES
The behavior of grep is affected by the following environment variables.The locale for category LC_foo is specified by examining the three environment variables LC_ALL, LC_foo, LANG, in that order. The first of these variables that is set specifies the locale. For example, if LC_ALL is not set, but LC_MESSAGES is set to pt_BR, then the Brazilian Portuguese locale is used for the LC_MESSAGES category. The C locale is used if none of these environment variables are set, if the locale catalog is not installed, or if grep was not compiled with national language support (NLS).
- GREP_OPTIONS
- This variable specifies default options to be placed in front of any explicit options. For example, if GREP_OPTIONS is '--binary-files=without-match --directories=skip', grep behaves as if the two options --binary-files=without-match and --directories=skip had been specified before any explicit options. Option specifications are separated by whitespace. A backslash escapes the next character, so it can be used to specify an option containing whitespace or a backslash.
- GREP_COLOR
- This variable specifies the color used to highlight matched (non-empty) text. It is deprecated in favor of GREP_COLORS, but still supported. The mt, ms, and mc capabilities of GREP_COLORS have priority over it. It can only specify the color used to highlight the matching non-empty text in any matching line (a selected line when the -v command-line option is omitted, or a context line when -v is specified). The default is 01;31, which means a bold red foreground text on the terminal's default background.
- GREP_COLORS
-
Specifies the colors and other attributes
used to highlight various parts of the output.
Its value is a colon-separated list of capabilities
that defaults to
ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36
with the
rv
and
ne
boolean capabilities omitted (i.e., false).
Supported capabilities are as follows.
-
- sl=
- SGR substring for whole selected lines (i.e., matching lines when the -v command-line option is omitted, or non-matching lines when -v is specified). If however the boolean rv capability and the -v command-line option are both specified, it applies to context matching lines instead. The default is empty (i.e., the terminal's default color pair).
- cx=
- SGR substring for whole context lines (i.e., non-matching lines when the -v command-line option is omitted, or matching lines when -v is specified). If however the boolean rv capability and the -v command-line option are both specified, it applies to selected non-matching lines instead. The default is empty (i.e., the terminal's default color pair).
- rv
- Boolean value that reverses (swaps) the meanings of the sl= and cx= capabilities when the -v command-line option is specified. The default is false (i.e., the capability is omitted).
- mt=01;31
- SGR substring for matching non-empty text in any matching line (i.e., a selected line when the -v command-line option is omitted, or a context line when -v is specified). Setting this is equivalent to setting both ms= and mc= at once to the same value. The default is a bold red text foreground over the current line background.
- ms=01;31
- SGR substring for matching non-empty text in a selected line. (This is only used when the -v command-line option is omitted.) The effect of the sl= (or cx= if rv) capability remains active when this kicks in. The default is a bold red text foreground over the current line background.
- mc=01;31
- SGR substring for matching non-empty text in a context line. (This is only used when the -v command-line option is specified.) The effect of the cx= (or sl= if rv) capability remains active when this kicks in. The default is a bold red text foreground over the current line background.
- fn=35
- SGR substring for file names prefixing any content line. The default is a magenta text foreground over the terminal's default background.
- ln=32
- SGR substring for line numbers prefixing any content line. The default is a green text foreground over the terminal's default background.
- bn=32
- SGR substring for byte offsets prefixing any content line. The default is a green text foreground over the terminal's default background.
- se=36
- SGR substring for separators that are inserted between selected line fields (:), between context line fields, (-), and between groups of adjacent lines when nonzero context is specified (--). The default is a cyan text foreground over the terminal's default background.
- ne
- Boolean value that prevents clearing to the end of line using Erase in Line (EL) to Right (\\\33[K) each time a colorized item ends. This is needed on terminals on which EL is not supported. It is otherwise useful on terminals for which the back_color_erase (bce) boolean terminfo capability does not apply, when the chosen highlight colors do not affect the background, or when EL is too slow or causes too much flicker. The default is false (i.e., the capability is omitted).
Note that boolean capabilities have no =... part. They are omitted (i.e., false) by default and become true when specified.
See the Select Graphic Rendition (SGR) section in the documentation of the text terminal that is used for permitted values and their meaning as character attributes. These substring values are integers in decimal representation and can be concatenated with semicolons. grep takes care of assembling the result into a complete SGR sequence (\\\33[...m). Common values to concatenate include 1 for bold, 4 for underline, 5 for blink, 7 for inverse, 39 for default foreground color, 30 to 37 for foreground colors, 90 to 97 for 16-color mode foreground colors, 38;5;0 to 38;5;255 for 88-color and 256-color modes foreground colors, 49 for default background color, 40 to 47 for background colors, 100 to 107 for 16-color mode background colors, and 48;5;0 to 48;5;255 for 88-color and 256-color modes background colors.
-
- LC_ALL, LC_COLLATE, LANG
- These variables specify the locale for the LC_COLLATE category, which determines the collating sequence used to interpret range expressions like [a-z].
- LC_ALL, LC_CTYPE, LANG
- These variables specify the locale for the LC_CTYPE category, which determines the type of characters, e.g., which characters are whitespace.
- LC_ALL, LC_MESSAGES, LANG
- These variables specify the locale for the LC_MESSAGES category, which determines the language that grep uses for messages. The default C locale uses American English messages.
- POSIXLY_CORRECT
- If set, grep behaves as POSIX.2 requires; otherwise, grep behaves more like other GNU programs. POSIX.2 requires that options that follow file names must be treated as file names; by default, such options are permuted to the front of the operand list and are treated as options. Also, POSIX.2 requires that unrecognized options be diagnosed as ``illegal'', but since they are not really against the law the default is to diagnose them as ``invalid''. POSIXLY_CORRECT also disables _N_GNU_nonoption_argv_flags_, described below.
- _N_GNU_nonoption_argv_flags_
- (Here N is grep's numeric process ID.) If the ith character of this environment variable's value is 1, do not consider the ith operand of grep to be an option, even if it appears to be one. A shell can put this variable in the environment for each command it runs, specifying which operands are the results of file name wildcard expansion and therefore should not be treated as options. This behavior is available only with the GNU C library, and only when POSIXLY_CORRECT is not set.
EXIT STATUS
Normally, the exit status is 0 if selected lines are found and 1 otherwise. But the exit status is 2 if an error occurred, unless the -q or --quiet or --silent option is used and a selected line is found. Note, however, that POSIX only mandates, for programs such as grep, cmp, and diff, that the exit status in case of error be greater than 1; it is therefore advisable, for the sake of portability, to use logic that tests for this general condition instead of strict equality with 2.COPYRIGHT
Copyright 1998-2000, 2002, 2005-2010 Free Software Foundation, Inc.This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
BUGS
Reporting Bugs
Email bug reports to<EMAIL_ADDRESS>a mailing list whose web page is <http://lists.gnu.org/mailman/listinfo/bug-grep>. grep's Savannah bug tracker is located at <http://savannah.gnu.org/bugs/?group=grep>.Known Bugs
Large repetition counts in the {n,m} construct may cause grep to use lots of memory. In addition, certain other obscure regular expressions require exponential time and space, and may cause grep to run out of memory.Back-references are very slow, and may require exponential time.
SEE ALSO
Regular Manual Pages
awk(1), cmp(1), diff(1), find(1), gzip(1), perl(1), sed(1), sort(1), xargs(1), zgrep(1), mmap(2), read(2), pcre(3), pcresyntax(3), pcrepattern(3), terminfo(5), glob(7), regex(7).POSIX Programmer's Manual Page
grep(1p).TeXinfo Documentation
The full documentation for grep is maintained as a TeXinfo manual. If the info and grep programs are properly installed at your site, the command- info grep
should give you access to the complete manual.
NOTES
GNU's not Unix, but Unix is a beast; its plural form is Unixen.
Index
- NAME
- SYNOPSIS
- DESCRIPTION
- OPTIONS
- REGULAR EXPRESSIONS
- ENVIRONMENT VARIABLES
- EXIT STATUS
- COPYRIGHT
- BUGS
- SEE ALSO
- NOTES
This document was created by man2html, using the manual pages.
Time: 05:29:04 GMT, December 24, 2015


This site is optimised for modern web browsers,
and does not fully support your version of Internet Explorer
Bologna sum up salad
It’s all about the ingredients here. Throw them together and enjoy this wonderful salad for a blast of Italian flavors.
By
Rick Stein
From
Rick Stein's Long Weekends
Ingredients
-
200g/7oz mix of bitter leaves, such as at least three of these: cime de rape, puntarelle, radicchio,
chicory
and curly endive
-
100g/3½oz
rocket
-
6 ripe
figs
, quartered or 2 ripe white peaches, stone removed and sliced
-
10 slices
prosciutto
, torn into pieces
-
50g/1¾oz
Parmesan
shavings
-
90g/3¼oz
gorgonzola
-
500g/1lb 2oz flavourful ripe
tomatoes
, core removed, cut into wedges
-
1 tbsp
capers
, drained
-
40g/1½oz toasted
pine nuts
-
handful
basil
leaves
-
60ml/2fl oz
olive oil
-
30ml/1fl oz sweet, aged
balsamic vinegar
Method
-
Mix the leaves and rocket in a large serving bowl. Top with chunks of fig or white peach, torn pieces of ham, shavings of Parmesan, chunks of gorgonzola and tomato wedges.
-
Sprinkle on the capers, basil leaves and pine nuts. Drizzle with olive oil and balsamic vinegar before tossing well and serving.


import numpy as np
import matplotlib.pyplot as plt
from scipy import stats
import pymc3 as pm
import arviz as az
az.style.use('arviz-darkgrid')
Visual diagnostics¶
We will discuss:
Trace plots
Autocorrelation plots
Rank plots
Trace plots¶
az.plot_trace()
MCMC samples should not be sensitive to the starting point, so if you sample more than one chain (starting from different places) you should basically get the same distribution within certain small error. As we already discussed in the numerical diagnostic section, MCMC samples should have the lowest possible autocorrelation
Trace plots can help diagnose:
Bad intialization
Difficult topologies (such as Neal’s funnel)
Multimodal posteriors
Pathological traces¶
The following figure shows examples of problematic samples:
On the first row we see that the MCMC chains has large autocorrelation, you can see the trace (left column) shows long regions of monoticity (the lines parallel to the x-axis). This could be a consequence of a multimodal posterior with barrier between modes of very low probability. Thus the samples has trouble to freely move from mode to mode. Another explanation could be high correlation between parameters, this can also be problematic for some samplers specially Metropolis. In such cases the multimodality could be apparent and not a real feature of our posterior.
On the second row we see two chains that started from two very different position and eventually converge to the same distribution. The first \(\approx\) 25 samples could bias our results so we can just remove them (burn-in).
ON the last row, we see two chains exploring two different regions of the parameter space. From the trace it seems they are in fact approaching each other at a slow rate and the maybe eventually reach the same stationary distribution.
Autocorrelation plot¶
az.plot_autocorr()
As we discussed in the Numerical Diagnostics section, we can see autocorrelation as a factor that decrease the actual amount of information contained in a sample. So we want to reduce autocorrelation as much as possible.
bad_chains = np.linspace(0, 1, 1000).reshape(2, -1)
az.plot_autocorr(bad_chains)
array([[<matplotlib.axes._subplots.AxesSubplot object at 0x7ffa6233fad0>,
<matplotlib.axes._subplots.AxesSubplot object at 0x7ffa622a37d0>]],
dtype=object)
The autocorrelation plot shows the degree of autocorrelation by default it used a maximum window of 100. The previous figure, corresponding to bad_chains
show a very high autocorrelation while the next figure corresponding to good_chains
show a very low autocorrelation.
good_chains = stats.uniform.rvs(0, 1, size=(2, 500))
az.plot_autocorr(good_chains)
array([[<matplotlib.axes._subplots.AxesSubplot object at 0x7ffa6061a490>,
<matplotlib.axes._subplots.AxesSubplot object at 0x7ffa621dcfd0>]],
dtype=object)
Rank plot¶
az.plot_rank()
Rank plots are histograms of the ranked posterior draws, ranked over all chains and then plotted separately for each chain. The idea behind this plot is that if all of the chains are targeting the same posterior, we expect the ranks in each chain to be uniform. Additionally, if rank plots of all chains look similar, this indicates good mixing of the chains
This is a recently proposed visual test, author argue superiority over trace plots:
az.plot_rank(good_chains);
We can see that for the good_chains
the histogram of the ranks is more or less uniform, uniformity will increasing with the sample size, and we can also see that both chains look similar with not distinctive pattern. This is in clear contrast the results for the bad_chains
, while they are uniform both chains are exploring two separate set of values. Notice how this is consistent to the way we create bad_chains
, 1000 ordered number from 0 to 1 split in two halves.
az.plot_rank(bad_chains);
The following is a snippet so you can get a better intuition of how to interpret rank plots. Notice that az.plot_rank
is doing a more involved computation, but to get intuition this block of code should be enough. Here the histogram of the rank (right panel) is rotated with respect to the previous histogram to match the cumulative distribution on the left panel. So you can see the bottom bar on the right contains the first 100 values from the cumulative distribution on the left, the second bar the second 100 values and so on.
You can see a rank plot as a device for detecting an excess of any given number, try for example uncommenting the line before and see how and excess of zeros affects the rank plot.
original_data = np.random.beta(2, 2, 1000)
#original_data[:100] = 0
ranked_data = stats.rankdata(original_data)
_, ax = plt.subplots(1, 2, figsize=(12, 4), sharey=True)
ax[0].plot(original_data, ranked_data, 'b.')
ax[0].set_xlabel('data values')
ax[0].set_ylabel('rank')
ax[0].set_xlim([0, 1])
ax[1].hist(ranked_data, bins=10, rwidth=0.9, orientation='horizontal')
ax[1].set_xlabel('frecuency');