Class: NRSER::Char::Special

Inherits:
Object show all
Defined in:
lib/nrser/char/special.rb

Overview

Lil’ structure with useful info and methods for special characters.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(char:, names: [], caret: nil, symbol: nil) ⇒ Special

Instantiate a new ‘Special`.

Parameters:

  • char (String) —

    The actual character as a length 1 UTF-8 string.

  • caret (nil | String) (defaults to: nil) —

    Optional ‘^X` replacement for control characters, see #caret for details.

  • names (Array<#to_s>) (defaults to: []) —

    Optional names this character goes by.

  • symbol (nil | String) (defaults to: nil) —

    Optional printable unicode character replacement, see #symbol for details.



107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/nrser/char/special.rb', line 107

def initialize char:, names: [], caret: nil, symbol: nil
  unless char.is_a?( String ) && char.length == 1
    raise ArgumentError,
      "char must be string of length 1"
  end
  
  @char = char.freeze
  @names = names.map { |n| n.to_s.freeze }.freeze
  @caret = caret.freeze
  @symbol = symbol.freeze
end

Instance Attribute Details

#caret ⇒ nil, String (readonly)

If the character is a control character, the “caret” (‘^X`) style replacement for it.

Examples:

NRSER::Char::NULL.caret
# => '^@'

Returns:

  • (nil) —

    If we don’t have a caret replacement for it.

  • (String) —

    If we have a caret replacement for it.



42
43
44
 
# File 'lib/nrser/char/special.rb', line 42

def caret
  @caret
end

#char ⇒ String (readonly)

The character as a length-one string (UTF-8 encoding).

Returns:



19
20
21
 
# File 'lib/nrser/char/special.rb', line 19

def char
  @char
end

#names ⇒ Array<String> (readonly)

Zero or more strings names for the character.

Returns:



26
27
28
 
# File 'lib/nrser/char/special.rb', line 26

def names
  @names
end

#symbol ⇒ nil, String (readonly) Also known as: picture

A printable Unicode “control picture” character that can be used as a replacement character for control characters.

The nice things about these is they:

  1. Should allow for replacement without changing the Ruby string length*.

    > * I say should because lengths of unicode strings can get funky > across different platforms due to bytes and code points and glyphs > and a bunch of other stuff it seems like only about three people > fully understand.. it often will change the *byte length*, and > who knows how that will go if you start handing it back and forth > to C or something else.

  2. Visually represent the replaced character. You know what it was without having to remember caret or hex representations.

  3. Have a far lower chance of ambiguity versus #carat, #esc_seq, etc. (is a control character or did the string really have a ‘^X` in it?).

Drawbacks:

  1. They’re all gonna be outside the ASCII range, so if you are for some reason stuck with something that can’t Unicode you’re gonna get some gibberish at best, if not outright breakage.

  2. They require font support, or you’re going to probably get one of those little box things that we used to see all over the web before browsers and operating systems managed to get their shit together.

Returns:

  • (nil) —

    If we don’t have an printable symbol for this character.

  • (String) —

    Length 1 printable unicode string.

See Also:



84
85
86
 
# File 'lib/nrser/char/special.rb', line 84

def symbol
  @symbol
end

Instance Method Details

#ascii? ⇒ Boolean

Returns ‘true` if the character code-point is in the ASCII range.

Returns:

  • (Boolean) —

    ‘true` if the character code-point is in the ASCII range.



170
171
172
 
# File 'lib/nrser/char/special.rb', line 170

def ascii?
  char.ascii_only?
end

#control? ⇒ Boolean

Returns ‘true` if the character is a control character.

Returns:

  • (Boolean) —

    ‘true` if the character is a control character.



158
159
160
 
# File 'lib/nrser/char/special.rb', line 158

def control?
  @control ||= NRSER::Char.control?( char )
end

#dec ⇒ Fixnum Also known as: ord

Decimal encoding of the character (with respect to UTF-8).

Equivalent to ‘.char.ord`.

Returns:

  • (Fixnum) 


142
143
144
 
# File 'lib/nrser/char/special.rb', line 142

def dec
  char.ord
end

#esc_seq ⇒ Object 



163
164
165
 
# File 'lib/nrser/char/special.rb', line 163

def esc_seq
  @esc_seq ||= char.inspect[1..-2].freeze
end

#hex ⇒ String

Returns Hex string as it would appear in ‘uXXXX`.

Returns:

  • (String) —

    Hex string as it would appear in ‘uXXXX`.



151
152
153
 
# File 'lib/nrser/char/special.rb', line 151

def hex
  @hex ||= ("%04X" % char.ord).freeze
end

#name ⇒ nil, String

The first of #names (if any).

Returns:



131
132
133
 
# File 'lib/nrser/char/special.rb', line 131

def name
  names[0]
end

#replace(string, with: :symbol) ⇒ String

Replace all occurrences of #char in the string.

Parameters:

  • string (String) —

    String to replace this character in.

  • with (Symbol | #to_s) (defaults to: :symbol) —

    What to replace the character with:

    1. Symbol - this method will be called on the instance and the ‘#to_s` of the response will be used.

    2. ‘#to_s` - string value will be used.

Returns:



191
192
193
194
 
# File 'lib/nrser/char/special.rb', line 191

def replace string, with: :symbol
  with = public_send( with ) if with.is_a?( Symbol )
  string.gsub char, with.to_s
end