Developing with Objective Pascal

Part 9: Parsing Objective C Header Files

Introduction
The Main Include File
The Parser Config File
Running the Parser
The Interface Unit
Creating a Patch File

Introduction

You can use Objective C classes in your Pascal app if you have a unit of Objective Pascal declarations that are equivalent to the ObjC header file declarations. Except for very simple ObjC classes, you'll want to use FPC's header file parser to assist in creating this Pascal interface unit. The latest version of the parser can be obtained from here:

iOS_6_Parsing_Status.html

The parser includes the parser input files and interface unit for the ASIHTTPRequest classes, so we'll use those files as examples and go over each file in some depth. The ASIHTTPRequest classes and header files to parse are available here:

http://allseeing-i.com/ASIHTTPRequest

The Main Include File

This is a Pascal include file (.inc) that serves both as a list of header files to parse and a list of nested include files, one per header file, that will be "included" in the interface unit.

The ASIHTTPRequest include file is Asihttp.inc and can be found in the parser's /uikit-skel/src/asihttp folder. You can create your own include file wherever you want and point the parser to it, as described below.

Here's what Asihttp.inc looks like:

{$include ASIHTTPRequest.inc}
{$include ASIHTTPRequestDelegate.inc}
{$include ASIProgressDelegate.inc}
{$include ASICacheDelegate.inc}
{$include ASIFormDataRequest.inc}
{$include ASINetworkQueue.inc}
{$include ASIDownloadCache.inc}
{$include ASIInputStream.inc}
{$include ASIDataDecompressor.inc}
{$include ASIDataCompressor.inc}
{$include ASIAuthenticationDialog.inc}

To save yourself some typing, you can open a Terminal window, change to where the header files are, and use the ls command with the -1 switch (numeric digit "one") to list the header files in a single column. You can then copy and paste this list into your .inc file, add {$include to each line, and change the file extensions from .h to .inc}. For example:

ls -1 *.h
ASIAuthenticationDialog.h
ASICacheDelegate.h
ASIDataCompressor.h
ASIDataDecompressor.h
ASIDownloadCache.h
ASIFormDataRequest.h
ASIHTTPRequest.h
ASIHTTPRequestConfig.h
ASIHTTPRequestDelegate.h
ASIInputStream.h
ASINetworkQueue.h
ASIProgressDelegate.h

This list will be in alphabetical order and you can start out keeping the .inc files in that order too, although you may need to change the order later if you have classes that reference other classes.

Note that there's no include file for ASIHTTPRequestConfig.h - this file does not have anything we need, so we've left it out. Some frameworks or classes will have a small .h file that just includes all the other .h files - you can leave out that file as well.

The Parser Config File

The other parser input file that you'll need to create is a small XML configuration file. This file has the same format as the parser's frameworks.xml file that defines the iOS and OS X system frameworks for the parser. Here's a blank template that you can use:

<?xml version="1.0" encoding="UTF-8" ?>
<frameworks>
  <framework>
    <name></name>
    <root></root>
    <headers></headers>
    <include_pattern></include_pattern>
    <header_pattern></header_pattern>
    <external_macro></external_macro>
    <ignore_lines>
    </ignore_lines>
    <ignore_types></ignore_types>
    <ignore_methods></ignore_methods>
    <replace_types>
    </replace_types>
  </framework>
</frameworks>

Note that even though we're defining these classes like a framework, they don't have to be in a framework. Actually, a framework is just a versioned library in a bundle (folder) with a .framework extension that contains the compiled library, headers and other files. From the point of view of the parser, there isn't much difference.

Here's the filled-in asihttp.xml file, with unused elements deleted (consult frameworks.xml for examples of how those elements are used):

<?xml version="1.0" encoding="UTF-8" ?>
<frameworks>
  <framework>
    <name>asihttp</name>
    <root>/asihttp/Asihttp.inc</root>
    <!-- Change the following path if ASI header files (.h) are located elsewhere --> 
    <headers>/Users/Shared/asi-http-request/Classes</headers>
    <include_pattern>{[$]+include (.*).inc}</include_pattern>
    <header_pattern>^(.*)\.h</header_pattern>
    <external_macro>extern</external_macro>
  </framework>
</frameworks>

It may still not be obvious what these elements should contain, so here's a brief explanation of each one:

name - you'll specify the framework or set of classes on the parser command line using this name.
root - this is the path to the main include file relative to the path specified on the parser command line.
headers - this is the path to the header files.
include_pattern - this is a regular expression that tells the parser what to look for in the include file. You can use the example in most cases.
header_pattern - this is a regular expression that tells the parser what header files to look for. You can use the example in most cases.
external_macro - some frameworks use special macros to indicate external references (for example, UIKIT_EXTERN), but most header files use extern. Knowing the macro allows the parser to skip it, simplifying parsing.

Running the Parser

To see a list of parser switches, run the parser without any switches:

  php parser.php

Here's the command line for parsing the ASIHTTPRequest headers using the two files described above. Enter this all on one line:

  php parser.php -all -frameworks=^foundation,^uikit,asihttp -aux_config=asihttp.xml -root=`pwd`/uikit-skel/src
    -framework_path=/Developer/Platforms/iPhoneOS.Platform/Developer/SDKs/iPhoneOS5.0.sdk/System/Library/Frameworks

Since this is quite a bit to type, it makes sense to put it in a script. See the parse-ios.sh script for examples of how to do this.

Here are the switches used:

-frameworks -- this switch specifies the entry to parse (asihttp), as well as any frameworks it depends on (foundation, uikit). The dependent frameworks can be specified with a "^" prefix to tell the parser to parse them for types, but not to create their .inc files. How do you know what frameworks a set of classes depends on? Just use grep on the header files. For example:
```
 grep "#import" *.h
 
```
If a header file depends on other frameworks, you'll see lines like this:
```
 ASIAuthenticationDialog.h:#import <Foundation/Foundation.h>
 ASIAuthenticationDialog.h:#import <UIKit/UIKit.h>
 
```
-aux_config -- unless you're parsing a framework defined in frameworks.xml, specify your XML configuration file with this switch.
-root -- the path specified here combined with the root from the config file forms the complete path to the main include file; the parser will also create the header .inc files in the same folder as the main include file. `pwd` indicates the current directory when the script was run.
-framework_path -- this specifies the path to the system frameworks; change this if you're parsing with a different SDK.

The Interface Unit

The easiest way to create the interface unit file is to make a copy of one of the interface units included with the parser and modify it. However, you may need to do some sleuthing to determine what all needs to go into this file, as described below for the sections of the Asihttp.pas file.

Linking

unit Asihttp;

{$mode delphi}
{$modeswitch objectivec1}
{$modeswitch cvar}
{$packrecords c}

interface

{$linkframework CFNetwork}
{$linkframework SystemConfiguration}
{$linkframework MobileCoreServices}

{$l libAsihttp.a}  //if have static library, use instead of .o files below}

(*
{$l ASIAuthenticationDialog.o}
{$l ASIDataCompressor.o}
{$l ASIDataDecompressor.o}
{$l ASIDownloadCache.o}
{$l ASIFormDataRequest.o}
{$l ASIHTTPRequest.o}
{$l ASIInputStream.o}
{$l ASINetworkQueue.o}
{$l Reachability.o}
*)

{$IFDEF CPUARM}
  {$linklib libgcc_s.1}
{$ENDIF}

$linkframework - With a framework unit file, use this directive to link to the framework; with a non-framework unit file, use this directive to link to the frameworks that the Objective C classes require. With the ASIHTTPRequest classes, the dependencies are listed here:
http://allseeing-i.com/ASIHTTPRequest/Setup-instructions
Note that the units included in the uses statement (see below) may also do some of the required linking.
$l - To statically link in the compiled Objective C files, specify a static library (see Part 8) or the individual object files.
$linklib - To dynamically link to a library (.dylib), use this directive. With an ASIHTTPRequest ObjC ARM executable, otool -L shows that it's linked to the libgcc_s.1.dylib system library - without this, you'll get undefined symbols at link-time.

Uses

uses
  ctypes,
  CFStream,
  CGBase,
  CFHTTPMessage, CFHTTPAuthentication,
  {SCNetworkReachability,}
  SecBase,
  zlib,
  iPhoneAll,
  AnonClassDefinitionsAsihttp;

ctypes - C types.
CFStream - Usually you'll need to use one or more CoreFoundation units.
CGBase - Ditto with CoreGraphics units.
CFHTTPMessage, CFHTTPAuthentication - This is a bit of a cheat in lieu of the CFNetwork unit, which does not yet parse and compile.
SCNetworkReachability - Uncomment this if you've parsed and included the Reachability.h file (required by ASIHTTPRequest, but not by Pascal).
SecBase - security declarations.
zlib - The ASIHTTPRequest classes require the system libz.dylib system library. Using the FPC zlib unit will also add {$linklib libz}.
iPhoneAll - Foundation, UIKit, QuartzCore and OpenGLES frameworks.
AnonClassDefinitionsAsihttp - anonymous class declarations for parsed frameworks.

Interface

The rest of the unit is the interface that your app will see and use. You can define additional types and constants here if necessary (see iPhoneAll.pas for better examples).

{$define INTERFACE}

type
  BytefPtr = pBytef;  //defined in zlib
//  sockaddr_inPtr = Pointer;  //only needed for Reachability.inc

{$define HEADER}
{$include asihttp/Asihttp.inc}
{$undef HEADER}

{$define TYPES}
{$include asihttp/Asihttp.inc}
{$undef TYPES}

{$define RECORDS}
{$include asihttp/Asihttp.inc}
{$undef RECORDS}

type
{$define FORWARD}
{$include asihttp/Asihttp.inc}
{$undef FORWARD}

{$define PROTOCOLS}
{$include asihttp/Asihttp.inc}
{$undef PROTOCOLS}

{$define CLASSES}
{$include asihttp/Asihttp.inc}
{$undef CLASSES}
 
{$define FUNCTIONS}
{$include asihttp/Asihttp.inc}
{$undef FUNCTIONS}

{$define EXTERNAL_SYMBOLS}
{$include asihttp/Asihttp.inc}
{$undef EXTERNAL_SYMBOLS}

{$define USER_PATCHES}
{$include asihttp/Asihttp.inc}
{$undef USER_PATCHES}

{$undef INTERFACE}
implementation
{$define IMPLEMENTATION}

{$define USER_PATCHES}
{$include asihttp/Asihttp.inc}
{$undef USER_PATCHES}

{$undef IMPLEMENTATION}
end.

Creating a Patch File

The parser isn't 100% accurate (and might never be), so you may need to edit one or more of the .inc files it creates in order for the interface unit to compile. If you'll never need to parse the header files again, you're done. But what if you will parse them again (for example, with an updated parser) or you want to provide your parser input files to someone else? In that case, you'll probably want to create a patch file, if only because it's usually easier than documenting or explaining what edits need to be made.

With the ASIDownloadCache.inc file that the parser creates, one edit needs to be made to eliminate a duplicate identifier error when compiling.

Make a copy of the file you'll be editing (ASIDownloadCache.inc.sav).
Edit the original file (add two underscores to to the defaultCachePolicy variable in ASIDownloadCache.inc).

From the parser directory, use the diff command to create the patch file. For example, enter this (all on the same line):

diff --unified=1 uikit-skel/src/asihttp/ASIDownloadCache.inc.sav 
 uikit-skel/src/asihttp/ASIDownloadCache.inc >asihttp.patch

Now, the next time you parse the ASIHTTPRequest headers, patch the ASIDownloadCache.inc file automatically using the patch command with your patch file:
```
patch -p0 < asihttp.patch
```
Add this command to your parsing script (see parse-ios.sh) and include the patch file if you distribute your parser input files.

macpgmr (at) fastermac (dot) net

First posted Nov. 12, 2011; last edited May 9, 2013.