Class: DataMetaXtra::FileSys::Perm

Inherits:
Object
  • Object
show all
Defined in:
lib/dataMetaXtra/fileSys.rb

Overview

A set of permissions: any mix of read, write and execute, including all set to false.

Constant Summary collapse

READ_MASK =

POSIX Read permission mask: binary 100

4
WRITE_MASK =

POSIX Write permission mask: binary 010

2
EXEC_MASK =

POSIX Execute permission mask: binary 1

1
STICKY_MASK =

Unix Sticky bit, the S_ISVTX mask (or S_ISTXT in BSD) defined in sys/stat.h. Use with caution because the semantics is fuzzy and, by some is considered obsolete.

01000
USER_ID_EXE_MASK =

Unix S_ISUID flag defined in sys/stat.h which sets the owner’s ID on executable regardless of who actually activates the executable. See this article for details.

04000
GROUP_ID_EXE_MASK =

Unix S_ISGID flag defined in sys/stat.h which sets the owner’s ID on executable regardless of who actually activates the executable. See this article for details.

02000
ALL =

Convenient instance - all perms

Perm.new(true, true, true)
NONE =

Convenient instance - no perms

Perm.new(false, false, false)
R =

Convenient instance - read only

Perm.new(true, false, false)
W =

Convenient instance - write only

Perm.new(false, true, false)
RW =

Convenient instance - read/write

Perm.new(true, true, false)
RX =

Convenient instance - read and exec

Perm.new(true, false, true)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(r, w, x) ⇒ Perm

Returns a new instance of Perm.



67
68
69
 
# File 'lib/dataMetaXtra/fileSys.rb', line 67

def initialize(r, w, x)
    @r, @w, @x = r, w, x
end

Instance Attribute Details

#r ⇒ Boolean

Returns read access, true or false.

Returns:

  • (Boolean) —

    read access, true or false



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/dataMetaXtra/fileSys.rb', line 34

class Perm
    attr_accessor :r, :w, :x

# POSIX Read permission mask: binary 100
    READ_MASK = 4

# POSIX Write permission mask: binary 010
    WRITE_MASK = 2

# POSIX Execute permission mask: binary 1
    EXEC_MASK = 1
=begin rdoc
Unix {http://en.wikipedia.org/wiki/Sticky_bit Sticky bit},
the +S_ISVTX+ mask (or +S_ISTXT+ in BSD) defined in
{http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html sys/stat.h}.
Use with caution because the semantics is fuzzy and, by some is considered obsolete.
=end
    STICKY_MASK = 01000

=begin rdoc
Unix +S_ISUID+ flag defined in {http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html sys/stat.h}
which sets the owner's ID on executable regardless of who actually activates the executable.
See {http://en.wikipedia.org/wiki/Setuid this article for details.}
=end
    USER_ID_EXE_MASK = 04000

=begin rdoc
Unix +S_ISGID+ flag defined in {http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html sys/stat.h}
which sets the owner's ID on executable regardless of who actually activates the executable.
See {http://en.wikipedia.org/wiki/Setuid this article for details.}
=end
    GROUP_ID_EXE_MASK = 02000

    def initialize(r, w, x)
        @r, @w, @x = r, w, x
    end

=begin rdoc
Standard Ruby object equality method for hashes and sets.
=end
    def eql?(other)
        self.r == other.r && self.w == other.w && self.x == other.x
    end

=begin rdoc
Redefine equality operator for simple comparison, not delegated to {#eql?}, code simply repeated here
for speed
=end
    def ==(other)
        self.r == other.r && self.w == other.w && self.x == other.x
    end
=begin rdoc
Creates an instance from textual specification, up to tree letters +r+, +w+, +x+ in any order,
'<tt>r</tt>' for 'read', '<tt>w</tt>' for 'write', '<tt>x</tt>' for 'execute.
Letter present turns the setting on, letter absent turns it off.
@param [String] specs String of letters as described or a Fixnum with usual Posix bitmask: 4 for read, 2 for write, 1 for exec.
@raise [ArgumentError] if the specs contain invalid character when specified as a String or if it does not fall into the range
    between 0 and 7 inclusively if passed as a Fixnum
@return [Perm] instance per the specs
=end
    def self.of(specs)
        result = Perm.new(false, false, false)
        case
            when specs.kind_of?(String)
                specs.each_char { |c|
                    case c
                        when 'r'
                            result.r = true
                        when 'w'
                            result.w = true
                        when 'x'
                            result.x = true
                        else
                            raise ArgumentError, %<Illegal perms letter "#{c}" in the string of "#{specs}">
                    end
                }
            when specs.kind_of?(Fixnum)
                raise ArgumentError, %<Illegal perm mask value of #{specs}> if specs < 0 || specs > 7
                result.r = true if specs & READ_MASK != 0
                result.w = true if specs & WRITE_MASK != 0
                result.x = true if specs & EXEC_MASK != 0
            else
                raise ArgumentError, %<Illegal specs: "#{specs.inspect}">
        end
        result
    end

=begin rdoc
Turns the permission into the 'rwx' format for brevity and serialization
=end
    def toRwx
        result = ''
        result << 'r' if r
        result << 'w' if w
        result << 'x' if x
        result
    end

=begin rdoc
Turns the permission into the bitmask format for brevity and serialization
=end

    def to_i
        result = 0
        result |= READ_MASK if r
        result |= WRITE_MASK if w
        result |= EXEC_MASK if x
        result
    end
=begin rdoc
Convenient instance - all perms
=end
    ALL = Perm.new(true, true, true)

=begin rdoc
Convenient instance - no perms
=end
    NONE = Perm.new(false, false, false)

=begin rdoc
Convenient instance - read only
=end
    R = Perm.new(true, false, false)

=begin rdoc
Convenient instance - write only
=end
    W = Perm.new(false, true, false)

=begin rdoc
Convenient instance - read/write
=end
    RW = Perm.new(true, true, false)

=begin rdoc
Convenient instance - read and exec
=end
    RX = Perm.new(true, false, true)
# Not providing constants for just exec and write+exec, those are not very useful and hardly ever seen.

=begin rdoc
Creates an instance with 3 booleans: read, write, exec
=end
end

#w ⇒ Boolean

Returns execute access, true or false.

Returns:

  • (Boolean) —

    execute access, true or false



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/dataMetaXtra/fileSys.rb', line 34

class Perm
    attr_accessor :r, :w, :x

# POSIX Read permission mask: binary 100
    READ_MASK = 4

# POSIX Write permission mask: binary 010
    WRITE_MASK = 2

# POSIX Execute permission mask: binary 1
    EXEC_MASK = 1
=begin rdoc
Unix {http://en.wikipedia.org/wiki/Sticky_bit Sticky bit},
the +S_ISVTX+ mask (or +S_ISTXT+ in BSD) defined in
{http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html sys/stat.h}.
Use with caution because the semantics is fuzzy and, by some is considered obsolete.
=end
    STICKY_MASK = 01000

=begin rdoc
Unix +S_ISUID+ flag defined in {http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html sys/stat.h}
which sets the owner's ID on executable regardless of who actually activates the executable.
See {http://en.wikipedia.org/wiki/Setuid this article for details.}
=end
    USER_ID_EXE_MASK = 04000

=begin rdoc
Unix +S_ISGID+ flag defined in {http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html sys/stat.h}
which sets the owner's ID on executable regardless of who actually activates the executable.
See {http://en.wikipedia.org/wiki/Setuid this article for details.}
=end
    GROUP_ID_EXE_MASK = 02000

    def initialize(r, w, x)
        @r, @w, @x = r, w, x
    end

=begin rdoc
Standard Ruby object equality method for hashes and sets.
=end
    def eql?(other)
        self.r == other.r && self.w == other.w && self.x == other.x
    end

=begin rdoc
Redefine equality operator for simple comparison, not delegated to {#eql?}, code simply repeated here
for speed
=end
    def ==(other)
        self.r == other.r && self.w == other.w && self.x == other.x
    end
=begin rdoc
Creates an instance from textual specification, up to tree letters +r+, +w+, +x+ in any order,
'<tt>r</tt>' for 'read', '<tt>w</tt>' for 'write', '<tt>x</tt>' for 'execute.
Letter present turns the setting on, letter absent turns it off.
@param [String] specs String of letters as described or a Fixnum with usual Posix bitmask: 4 for read, 2 for write, 1 for exec.
@raise [ArgumentError] if the specs contain invalid character when specified as a String or if it does not fall into the range
    between 0 and 7 inclusively if passed as a Fixnum
@return [Perm] instance per the specs
=end
    def self.of(specs)
        result = Perm.new(false, false, false)
        case
            when specs.kind_of?(String)
                specs.each_char { |c|
                    case c
                        when 'r'
                            result.r = true
                        when 'w'
                            result.w = true
                        when 'x'
                            result.x = true
                        else
                            raise ArgumentError, %<Illegal perms letter "#{c}" in the string of "#{specs}">
                    end
                }
            when specs.kind_of?(Fixnum)
                raise ArgumentError, %<Illegal perm mask value of #{specs}> if specs < 0 || specs > 7
                result.r = true if specs & READ_MASK != 0
                result.w = true if specs & WRITE_MASK != 0
                result.x = true if specs & EXEC_MASK != 0
            else
                raise ArgumentError, %<Illegal specs: "#{specs.inspect}">
        end
        result
    end

=begin rdoc
Turns the permission into the 'rwx' format for brevity and serialization
=end
    def toRwx
        result = ''
        result << 'r' if r
        result << 'w' if w
        result << 'x' if x
        result
    end

=begin rdoc
Turns the permission into the bitmask format for brevity and serialization
=end

    def to_i
        result = 0
        result |= READ_MASK if r
        result |= WRITE_MASK if w
        result |= EXEC_MASK if x
        result
    end
=begin rdoc
Convenient instance - all perms
=end
    ALL = Perm.new(true, true, true)

=begin rdoc
Convenient instance - no perms
=end
    NONE = Perm.new(false, false, false)

=begin rdoc
Convenient instance - read only
=end
    R = Perm.new(true, false, false)

=begin rdoc
Convenient instance - write only
=end
    W = Perm.new(false, true, false)

=begin rdoc
Convenient instance - read/write
=end
    RW = Perm.new(true, true, false)

=begin rdoc
Convenient instance - read and exec
=end
    RX = Perm.new(true, false, true)
# Not providing constants for just exec and write+exec, those are not very useful and hardly ever seen.

=begin rdoc
Creates an instance with 3 booleans: read, write, exec
=end
end

#x ⇒ Object

Returns the value of attribute x.



35
36
37
 
# File 'lib/dataMetaXtra/fileSys.rb', line 35

def x
  @x
end

Class Method Details

.of(specs) ⇒ Perm

Creates an instance from textual specification, up to tree letters r, w, x in any order, ‘r’ for ‘read’, ‘w’ for ‘write’, ‘x’ for ‘execute. Letter present turns the setting on, letter absent turns it off.

Parameters:

  • specs (String) —

    String of letters as described or a Fixnum with usual Posix bitmask: 4 for read, 2 for write, 1 for exec.

Returns:

  • (Perm) —

    instance per the specs

Raises:

  • (ArgumentError) —

    if the specs contain invalid character when specified as a String or if it does not fall into the range between 0 and 7 inclusively if passed as a Fixnum



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/dataMetaXtra/fileSys.rb', line 94

def self.of(specs)
    result = Perm.new(false, false, false)
    case
        when specs.kind_of?(String)
            specs.each_char { |c|
                case c
                    when 'r'
                        result.r = true
                    when 'w'
                        result.w = true
                    when 'x'
                        result.x = true
                    else
                        raise ArgumentError, %<Illegal perms letter "#{c}" in the string of "#{specs}">
                end
            }
        when specs.kind_of?(Fixnum)
            raise ArgumentError, %<Illegal perm mask value of #{specs}> if specs < 0 || specs > 7
            result.r = true if specs & READ_MASK != 0
            result.w = true if specs & WRITE_MASK != 0
            result.x = true if specs & EXEC_MASK != 0
        else
            raise ArgumentError, %<Illegal specs: "#{specs.inspect}">
    end
    result
end

Instance Method Details

#==(other) ⇒ Object

Redefine equality operator for simple comparison, not delegated to #eql?, code simply repeated here for speed



82
83
84
 
# File 'lib/dataMetaXtra/fileSys.rb', line 82

def ==(other)
    self.r == other.r && self.w == other.w && self.x == other.x
end

#eql?(other) ⇒ Boolean

Standard Ruby object equality method for hashes and sets.

Returns:

  • (Boolean) 


74
75
76
 
# File 'lib/dataMetaXtra/fileSys.rb', line 74

def eql?(other)
    self.r == other.r && self.w == other.w && self.x == other.x
end

#to_i ⇒ Object

Turns the permission into the bitmask format for brevity and serialization



136
137
138
139
140
141
142
 
# File 'lib/dataMetaXtra/fileSys.rb', line 136

def to_i
    result = 0
    result |= READ_MASK if r
    result |= WRITE_MASK if w
    result |= EXEC_MASK if x
    result
end

#toRwx ⇒ Object

Turns the permission into the ‘rwx’ format for brevity and serialization



124
125
126
127
128
129
130
 
# File 'lib/dataMetaXtra/fileSys.rb', line 124

def toRwx
    result = ''
    result << 'r' if r
    result << 'w' if w
    result << 'x' if x
    result
end