Source

nsstringgen / README.rst

Full commit
Juri Pakaste 8436f0b 


Juri Pakaste 14c60a0 
Juri Pakaste 8436f0b 
Juri Pakaste 3118bd3 


Juri Pakaste daae95c 
Juri Pakaste 3118bd3 
Juri Pakaste 14c60a0 

Juri Pakaste 8436f0b 
Juri Pakaste 14c60a0 
Juri Pakaste 8436f0b 
Juri Pakaste 14c60a0 

Juri Pakaste 4a537e9 


Juri Pakaste daae95c 

Juri Pakaste fe118c1 
Juri Pakaste 4a537e9 


Juri Pakaste 14c60a0 


Juri Pakaste daae95c 

Juri Pakaste fe118c1 
Juri Pakaste 4a537e9 

Juri Pakaste daae95c 
Juri Pakaste fe118c1 
Juri Pakaste daae95c 
Juri Pakaste 4a537e9 







Juri Pakaste daae95c 

Juri Pakaste fe118c1 
Juri Pakaste 4a537e9 







Juri Pakaste 14c60a0 
Juri Pakaste 4eff1ea 

Juri Pakaste 14c60a0 

Juri Pakaste daae95c 

Juri Pakaste fe118c1 
Juri Pakaste 4a537e9 

Juri Pakaste daae95c 
Juri Pakaste fe118c1 
Juri Pakaste daae95c 
Juri Pakaste 4a537e9 







Juri Pakaste daae95c 










Juri Pakaste fe118c1 
Juri Pakaste daae95c 







Juri Pakaste 14c60a0 





nsstringfromenumgen
===================

nsstringfromenumgen generates Objective-C functions for converting enums to NSStrings. It uses libclang for parsing.

Licensing
---------

The NSStringFromEnumGenerator.py module and nsstringfromenumgen script are distributed under the terms of the MIT License. See ``LICENSE.TXT`` for details. The repository also includes and installs libclang Python bindings. See ``clang/LICENSE.TXT`` for details on them.

Requirements
------------

Assuming you're on a Mac, you need Xcode and the command line tools installed. On other platforms you probably need libclang somewhere where Python finds it.

This software includes a copy of the libclang Python bindings because they aren't installed by Xcode. They require LLVM 3.1 which is included at least in Xcode 4.5.2.

Installation
------------

To install, use ``setup.py``:

.. code:: bash

 $ sudo python ./setup.py install

Usage
-----

Call ``nsstringfromenumgen`` with one or more Objective-C source files. It parses them and outputs NSStringFromEnum functions for each enumeration found. It tries to be smart with typedefs and enum names and if it finds both names, it produces two functions. It also outputs an extern declaration for each function:

.. code:: bash

 $ nsstringfromenumgen Foo.h

.. code:: objc

 extern NSString* NSStringFromAnEnum(AnEnum v);
 NSString* NSStringFromAnEnum(AnEnum v) {
   switch (v) {
     case AnEnumFirstValue: return @"AnEnumFirstValue";
     case AnEnumSecondValue: return @"AnEnumSecondValue";
   }
 }

If your enums have values defined, they will be included too:

.. code:: objc

 extern NSString* NSStringFromValuesEnum(ValuesEnum v);
 NSString* NSStringFromValuesEnum(ValuesEnum v) {
   switch (v) {
     case ValuesEnumFirstValue: return [NSString stringWithFormat:@"ValuesEnumFirstValue (%d)", 1];
     case ValuesEnumSecondValue: return [NSString stringWithFormat:@"ValuesEnumSecondValue (%d)", 2];
   }
 }

You can use ``-`` as the file name, in which case ``nsstringfromenumgen`` expects to receive the file contents from standard input. You can use this to feed a single enum definition ``nsstringfromenumgen``, instead of a whole source file. However, if you're using the recently added ``NS_ENUM`` and ``NS_OPTIONS`` macros, you'll need to use the ``--include`` flag to include ``NSObjCRuntime.h`` (or another header that includes it, such as ``Foundation.h``.)

If your code relies on a prefix header, you need to include it on the command line with the ``--include`` flag. You can specify more than one of them if necessary.

You can also instruct ``nsstringfromenumgen`` to treat your enums as options for a bitmask by including the ``--mask`` flag:

.. code:: bash

 $ nsstringfromenumgen Foo.h --mask

.. code:: objc

 extern NSString* NSStringFromMaskEnum(enum MaskEnum v);
 NSString* NSStringFromMaskEnum(enum MaskEnum v) {
   NSMutableArray *bits = [NSMutableArray array];
   if (v & MaskEnumFirstValue) [bits addObject:@"MaskEnumFirstValue"];
   if (v & MaskEnumSecondValue) [bits addObject:@"MaskEnumSecondValue"];
   return [bits componentsJoinedByString:@" | "];
 }

Service
-------

If you want to use ``nsstringfromenumgen`` as an OS X Service, there's an `Automator <http://support.apple.com/kb/HT2488>`_ workflow in ``service.workflow``. It's not installed by ``setup.py``, but you can use Automator to modify it as necessary and install it as a service. It assumes the following:

1. You'll install the ``nsstringfromenumgen`` script in ``/usr/local/bin``,
2. Have ``/System/Library/Frameworks/Foundation.framework/Headers/NSObjCRuntime.h`` which it includes automatically,
3. You want to read stdin and copy the results to clipboard.

If that sounds right and you install it as a service, you can feed it code blocks like:

.. code:: objc

   typedef NS_ENUM(NSInteger, AnEnum) {
     AnEnumFirstValue,
     AnEnumSecondValue
   };

and get the right thing on your clipboard.

Caveats
-------

Because libclang is a real C parser, your file needs to make sense. If libclang produces errors, nsstringfromenumgen gives up because the syntax tree tends to be unpredictable in the presence of errors.