StringPattern

With this gem you can easily generate strings supplying a very simple pattern. Also you can validate if a text fulfill an specific pattern or even generate a string following a pattern and returning wrong length, value... for testing your applications.

Installation

Add this line to your application's Gemfile:

gem 'string_pattern'

And then execute:

$ bundle

Or install it yourself as:

$ gem install string_pattern

Usage

What is a string pattern?

A pattern is a string where we supply these elements "a-b:c" where a is min_length, b is max_length (optional) and c is a set of symbol_type

min_length: minimum length of the string

max_length (optional): maximum length of the string. If not provided, the result will be with the min_length provided

symbol_type: The type of the string we want.
    x: from a to z (lowercase)
    X: A to Z (capital letters)
    L: A to Z and a to z
    T: National characters defined on StringPattern.national_chars
    n or N: for numbers. 0 to 9
    $: special characters, $%&#...  (includes blank space)
    _: blank space
    *: all characters
    0: empty string will be accepted.  It needs to be at the beginning of the symbol_type string
    @: It will generate a valid email following the official algorithm. It cannot be used with other symbol_type

How to generate a string following a pattern

To generate a string following a pattern you can do it using directly the StringPattern class or the generate method in the class, be aware you can always use also the alias method: gen


    require 'string_pattern'

    #StringPattern class
    p StringPattern.generate "10:N"
    #>3448910834
    p StringPattern.gen "5:X"
    #>JDDDK

    #String class
    p "4:Nx".gen
    #>xaa3

    #Symbol class
    p :"10:T".generate
    #>AccBdjklñD

    #Array class
    p [:"3:N", "fixed", :"3:N"].gen
    #>334fixed920
    p "(,3:N,) ,3:N,-,2:N,-,2:N".split(',').generate 
    #>(937) 980-65-05

    #Kernel
    p gen "3:N"
    #>443

Custom characters

Also it's possible to provided the characters we want. To do that we'll use the symbol_type [characters]

If we want to add the character ] we have to write ]]

Examples

# four chars from the ones provided: asDF9
p "4:[asDF9]".gen    #> aaaa, asFF, 9sFD

# from 2 to 20 chars, capital and lower chars (Xx) and also valid the characters $#6
p "2-20:[$#6]Xx".gen    #> aaaa, asFF, 66, B$DkKL#9aDD

# four chars from these: asDF]9
p "4:[asDF]]9]".gen    #> aa]a, asFF, 9s]D

Required characters or symbol types

We'll use the symbol / to specify which characters or symbols we want to be included on the resulting string as required values /symbols or characters/

If we need to add the character / we'll use //

Examples:

# four characters. optional: capitals and numbers, required: lower
"4:XN/x/".gen    # aaaa, FF9b, j4em, asdf, ADFt

# from 6 to 15 chars. optional: numbers, capitals and the chars $ and Æ. required the chars: 23abCD
"6-15:[/23abCD/$Æ]NX".gen    # bCa$D32, 32DJIOKLaCb, b23aD568C

# from 4 to 9 chars. optional: numbers and capitals. required: lowers and the characters $ and 5
"4-9:[/$5/]XN/x/".generate    # aa5$, F5$F9b, j$4em5, a5sdf$, $ADFt5

Excluded characters

If we want to exclude a few characters in the result, we'll use the symbol %characters%

If you need to exclude the character %, you should use %%

Examples:

# from 2 to 20 characters. optional: Numbers and characters A, B and C. excluded: the characters 8 and 3
"2-20:[%83%ABC]N".gen    # B49, 22900, 9CAB, 22, 11CB6270C26C4572A50C

# 10 chars. optional: Letters (capital and lower). required: numbers. excluded: the characters 0 and WXYzZ
"10:L/n/[%0WXYzZ%]".gen    # GoO2ukCt4l, Q1Je2remFL, qPg1T92T2H, 4445556781

Not fulfilling a pattern

If we want our resulting string doesn't fulfill the pattern we supply, then we'll use the symbol ! at the beginning

Examples:

"!4:XN/x/".gen    # a$aaa, FF9B, j4DDDem, as, 2345

"!10:N".gen     # 123, 34899Add34, 3434234234234008, AAFj#kd2x

Generate a string with specific expected errors

Usually for testing purposes you need to generate strings that don't fulfill an specific pattern, then you can supply as a parameter expected_errors (alias: errors)

The possible values you can specify is one or more of these ones: :length, :min_length, :max_length, :value, :required_data, :excluded_data, :string_set_not_allowed

:length: wrong length, minimum or maximum
:min_length: wrong minimum length
:max_length: wrong maximum length
:value: wrong resultant value
:required_data: the output string won't include all necessary required data. It works only if required data supplied on the pattern.
:excluded_data: the resultant string will include one or more characters that should be excluded. It works only if excluded data supplied on the pattern.
:string_set_not_allowed: it will include one or more characters that are not supposed to be on the string.

Examples:

"10-20:N".gen errors: [:min_length]
#> 627, 098262, 3408

"20:N".gen errors: [:length, :value]
#> |13, tS1b)r-1)<RT65202eTo6bV0g~, 021400323<2ahL0NP86a698063*56076

"10:L/n/".gen errors: [:value]
#> 1hwIw;v{KQ, mpk*l]!7:!, wocipgZt8@

Validate if a string is following a pattern

If you need to validate if a specific text is fulfilling the pattern you can use the validate method.

If a string pattern supplied and no other parameters supplied the output will be an array with the errors detected.

Possible output values, empty array (validation without errors detected) or one or more of: :min_length, :max_length, :length, :value, :string_set_not_allowed, :required_data, :excluded_data

In case an array of patterns supplied it will return only true or false

Examples:

#StringPattern class
StringPattern.validate((text: "This text will be validated", pattern: :"10-20:Xn")
#> [:max_length, :length, :value, :string_set_not_allowed]

#String class
"10:N".validate "333444"
#> [:min_length, :length]

#Symbol class
:"10:N".validate("333444")
#> [:min_length, :length]

#Array class
["5:L","3:xn","4-10:n"].validate "DjkljFFc343444390"
#> false

If we want to validate a string with a pattern and we are expecting to get specific errors, you can supply the parameter expected_errors (alias: errors) or not_expected_errors (aliases: non_expected_errors, not_errors).

In this case the validate method will return true or false.

Examples:

"10:N".val "3445", errors: [:min_length]
#> true

"10:N/[09]/".validate "4434039440", errors: [:value]
#> false

"10-12:XN/x/".validate "FDDDDDAA343434", errors: [:max_length, :required_data]
#> true

Configure

SP_ADD_TO_RUBY

This gem adds the methods generate (alias: gen) and validate (alias: val) to the Ruby classes: String, Array and Symbol.

Also adds the method generate (alias: gen) to Kernel. By default (true) it is always added.

In case you don't want to be added, just before requiring the library set:

SP_ADD_TO_RUBY = false
require 'string_pattern'

In case it is set to true (default) then you will be able to use:

require 'string_pattern'

#String object
"20-30:@".gen 
#>[email protected]

"10:L/N/[/-./%d%]".validate("12ds6f--.s") 
#>[:value, :string_set_not_allowed]

"20-40:@".validate(my_email)

#Kernel
gen "10:N"
#>3433409877

#Array object
"(,3:N,) ,3:N,-,2:N,-,2:N".split(",").generate 
#>(937) 980-65-05

%w{( 3:N ) 1:_ 3:N - 2:N - 2:N}.gen 
#>(045) 448-63-09

["1:L", "5-10:LN", "-", "3:N"].gen 
#>zqWihV-746

national_chars

To specify which national characters will be used when using the symbol type: T, you use StringPattern.national_chars, by default is the English alphabet

StringPattern.national_chars = (('a'..'z').to_a + ('A'..'Z').to_a).join + "áéíóúÁÉÍÓÚüÜñÑ"
"10-20:Tn".gen #>AAñ34Ef99éNOP

optimistic

If true it will check on the strings of the array positions supplied if they have the pattern format and assume in that case that is a pattern. If not it will assume the patterns on the array will be supplied as symbols. By default is set to true.

StringPattern.optimistic = false
["5:X","fixedtext", "3:N"].generate
#>5:Xfixedtext3:N
[:"5:X","fixedtext", :"3:N"].generate
#>AUJKJfixedtext454

StringPattern.optimistic = true
["5:X","fixedtext", "3:N"].generate
#>KKDMEfixedtext344
[:"5:X","fixedtext", :"3:N"].generate
#>SAAERfixedtext988

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/marioruiz/string_pattern.

License

The gem is available as open source under the terms of the MIT License.