README

   1 =========
   2  ironout
   3 =========
   4
   5 Ironout_ is a C refactoring tool.  It tries to be simple and fast.
   6
   7 .. _ironout: http://ironout.berlios.de
   8
   9
  10 NEWS
  11 ====
  12
  13 The command line interface has been enhanced to support using variable
  14 names for specifying what to rename or find; see the examples in usage
  15 section.
  16
  17 A new function, ``typedef_name`` in ``typedef.c``, is called to decide
  18 whether a name is a typedef or an identifier.  This is the place to
  19 change in order to support parsing files with typedefs.
  20
  21 There were many bug fixes and minor enhancements; now ironout can be
  22 used on itself.  See repository logs for more information.
  23
  24
  25 LIMITATIONS
  26 ===========
  27
  28 Patches are welcome ;-)
  29
  30 *typedefs*:
  31
  32 Currently typedefs make parsing errors.  The problem is C is a context
  33 dependent language.  That is we should know whether a name is an
  34 identifier or a typedef when parsing the source code.  I can think of
  35 hacks to make it work for some situations but not a clean approach
  36 that handles most.  This will be improved in future.
  37
  38 *macros*:
  39
  40 I think the only reliable way of handling macros is to use a
  41 pre-processor.  But the problem is we need offset information
  42 collected during parsing; the output of pre-processor tells us nothing
  43 about the original source code name offsets.
  44
  45 So currently macro definitions are ignored and macro usages are
  46 thought of as normal functions and variables (the latter might cause
  47 syntax errors for complex macros).
  48
  49 *fields*:
  50
  51 In order to rename fields, we need to compute and save types involved
  52 in a C program.  Currently ironout does not do that; planned for
  53 future releases.
  54
  55
  56 USAGE
  57 =====
  58
  59 For compiling you'll need flex and bison.  After compiling the
  60 sources, a binary named ``ironout`` will be created; copy this file to
  61 a folder in your ``$PATH`` if you like.
  62
  63 EMACS
  64 -----
  65
  66 Ironout comes with a simple emacs minor mode.  To make it work add::
  67
  68   (setq ironout-path "/path/to/compiled/ironout")
  69   (load-file "/path/to/ironout.el")
  70
  71 to your ``~/.emacs`` file.  The minor mode is automatically activated
  72 in C files.  You can use these commands:
  73
  74 =================  ========  ==============================
  75 Command            Key       Description
  76 =================  ========  ==============================
  77 ironout-rename     C-c i r   show renaming changes in a buffer
  78 ironout-find       C-c i f   find occurrences of a name
  79 =================  ========  ==============================
  80
  81 You can use keys like "C-x `" that work with compilation buffer to
  82 move through occurrences after ``ironout-find`` command.
  83
  84 CLI
  85 ---
  86
  87 You can use the command line interface to work with ``ironout``.
  88 As an example if ``test.c`` contains::
  89
  90   int var;
  91   void f()
  92   {
  93         var++;
  94   }
  95
  96 You can test ironout with::
  97
  98   $ ironout find test.c 4
  99   test.c 4 7
 100   test.c 21 24
 101   $ ironout rename test.c 4 newvar
 102   --- a/test.c
 103   +++ b/test.c
 104   @@ -1,5 +1,5 @@
 105   -int var;
 106   +int newvar;
 107    void f()
 108    {
 109   -       var;
 110   +       newvar;
 111    }
 112
 113 Unless you're writing a plugin, working with offsets is hard; instead
 114 you can use name hierarchies for specifying names.  For instance, if
 115 ``test.c`` contains::
 116
 117   struct var {
 118           int field;
 119   };
 120   void f()
 121   {
 122           struct var var;
 123           var.field = 0;
 124   }
 125
 126 These command are valid::
 127
 128   $ ironout rename test.c "struct var" newvar
 129   diff --git a/test.c b/test.c
 130   --- a/test.c
 131   +++ b/test.c
 132   @@ -1,8 +1,8 @@
 133   -struct var {
 134   +struct newvar {
 135           int field;
 136    };
 137    void f()
 138    {
 139   -     struct var var;
 140   +     struct newvar var;
 141           var.field = 0;
 142    }
 143   $ ironout rename test.c f:var newvar
 144   diff --git a/test.c b/test.c
 145   --- a/test.c
 146   +++ b/test.c
 147   @@ -3,6 +3,6 @@
 148    };
 149    void f()
 150    {
 151   -     struct var var;
 152   -     var.field = 0;
 153   +     struct var newvar;
 154   +     newvar.field = 0;
 155    }
 156
 157 A few notes:
 158
 159 * All C files in the same directory as ``test.c`` are considered to be
 160   in the same project.  So renaming a name searches all of these
 161   files.
 162 * A colon can be used to point to names inside functions; like
 163   ``f:var`` as shown above
 164 * struct, union, enum and label tags can be used to rename names with
 165   tags; like ``struct var`` in above example.
 166
 167
 168 HACKING
 169 =======
 170
 171 Send patches, bug reports and feature requests to `ironout (at)
 172 googlegroups.com`_.  Send a mail to ``ironout-subscribe (at)
 173 googlegroups.com`` to subscribe.
 174
 175 Also ironout's git repository is located at
 176 git://git.berlios.de/ironout.
 177
 178 .. _`ironout (at) googlegroups.com`: http://groups.google.com/group/ironout
 179
 180
 181 TESTING
 182 =======
 183
 184 Ironout tests are located in ``tests`` folder.  Running ``make test`` will
 185 build ``tests/runtests``.  It can be used like::
 186
 187   $ tests/runtests tests
 188
 189 ``runtests`` takes the directory which contains test files.  The name
 190 of each test file starts with ``test-``.
 191
 192 The format of this file is like::
 193
 194   SEP COMMAND ARGS
 195   COMMAND_BLOCK
 196   SEP NEXT_COMMAND ARGS
 197   COMMAND_BLOCK
 198   ...
 199
 200 Where ``SEP`` is a string that does not contain spaces; it is used to
 201 find where commands start and end (currently a colon is used as the
 202 separator in all of the tests).  ``COMMAND`` shows what to do; they
 203 are listed in the following table:
 204
 205 =========  ======  =================================================
 206 Command    Short   Description
 207 =========  ======  =================================================
 208 write      >       Write the following block to file
 209 read       <       Read file and check if its contents matches
 210                    the following block
 211 ironout            Execute ironout with the given arguments and make
 212                    sure the output matches the following block
 213 comment    #       Ignore arguments and the following block
 214 =========  ======  =================================================
 215
 216 For examples, see test files in ``tests`` directory.
 217
 218 LICENSE
 219 =======
 220
 221 This program is under the terms of GNU GPL.  Have a look at COPYING
 222 file for more information.