(index ("irregex" 0) ("string->irregex" 0) ("sre->irregex" 0) ("string->sre" 1538) ("maybe-string->sre" 1538) ("irregex?" 2095) ("irregex-search" 2220) ("irregex-match" 3497) ("irregex-match-data?" 3939) ("irregex-num-submatches" 4150) ("irregex-match-num-submatches" 4150) ("irregex-names" 4419) ("irregex-match-names" 4419) ("irregex-match-valid-index?" 4924) ("irregex-match-substring" 5163) ("irregex-match-start-index" 5163) ("irregex-match-end-index" 5163) ("irregex-match-subchunk" 5650) ("irregex-replace" 6003) ("irregex-replace/all" 6003) ("irregex-split" 7014) ("irregex-extract" 7014) ("irregex-fold" 7451) ("make-irregex-chunker" 9085) ("irregex-search/chunked" 10844) ("irregex-match/chunked" 10844) ("irregex-fold/chunked" 12220) ("irregex-quote" 12410) ("irregex-opt" 12629) ("sre->string" 12893))
(def (sig (procedure "(irregex <posix-string-or-sre> [<options> ...])" (id irregex)) (procedure "(string->irregex <posix-string> [<options> ...])" (id string->irregex)) (procedure "(sre->irregex <sre> [<options> ...])" (id sre->irregex))) (p "Compiles a regular expression from either a POSIX-style regular expression string (with most PCRE extensions) or an SCSH-style SRE. There is no " (tt "(rx ...)") " syntax - just use normal Scheme lists, with " (tt "quasiquote") " if you like.") (p "Technically a string by itself could be considered a valid (though rather silly) SRE, so if you want to just match a literal string you should use something like " (tt "(irregex `(: ,str))") ", or use the explicit " (tt "(sre->irregex str)") ".") (p "The options are a list of any of the following symbols:") (dl (dt (tt "'i") ", " (tt "'case-insensitive")) (dd "match case-insensitively") (dt (tt "'m") ", " (tt "'multi-line")) (dd "treat string as multiple lines (effects " (tt "^") " and " (tt "$") ")") (dt (tt "'s") ", " (tt "'single-line")) (dd "treat string as a single line (" (tt ".") " can match newline)") (dt (tt "'utf8")) (dd "utf8-mode (assumes strings are byte-strings)") (dt (tt "'fast")) (dd "try to optimize the regular expression") (dt (tt "'small")) (dd "try to compile a smaller regular expression") (dt (tt "'backtrack")) (dd "enforce a backtracking implementation")) (p "The " (tt "'fast") " and " (tt "'small") " options are heuristic guidelines and will not necessarily make the compiled expression faster or smaller."))
(def (sig (procedure "(string->sre <str>)" (id string->sre)) (procedure "(maybe-string->sre <obj>)" (id maybe-string->sre))) (p "For backwards compatibility, procedures to convert a POSIX string into an SRE.") (p (tt "maybe-string->sre") " does the same thing, but only if the argument is a string, otherwise it assumes " (tt "<obj>") " is an SRE and returns it as-is.  This is useful when you want to provide an API that allows either a POSIX string or SRE (like " (tt "irregex") " or " (tt "irregex-search") " below) - it ensures the result is an SRE."))
(def (sig (procedure "(irregex? <obj>)" (id irregex?))) (p "Returns " (tt "#t") " iff the object is a regular expression."))
(def (sig (procedure "(irregex-search <irx> <str> [<start> <end>])" (id irregex-search))) (p "Searches for any instances of the pattern " (tt "<irx>") " (a POSIX string, SRE sexp, or pre-compiled regular expression) in " (tt "<str>") ", optionally between the given range.  If a match is found, returns a match object, otherwise returns " (tt "#f") ".") (p "Match objects can be used to query the original range of the string or its submatches using the " (tt "irregex-match-*") " procedures below.") (p "Examples:") (highlight scheme "(irregex-search \"foobar\" \"abcFOOBARdef\") => #f\n\n(irregex-search (irregex \"foobar\" 'i) \"abcFOOBARdef\") => #<match>\n\n(irregex-search '(w/nocase \"foobar\") \"abcFOOBARdef\") => #<match>") (p "Note, the actual match result is represented by a vector in the default implementation.  Throughout this manual, we'll just write " (tt "#<match>") " to show that a successful match was returned when the details are not important.") (p "Matching follows the POSIX leftmost, longest semantics, when searching.  That is, of all possible matches in the string, " (tt "irregex-search") " will return the match at the first position (leftmost).  If multiple matches are possible from that same first position, the longest match is returned."))
(def (sig (procedure "(irregex-match <irx> <str> [<start> <end>])" (id irregex-match))) (p "Like " (tt "irregex-search") ", but performs an anchored match against the beginning and end of the substring specified by " (tt "<start>") " and " (tt "<end>") ", without searching.") (p "Examples:") (highlight scheme "(irregex-match '(w/nocase \"foobar\") \"abcFOOBARdef\") => #f\n\n(irregex-match '(w/nocase \"foobar\") \"FOOBAR\") => #<match>"))
(def (sig (procedure "(irregex-match-data? <obj>)" (id irregex-match-data?))) (p "Returns " (tt "#t") " iff the object is a successful match result from " (tt "irregex-search") " or " (tt "irregex-match") "."))
(def (sig (procedure "(irregex-num-submatches <irx>)" (id irregex-num-submatches)) (procedure "(irregex-match-num-submatches <match>)" (id irregex-match-num-submatches))) (p "Returns the number of numbered submatches that are defined in the irregex or match object."))
(def (sig (procedure "(irregex-names <irx>)" (id irregex-names)) (procedure "(irregex-match-names <match>)" (id irregex-match-names))) (p "Returns an association list of named submatches that are defined in the irregex or match object.  The " (tt "car") " of each item in this list is the name of a submatch, the " (tt "cdr") " of each item is the numerical submatch corresponding to this name.  If a named submatch occurs multiple times in the irregex, it will also occur multiple times in this list."))
(def (sig (procedure "(irregex-match-valid-index? <match> <index-or-name>)" (id irregex-match-valid-index?))) (p "Returns " (tt "#t") " iff the " (tt "index-or-name") " named submatch or index is defined in the " (tt "match") " object."))
(def (sig (procedure "(irregex-match-substring <match> [<index-or-name>])" (id irregex-match-substring)) (procedure "(irregex-match-start-index <match> [<index-or-name>])" (id irregex-match-start-index)) (procedure "(irregex-match-end-index <match> [<index-or-name>])" (id irregex-match-end-index))) (p "Fetches the matched substring (or its start or end offset) at the given submatch index, or named submatch.  The entire match is index 0, the first 1, etc.  The default is index 0."))
(def (sig (procedure "(irregex-match-subchunk <match> [<index-or-name>])" (id irregex-match-subchunk))) (p "Generates a chunked data-type for the given match item, of the same type as the underlying chunk type (see Chunked String Matching below). This is only available if the chunk type specifies the get-subchunk API, otherwise an error is raised."))
(def (sig (procedure "(irregex-replace <irx> <str> [<replacements> ...])" (id irregex-replace)) (procedure "(irregex-replace/all <irx> <str> [<replacements> ...])" (id irregex-replace/all))) (p "Matches a pattern in a string, and replaces it with a (possibly empty) list of substitutions.  Each " (tt "<replacement>") " can be either a string literal, a numeric index, a symbol (as a named submatch), or a procedure which takes one argument (the match object) and returns a string.") (p "Examples:") (highlight scheme "(irregex-replace \"[aeiou]\" \"hello world\" \"*\") => \"h*llo world\"\n\n(irregex-replace/all \"[aeiou]\" \"hello world\" \"*\") => \"h*ll* w*rld\"\n\n(irregex-replace \"(.)(.)\" \"ab\" 2 1 \"*\")  => \"ba*\"\n\n(irregex-replace \"...bar\" \"xxfoobar\" (lambda (m) \n              (string-reverse (irregex-match-substring m)))) => \"xxraboof\"\n\n(irregex-replace \"(...)(bar)\" \"xxfoobar\"  2 (lambda (m) \n              (string-reverse (irregex-match-substring m 1)))) => \"xxbaroof\""))
(def (sig (procedure "(irregex-split <irx> <str> [<start> <end>])" (id irregex-split)) (procedure "(irregex-extract <irx> <str> [<start> <end>])" (id irregex-extract))) (p (tt "irregex-split") " splits the string " (tt "<str>") " into substrings divided by the pattern in " (tt "<irx>") ".  " (tt "irregex-extract") " does the opposite, returning a list of each instance of the pattern matched disregarding the substrings in between."))
(def (sig (procedure "(irregex-fold <irx> <kons> <knil> <str> [<finish> <start> <end>])" (id irregex-fold))) (p "This performs a fold operation over every non-overlapping place " (tt "<irx>") " occurs in the string " (tt "str") ".") (p "The " (tt "<kons>") " procedure takes the following signature:") (highlight scheme "(<kons> <from-index> <match> <seed>)") (p "where " (tt "<from-index>") " is the index from where we started searching (initially " (tt "<start>") " and thereafter the end index of the last match), " (tt "<match>") " is the resulting match-data object, and " (tt "<seed>") " is the accumulated fold result starting with " (tt "<knil>") ".") (p "The rationale for providing the " (tt "<from-index>") " (which is not provided in the SCSH " (tt "regexp-fold") " utility), is because this information is useful (e.g. for extracting the unmatched portion of the string before the current match, as needed in " (tt "irregex-replace") "), and not otherwise directly accessible.") (p "The optional " (tt "<finish>") " takes two arguments:") (highlight scheme "(<finish> <from-index> <seed>)") (p "which simiarly allows you to pick up the unmatched tail of the string, and defaults to just returning the " (tt "<seed>") ".") (p (tt "<start>") " and " (tt "<end>") " are numeric indices letting you specify the boundaries of the string on which you want to fold.") (p "To extract all instances of a match out of a string, you can use") (highlight scheme "(map irregex-match-substring\n     (irregex-fold <irx>\n                   (lambda (i m s) (cons m s))\n\t\t   '()\n\t\t   <str>\n\t\t   (lambda (i s) (reverse s))))"))
(def (sig (procedure "(make-irregex-chunker <get-next> <get-string> [<get-start> <get-end> <get-substring> <get-subchunk>])" (id make-irregex-chunker))) (p "where") (p (tt "(<get-next> chunk) => ") " returns the next chunk, or " (tt "#f") " if there are no more chunks") (p (tt "(<get-string> chunk) => ") " a string source for the chunk") (p (tt "(<get-start> chunk) => ") " the start index of the result of " (tt "<get-string>") " (defaults to always 0)") (p (tt "(<get-end> chunk) => ") " the end (exclusive) of the string (defaults to " (tt "string-length") " of the source string)") (p (tt "(<get-substring> cnk1 i cnk2 j) => ") " a substring for the range between the chunk " (tt "cnk1") " starting at index " (tt "i") " and ending at " (tt "cnk2") " at index " (tt "j")) (p (tt "(<get-subchunk> cnk1 i cnk2 j) => ") " as above but returns a new chunked data type instead of a string (optional)") (p "There are two important constraints on the " (tt "<get-next>") " procedure. It must return an " (tt "eq?") " identical object when called multiple times on the same chunk, and it must not return a chunk with an empty string (start == end).  This second constraint is for performance reasons - we push the work of possibly filtering empty chunks to the chunker since there are many chunk types for which empty strings aren't possible, and this work is thus not needed.  Note that the initial chunk passed to match on is allowed to be empty.") (p (tt "<get-substring>") " is provided for possible performance improvements - without it a default is used.  " (tt "<get-subchunk>") " is optional - without it you may not use " (tt "irregex-match-subchunk") " described above.") (p "You can then match chunks of these types with the following procedures:"))
(def (sig (procedure "(irregex-search/chunked <irx> <chunker> <chunk> [<start>])" (id irregex-search/chunked)) (procedure "(irregex-match/chunked <irx> <chunker> <chunk> [<start>])" (id irregex-match/chunked))) (p "These return normal match-data objects.") (p "Example:") (p "To match against a simple, flat list of strings use:") (highlight scheme "  (define (rope->string rope1 start rope2 end)\n    (if (eq? rope1 rope2)\n        (substring (car rope1) start end)\n        (let loop ((rope (cdr rope1))\n                   (res (list (substring (car rope1) start))))\n           (if (eq? rope rope2)\n               (string-concatenate-reverse      ; from SRFI-13\n                (cons (substring (car rope) 0 end) res))\n               (loop (cdr rope) (cons (car rope) res))))))\n\n  (define rope-chunker\n    (make-irregex-chunker (lambda (x) (and (pair? (cdr x)) (cdr x)))\n                          car\n                          (lambda (x) 0)\n                          (lambda (x) (string-length (car x)))\n                          rope->string))\n\n  (irregex-search/chunked <pat> rope-chunker <list-of-strings>)") (p "Here we are just using the default start, end and substring behaviors, so the above chunker could simply be defined as:") (highlight scheme "  (define rope-chunker\n    (make-irregex-chunker (lambda (x) (and (pair? (cdr x)) (cdr x))) car))"))
(def (sig (procedure "(irregex-fold/chunked <irx> <kons> <knil> <chunker> <chunk> [<finish> [<start-index>]])" (id irregex-fold/chunked))) (p "Chunked version of " (tt "irregex-fold") "."))
(def (sig (procedure "(irregex-quote <str>)" (id irregex-quote))) (p "Returns a new string with any special regular expression characters escaped, to match the original string literally in POSIX regular expressions."))
(def (sig (procedure "(irregex-opt <list-of-strings>)" (id irregex-opt))) (p "Returns an optimized SRE matching any of the literal strings in the list, like Emacs' " (tt "regexp-opt") ".  Note this optimization doesn't help when irregex is able to build a DFA."))
(def (sig (procedure "(sre->string <sre>)" (id sre->string))) (p "Convert an SRE to a PCRE-style regular expression string, if possible."))
