Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    StringScannerpublic

    StringScanner

    StringScanner performs lexical scanning operations on a string. Inspired by Ruby's StringScanner class

    How To Use

    Instantiate a new StringScanner by passing its constructor the string to scan.

    var StringScanner = require("StringScanner");
    var ss = new StringScanner("abc123 def456");
    // #<StringScanner 0/13 @ "abc12...">
    

    For the following examples, ss represents the StringScanner instance defined above.

    bol / beginningOfLine

    Returns true if the scan pointer is at the beginning of a line (right after \n) or the beginning of the string, false otherwise.

    ss.reset()    // #<StringScanner 0/13 @ "abc12...">
    ss.pointer()  // 0
    ss.bol()      // true
    ss.scan(/./)  // "a"
    ss.pointer()  // 1
    ss.bol()      // false
    

    captures

    Returns an Array containing the contents of the capturing groups in the last evaluated pattern match.

    ss.reset()              // #<StringScanner 0/13 @ "abc12...">
    ss.check(/.*(..) (..)/  // "abc123 de"
    ss.captures()           // ["23","de"]
    ss.check(/\w+/)         // "abc123"
    ss.captures()           // []
    ss.check(/\s+/)         // null
    ss.captures()           // []
    

    check(pattern)

    Note: this method alters last match results

    Checks if a scan of the given pattern would succeed without advancing the scan pointer. Returns the portion of the string matched on successful match, null otherwise.

    ss.reset()           // #<StringScanner 0/13 @ "abc12...">
    ss.check(/[a-z]+/i)  // "abc"
    ss.check(/[a-z]+/i)  // "abc"
    ss.scan(/[a-z]+/i)   // "abc"
    ss.check(/[a-z]+/i)  // null
    ss.check(/[\d\s]+/)  // "123 "
    

    checkUntil(pattern)

    Note: this method alters last match results

    Checks if a scanUntil would succeed without advancing the scan pointer. Returns the portion of the string being scanned from the scan pointer to the end of the matched string on successful match, null otherwise.

    ss.reset()           // #<StringScanner 0/13 @ "abc12...">
    ss.checkUntil(/\s/)  // "abc123 "
    ss.checkUntil(/\s/)  // "abc123 "
    ss.checkUntil(/r/)   // null
    ss.scanUntil(/e/)    // "abc123 de"
    ss.checkUntil(/\s/)  // null
    

    clone / dup

    Creates a duplicate of this instance of StringScanner.

    concat(str)

    Appends the given string to the string being scanned.

    ss.reset()            // #<StringScanner 0/13 @ "abc12...">
    ss.checkUntil(/h/)    // null
    ss.concat(" ghi789")  // #<StringScanner 0/20 @ "abc12..."
    ss.checkUntil(/h/)    // "abc123 def456 gh"
    

    eos / endOfString

    Returns true if the scan pointer is at the end of the string being scanned, false otherwise.

    ss.reset()     // #<StringScanner 0/13 @ "abc12...">
    ss.pointer()   // 0
    ss.eos()       // false
    ss.scan(/.*/)  // "abc123 def456"
    ss.pointer()   // 13
    ss.eos()       // true
    

    exists(pattern) / exist(pattern)

    Note: this method alters last match results

    Warning: this method may return 0 on a successful operation. Use === comparision to null for failure check, for example: ss.exists(/a/i)===null

    Checks if the given pattern matches anywhere after the current scan pointer. This will determine if a scanUntil operation will succeed. Returns the number of characters between the scan pointer and the position in which the match was found on success, null otherwise.

    ss.reset()
    // ----
    ss.exists(/c/)   // 2
    ss.match()       // "c"
    ss.matched()     // true
    // ----
    ss.exists(/a/)   // 0
    ss.match()       // "a"
    ss.matched()     // true
    // ----
    ss.exists(/b*/)  // 0
    ss.match()       // ""
    ss.matched()     // true
    // ----
    ss.exists(/m/)   // null
    ss.match()       // null
    ss.matched()     // false
    

    getch / getChar

    Note: this method alters last match results

    Note: Ruby equivalent: get_byte

    scans one character and returns it; exactly equivalent to scan(/./).

    ss.reset()    // #<StringScanner 0/13 @ "abc12...">
    ss.getch()    // "a"
    ss.reset()    // #<StringScanner 0/13 @ "abc12...">
    ss.scan(/./)  // "a"
    

    match

    Note: Ruby equivalent: matched

    Returns the last string matched or null if the last attempted match failed.

    ss.reset()           // #<StringScanner 0/13 @ "abc12...">
    ss.scan(/[a-z]+/i)   // "abc"
    ss.match()           // "abc"
    ss.check(/[a-z]+/i)  // null
    ss.match()           // null
    

    matches(pattern)

    Note: Ruby equivalent: match?

    Checks if a scan of the given pattern would succeed without advancing the scan pointer. Returns the length of the string matched on successful match, null otherwise.

    ss.reset()             // #<StringScanner 0/13 @ "abc12...">
    ss.matches(/[a-z]+/i)  // 3
    ss.matches(/[a-z]+/i)  // 3
    ss.scan(/[a-z]+/i)     // "abc"
    ss.matches(/[a-z]+/i)  // null
    ss.matches(/[\d\s]+/)  // 4
    

    matched

    Note: Ruby equivalent: matched?

    Returns true if the last attempted match was successful, false otherwise.

    ss.reset()      // #<StringScanner 0/13 @ "abc12...">
    ss.scan(/\w+/)  // "abc123"
    ss.matched()    // true
    ss.scan(/\w+/)  // null
    ss.matched()    // false
    

    matchSize

    Warning: this method may return 0 on a successful operation. Use === comparision to null for failure check, for example: ss.matchSize()===null

    Returns the length of the most recently matched string if the most recent match attempt succeeded, null otherwise.

    ss.reset()       // #<StringScanner 0/13 @ "abc12...">
    ss.scan(/\w+/)   // "abc123"
    ss.matchSize()   // 6
    ss.check(/\w*/)  // ""
    ss.matchSize()   // 0
    ss.check(/\w+/)  // null
    ss.matchSize()   // null
    

    peek(len)

    Returns len characters after the scan pointer, or the rest of the string, whichever is shorter.

    ss.reset()      // #<StringScanner 0/13 @ "abc12...">
    ss.scan(/.*d/)  // "abc123 d"
    ss.peek(3)      // "ef4"
    ss.peek(9001)   // "ef456"
    ss.peek(0)      // ""
    ss.peek(-3)     // ""
    

    pointer / position

    Returns the scan pointer position as an integer.

    ss.reset()            // #<StringScanner 0/13 @ "abc12...">
    ss.pointer()          // 0
    ss.scan(/\w+\d+\s+/)  // "abc123 "
    ss.pointer()          // 7
    ss.scan([a-z]+)       // "def"
    ss.pointer()          // 10
    

    setPointer(pos)

    Manually move the scan pointer to pos characters from the beginning of the string. The scan pointer is bounded between zero and the scanning string's length. Returns the position to which the scan pointer was moved. setPointer neither resets nor modifies the last match results.

    ss.reset()         // #<StringScanner 0/13 @ "abc12...">
    ss.setPointer(4)   // 4
    ss.scan(/\d+/)     // "23"
    ss.pointer()       // 6
    ss.setPointer(-4)  // 0
    ss.setPointer(99)  // 13
    

    reset

    Moves the scan pointer back to the beginning of the string being scanned and clears the last match results.

    ss.reset()            // #<StringScanner 0/13 @ "abc12...">
    ss.scanUntil(/(\s)/)  // "abc123 "
    ss.pointer()          // 7
    ss.match()            // "abc123 "
    ss.captures()         // [" "]
    ss.reset()            // #<StringScanner 0/13 @ "abc12...">
    ss.pointer()          // 0
    ss.match()            // null
    ss.captures()         // []
    

    rest

    Returns the portion of the string being scanned after the scan pointer.

    ss.reset()          // #<StringScanner 0/13 @ "abc12...">
    ss.scanUntil(/\s/)  // "abc123 "
    ss.rest()           // "def456"
    

    scan(pattern)

    Note: this method alters last match results

    Attempts to match the given pattern at the position of the scan pointer. Returns the matched string and advances the string pointer upon successful match. A failed match will result in a null value being returned.

    ss.reset()         // #<StringScanner 0/13 @ "abc12...">
    ss.scan(/[a-z]+/)  // "abc"
    ss                 // #<StringScanner 3/13 @ "abc12...">
    ss.scan(/[a-z]+/)  // null
    ss                 // #<StringScanner 3/13 @ "abc12...">
    ss.scan(/[0-9]+/)  // "123"
    ss                 // #<StringScanner 6/13 @ "abc12...">
    

    scanUntil(pattern)

    Note: this method alters last match results

    Attempts to match the pattern against the string being scanned. On a successful match, the scan pointer is advanced to the end of the matched portion of the string and the portion of the string being scanned up to and including the matched string is returned. On a failed match, null is returned.

    ss.reset()         // #<StringScanner 0/13 @ "abc12...">
    ss.scanUntil(/ /)  // "abc123 "
    ss.scanUntil(/f/)  // "def"
    ss.scanUntil(/f/)  // null
    

    skip(pattern)

    Note: this method alters last match results

    Performs a scan, returning the length of the matched string on successful match, null otherwise.

    ss.reset()         // #<StringScanner 0/13 @ "abc12...">
    ss.skip(/[a-z]+/)  // 3
    ss.skip(/[a-z]+/)  // null
    ss.skip(/[0-9]+/)  // 3
    

    skipUntil(pattern)

    Note: this method alters last match results

    Performs a scanUntil, returning the length of the matched string on successful match, null otherwise.

    ss.reset()         // #<StringScanner 0/13 @ "abc12...">
    ss.skipUntil(/ /)  // 7
    ss.skipUntil(/f/)  // 3
    ss.skipUntil(/f/)  // null
    

    string

    Returns the entire string being scanned.

    ss.string()  // "abc123 def456"
    ss.getch()   // "a"
    ss.string()  // "abc123 def456"
    

    terminate / clear

    Advances the scan pointer to the end of the string being scanned and resets the last match results.

    ss.reset()      // #<StringScanner 0/13 @ "abc12...">
    ss.getch()      // "a"
    ss.pointer()    // 1
    ss.terminate()  // #<StringScanner fin>
    ss.pointer()    // 13
    ss.eos()        // true
    ss.match()      // null
    

    Known Issues

    Not really an issue, but StringScanner assumes the global flag (g) is disabled on any RegExp objects passed as patterns to any of its methods. If the global flag is enabled, StringScanner may produce unexpected results.

    Additional Info

    I am always open for feature requests or any feedback. I can be reached at Github.

    Thanks to the Ruby community for the original idea and implementation.

    Keywords

    none

    install

    npm i StringScanner

    Downloadsweekly downloads

    3,418

    version

    0.0.3

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar