BlackStack Core

This gem has been designed as a part of the BlackStack framework.

It has some commons functions that are needed for most of all the BlackStack projects.

I ran tests on:

Ubuntu 18.04,
Ubuntu 20.04, and
Windows 7 only.

Email to me if you want to collaborate.

Outline

Installation
Sandbox
Internal API
Break Points
Passwords Validation
GUIDs Validation
Filenames Validation
Emails Validation
Domains Validation
Phone Numbers Validation
URLs Validation
Integers Validation
SQL Date-Times Validation
GUID Normalization
SQL Encoding
Spintax Validation
Spintax Errors
Spintax Sampling
Numbers Labeling
Time Spent Labeling
Exceptions Encoding
Encoding Strings

1. Installation

gem install blackstack-core

Require blackstack-core in your Ruby scripts.

require 'blackstack-core

2. Sandbox

This function returns true if there is a .sandbox file in the current folder ./.

It is often used by my.saas and by many micro-services, to switch configurations between development environment and production environment.

You can create the .sandbox file using the touch command, like is shown below:

touch .sandbox

You can check if the .sandbox file exists, using the Ruby code below.

puts BlackStack.sandbox?
# => true

3. Internal API

This module is used by my.saas and by many micro-services for internal communication between them.

This module is to register the API key and URL of the my.saas, where all micro-services must submit the results of their jobs.

# Setup connection to the API, in order get micro-services requesting and pushing data from/to the my.saas.
#
BlackStack::API::set_client({
  :api_key => '118f3c32-****-****-****-************', 
  :api_protocol => BlackStack.sandbox? ? 'http' : 'https',
  :api_domain => BlackStack.sandbox? ? '127.0.0.1' : 'connectionsphere.com', 
  :api_port => BlackStack.sandbox? ? '3000' : '443',
})

Getting the api-key anywhere:

puts BlackStack::API.api_key
# => 118f3c32-****-****-****-************

Getting secure API URL:

puts BlackStack::API.api_url
# => https://connectionspher.com:443

Getting secure API less secure URL:

puts BlackStack::API.api_less_secure_url
# => http://connectionspher.com:3000

4. Break Points

The BlackStack::Debugging can be configured to enable or disable Pry's binding.pry breakpoints.

binding.pry can be invoked in the middle of a running program.

It opens a Pry session at the point it's called and makes all program state at that point available.

When the session ends the program continues with any modifications you made to it.

The binding.pry works only if BlackStack::Debugging::allow_breakpoints has not been set as false.

If BlackStack::Debugging::allow_breakpoints has been set as false, then BlackStack::Debugging does a monkey-patch to that Pry's binding.pry method.

Example:

require_relative 'blackstack-core'

BlackStack::Debugging.set({
    # set this to false to do a monkey-patch into the `binding.pry` method,
    # in order to disable the breakpoint functionality. 
    # 
    # activate this in your development environment only.
    # never activate it in production.
    :allow_breakpoints => true, # it is false by default
    # activate this to do a `print "Breakpoint are not allowed"` when calling `binding.pry` but `allow_breakpoints` is `false`
    :verbose => true, # it is false by default
})

(1..100).each do |i|
  binding.pry if i == 50
  puts i
end

The goal of using BlackStack::Debugging instead of the original binding.pry function, is to keep the brakpoints in your source off when running on production.

To accomplish with that, we combine BlackStack::Debugging with BlackStack.sandbox?.

Example:

require_relative 'blackstack-core'

BlackStack::Debugging.set({
    # set this to false to do a monkey-patch into the `binding.pry` method,
    # in order to disable the breakpoint functionality. 
    # 
    # activate this in your development environment only.
    # never activate it in production.
    :allow_breakpoints => BlackStack.sandbox?, # it is false by default
    # activate this to do a `print "Breakpoint are not allowed"` when calling `binding.pry` but `allow_breakpoints` is `false`
    :verbose => true, # it is false by default
})

5. Passwords Validation

Use the password? method to check if a password meets with stregth standard of BlackStack.

require 'blackstack-core'

# returns true if the string meets all the security requirements for a password
puts ""
puts "Passwords"
a = ['Hello', 'HelloWorld12$3']
a.each { |s|
  print "'#{s}'.password?... "
  puts s.password?.to_s  
}

Passwords
'Hello'.password?... false
'HelloWorld12$3'.password?... true

6. GUIDs Validation

require 'blackstack-core'

# returns true if the string match with the regex of a GUID
puts ""
puts "GUIDs"
a = [
  '{331a92c3-5fe1-47a2-a31b-cfa439b5b4f9}',
  '331a92c3-5fe1-47a2-a31b-cfa439b5b4f9',
  '{331A92C3-5FE1-47A2-A31B-CFA439B5B4F9}',
  '331A92C3-5FE1-47A2-A31B-CFA439B5B4F9',
  '331A92C35FE147A2A31BCFA439B5B4F9',
]
a.each { |s|
  print "'#{s}'.guid?... "
  puts s.guid?.to_s  
}

GUIDs
'{331a92c3-5fe1-47a2-a31b-cfa439b5b4f9}'.guid?... true
'331a92c3-5fe1-47a2-a31b-cfa439b5b4f9'.guid?... true
'{331A92C3-5FE1-47A2-A31B-CFA439B5B4F9}'.guid?... true
'331A92C3-5FE1-47A2-A31B-CFA439B5B4F9'.guid?... true
'331A92C35FE147A2A31BCFA439B5B4F9'.guid?... false

7. Filenames Validation

require 'blackstack-core'

# returns true if the string match with the regex of a filename
puts ""
puts "Filenames"
a = [
  'filename.txt',
  'filename',
  'filename.txt.rar',
]
a.each { |s|
  print "'#{s}'.filename?... "
  puts s.filename?.to_s
}

Filenames
'filename.txt'.filename?... true
'filename'.filename?... false
'filename.txt.rar'.filename?... false

8. Emails Validation

require 'blackstack-core'

# returns true if the string match with the regex of an email
puts ""
puts "Emails"
a = [
  '[email protected]',
  '[email protected]',
  'tango',
  'tango@',
]
a.each { |s|
  print "'#{s}'.email?... "
  puts s.email?.to_s
}

Emails
'[email protected]'.email?... true
'[email protected]'.email?... true
'tango'.email?... false
'tango@'.email?... false

9. Domains Validation

require 'blackstack-core'

# returns true if the string match with the regex of a domain
puts ""
puts "Domains"
a = [
  'tango',
  'tango@expandedventure',
  '[email protected]',
  '[email protected]',
  'expandedventure.com',
  'expandedventure.com.ar',
  'https://expandedventure.com.ar',
  'www.expandedventure.com.ar',
  'https://www.expandedventure.com.ar',
]
a.each { |s|
  print "'#{s}'.domain?... "
  puts s.domain?.to_s
}

Domains
'tango'.domain?... false
'tango@expandedventure'.domain?... false
'[email protected]'.domain?... true
'[email protected]'.domain?... true
'expandedventure.com'.domain?... true
'expandedventure.com.ar'.domain?... true
'https://expandedventure.com.ar'.domain?... true
'www.expandedventure.com.ar'.domain?... true
'https://www.expandedventure.com.ar'.domain?... true

10. Phone Numbers Validation

require 'blackstack-core'

# returns true if the string match with the regex of a phone number
puts ""
puts "Phone Numbers"
a = [
  '+54 9 11 5061 2148',
  '545-5561-2148',
  '545-561-2148',
  '545 561 2148',
  '54 545 561 2148',
  '+54 545 561 2148',
  '+54 545-561-2148',
  '+54-545-561-2148',
]
a.each { |s|
  print "'#{s}'.phone?... "
  puts s.phone?.to_s
}

Phone Numbers
'+54 9 11 5061 2148'.domain?... false
'545-5561-2148'.domain?... false
'545-561-2148'.domain?... true
'545 561 2148'.domain?... true
'54 545 561 2148'.domain?... true
'+54 545 561 2148'.domain?... true
'+54 545-561-2148'.domain?... true
'+54-545-561-2148'.domain?... true

11. URLs Validation

require 'blackstack-core'

# returns true if the string match with the regex of a URL
puts ""
puts "URLs"
a = [
  'tango',
  'tango@expandedventure',
  '[email protected]',
  '[email protected]',
  'expandedventure.com',
  'expandedventure.com.ar',
  'https://expandedventure.com.ar',
  'www.expandedventure.com.ar',
  'https://www.expandedventure.com.ar',
]
a.each { |s|
  print "'#{s}'.url?... "
  puts s.url?.to_s
}

URLs
'tango'.url?... false
'tango@expandedventure'.url?... false
'[email protected]'.url?... true
'[email protected]'.url?... true
'expandedventure.com'.url?... true
'expandedventure.com.ar'.url?... true
'https://expandedventure.com.ar'.url?... true
'www.expandedventure.com.ar'.url?... true
'https://www.expandedventure.com.ar'.url?... true

12. Integers Validation

require 'blackstack-core'

# returns true if the string match with the regex of a number
puts ""
puts "Fixnums"
a = [
  '5',
  '5.5',
  '5,5',
  '5000',
  '5,000',
  '5.000',
]
a.each { |s|
  print "'#{s.to_s}'.fixnum?... "
  puts s.fixnum?.to_s
}

Fixnums
'5'.fixnum?... true
'5.5'.fixnum?... false
'5,5'.fixnum?... false
'5000'.fixnum?... true
'5,000'.fixnum?... false
'5.000'.fixnum?... false

13. SQL Date-Times Validation

require 'blackstack-core'

# returns true if the string match with the regex of a datetime used in the BlackStack's API
puts ""
puts "SQL DateTimes"
a = [
  '20191106215030',
  '20191106',
  '2019-11-06',
  '2019-11-06 21:50:30',
  '2019-13-06 21:50:30', # invalid month
  '2019-11-06 25:50:30', # invalid hour
  '2019-11-06 21:70:30', # invalid minute
  '2019-11-06 21:50:70', # invalid second
]
a.each { |s|
  print "'#{s.to_s}'.sql_datetime?... "
  puts s.sql_datetime?.to_s
}

SQL DateTimes
'20191106215030'.sql_datetime?... false
'20191106'.sql_datetime?... false
'2019-11-06'.sql_datetime?... false
'2019-11-06 21:50:30'.sql_datetime?... true
'2019-13-06 21:50:30'.sql_datetime?... false
'2019-11-06 25:50:30'.sql_datetime?... false
'2019-11-06 21:70:30'.sql_datetime?... false
'2019-11-06 21:50:70'.sql_datetime?... false

14. GUID Normalization

require 'blackstack-core'

# Rewrite a GUID as a standard (normalized) format.
puts ""
puts "Any GUID -> Normalized Guid"
a = [
  '{331a92c3-5fe1-47a2-a31b-cfa439b5b4f9}',
  '331a92c3-5fe1-47a2-a31b-cfa439b5b4f9',
  '{331A92C3-5FE1-47A2-A31B-CFA439B5B4F9}',
  '331A92C3-5FE1-47A2-A31B-CFA439B5B4F9',
]
a.each { |s|
  print "'#{s}'.to_guid... "
  puts s.to_guid.to_s  
}

Any GUID -> Normalized Guid
'{331a92c3-5fe1-47a2-a31b-cfa439b5b4f9}'.to_guid... 331A92C3-5FE1-47A2-A31B-CFA439B5B4F9
'331a92c3-5fe1-47a2-a31b-cfa439b5b4f9'.to_guid... 331A92C3-5FE1-47A2-A31B-CFA439B5B4F9
'{331A92C3-5FE1-47A2-A31B-CFA439B5B4F9}'.to_guid... 331A92C3-5FE1-47A2-A31B-CFA439B5B4F9
'331A92C3-5FE1-47A2-A31B-CFA439B5B4F9'.to_guid... 331A92C3-5FE1-47A2-A31B-CFA439B5B4F9

15. SQL Encoding

require 'blackstack-core'

# Escape simple-quotes too add the string into literal-string of a dynamic query build into the Ruby code.
# Example: "I'm BlackStack" -> "I''m BlackStack" 
puts ""
puts "Any String -> String with Escaped Quotes"
a = [
  "I'm BlackStack",
  "Hello World!",
]
a.each { |s|
  print "'#{s}'.to_sql... "
  puts s.to_sql.to_s  
}

Any String -> String with Escaped Quotes
'I'm BlackStack'.to_sql... I''m BlackStack
'Hello World!'.to_sql... Hello World!

16. Spintax Validation

require 'blackstack-core'

# 
puts ""
puts "Spintax"
a = [
  "I'm BlackStack",
  "Hello World!",
  "{Hello|Hi} World!",
  "{Hello|Hi|Good {Morning|Afternoon}} World!", # Nexted spintax. Not supported.
  "{Hello|Hi World!", # wrong syntax.
]
a.each { |s|
  print "'#{s}'.spintax?... "
  puts s.spintax?.to_s  
}

Spintax
'I'm BlackStack'.spintax?... false
'Hello World!'.spintax?... false
'{Hello|Hi} World!'.spintax?... true
'{Hello|Hi|Good {Morning|Afternoon}} World!'.spintax?... false
'{Hello|Hi World!'.spintax?... false

17. Spintax Errors

require 'blackstack-core'

# 
puts ""
puts "Spintax"
a = [
  "I'm BlackStack",
  "Hello World!",
  "{Hello|Hi} World!",
  "{Hello|Hi|Good {Morning|Afternoon}} World!", # Nexted spintax. Not supported.
  "{Hello|Hi World!", # wrong syntax.
]
a.each { |s|
  print "'#{s}'.spintax?... "
  puts s.valid_spinning_syntax?.to_s  
}

Spintax
'I'm BlackStack'.spintax?... false
'Hello World!'.spintax?... false
'{Hello|Hi} World!'.spintax?... true
'{Hello|Hi|Good {Morning|Afternoon}} World!'.spintax?... false
'{Hello|Hi World!'.spintax?... false

18. Spintax Sampling

require 'blackstack-core'

# Returns a random spin from a spintax
puts ""
puts "Spin"
a = [
  "{Hello|Hi|Good Morning|Good Afternoon} World!",
  "{Hello|Hi|Good Morning|Good Afternoon} World!",
  "{Hello|Hi|Good Morning|Good Afternoon} World!",
  "{Hello|Hi|Good Morning|Good Afternoon} World!",
]
a.each { |s|
  print "'#{s}'.spin... "
  puts s.spin  
}

Spin
'{Hello|Hi|Good Morning|Good Afternoon} World!'.spin... Good Afternoon World!
'{Hello|Hi|Good Morning|Good Afternoon} World!'.spin... Hi World!
'{Hello|Hi|Good Morning|Good Afternoon} World!'.spin... Hello World!
'{Hello|Hi|Good Morning|Good Afternoon} World!'.spin... Good Morning World!

19. Numbers Labeling

require 'blackstack-core'

# Converts number to a string with a format like xx,xxx,xxx.xxxx 
puts ""
puts "Fixnum & Floats -> Screen Friendly Text"
a = [
  64443,
  64443.5454,
]
a.each { |i|
  print "'#{i.to_s}'.to_label... "
  puts i.to_label
}

Fixnum & Floats -> Screen Friendly Text
'64443'.to_label... 64,443
'64443.5454'.to_label... 64,443.5454

20. Time Spent Labeling

Convert FixNum Minutes to String with Description of Time Spent

require 'blackstack-core'

# Converts number to a string with a format like xx,xxx,xxx.xxxx 
puts ""
puts "Fixnum Minutes -> Time Spent (days, hours, minutes)"
a = [
  59,
  60,
  61,
  600,
  601,
  1440,
  1441,
  1500,
  1501,
]
a.each { |i|
  print "Minutes '#{i.to_s}'.to_time_spent... "
  puts i.to_time_spent
}

Fixnum Minutes -> Time Spent (days, hours, minutes)
Minutes '59'.to_time_spent... 59 minutes
Minutes '60'.to_time_spent... 1 hours, 0 minutes
Minutes '61'.to_time_spent... 1 hours, 1 minutes
Minutes '600'.to_time_spent... 10 hours, 0 minutes
Minutes '601'.to_time_spent... 10 hours, 1 minutes
Minutes '1440'.to_time_spent... 1 days, 0 hours
Minutes '1441'.to_time_spent... 1 days, 0 hours
Minutes '1500'.to_time_spent... 1 days, 1 hours
Minutes '1501'.to_time_spent... 1 days, 1 hours

21. Exceptions Encoding

How an exception message.

print 'Do something... '
begin
  raise "An error happened here"
  puts 'done'
rescue => e
  puts e.to_console
end

By default, to_console includes all the backtrace. You can disable it.

print 'Do something... '
begin
  raise "An error happened here"
  puts 'done'
rescue => e
  puts e.to_console(false)
end

If you want to show the backtrace into a webpage, use to_html instead, in order to encode the content properly.

print 'Do something... '
begin
  raise "An error happened here"
  puts 'done'
rescue => e
  puts e.to_html
end

22. Encoding Strings

To show any string into an HTML page, you have to encode it properly.

<%
lesson = 'Use HTML entieties (e.g.: &cent;) and tabas (e.g.: <h1>title</h1>) in your HTML code.'
%>
<h1>Introduction to HTML</h1>
<p><%=lesson%></p>

Change Log

Version
1.1.x	Supporting Ruby 2.2.4
1.2.x	Supporting Ruby 3.1.2 (refer to #3 for more information)

Versioning

We use SemVer for versioning. For the versions available, see the last ruby gem.

Authors

Leandro Daniel Sardi - Initial work - LeandroSardi

License

This project is licensed under the MIT License - see the LICENSE.md file for details

23. OCRA Packaging

The BlackStack::OCRA module provides utilities for working with OCRA, an open-source Ruby-to-exe application packager.

Example:

# Initialize OCRA configuration settings
BlackStack::OCRA.init_settings

24. DateTime Utilities

BlackStack::DateTime provides common functions for handling date and time operations.

24.1 Encoding

The DateTime::Encoding submodule offers methods to format and handle various date and time representations.

Example:

# Format a DateTime object into an SQL-friendly string
puts Time.now.to_sql
# => "YYYY-MM-DD HH:MM:SS"

24.2 Miscellaneous

The DateTime::Misc submodule contains various helper methods for date and time calculations not covered in encoding.

Example:

# Check if a given year is a leap year
puts BlackStack::DateTime::Misc.leap_year?(2024)

25. Number Handling

BlackStack::Number includes functions related to number formatting and presentation.

25.1 Encoding

Number::Encoding offers functionality to convert numbers into human-readable formats, such as with thousands separators or as time spent descriptions.

Example:

# Format a large number with separators
puts 1234567.to_label
# => "1,234,567"

26. String Extensions

BlackStack::Strings extends the String class with additional validation, comparison, and formatting methods.

26.1 SQL Helpers

Strings::SQL provides methods to properly escape strings for use in SQL queries.

Example:

# Escape single quotes for SQL insertion
puts "OReilly".to_sql
# => "OReilly"

26.2 Comparing Strings

Strings::Comparing offers methods to compare strings, such as case-insensitive comparisons.

Example:

# Compare strings case-insensitively
puts "Test".same_as?("test")
# => true

26.3 DateTime Parsing

Strings::DateTime provides methods for parsing and working with date-time strings.

Example:

# Parse a date-time string into a Time object
puts "2021-04-25 14:00:00".to_time
# => 2021-04-25 14:00:00 -0400

26.4 Spintax Handling

Strings::Spinning includes methods for working with spintax, allowing for the generation of varied text from patterns.

Example:

# Spin a spintax string to produce random variations
puts "{Hello|Hi|Hey} there!".spin
# => "Hi there!"

26.5 Miscellaneous

Strings::Misc includes a collection of miscellaneous string-related helper methods.

Example:

# Remove all non-numeric characters from a string
puts "Order #12345".only_numbers

26.6 Appending Content

Strings::Appending offers methods to format and append content to strings effectively.

Example:

# Append a string with a delimiter
puts "Hello".append_with_comma("World")
# => "Hello, World"

27. Networking Utilities

BlackStack::Netting includes methods for handling common networking tasks, such as making HTTP requests or parsing URLs.

Example:

# Perform a simple GET request to an API endpoint
response = BlackStack::Netting.simple_get("http://example.com/api/data")
puts response.body

Name		Name	Last commit message	Last commit date
Latest commit History 103 Commits
examples		examples
gems		gems
lib		lib
.gitignore		.gitignore
README.md		README.md
blackstack-core.gemspec		blackstack-core.gemspec

leandrosardi/blackstack-core

Folders and files

Latest commit

History

Repository files navigation

BlackStack Core

1. Installation

2. Sandbox

3. Internal API

4. Break Points

5. Passwords Validation

6. GUIDs Validation

7. Filenames Validation

8. Emails Validation

9. Domains Validation

10. Phone Numbers Validation

11. URLs Validation

12. Integers Validation

13. SQL Date-Times Validation

14. GUID Normalization

15. SQL Encoding

16. Spintax Validation

17. Spintax Errors

18. Spintax Sampling

19. Numbers Labeling

20. Time Spent Labeling

21. Exceptions Encoding

22. Encoding Strings

Change Log

Versioning

Authors

License

23. OCRA Packaging

24. DateTime Utilities

24.1 Encoding

24.2 Miscellaneous

25. Number Handling

25.1 Encoding

26. String Extensions

26.1 SQL Helpers

26.2 Comparing Strings

26.3 DateTime Parsing

26.4 Spintax Handling

26.5 Miscellaneous

26.6 Appending Content

27. Networking Utilities

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages