module Net::IMAP::StringPrep - net-imap: Ruby Standard Library Documentation

# module Net::IMAP::StringPrep

Regexps and utility methods for implementing stringprep profiles. The StringPrep algorithm is defined by RFC-3454. Each codepoint table defined in the RFC-3454 appendices is matched by a Regexp defined in this module.

### Public Class Methods

[](table) click to toggle source

Returns a Regexp matching the given `table` name.

    # File net-imap-0.5.4/lib/net/imap/stringprep.rb, line 49
    def self.[](table)
      Tables::REGEXPS.fetch(table)
    end

### Public Instance Methods

check_bidi!(string, c_8: false, profile: nil) click to toggle source

Checks that `string` obeys all of the “Bidirectional Characters” requirements in RFC-3454, §6:

- The characters in StringPrep["C.8"] MUST be prohibited

- If a string contains any RandALCat character, the string MUST NOT contain any LCat character.

- If a string contains any RandALCat character, a RandALCat character MUST be the first character of the string, and a RandALCat character MUST be the last character of the string.

This is usually combined with `check_prohibited!`, so table “C.8” is only checked when `c_8: true`.

Raises either `ProhibitedCodepoint` or `BidiStringError` unless all requirements are met. `profile` is an optional string which will be added to any exception that is raised (it does not affect behavior).

    # File net-imap-0.5.4/lib/net/imap/stringprep.rb, line 144
    def check_bidi!(string, c_8: false, profile: nil)
      check_prohibited!(string, "C.8", profile: profile) if c_8
      if Tables::BIDI_FAILS_REQ2.match?(string)
        raise BidiStringError.new(
          Tables::BIDI_DESC_REQ2, string: string, profile: profile,
        )
      elsif Tables::BIDI_FAILS_REQ3.match?(string)
        raise BidiStringError.new(
          Tables::BIDI_DESC_REQ3, string: string, profile: profile,
        )
      end
    end

check_prohibited!(string, *tables, bidi: false, unassigned: "A.1", stored: false, profile: nil) click to toggle source

Checks `string` for any codepoint in `tables`. Raises a `ProhibitedCodepoint` describing the first matching table.

Also checks bidirectional characters, when `bidi: true`, which may raise a `BidiStringError`.

`profile` is an optional string which will be added to any exception that is raised (it does not affect behavior).

    # File net-imap-0.5.4/lib/net/imap/stringprep.rb, line 104
    def check_prohibited!(string,
                          *tables,
                          bidi: false,
                          unassigned: "A.1",
                          stored: false,
                          profile: nil)
      tables  = Tables::TITLES.keys.grep(/^C/) if tables.empty?
      tables |= [unassigned] if stored
      tables |= %w[C.8] if bidi
      table   = tables.find {|t|
        case t
        when String then Tables::REGEXPS.fetch(t).match?(string)
        when Regexp then t.match?(string)
        else raise ArgumentError, "only table names and regexps can be checked"
        end
      }
      if table
        raise ProhibitedCodepoint.new(
          table, string: string, profile: profile
        )
      end
      check_bidi!(string, profile: profile) if bidi
    end

map_tables!(string, *tables) click to toggle source

    # File net-imap-0.5.4/lib/net/imap/stringprep.rb, line 88
    def map_tables!(string, *tables)
      tables.each do |table|
        regexp, replacements = Tables::MAPPINGS.fetch(table)
        string.gsub!(regexp, replacements)
      end
      string
    end

stringprep(string, maps:, normalization:, prohibited:, **opts) click to toggle source

> 1. Map – For each character in the input, check if it has a mapping and, if so, replace it with its mapping. This is described in section 3.

> 2. Normalize – Possibly normalize the result of step 1 using Unicode normalization. This is described in section 4.

> 3. Prohibit – Check for any characters that are not allowed in the output. If any are found, return an error. This is described in section 5.

> 4. Check bidi – Possibly check for right-to-left characters, and if any are found, make sure that the whole string satisfies the requirements for bidirectional strings. If the string does not satisfy the requirements for bidirectional strings, return an error. This is described in section 6.

> The above steps MUST be performed in the order given to comply with this specification.

    # File net-imap-0.5.4/lib/net/imap/stringprep.rb, line 76
    def stringprep(string,
                   maps:,
                   normalization:,
                   prohibited:,
                   **opts)
      string = string.encode("UTF-8") # also dups (and raises invalid encoding)
      map_tables!(string, *maps)                     if maps
      string.unicode_normalize!(normalization)       if normalization
      check_prohibited!(string, *prohibited, **opts) if prohibited
      string
    end