Library

xs grep provides a library for grep-like searches.

Include to CMake-Project

1. Download xs grep into your projects root directory: git clone https://github.com/lfreist/xsgrep

   If you use git as version control, I recommend including it via git modules: git submodule add https://github.com/lfreist/xsgrep

2. Copy the following into your projects root CMakeList.txt:

   # CMakeList.txt
   
   # ...
   add_subdirectory(xsgrep)
   include_directories(xsgrep/include)
   # ...

3. Write your code (I'll provide more details on xs greps API later):

   // main.cpp
   
   #include <xsgrep/grep.h>
   
   int main() {
       // ...
       Grep grep("Sherlock", "sample.txt");  // search "Sherlock" within "sample.txt"
       auto result = grep.search();
       // ...
   }

4. Build your project and link xs grep:

   # CMakeList.txt
   
   # ...
   add_executable(MyProgram main.cpp)
   target_link_libraries(MyProgram PRIVATE libgrep)
   # ...

API

Grep

Grep is the base object that must be initialized to perform grep-like searches.

Construction

• Grep::Grep(): default constructor
• Grep::Grep(std::string pattern, std::string file): constructor initializing pattern and file
  • pattern: The pattern that is searched for
  • file: The file that is searched
• Grep::Grep(Grep::Options options): constructor with complete options instance

Run Searches

Grep provides three methods for performing searches:

• Grep::count(): Count the number of matching lines and return the result as uint64_t
• Grep::search(): Perform search according to the set options and return the results as std::vector<Grep::Match> (c.f. Grep::Match)
• Grep::write(std::ostream* stream): Perform search according to the set options and write the results to stream in a GNU grep-like format

Configuration

The configuration of the search and output control is stored within an options instance. However, Grep provides methods for setting and getting the values of the options.

Setters

All setters return the Grep instance itself.

• Grep::set_file(std::string file): Set file to the file that is searched
• Grep::set_meta_file(std::string metafile): Set metafile to the corresponding metafile of file
• Grep::set_pattern(std::string pattern): Set pattern to the pattern that is searched for
• Grep::set_count_only(bool val): true: count matches, false: search matches
• Grep::set_fixed_string(bool val): true: Perform literal search, false: perform regex search
• Grep::set_line_number(bool val): true: Search and output line numbers
• Grep::set_byte_offset(bool val): true: Output byte offsets
• Grep::set_only_matching(bool val): true: search matches, false: search matching lines
• Grep::set_ignore_case(bool val): true: case-insensitive search, false: case sensitive search
• Grep::set_print_file_path(bool val): true: output file path
• Grep::set_use_mmap(bool val): true: use memory mapping, false: use file stream for reading
• Grep::set_num_threads(int val): Set number of worker threads using the following heuristics:
  • val < 0: number of physical cores available
  • val == 0: half of physical cores available
  • val > 0: val, but max. number of physical cores
• Grep::set_num_reader_threads(int val): Set the maximum number of threads that concurrently read using the following heuristics:
  • val < 1: 1
  • val >= 1: val, but max. number of physical cores

Getters

All getters return their attributes currently set value and are marked as const

• const std::string& Grep::file()
• const std::string& Grep::meta_file()
• const std::string& Grep::pattern()
• bool Grep::count_only()
• bool Grep::fixed_string()
• bool Grep::line_number()
• bool Grep::byte_offset()
• bool Grep::only_matching()
• bool Grep::count_only()
• bool Grep::ignore_case()
• bool Grep::print_filepath()
• bool Grep::use_mmap()
• int Grep::num_threads()
• int Grep::num_reader_threads()
• Grep::Color Grep::color()
• Grep::Locale Grep::locale()

Grep::Options

This structs members define the search and output formatting.

Member	Type	Description
count	bool	Count number of matching lines or matches (if match_only)
fixed_string	bool	Perform literal search for regex characters
line_number	bool	Search and output line numbers along matches
byte_offset	bool	Output byte offsets along matches
only_matching	bool	Search for matches instead of matching lines
ignore_case	bool	Perform case-insensitive search
no_mmap	bool	Read file using a file stream instead of memory mapping
color	Grep::Color	AUTO, ON, OFF: colored output
locale	Grep::Locale	AUTO, ASCII, UTF8
num_threads	int	Number of worker threads
pattern	std::string	The pattern that is searched for
file	std::string	The file that is searched
metafile	std::string	The files corresponding metafile (if available)

Grep::Match

This struct represents a single match of the search.

Member	Type	Description
byte_position	int64_t	The byte position of a match (or matching line, depending on the -o flag)
line_number	int64_t	The line number of a match (only if -n is set)
match	std::string	The content of the match (either the match if -o is set or the matching line).