Creating bindings for C libraries/ru: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		# Введение
2	2
3	3		Эта статья описывает, как подключить и использовать С-библиотеки в языке Паскаль. Для использования библиотек, написанных на языке С вы должны преобразовать все типы данных, функции и переменные в библиотеках в соответствии стандартам языка Паскаль. Выполнить данную операцию можно используя утилиту h2pas (или аналогичное ПО), либо вручную, переписав код.
4	4
5	5		# H2PAS
6	6
7	7		## Обзор
8	8
9	9		[[H2Pas/ru\|H2Pas]] это инструмент, который автоматически переводит C библиотеки. GUI для Lazarus, использующее h2pas и другие инструменты автоматизируют процесс. Он помогает создать набор правил, которые можно использовать чтобы обновить порт, отчего после обновления C библиотеки перевести ее будет намного проще. Приятной особенностью является то, что Мастер h2pas использует временные файлы, поэтому файлы заголовков остаются нетронутыми.
10	10
11	11		## Процесс работы
12	12
13	13		- Найдите C заголовки, которые вы хотите перевести.
14	14		- Создайте папку для работы и придумайте имя для портированной библиотеки.
15	15		- Создайте проект h2pas используя Мастер h2pas.
16	16		- Добавьте заголовочные файлы в проект.
17	17		- Настройте проект h2pas.
18	18		- Запустите мастер.
19	19		- Исправьте ошибки и запустите мастер еще раз.
20	20		- Когда h2pas запустится без ошибок, протестируйте сборку и отформатируйте код.
21	21		- Напишите пару программ для тестов.
22	22		- Опубликуйте порт на lazarus-ccr или на сайте FreePascal.
23	23
24	24		## Установка инструментов
25	25
26	26		Инструмент h2pas поставляется с каждой обычной установкой fpc
27	27
28	28		Установите пакет h2paswizard в IDE Lazarus. Откройте "Package-\>Install/Uninstall Packages", выберите в правом списке пакет H2PasWizard и щёлкните 'Install selection', потом - 'Save and rebuild IDE'. Перезапустите IDE и у вас появится новый пункт меню: Tools -\> h2pas
29	29
30	30		## Получение заголовочных файлов C
31	31
32	32		Заголовочный файл C имеет расширение .h и описывает интерфейс C библиотеки. Обычно их не предоставляют вместе с библиотекой. Для этого нужно скачать исходный код или пакет разработчика библиотеки. Например заголовочные файлы библиотеки gtk находятся в gtk+-devel.
33	33
34	34		### Пример: MPICH2
35	35
36	36		Скачайте mpich2-1.0.3.tar.gz здесь: <http://www-unix.mcs.anl.gov/mpi/mpich2/> и распакуйте его. Файлы .h находятся в mpich2-1.0.3/src/include.
37	37
38	38		Больше информации о MPICH для FPC вы можете найти [[MPICH\|здесь]].
39	39
40	40		## Создание папки для работы, выбор имени
41	41
42	42		Создайте папку с подходящим названием. Имя не должно содержать специальных символов: пробелов, запятых и т.д. Скопируйте файлы .h в эту папку.
43	43
44	44		### Пример: MPICH2
45	45
46	46		Мы будем использовать папку h2p для файлов Pascal. h2p/c_sources будет использоваться для файлов .h.
47	47
48	48		``` bash
49	49		mkdir -p h2p/c_sources
50	50		cp mpich2-1.0.3/src/include/*.h h2p/c_sources/
51	51		```
52	52
53	53		## Создание проекта h2pas с помощью мастера
54	54
55	55		Откройте мастер h2pas: "Tools -\> h2pas". Вы сможете переключаться между окном мастера и другими окнами IDE. Ваш последний проект h2pas откроется автоматически. Чтобы создать новый проект, нажмите "Settings -\> New/Clear settings". Потом нажмите на кнопку "Save settings" и выберете имя файла.
56	56
57	57		Заметка: Если вы открываете мастер в первый раз, то вам нужно будет в меню настроек задать путь к h2pas.exe. Конвертер h2pas находится там-же где и компилятор FreePascal (fpc.exe), если вы скачали FPC вместе с Lazarus, то смотрите в ...\Lazarus\fpc\version\bin. Сохраните настройки чтоб не повторять те же действия снова.
58	58
59	59		### Пример: MPICH2
60	60
61	61		Нажмите "Settings -\> New/Clear settings".Потом нажмите на кнопку "Save settings" и сохраните как h2p/mpi2.h2p.
62	62
63	63		## Add the .h files to the h2pas-project
64	64
65	65		In the "C header files" page you can add/delete the .h files. You can enable/disable .h files to convert only part of the files.
66	66
67	67		### Example: MPICH2
68	68
69	69		Click on "C header files -\> Add .h files ..." and select "mpi.h" and "mpio.h". They will be enabled automatically. Select the mpi.h file and click "Merge all but this", so that the wizard combines all header files into one unit (mpi.pas).
70	70
71	71		## Setup the h2pas options
72	72
73	73		Under "h2pas Options" you can set the parameters for the h2pas program.
74	74
75	75		### Example: MPICH2
76	76
77	77		- Enable -e, -D, -p, -w and disable all others.
78	78		- The -l library path is "mpich".
79	79		- Output extension is ".pas"
80	80		- Output directory is h2pas/, which is the default, so leave it empty
81	81
82	82		## Run the wizard
83	83
84	84		Click on the bottom button "Run h2pas". This will copy the \<example\>.h file to a temporary \<example\>.tmp.h file and run the tools listed under "Before h2pas". Then it runs h2pas to convert the \<example\>.tmp.h into \<example\>.inc or \<example\>.pas or whatever output extension you setup on the h2pas page. Then it runs the tools listed under "After h2pas" on the output files.
85	85
86	86		If h2pas finds a syntax error, the IDE will open the example.tmp.h file and jumps to the error line. h2pas often only reports 'syntax error', which is very unspecific. See [[Common problems when converting C header files]].
87	87
88	88		### Example: MPICH2
89	89
90	90		The h2pas wizard already contains all tools to convert all the specials of this header file, so h2pas runs without errors. But the created unit is not yet ready. Read further.
91	91
92	92		Add the following to the Undefines property:
93	93
94		-	~~` MPI_INCLUDED`\~~
95		-	~~` MPIO_INCLUDE`\~~
96		-	~~` NEEDS_MPI_FINT`\~~
97		-	~~` MPI_BUILD_PROFILING`\~~
98		-	~~` MPICH_SUPPRESS_PROTOTYPES`\~~
99		-	~~` MPI_Wtime`\~~
100		-	~~` HAVE_MPICH2G2`\~~
101		-	~~` FOO`\~~
102		-	~~` HAVE_PRAGMA_HP_SEC_DEF`~~
	94	+	```text
	95	+	MPI_INCLUDED
	96	+	MPIO_INCLUDE
	97	+	NEEDS_MPI_FINT
	98	+	MPI_BUILD_PROFILING
	99	+	MPICH_SUPPRESS_PROTOTYPES
	100	+	MPI_Wtime
	101	+	HAVE_MPICH2G2
	102	+	FOO
	103	+	HAVE_PRAGMA_HP_SEC_DEF
	104	+	```
103	105
104	106		Add the following to the Defines property:
105	107
106		-	~~` MPICH2`\~~
107		-	~~` MPICH_NEW_MPIIO`~~
	108	+	```text
	109	+	MPICH2
	110	+	MPICH_NEW_MPIIO
	111	+	```
108	112
109	113		## Writing your own converter tools
110	114
111	115		### Using the tool "Search and replace"
112	116
113	117		Many things like renaming a variable can be done by the Search and replace tool. Add the tool via the Add new tool button on either the 'Before h2pas' or the 'After h2pas' page. Then set the SearchFor, ReplaceWith, Options and Caption property.
114	118
115	119		### Example: rename an identifier Tguint to guint
116	120
117	121		\| Property \| Value \|
118	122		\|-------------\|-------------------------------\|
119	123		\| Caption \| Rename Tguint to guint \|
120	124		\| SearchFor \| Tguint \|
121	125		\| ReplaceWith \| guint \|
122	126		\| Options \| \[trtMatchCase,trtWholeWord\] \|
123	127
124	128		### Example: rename several identifiers
125	129
126	130		Rename Tguint to guint, Tgulong to gulong, Tgint to gint:
127	131
128	132		Property
129	133
130	134		Value
131	135
132	136		Caption
133	137
134	138		Rename Tguint to guint
135	139
136	140		SearchFor
137	141
138	142		T(guint\|gint\|gulong)
139	143
140	144		ReplaceWith
141	145
142	146		\$1
143	147
144	148		Options
145	149
146	150		\[trtMatchCase,trtWholeWord,trtRegExpr\]
147	151
148	152		### Example: MPICH2
149	153
150	154		#### Removing Makro MPI_DUP_FN
151	155
152	156		The MPI_DUP_FN is defined two times in the mpi C headers. Once as a macro to something that does not exist, and later to a real function. So, the first should be deleted.
153	157
154	158		Add a 'Search and replace' tool to the before H2Pas tools (at the end) with the following settings:
155	159
156	160		Property
157	161
158	162		Value
159	163
160	164		Caption
161	165
162	166		Remove dummy define MPI_DUP_FN
163	167
164	168		Name
165	169
166	170		RemoveDummyDefineMPI_DUP_FN
167	171
168	172		SearchFor
169	173
170	174		^#define\s+MPI_DUP_FN\s+MPIR_Dup_fn
171	175
172	176		ReplaceWith
173	177
174	178		Options
175	179
176	180		\[trtMatchCase,trtRegExpr\]
177	181
178	182		#### Removing typecasts to MPI_DUP_FN
179	183
180	184		Add a 'Search and replace' tool to the before H2Pas tools (at the end) with the following settings:
181	185
182	186		Property
183	187
184	188		Value
185	189
186	190		Caption
187	191
188	192		Remove MPI_DUP_FN Makros
189	193
190	194		Name
191	195
192	196		Remove_MPI_DUP_Func
193	197
194	198		SearchFor
195	199
196	200		^#define .MPI_DUP_FN\).$
197	201
198	202		ReplaceWith
199	203
200	204		Options
201	205
202	206		\[trtMatchCase,trtRegExpr\]
203	207
204	208		#### Removing functions MPIO_Test, PMPIO_Test, MPIO_Wait and PMPIO_Wait
205	209
206	210		The MPIO_Test, PMPIO_Test, MPIO_Wait and PMPIO_Wait functions are defined twice and redefined via macro. So, the functions can be removed:
207	211
208	212		Add a 'Search and replace' tool to the before H2Pas tools (at the end) with the following settings:
209	213
210	214		Property
211	215
212	216		Value
213	217
214	218		Caption
215	219
216	220		Remove Func P?MPIO_(Test\|Wait)
217	221
218	222		Name
219	223
220	224		RemoveFuncP_MPIO_Test_Wait
221	225
222	226		SearchFor
223	227
224	228		^int P?MPIO_(Test\|Wait).*$
225	229
226	230		ReplaceWith
227	231
228	232		Options
229	233
230	234		\[trtMatchCase,trtRegExpr\]
231	235
232	236		## Improving an existing tool
233	237
234	238		You found a bug and want to fix it or you want to extend one of the above tools. Great!
235	239
236	240		Most of the above tools are defined in the h2pasconvert unit, which is part of the h2paswizard package. Basically a tool needs a classname, a description and an Execute method. To test/debug a tool outside the IDE and save a lot of compilation time, see the project components/simpleideintf/examples/testh2pastool.lpi. Compile it and start it on a console/terminal with the filename of a .h file as first command parameter. For example:
237	241
238	242		``` bash
239	243		./testh2pastool files/h2pastest.pas
240	244		```
241	245
242	246		## Writing a custom tool
243	247
244	248		You can write your own conversion tools and register them in the IDE easily. Start a package and a add a new unit (say unit1) for your new class. See the existing tools as example and read the prior section. When you wrote a new tool and tested it with the above simpleideintf project, then register it in the IDE: Add a register procedure to your unit (unit1), like the following (pseudo code):
245	249
246	250		``` pascal
247	251		uses
248	252		Classes, ..., IDETextConverter;
249	253
250	254		type
251	255		TYourToolClass = class(TCustomTextConverterTool)
252	256		public
253	257		class function ClassDescription: string; override;
254	258		function Execute(aText: TIDETextConverter): TModalResult; override;
255	259		end;
256	260
257	261		procedure Register;
258	262
259	263		implementation
260	264
261	265		procedure Register;
262	266		begin
263	267		TextConverterToolClasses.RegisterClass(TYourToolClass);
264	268		end;
265	269		```
266	270
267	271		Do not forget to enable the register checkbox of the unit in the package editor, otherwise the Register procedure will not be called by the IDE. Then install your package in the IDE.
268	272
269	273		## Future work / Missing stuff
270	274
271	275		- A tool to convert static linked procedures to dynamic linked procedure variables
272	276		- A tool to fix functions without parameter names by searching the .c files. This could also add a comment, in which c file it found the function.
273	277		- Find missing identifiers and let the user check which one to comment or replace with base types.
274	278		- Create a list of macro functions, which were half translated.
275	279
276	280		C:
277	281
278	282		``` c
279	283		typedef struct page
280	284		{
281	285		u32int present : 1; // Page present in memory
282	286		u32int rw : 1; // Read-only if clear, readwrite if set
283	287		u32int user : 1; // Supervisor level only if clear
284	288		u32int accessed : 1; // Has the page been accessed since last refresh?
285	289		u32int dirty : 1; // Has the page been written to since last refresh?
286	290		u32int unused : 7; // Amalgamation of unused and reserved bits
287	291		u32int frame : 20; // Frame address (shifted right 12 bits)
288	292		} page_t;
289	293		```
290	294
291	295		Pascal:
292	296
293	297		``` pascal
294	298		type
295	299		Unsigned_7 = 0 .. (1 shl 7) - 1;
296	300		Unsigned_20 = 0 .. (1 shl 20) - 1;
297	301
298	302		type
299	303		page_t = bitpacked record
300	304		present : boolean;
301	305		rw : boolean;
302	306		user : boolean;
303	307		accessed : boolean;
304	308		dirty : boolean;
305	309		unused : Unsigned_7;
306	310		frame : Unsigned_20;
307	311		end;
308	312		```
309	313
310	314		# Convert C to Pascal with lua script
311	315
312	316		I'm impressed by the power of the lua scripting language and how easy it is to do funny things with it.
313	317
314	318		``` lua
315	319		--
316	320		-- Please send any improvement to mingodadATgmailDOTcom.
317	321		--
318	322
319	323		inFileName = arg[1] or 'g:\\tmp\\plua\\clua\\lvm.c'
320	324
321	325		fh = assert(io.open(inFileName))
322	326		cbody = fh:read('*a')
323	327		fh:close()
324	328
325	329		pasbody = cbody
326	330
327	331		function split(str, pat)
328	332		local t = {} -- NOTE: use {n = 0} in Lua-5.0
329	333		local fpat = '(.-)' .. pat
330	334		local last_end = 1
331	335		local s, e, cap = str:find(fpat, 1)
332	336		while s do
333	337		if s ~= 1 or cap ~= '' then
334	338		table.insert(t, cap)
335	339		end
336	340		last_end = e+1
337	341		s, e, cap = str:find(fpat, last_end)
338	342		end
339	343		if last_end <= #str then
340	344		cap = str:sub(last_end)
341	345		table.insert(t, cap)
342	346		end
343	347		return t
344	348		end
345	349
346	350		function trim(s)
347	351		-- from PiL2 20.4
348	352		return (s:gsub('^%s(.-)%s$', '%1'))
349	353		end
350	354
351	355		function trimChars(str, c1, c2)
352	356		return str:gsub('^%' .. c1 .. '(.-)%' .. c2 .. '$', '%1')
353	357		end
354	358
355	359		function getPascalType(cType)
356	360		if cType == 'void' then
357	361		return 'pointer'
358	362		elseif cType == 'int' then
359	363		return 'integer'
360	364		elseif cType == 'short' then
361	365		return 'Shortint'
362	366		elseif cType == 'define' then
363	367		return 'is_define'
364	368		else
365	369		return cType
366	370		end
367	371		end
368	372
369	373		--check var name and type
370	374		--if var starts with a capital letter
371	375		-- add 'T' informt of it
372	376		--if var is preceded by * then add a 'P' for type
373	377
374	378		function checkVarType(aType, aVar)
375	379		aType = getPascalType(aType)
376	380		aType = aType:gsub('^(%u)', 'T%1')
377	381		aVar = aVar:gsub('^(%*)', function(m)
378	382		aType = 'P' .. aType
379	383		return ''
380	384		end)
381	385		aVar = aVar:gsub('(%[[^]]+%])', function(m)
382	386		aType = 'array' .. m .. ' of ' .. aType
383	387		return ''
384	388		end)
385	389		return aType, aVar
386	390		end
387	391
388	392		function varDeclaration(aType, aVar)
389	393		aType, aVar = checkVarType(aType, aVar)
390	394		return aVar .. ' : ' .. aType
391	395		end
392	396
393	397		function checkDeclarationOrGoto(m1, m2, m3)
394	398		if m2 ~= 'goto' then
395	399		return '\n' .. m1 .. varDeclaration(m2, m3) .. ';'
396	400		else
397	401		return '\n' .. m1 .. m2 .. ' ' .. m3 .. ';'
398	402		end
399	403		end
400	404
401	405		function addProcFunc(mtype, mname, mparams, mbody)
402	406		local str, isFunc, rType, k, v
403	407		if mtype == 'void' then
404	408		str = '\nprocedure '
405	409		isFunc = false
406	410		else
407	411		str = '\nfunction '
408	412		isFunc = true
409	413		end
410	414		mtype, mname = checkVarType(mtype, mname)
411	415		local vparams = split(trimChars(mparams, '(',')'), ',')
412	416		str = str .. mname .. '('
413	417
414	418		local tparams = {}
415	419		for k, v in pairs(vparams) do
416	420		local vparam = split(trim(v), ' ')
417	421		if #vparam > 2 then
418	422		table.insert(tparams, vparam[1] .. ' ' .. varDeclaration(vparam[2], vparam[3]))
419	423		else
420	424		--print(vparam[1], vparam[2])
421	425		table.insert(tparams, varDeclaration(vparam[1], vparam[2] or 'is_define'))
422	426		end
423	427		end
424	428
425	429		str = str .. table.concat(tparams, '; ') .. ')'
426	430		if isFunc then
427	431		if mtype == 'int' then
428	432		rType = 'integer'
429	433		else
430	434		rType = mtype
431	435		end
432	436		str = str .. ':' .. rType
433	437		end
434	438
435	439		if mbody then
436	440		local tblLabels = {}
437	441		for v in mbody:gmatch('\n[\t ]([%w_]+)[\t ]:[^=]') do
438	442		if v ~= 'default' then
439	443		table.insert(tblLabels, v)
440	444		end
441	445		end
442	446
443	447		if #tblLabels > 0 then
444	448		str = str .. ';\nlabel\n '.. table.concat(tblLabels, ', ')
445	449		end
446	450
447	451		local declarations = {}
448	452
449	453		mbody = mbody:gsub('(\n[\t ])const[\t ]+([%w_]+)[\t ]+(%?[%w_]+)[\t ]:%=[\t ]([^;\n]+;)','%1 %2 %3 := %4')
450	454
451	455		mbody = mbody:gsub('(\n[\t ])([%w_]+)[\t ]+(%?[%w_]+)[\t ]:%=[\t ]([^;\n]+;)', function(m1, m2, m3, m4)
452	456		table.insert(declarations, varDeclaration(m2, m3) .. ';' )
453	457		return m1 .. m3 .. ' := ' .. m4
454	458		end)
455	459
456	460		mbody = mbody:gsub('\n[\t ]const[\t ]([%w_]+)[\t ]+(%?[%w_]+)[\t ];', function(m1,m2)
457	461		table.insert(declarations, varDeclaration(m1, m2) .. ';')
458	462		return ''
459	463		end)
460	464
461	465		mbody = mbody:gsub('\n([\t ])([%w_]+)[\t ]+(%?[%w_ ,]+);', function(m1,m2,m3)
462	466		if m2 ~= 'goto' then
463	467		table.insert(declarations, varDeclaration(m2, m3) .. ';')
464	468		return ''
465	469		else
466	470		return '\n' .. m1 .. m2 .. ' ' .. m3 .. ';'
467	471		end
468	472		end)
469	473
470	474		if #declarations > 0 then
471	475		local unique_decl = {}
472	476		table.sort(declarations)
473	477		local lastV = ''
474	478		local k2, v2
475	479		for k2,v2 in pairs(declarations) do
476	480		if v2 ~= lastV then
477	481		lastV = v2
478	482		table.insert(unique_decl, v2)
479	483		end
480	484		end
481	485		str = str .. ';\nvar\n '.. table.concat(unique_decl, '\n ') .. '\n'
482	486		else
483	487		str = str .. ';\n'
484	488		end
485	489
486	490		str = str .. 'begin' .. trimChars(mbody, '{','}') .. 'end'
487	491		end
488	492		return str .. ';'
489	493		end
490	494
491	495		--*************************************
492	496		--
493	497		-- Order of substitutions are important
494	498		--
495	499		--*************************************
496	500
497	501		--=assignements statements
498	502		pasbody = pasbody:gsub("([\t ])([%w_]+)[\t ]=[\t ]*([^=;\n]+);", '%1%2 := %3;')
499	503
500	504		--return
501	505		pasbody = pasbody:gsub('([\t ]*)return[\t ]+([^;]+);', '%1exit(%2);')
502	506
503	507		--NULL
504	508		pasbody = pasbody:gsub('([^%w]+)NULL([^%w]+)', '%1nil%2')
505	509
506	510		--void functions to procedure declaratios
507	511		pasbody = pasbody:gsub('([%w_]+)[\t ]+([%w_]+)[\t ](%b())[%s](%b{})', addProcFunc)
508	512		--pasbody = pasbody:gsub('\n([%w_]+)%s+([^%s]+)%s*(%b());', addProcFunc)
509	513
510	514		--const/static
511	515		tblLeaveCommented = {
512	516		'const', 'static'
513	517		}
514	518		for k,v in pairs(tblLeaveCommented) do
515	519		pasbody = pasbody:gsub('([\t ])(' .. v .. ')([\t ])', '%1{%2}%3')
516	520		end
517	521
518	522		--defines to const
519	523		isConstEmmited = false
520	524		function addConst(m1,m2)
521	525		local sm
522	526		sm = ''
523	527		if not isConstEmmited then
524	528		isConstEmmited = true
525	529		sm = '\nconst'
526	530		end
527	531		return sm .. '\n\t' .. m1 .. ' = ' .. m2 .. ';'
528	532		end
529	533
530	534		isConstEmmited = false
531	535		pasbody = pasbody:gsub('\n#define%s+([^%s]+)%s+(%b())', '\nconst %1 = %2;')
532	536		isConstEmmited = false
533	537		pasbody = pasbody:gsub('\n#define%s+([^%s]+)[ \t]+([^%s]+)', '\nconst %1 = %2;')
534	538
535	539		--includes
536	540		tblUses = {}
537	541		pasbody = pasbody:gsub('\n#[ \t]*(include)%s+([^\n]+)', function(m1,m2)
538	542		for w in m2:gmatch('"([^.]+)%..+"') do
539	543		table.insert(tblUses, w)
540	544		end
541	545		return '\n//#' .. m1 .. ' ' .. m2
542	546		end)
543	547		pasbody = '//uses ' .. table.concat(tblUses, ', ') .. ';\n' .. pasbody
544	548
545	549		--defines to compiler directives
546	550		pasbody = pasbody:gsub('\n#([^\n]+)', '\n{$%1}')
547	551
548	552		--comments
549	553		pasbody = pasbody:gsub('\n#', '\n//#')
550	554		pasbody = pasbody:gsub('/%', '(')
551	555		pasbody = pasbody:gsub('%/', ')')
552	556
553	557		--declarations
554	558		pasbody = pasbody:gsub('\n([\t ]*)([%w_]+)[\t ]+([%w_ ,]+);', checkDeclarationOrGoto)
555	559
556	560		--structs
557	561		function parseStruct(m1, m2)
558	562		return '\n' .. m1 .. ' = record\n' .. trimChars(m2, '{', '}') .. '\nend'
559	563		end
560	564		pasbody = pasbody:gsub('\n[\t ]struct[\t ]+([%w_]+)[\t ](%b{})', parseStruct)
561	565
562	566		--if statements
563	567		parseStatementCalled = false
564	568
565	569		function parseStatement(mSpace, mStatement, mCond, mBody)
566	570		parseStatementCalled = true
567	571		local vStatement
568	572		if mStatement == 'if' then
569	573		vStatement = mStatement .. ' ' .. mCond .. ' then'
570	574		elseif mStatement == 'else' then
571	575		return mSpace .. mStatement .. ' begin' .. trimChars(mCond, '{', '}') .. ' end;'
572	576		elseif (mStatement == 'while') then
573	577		vStatement = mStatement .. ' ' .. mCond .. ' do'
574	578		elseif (mStatement == 'for') then
575	579		vStatement = mStatement .. ' ' .. mCond .. ' do'
576	580		--local forArgs = split(trimChars(mCond, '(', ')'), ';')
577	581		--return mSpace .. (forArgs[1] or '') .. ';' .. mSpace ..'while (' ..
578	582		-- (forArgs[2] or 'true') .. ') do' .. mSpace .. 'begin' .. mSpace .. trimChars(mBody, '{', '}') .. '\n' .. mSpace ..
579	583		-- (forArgs[3] or '') .. ';\n' .. mSpace .. 'end;'
580	584		else
581	585		vStatement = mStatement .. ' ' .. mCond .. '\n'
582	586		end
583	587		return mSpace .. vStatement .. ' begin' .. trimChars(mBody, '{', '}') .. 'end;'
584	588		end
585	589
586	590		-- for nested blocks
587	591		parseStatementCalled = true
588	592		while(parseStatementCalled) do
589	593		parseStatementCalled = false
590	594		pasbody = pasbody:gsub('([^%w_])(if)[\t ](%b())[\t ](%b{})', parseStatement)
591	595		end
592	596
593	597		-- else
594	598		pasbody = pasbody:gsub('([\t ]+)(else)[\t ]*(%b{})', parseStatement)
595	599
596	600		pasbody = pasbody:gsub("([^%w_])if[\t ](%b())[\t ]([^;\n]+);", '%1if %2 then %3;')
597	601
598	602		--?: short if
599	603		pasbody = pasbody:gsub("([^?])?([^:;\n]):[\t ]*([^%s;]+);", ' iff(%1, %2, %3) ')
600	604
601	605		--while loop
602	606		-- for nested blocks
603	607		parseStatementCalled = true
604	608		while(parseStatementCalled) do
605	609		parseStatementCalled = false
606	610		pasbody = pasbody:gsub('([^%w_])(while)[\t ](%b())[\t ](%b{})', parseStatement)
607	611		end
608	612
609	613		--for loop
610	614		-- for nested blocks
611	615		parseStatementCalled = true
612	616		while(parseStatementCalled) do
613	617		parseStatementCalled = false
614	618		pasbody = pasbody:gsub('([^%w_])(for)[\t ](%b())%s(%b{})', parseStatement)
615	619		end
616	620
617	621		--do/while
618	622		-- for nested blocks
619	623		parseStatementCalled = true
620	624		while(parseStatementCalled) do
621	625		parseStatementCalled = false
622	626		pasbody = pasbody:gsub("([^%w_])do[\t ](%b{})[\t ]while([^;\n]+);",
623	627		function(m1, m2, m3)
624	628		parseStatementCalled = true
625	629		return m1 .. 'repeat ' .. trimChars(m2, '{', '}') .. 'until not' .. m3
626	630		end)
627	631		end
628	632
629	633		--switch/case statements
630	634
631	635		--begin/end enclose blocks around
632	636		-- for nested blocks
633	637		parseStatementCalled = true
634	638		while(parseStatementCalled) do
635	639		parseStatementCalled = false
636	640		pasbody = pasbody:gsub("([^%w_]case[\t ]+[^:]+)[\t ]:[%s](%b{})",
637	641		function(m1, m2, m3)
638	642		parseStatementCalled = true
639	643		return m1 .. ': begin' .. trimChars(m2, '{', '}') .. 'end;'
640	644		end)
641	645		pasbody = pasbody:gsub("([^%w_]default[\t ]):[%s](%b{})",
642	646		function(m1, m2, m3)
643	647		parseStatementCalled = true
644	648		return m1 .. ': begin' .. trimChars(m2, '{', '}') .. 'end;'
645	649		end)
646	650		end
647	651
648	652		--breaks remove
649	653		pasbody = pasbody:gsub("([^%w_]case[\t ]+[^:]+)[\t ]:[%s](.-)break;", '%1: %2')
650	654
651	655		--case
652	656		pasbody = pasbody:gsub("([^%w_])case[\t ]+([^:]+):", '%1%2:')
653	657
654	658		-- for nested blocks
655	659		parseStatementCalled = true
656	660		while(parseStatementCalled) do
657	661		parseStatementCalled = false
658	662		pasbody = pasbody:gsub("([^%w_])switch[\t ](%b())[\t ](%b{})",
659	663		function(m1, m2, m3)
660	664		parseStatementCalled = true
661	665		return m1 .. 'case ' .. m2 .. ' of ' .. trimChars(m3, '{', '}') .. 'end;'
662	666		end)
663	667		end
664	668
665	669		--pasbody = pasbody:gsub("([\t ])case[\t ]+('.')[\t ]:\n", '%1%2:\n')
666	670		--pasbody = pasbody:gsub("([\t ])case[\t ]+(%d+)[\t ]:\n", '%1%2:\n')
667	671		--pasbody = pasbody:gsub("([\t ])(case)[\t ]+('.')[\t ]:[\t ]*(%b{})", '%1%2 : %3')
668	672
669	673		--pre/pos increments
670	674		-- (n)++ -> PosInc(n)
671	675		pasbody = pasbody:gsub("(%([^%s+]+%))%+%+", 'PosInc%1')
672	676		-- n++ -> PosInc(n)
673	677		pasbody = pasbody:gsub("([^%s*+]+)%+%+", 'PosInc(%1)')
674	678		-- ++(n) -> PreInc(n)
675	679		pasbody = pasbody:gsub("%+%+(%([^%s;+]+%))", 'PreInc%1')
676	680		-- ++*n -> PreInc(n)
677	681		pasbody = pasbody:gsub("%+%+([^%s*;+]+)", 'PreInc(%1)')
678	682
679	683		-- (n)--
680	684		pasbody = pasbody:gsub("(%([^%s-]+%))%-%-", 'PosDec%1')
681	685		-- n*--
682	686		pasbody = pasbody:gsub("([^%s*-]+)%-%-", 'PosDec(%1)')
683	687		-- --(n)
684	688		pasbody = pasbody:gsub("%-%-(%([^%s;-]+%))", 'PreDec%1')
685	689		-- --n
686	690		pasbody = pasbody:gsub("%-%-([^%s;-]+)", 'PreDec(%1)')
687	691
688	692		--boolean operators
689	693		tblBooleanOperators = {
690	694		{'\|\|', 'or'},
691	695		{'&&', 'and'},
692	696		}
693	697		for k,v in pairs(tblBooleanOperators) do
694	698		pasbody = pasbody:gsub('([\t ])' .. v[1] .. '([\t ])', '%1) ' .. v[2] .. ' (%2')
695	699		end
696	700
697	701		--pointers
698	702		pasbody = pasbody:gsub("%->", '.')
699	703		pasbody = pasbody:gsub("%(%*([%w_]+)", '(%1^')
700	704		pasbody = pasbody:gsub("%%([%w_]+)", '%1^^')
701	705		pasbody = pasbody:gsub("&([%w_]+)", '@%1')
702	706		pasbody = pasbody:gsub("%([%w_]+)[\t ]:[\t ]*([%w_]+);", '%1 : ^%2;')
703	707		pasbody = pasbody:gsub("%^char", 'pchar')
704	708		--pasbody = pasbody:gsub("%([%w_]+)[\t ]:=[\t ]*([^;\n]+);", '%1^ := %2;')
705	709
706	710		--bit operators
707	711		tblBitOperators = {
708	712		{'<<', 'shl'},
709	713		{'>>', 'shr'},
710	714		{'\|', 'or'},
711	715		{'&', 'and'},
712	716		{'~', 'not'},
713	717		}
714	718
715	719		for k,v in pairs(tblBitOperators) do
716	720		pasbody = pasbody:gsub('([\t ])' .. v[1] .. '([\t ])', '%1 ' .. v[2] .. ' %2')
717	721		end
718	722
719	723		--==eq operator
720	724		pasbody = pasbody:gsub("([\t ])%=%=([\t ])", '%1 = %2')
721	725
722	726		--!= not eq operator
723	727		pasbody = pasbody:gsub("([\t ])!%=([\t ])", '%1 <> %2')
724	728
725	729		--! unary
726	730		pasbody = pasbody:gsub('([\t ])!([\t ])', '%1 not %2')
727	731
728	732		--blocks
729	733		--pasbody = pasbody:gsub("(%b{})", function(m1) return 'begin' .. trimChars(m1, '{', '}') .. 'end;' end)
730	734		--pasbody = pasbody:gsub("(%b{})", function(m1) return 'begin' .. trimChars(m1, '{', '}') .. 'end;' end)
731	735
732	736		--strings and escaped characters
733	737		tblEscapedCahrs = {
734	738		{'\\"', '"'},
735	739		{'\\\\', '\\'},
736	740		{'\\t', "'#9"},
737	741		{'\\n', "'#10'"},
738	742		{'\\f', "'#12'"},
739	743		}
740	744		pasbody = pasbody:gsub('%b""', function(m1)
741	745		return "'" .. trimChars(m1:gsub("'", "''") , '"', '"') .. "'"
742	746		end)
743	747		for k,v in pairs(tblEscapedCahrs) do
744	748		pasbody = pasbody:gsub(v[1], v[2])
745	749		end
746	750
747	751		--common functions/procedure
748	752		tblOrigFuncNewFunc = {
749	753		{'printf', 'format'},
750	754		{'malloc', 'GetMem'},
751	755		{'free', 'Dispose'},
752	756		{'memcpy', 'Move'},
753	757		}
754	758
755	759		for k,v in pairs(tblOrigFuncNewFunc) do
756	760		pasbody = pasbody:gsub('([\t ]+)' .. v[1] .. '%(', '%1' .. v[2] .. '(')
757	761		end
758	762
759	763		--typedefs
760	764		isTypeEmmited = false
761	765		function addType(m1,m2)
762	766		local sm
763	767		sm = ''
764	768		if not isTypeEmmited then
765	769		isTypeEmmited = true
766	770		sm = '\ntype'
767	771		end
768	772		return sm .. '\n\t' .. m2 .. ' = ' .. m1 .. ';'
769	773		end
770	774		--pasbody = pasbody:gsub('\ntypedef%s+struct%s+([^%s]+)%s+([^;]+)', addType)
771	775		--pasbody = pasbody:gsub('\ntypedef%s+([^%s]+)%s+([^;]-)', addType)
772	776		pasbody = pasbody:gsub('\n[\t ]*typedef[\t ]+struct[\t ]+([%w_]+)[\t ]+([^;]+)', '\n%2 = %1')
773	777		pasbody = pasbody:gsub('\n[\t ]*typedef[\t ]+struct%s+(%b{})%s+([%w_]+);',
774	778		function(m1, m2) return m2 .. ' = record' .. trimChars(m1, '{', '}') .. 'end;' end)
775	779
776	780		-- print the results
777	781		print(pasbody)
778	782		```
779	783
780	784		Here is an example of a c file converted.
781	785
782	786		``` pascal
783	787		//uses lua, llimits, lmem, lstate, lzio;
784	788		(*
785	789		** $Id: lzio.c,v 1.31.1.1 2007/12/27 13:02:25 roberto Exp $
786	790		** a generic input stream interface
787	791		** See Copyright Notice in lua.h
788	792		*)
789	793
790	794		//#include <string.h>
791	795
792	796		{$define lzio_c}
793	797		{$define LUA_CORE}
794	798
795	799		//#include 'lua.h'
796	800
797	801		//#include 'llimits.h'
798	802		//#include 'lmem.h'
799	803		//#include 'lstate.h'
800	804		//#include 'lzio.h'
801	805
802	806		function luaZ_fill(z : PTZIO):integer;
803	807		var
804	808		L : Plua_State;
805	809		buff : Pchar;
806	810		size : size_t;
807	811		begin
808	812		*L := z.L;
809	813		lua_unlock(L);
810	814		buff := z.reader(L, z.data, @size);
811	815		lua_lock(L);
812	816		if (buff = nil ) or ( size = 0) then exit(EOZ);
813	817		z.n := size - 1;
814	818		z.p := buff;
815	819		exit(char2int(PosInc^((z.p))));
816	820		end;
817	821
818	822		function luaZ_lookahead(z : PTZIO):integer;
819	823		begin
820	824		if (z.n = 0) then begin
821	825		if (luaZ_fill(z) = EOZ)
822	826		exit(EOZ);
823	827		else begin
824	828		PosInc(z.n); (* luaZ_fill removed first byte; put back it *)
825	829		z-PosDec(>p);
826	830		end;
827	831		end;
828	832		exit(char2int(z^.p));
829	833		end;
830	834
831	835		procedure luaZ_init(L : Plua_State; z : PTZIO; reader : lua_Reader; data : Ppointer);
832	836		begin
833	837		z.L := L;
834	838		z.reader := reader;
835	839		z.data := data;
836	840		z.n := 0;
837	841		z.p := nil;
838	842		end;
839	843
840	844		(* --------------------------------------------------------------- read --- *)
841	845
842	846		function luaZ_read(z : PTZIO; b : Ppointer; n : size_t):size_t;
843	847		var
844	848		m : size_t;
845	849		begin
846	850		while (n) do begin
847	851		if (luaZ_lookahead(z) = EOZ)
848	852		exit(n); (* exit(number of missing bytes *)
849	853		m = (n <= z.n) ? n : z.n); (* min. between n and z.n *)
850	854		Move(b, z.p, m);
851	855		z.n -= m;
852	856		z.p += m;
853	857		b := (char *)b + m;
854	858		n -= m;
855	859		end;
856	860		exit(0);
857	861		end;
858	862
859	863		(* ------------------------------------------------------------------------ *)
860	864
861	865		function luaZ_openspace(L : Plua_State; buff : PTMbuffer; n : size_t):Pchar;
862	866		begin
863	867		if (n > buff.buffsize) then begin
864	868		if (n < LUA_MINBUFFER) then n := LUA_MINBUFFER;
865	869		luaZ_resizebuffer(L, buff, n);
866	870		end;
867	871		exit(buff.buffer);
868	872		end;
869	873		```
870	874
871	875		# Manual conversion of C headers to Pascal
872	876
873	877		In this case one should utilize ones knowledge of C and Pascal together to make the headers. One can learn how to do the conversion by looking at examples.
874	878
875	879		## Converting constants
876	880
877	881		C:
878	882
879	883		``` c
880	884		#define SOME_CONSTANT 5
881	885		#define ANOTHER_CONSTANT 6
882	886		```
883	887
884	888		Pascal:
885	889
886	890		``` pascal
887	891		const
888	892		SOME_CONSTANT = 5;
889	893		ANOTHER_CONSTANT = 6;
890	894		```
891	895
892	896		## Converting exported routines
893	897
894	898		The most basic routines can be translated like this:
895	899
896	900		C:
897	901
898	902		``` c
899	903		int somekind_of_method(int* param_first, int* param_second)
900	904		void another_method(char*)
901	905		```
902	906
903	907		Pascal:
904	908
905	909		``` pascal
906	910		uses ctypes;
907	911
908	912		const
909	913		MyLib = 'mylib';
910	914
911	915		function somekind_of_method(param_first, param_second: pcint): cint; external MyLib;
912	916		procedure another_method_renamed(param1: PChar); external MyLib name 'another_method';
913	917		```
914	918
915	919		Note that one should use the ctypes unit together with the types that it declares to convert C headers instead of trying to use the basic Pascal types directly. This ensures that the bindings are correct in all platforms, as the C types might have different sizes on different architectures and operating systems.
916	920
917	921		Also, note that pointers to basic C types can be converted to types declared in ctypes, for example, int* is a pointer to a C int, so we can use the type pcint (pointer to a c integer). The C type int can be converted to cint and in Pascal we can shorten the declaration of parameters which are declared one after as folows: "param_first, param_second: pcint".
918	922
919	923		Finally, note that if the return value is void, then we should use a procedure instead of function.
920	924
921	925		See also the [[http://www.freepascal.org/docs-html/ref/refse85.html External Functions]] section of the reference guide.
922	926
923	927		# Publish your bindings on Lazarus-CCR or Free Pascal
924	928
925	929		You can submit your binding code to the Lazarus CCR repository (see e.g. [[Using the Lazarus-ccr SVN repository]]) so others can use (and maintain) it, too. If the bindings are useful for general, cross-platform work, they could be included in the FreePascal distribution as well.
926	930
927	931		# See also
928	932
929	933		- [1](http://gd.tuwien.ac.at/languages/pascal/fpc/docs-pdf/CinFreePascal.pdf) Short tutorial that describes the process of using C and C++ code in FreePascal, including writing of wrapper code
930	934		- [[Common problems when converting C header files]]
931	935		- [[Pascal for C users]]
932	936		- [[Lazarus/FPC Libraries]]
933	937		- [[SWIG]]
934	938
935	939		---
936	940		From the Free Pascal wiki, page "Creating bindings for C libraries/ru", as it stood on 2020-02-12 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history