Difference between revisions of "ObjCParser"

From Lazarus wiki
Jump to navigationJump to search
m (Category Mac OS X added)
m (→‎Type replacement: Asterix -> asterisk)
 
(8 intermediate revisions by 6 users not shown)
Line 1: Line 1:
ObjCparser is the tool that helps to convert obj-c header to FPC headers as described at [[PasCocoa]]
+
{{LanguageBar}}
  
 +
== Overview ==
 +
ObjCparser is the tool that helps to convert Objective-C headers to FPC headers as described at [[PasCocoa]]
  
Currently ObjCParser supports Objective-C 1.0 language specification. (Objective-C 2.0 properties are not yet supported).
+
Currently, the ObjCParser supports the Objective-C 1.0 language specification. (Objective-C 2.0 properties are not yet supported).
  
ObjCParser is available at PasCocoa/Parser folder  
+
== Installation ==
 +
ObjCParser is available from the PasCocoa/Parser folder:
  
SVN: https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/bindings/pascocoa/parser/
+
SVN: https://sourceforge.net/p/lazarus-ccr/svn/475/tree/bindings/pascocoa/parser/
  
 
+
== Usage ==
Command line usage is the following:
+
The command line usage of the Parser is the following:
  
 
objcparser [switches] [headername.h]  
 
objcparser [switches] [headername.h]  
Line 21: Line 24:
 
-uini (setting file to write to updated files. Type definition information [TypeDefs] is written to the specified file  )
 
-uini (setting file to write to updated files. Type definition information [TypeDefs] is written to the specified file  )
  
-noout (.inc files are not generated, though config file (is still written, if specified)
+
-noout (.inc files are not generated. However, if specified, the config file is still written)
  
 
=== Configuration File Sections ===
 
=== Configuration File Sections ===
  
Configuration file uses simple .INI file format, so it can be easily edited by any editor available.
+
The configuration file uses the simple .INI file format. So, it can be easily edited by any editor available.
  
== Common flags ==
+
=== Common flags ===
  
Following parsing settings are defined at [Common] section
+
Following parsing settings are defined in the [Common] section
  
 
* mainunit=mainunitname
 
* mainunit=mainunitname
Line 36: Line 39:
 
   mainunit=HelloWorld.pas
 
   mainunit=HelloWorld.pas
  
would result, each .inc generated file to contain
+
As a result, each .inc generated file contains
<delphi>
+
<syntaxhighlight lang="pascal">
 
{$mainunit HelloWorld.pas}
 
{$mainunit HelloWorld.pas}
</delphi>
+
</syntaxhighlight>
 
 
 
 
  
 
* ignoreinclude
 
* ignoreinclude
 
specifies, what file #include or #import must be ignored, otherwise file would be also $include-d.
 
specifies, what file #include or #import must be ignored, otherwise file would be also $include-d.
Full file name must be specified, or if file name ends with back slash (CoreFoundation/), all files that belongs to the path would also be ignored (like: CoreFoundation/SomeFile.h,  CoreFoundation/SomeFile2.h)
+
The full file name must be specified, or if the file name ends with back slash (CoreFoundation/), all files that belongs to the path would also be ignored (like: CoreFoundation/SomeFile.h,  CoreFoundation/SomeFile2.h)
 +
 
 +
Files specified as ignoreinclude value should be space separated.
  
files specified as ignoreinclude value should be space separated.
+
It is possible to define any number of ignoreinclude values, but they must be prefixed whith 'ignoreinclude'.
  
it is possible to define any number of ignoreinclude values, but they must be prefixed whith 'ignoreinclude', for example
+
Example:
 
   [Common]
 
   [Common]
 
   ignoreinclude = "ioctrl.h"
 
   ignoreinclude = "ioctrl.h"
Line 55: Line 58:
 
   ignoreinclude2 = "Foundation/ MyLib/hello2.h"
 
   ignoreinclude2 = "Foundation/ MyLib/hello2.h"
  
in this case: #include or #import definition containing: "ioctrl.h", "iostd.h", "conio.h" or "MyLib/hello2.h" or any file that is sub-file to "Foundation" or "SomeLib" folders are ignored.
+
in this case: #include or #import definition containing: "ioctrl.h", "iostd.h", "conio.h" or "MyLib/hello2.h" or any file that is a sub-file to "Foundation" or "SomeLib" folders is ignored.
  
There's no difference if <> or "" is used to #include or #import a file.
+
There is no difference whether <> or "" is used to #include or #import a file.
  
== Type replacement ==
+
=== Type replacement ===
  
 
[TypeReplace]
 
[TypeReplace]
Replaces type name (at method params, results, and type structures) with specified type name.
+
Replaces type name (at method params, results, and type structures) with the specified type name.
type replacement can also be specified for type references, for this case type name must end with '*' (asterix)
+
type replacement can also be specified for type references, for this case type the name must end with '*' (asterisk)
  
for example
+
Example:
 
  [TypeReplace]
 
  [TypeReplace]
 
  NSUInteger = Longword;
 
  NSUInteger = Longword;
 
  NSUInteger* = PLongWord;
 
  NSUInteger* = PLongWord;
  
so the following code would be generated
+
This generates the following code:
 
objc:
 
objc:
 
<objc>
 
<objc>
Line 77: Line 80:
  
 
pascal:
 
pascal:
<delphi>
+
<syntaxhighlight lang="pascal">
 
function SomeClass.doSomethingWithNumber(num: PLongword): LongWord;
 
function SomeClass.doSomethingWithNumber(num: PLongword): LongWord;
</delphi>
+
</syntaxhighlight>
  
== Type name definition ==
+
=== Type name definition ===
  
 
[TypeDefs]
 
[TypeDefs]
 
Specifies the type name usage.  
 
Specifies the type name usage.  
  
There're 4 types available:
+
There are 4 types available:
  
* int (any type that can be casted to 4-byte integer)
+
* int (any type that can be cast to a 4-byte integer)
  
* float (float point value: single or double)
+
* float (floating point value: single or double)
  
* struct (any type or structure that cannot be cased to 4 byte integer or larger than 4 bytes)  
+
* struct (any type or structure that cannot be cast to a 4 byte integer or larger than 4 bytes)  
  
 
* objcclass (objective-c class)
 
* objcclass (objective-c class)
  
if type definition is not specified, it's considered to be int-typed.
+
if no type definition is specified, it is considered to be int-typed.
  
this information is critical to select proper objc_msgSend function (implementation section). objcclass types are also replaced with 'objc.id' type to avoid type naming conflicts between pascal and objc class names.
+
this information is critical to select the proper objc_msgSend function (implementation section). objcclass types are also replaced with the 'objc.id' type to avoid type naming conflicts between pascal and objc class names.
  
== Token Replacement ==
+
=== Token Replacement ===
  
 
Token replacement (currently REMOVE ONLY) should be used to get rid of C pre-compiler defined values.   
 
Token replacement (currently REMOVE ONLY) should be used to get rid of C pre-compiler defined values.   
Line 107: Line 110:
  
 
AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER token is usually met
 
AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER token is usually met
by method, function or type declaration. It should be removed, or file is cannot be parsed correctly.
+
by the method, function or type declaration. It should be removed or the file cannot be parsed correctly.
Remember double quotes "" (empty string) must be specified, or parser ignores TokenReplacement
+
Remember, that double quotes "" (empty string) must be specified or the parser ignores TokenReplacement
  
[[Category:Mac OS X]]
+
[[Category:macOS]]
 +
[[Category:Objective-C]]
 +
[[Category:Objective Pascal]]
 +
[[Category:Lazarus-CCR]]

Latest revision as of 12:58, 12 June 2020

English (en)

Overview

ObjCparser is the tool that helps to convert Objective-C headers to FPC headers as described at PasCocoa

Currently, the ObjCParser supports the Objective-C 1.0 language specification. (Objective-C 2.0 properties are not yet supported).

Installation

ObjCParser is available from the PasCocoa/Parser folder:

SVN: https://sourceforge.net/p/lazarus-ccr/svn/475/tree/bindings/pascocoa/parser/

Usage

The command line usage of the Parser is the following:

objcparser [switches] [headername.h]

Supported switches:

-all (any file named *.h is considered a header file and being parsed);

-ini (setting file)

-uini (setting file to write to updated files. Type definition information [TypeDefs] is written to the specified file )

-noout (.inc files are not generated. However, if specified, the config file is still written)

Configuration File Sections

The configuration file uses the simple .INI file format. So, it can be easily edited by any editor available.

Common flags

Following parsing settings are defined in the [Common] section

  • mainunit=mainunitname

defines the main unit specifier to be added to the generated pascal files

 [Common]
 mainunit=HelloWorld.pas

As a result, each .inc generated file contains

{$mainunit HelloWorld.pas}
  • ignoreinclude

specifies, what file #include or #import must be ignored, otherwise file would be also $include-d. The full file name must be specified, or if the file name ends with back slash (CoreFoundation/), all files that belongs to the path would also be ignored (like: CoreFoundation/SomeFile.h, CoreFoundation/SomeFile2.h)

Files specified as ignoreinclude value should be space separated.

It is possible to define any number of ignoreinclude values, but they must be prefixed whith 'ignoreinclude'.

Example:

 [Common]
 ignoreinclude = "ioctrl.h"
 ignoreinclude1 = "iostd.h conio.h SomeLib/"
 ignoreinclude2 = "Foundation/ MyLib/hello2.h"

in this case: #include or #import definition containing: "ioctrl.h", "iostd.h", "conio.h" or "MyLib/hello2.h" or any file that is a sub-file to "Foundation" or "SomeLib" folders is ignored.

There is no difference whether <> or "" is used to #include or #import a file.

Type replacement

[TypeReplace] Replaces type name (at method params, results, and type structures) with the specified type name. type replacement can also be specified for type references, for this case type the name must end with '*' (asterisk)

Example:

[TypeReplace]
NSUInteger = Longword;
NSUInteger* = PLongWord;

This generates the following code: objc: <objc> -(NSUInteger) doSomethingWithNumber: (NSUInteger *) num </objc>

pascal:

function SomeClass.doSomethingWithNumber(num: PLongword): LongWord;

Type name definition

[TypeDefs] Specifies the type name usage.

There are 4 types available:

  • int (any type that can be cast to a 4-byte integer)
  • float (floating point value: single or double)
  • struct (any type or structure that cannot be cast to a 4 byte integer or larger than 4 bytes)
  • objcclass (objective-c class)

if no type definition is specified, it is considered to be int-typed.

this information is critical to select the proper objc_msgSend function (implementation section). objcclass types are also replaced with the 'objc.id' type to avoid type naming conflicts between pascal and objc class names.

Token Replacement

Token replacement (currently REMOVE ONLY) should be used to get rid of C pre-compiler defined values.

[TokenReplace]
AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER=""

AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER token is usually met by the method, function or type declaration. It should be removed or the file cannot be parsed correctly. Remember, that double quotes "" (empty string) must be specified or the parser ignores TokenReplacement