/src/wrappers/glib/library/utilities/g_pattern.e

  1indexing
  2	description: "Glob-style pattern matching."
  3	copyright: "[
  4					Copyright (C) 2007 Paolo Redaelli, Glib developers
  5					
  6					This library is free software; you can redistribute it and/or
  7					modify it under the terms of the GNU Lesser General Public License
  8					as published by the Free Software Foundation; either version 2.1 of
  9					the License, or (at your option) any later version.
 10					
 11					This library is distributed in the hope that it will be useful, but
 12					WITHOUT ANY WARRANTY; without even the implied warranty of
 13					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 14					Lesser General Public License for more details.
 15
 16					You should have received a copy of the GNU Lesser General Public
 17					License along with this library; if not, write to the Free Software
 18					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 19					02110-1301 USA
 20			]"
 21
 22class G_PATTERN
 23	-- Glob-style pattern matching - matches strings against patterns
 24	-- containing '*' (wildcard) and '?' (joker).
 25	
 26	-- G_PATTERN match a string against a pattern containing '*' and
 27	-- '?' wildcards with similar semantics as the standard glob()
 28	-- function: '*' matches an arbitrary, possibly empty, string, '?'
 29	-- matches an arbitrary character.
 30
 31	-- Note that in contrast to glob(), the '/' character can be
 32	-- matched by the wildcards, there are no '[...]' character ranges
 33	-- and '*' and '?' can not be escaped to include them literally in
 34	-- a pattern.
 35
 36	-- When multiple strings must be matched against the same pattern,
 37	-- it is better to compile the pattern to a GPatternSpec using
 38	-- `make' and use `match_string' instead of `match_simple'. This
 39	-- avoids the overhead of repeated pattern compilation.
 40
 41inherit
 42		C_STRUCT redefine is_equal, free end
 43		EIFFEL_OWNED redefine free end
 44
 45creation make
 46
 47creation {WRAPPER, WRAPPER_HANDLER} from_external_pointer
 48
 49feature {} -- Creation
 50
 51	make (a_pattern: STRING) is
 52			-- Compiles `a_pattern' into a G_PATTERN.
 53
 54			-- TODO: `a_pattern' should be a zero-terminated UTF-8
 55			-- encoded string.
 56		require pattern_not_void: a_pattern /= Void
 57		do
 58			from_external_pointer(g_pattern_spec_new(a_pattern.to_external))
 59		end
 60
 61feature 
 62	is_equal (another: like Current): BOOLEAN is
 63			-- Compares Current and `another' patterns. Will they match
 64			-- the same set of strings?
 65		do
 66			Result:=(g_pattern_spec_equal(Current.handle,
 67													another.handle)).to_boolean
 68		end
 69
 70	match (a_string: STRING): BOOLEAN is
 71			-- Matches a string against a compiled pattern.
 72
 73			-- TODO: a_string should be an UTF8 string.
 74		
 75			-- TODO: provide a variant of the call the require the
 76			-- reversed string, since there is an algorithm requiring the
 77			-- reverse of the string than in some cases is (much) more
 78			-- efficient. See the comment in feature code for further
 79			-- informations.
 80		require string_not_void: a_string/=Void
 81		do
 82			-- Passing the correct length of the string given is
 83			-- mandatory. The reversed string can be omitted by passing
 84			-- NULL, this is more efficient if the reversed version of
 85			-- the string to be matched is not at hand, as
 86			-- g_pattern_match() will only construct it if the compiled
 87			-- pattern requires reverse matches.
 88
 89			-- Note that, if the user code will (possibly) match a string
 90			-- against a multitude of patterns containing wildcards,
 91			-- chances are high that some patterns will require a
 92			-- reversed string. In this case, it's more efficient to
 93			-- provide the reversed string to avoid multiple
 94			-- constructions thereof in the various calls to
 95			-- g_pattern_match().
 96
 97			-- Note also that the reverse of a UTF-8 encoded string can
 98			-- in general not be obtained by g_strreverse(). This works
 99			-- only if the string doesn't contain any multibyte
100			-- characters. Glib offers the g_utf_strreverse() function to
101			-- reverse UTF-8 encoded strings.
102
103			-- pspec :           a GPatternSpec.
104			-- string_length :   the length of string.
105			-- string :          the UTF-8 encoded string to match.
106			-- string_reversed : the reverse of string or NULL.
107			Result:=(g_pattern_match(handle, a_string.count, a_string.to_external,
108											 default_pointer)).to_boolean
109		end
110
111	match_string (a_string: STRING): BOOLEAN is
112			-- Matches `a_string' against Current compiled pattern. If
113			-- the string is to be matched against more than one pattern,
114			-- consider using `match' instead while supplying the
115			-- reversed string.
116
117			-- TODO: `a_string' should be an UTF-8 encoded string to
118			-- match.
119		require string_not_void: a_string/=Void
120		do
121			Result:=g_pattern_match_string(handle,a_string.to_external).to_boolean
122		end
123	
124	match_simple (a_pattern, a_string: STRING): BOOLEAN is
125			--  Matches `a_string' against `a_pattern' given as a
126			--  string. If this function is to be called in a loop, it's
127			--  more efficient to compile the pattern once with `make'
128			--  and call `match_string' repetively.
129
130			-- TODO: `a_pattern': the UTF-8 encoded pattern.
131
132			-- TODO: `a_string': the UTF-8 encoded string to match.
133		require
134			pattern_not_void: a_pattern/=Void
135			string_not_void: a_string/=Void
136		do
137			Result:=g_pattern_match_simple(a_pattern.to_external, a_string.to_external).to_boolean
138		end
139
140feature {} -- External calls
141
142	g_pattern_spec_new (a_pattern: POINTER): POINTER is
143			--  GPatternSpec* g_pattern_spec_new (const gchar *pattern);
144		external "C use <glib.h>"
145		end
146
147	free (a_pattern: POINTER) is
148			--  void g_pattern_spec_free (GPatternSpec *pspec);
149		external "C use <glib.h>"
150		alias "g_pattern_spec_free"
151		end
152
153	g_pattern_spec_equal (a_pspec1,a_pspec2: POINTER): INTEGER is
154			--  gboolean g_pattern_spec_equal (GPatternSpec *pspec1,
155			--  GPatternSpec *pspec2);
156		external "C use <glib.h>"
157		end
158
159	g_pattern_match (a_pspec: POINTER; a_string_length: INTEGER; a_string, a_string_reversed: POINTER): INTEGER is
160			-- gboolean g_pattern_match (GPatternSpec *pspec, guint
161			-- string_length, const gchar *string, const gchar
162			-- *string_reversed);
163		external "C use <glib.h>"
164		end
165
166	g_pattern_match_string (a_pspec, a_string: POINTER): INTEGER is
167			--  gboolean g_pattern_match_string (GPatternSpec *pspec,
168			--  const gchar *string);
169		external "C use <glib.h>"
170		end
171
172	g_pattern_match_simple (a_pattern,a_string: POINTER): INTEGER is
173			--  gboolean g_pattern_match_simple (const gchar *pattern,
174			--  const gchar *string);
175		external "C use <glib.h>"
176		end
177
178feature -- size
179	struct_size: INTEGER is
180		external "C inline use <glib.h>"
181		alias "sizeof(GPatternSpec)"
182		end
183
184end -- class class G_PATTERN
185