daft.txt

                           **Daft Func Spec**

Daft Func is a command-line tool for navigating, summarizing and refactoring C
code, with a primary focus on functions.

Capabilities
============

Spec'ed
-------
- List all functions in a file
- Show where a function is declared
- List all the functions a function calls
- List the places a function is called
- Rename function
- Change function args
    - Add new args to the callers
    - Remove old args from the callers


Maybe
-----
- Hoist code range out of function
- Merge function into code

Command-line
============

daft <file>/<dir>
    List functions in a dir or file, or if no file is specified, in the cwd.

daft <func>
    Print function signature, decl & def location.

daft calls <func>/<file>/<dir>
    List functions that a function calls.

    If no function name is specified, this prints the call-graph in the cwd. If
    one or more directory names or file names are specified, the call-graph is
    printed only for these.

daft callers <func>/<file>/<dir>
    List the places that a function is called.

    If not a function name, inverted call graph is printed.

daft refactor <old_func> <new_func> <file>/<dir>
    Refactors or renames functions. The args can be given in two ways:
    1. Only function names as args
    2. Entire function signatures in quotes (TODO: Handle multi-line signatures)

    If a function signature refactor removes a param, that param will be auto-
    deleted from all of the callers.

    If params are added, the program will ask the user for the argument to be
    passed in all the callers. This will be a simple token input that will be
    added in the correct place in the function call.

    (TODO: If params are changed - i.e. neither only added or removed - the
    intent is ambiguous. Either disallow this - making the user define a change
    as multiple removals/additions, or ignore type/name changes. Needs more
    thought and an elegant solution.)

    If a file/dir is specified, this refactor will only occur there. If not,
    changes will occur in the cwd.

Advanced usage examples
=======================

CamelCase to snake_case
-----------------------

A simple python or bash wrapper can be written to change functions from
CamelCase to snake_case in an entire project. Steps:

    Go to root directory of project
    For each `file` recursively:
        If file extension not .c or .h, continue
        `daft <file>` to list functions
        For each function `MyFunc`:
            `daft refactor MyFunc my_func file`

Misc
----

Daily command-line use!
Editor extensions
Interactive call-graph viewer

Limitations
===========

- Variables and types unsupported. Can be added by expanding the cmd-line
  surface area.
- Function pointers unsupported. Will have to be edited by hand.
- No preprocessing will be done before parsing. Can be done, but not worth it,
  in my opinion.