Source

c-code-cleaner /

Filename Size Date modified Message
Code
doc
input
output
tools
295 B
3.5 KB
2.7 KB
3.8 KB
1.2 KB
6 B
5.0 KB
50.2 KB
5.4 KB
900 B
1.5 KB
2.3 KB
3.4 KB
1.5 KB
16.7 KB
20.5 KB
5.5 KB
31.0 KB
4.9 KB
9.3 KB
5.8 KB
1.7 KB
4.7 KB
11.4 KB
103.4 KB
19.9 KB
57.1 KB
.. -*- coding: utf-8 -*-
.. \||<-snip->|| start
.. Copyright (C) 2006, 2012, Wolfgang Scherer, <Wolfgang.Scherer at gmx.de>
..
.. This file is part of Code Cleaner.
..
.. Permission is granted to copy, distribute and/or modify this document
.. under the terms of the GNU Free Documentation License, Version 1.3
.. or any later version published by the Free Software Foundation;
.. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.. A copy of the license is included in the section entitled "GNU
.. Free Documentation License".

.. inline comments (with ws_docutils)
.. role:: rem(span)
   :format: ''
.. role:: html(span)
   :format: html
   :raw:

##################################################
:rem:`|||:sec:|||`\ C Code Cleaner
##################################################
.. \||<-snap->|| skip

:Author: `Wolfgang Scherer`_

.. contents::
..
    1  Code Parser
    2  Scan Defines GUI
      2.1  INSTALLATION
    3  Scan Defines
      3.1  INSTALLATION
      3.2  USAGE
      3.3  DEVELOPMENT/MODIFICATIONS
    4  Switch File Generator
      4.1  INSTALLATION
      4.2  USAGE
      4.3  DEVELOPMENT/MODIFICATIONS
    5  Code Cleaner
      5.1  INSTALLATION
      5.2  USAGE
      5.3  DEVELOPMENT/MODIFICATIONS

.. \||<-snap->|| skip
.. \||<-snap->|| include ^index-header.snip$

==================================================
Code Parser
==================================================

Currently, a full C preprocessor parser is implemented.

The purpose is to manage preprocessor symbols and to physically remove
source code based on (non-)definition of preprocessor symbols.

There is some documentation in doc/html and doc/pdf.

Starting point is doc/html/cond-use-case.html or doc/html/cond-design.html,
respectively doc/pdf/cond-use-case.pdf and doc/pdf/cond-design.pdf.

If you make any changes to the grammar in Code/C/Grammar.yp, you need
the Parser/Yapp module from CPAN installed.

The applications for the C-code parser are

- `sd_gui.pl`
  Tk GUI for `scan_defines.pl`

- `scan_defines.pl`
  Scan for and report unknown preprocessor symbols used in #if
  conditionals.

- `gen_switch.pl`
  Generate switch files from combinations of switch files, as diff
  between known and used switches. Output can also be inverted.

- `clean_file.pl`
  Clean C-sources evaluating #if blocks based on symbol tables.

- `file-struct.pl`
  Demo application showing the structure of a C-source file.

==================================================
Scan Defines GUI
==================================================

::

    sd_gui.pl - GUI Frontend to scan_define.pl

    usage: sd_gui.pl [modules-file]

    KEY BINDINGS
      Listbox 'Known Switches'
        Ctrl-a     select all entries
        d          change all selected switches to defined (-D)
        u          change all selected switches to undefined (-U)
        DEL        delete all selected switches

      Listbox 'Symbols'
        Ctrl-a     select all entries
        d          move all selected symbols to switches as defined (-D)
        u          move all selected symbols to switches as undefined (-U)
        DEL        delete all selected symbols
        RET        find all selected symbols in selected modules
        DBL-Click  find symbol in selected modules

    SWITCH FILES
      Besides regular switch files (*.opt) you can also load saved plain
      symbol files (*.txt).
      Unqualifed Symbols (without -D or -U) are added as defined.

--------------------------------------------------
INSTALLATION
--------------------------------------------------

Copy `sd_gui.pl` and `scan_defines.pl` somewhere in your path or use
them with a fully qualified pathname.

==================================================
Scan Defines
==================================================

The define scanner reports all (unknown) symbols found in C source
files. Alternatively it can find only known symbols. (See
`doc/*/cond-use-case` for use cases).

--------------------------------------------------
INSTALLATION
--------------------------------------------------

Copy `scan_defines.pl` somewhere in your path or use it with a fully
qualified pathname.

--------------------------------------------------
USAGE
--------------------------------------------------

::

    scan_defines.pl - scan for and report unknown preprocessor symbols used in #if conditionals

    usage: scan_defines.pl [OPTIONS] file-or-dir-name ..

    OPTIONS
      -i, --input        filelist Read input files from filelist.
      -s, --switches     deffile  File with switch definitions.
                                  If this option appears multiple times,
                                  all stated deffiles are parsed.
      -Dsymbol[=value]            Define symbol with optional value.
      -Usymbol                    Undefine symbol.
      --define-file-switches      Define expected file switches.
                                  (e.g., spw10scan.c => SPW10SCAN_C)

      --allow-nested-comments     Allow nested comments.

      -w, --warnings              Report all warnings and non-fatal errors.
      -t, --trace[=level]         Turn tracing on (set to level).
      -l, --lex-debug             Switch on lex debugging
      -y, --yapp-debug            Switch on yapp debugging

    OPTIONS FOR FILE SELECTION
      -m, --match-rx     perl-rx  Perl regex that a source file must match.
                                  default: '[.]([ch][^.]*)$'
      -k, --skip-rx      perl-rx  Perl regex that a source file may not match.
                                  default: '[.](cla|cmm|cnf|cvsignore)$'

    The MATCH REGEXP is applied to the filename first.
    - If it does NOT MATCH, the file is NOT USED as source file.
    - If it MATCHES, the filename is matched against the SKIP REGEXP.
      - If it MATCHES, the file is NOT USED as source file.
      - If it DOES NOT MATCH, the file is USED as source file.

    REPORTING OPTIONS
      -c, --count                 Report symbol counts.
      -g, --grep                  Report file locations.
      -v, --verify                Show all warnings and non-fatal errors.

    The default mode is to report any unknown symbols. I.e., all defined
    or undefined switches from a deffile or the `-D' and `-U' options are
    ignored.

      -f, --find                  Find known symbols.

    With option `--find', the reporting logic is reversed and all
    unknown symbols are ignored. I.e., all defined or undefined switches
    from a deffile or the `-D' and `-U' options are reported.

--------------------------------------------------
DEVELOPMENT/MODIFICATIONS
--------------------------------------------------

Use `scan_defines__.pl` and the Code package tree for
development/modifications.

The file `scan_defines.pl` is generated from `scan_defines__.pl` and the
Code package tree as a standalone perl program which does not need any
non-standard external packages.

==================================================
Switch File Generator
==================================================

The switch file generator can be used to create combined switch files
and switch diff files as well as inverted switch files.

--------------------------------------------------
INSTALLATION
--------------------------------------------------

Copy `gen_switch.pl` somewhere in your path or use it with a fully
qualified pathname.

--------------------------------------------------
USAGE
--------------------------------------------------

::

    gen_switch.pl - generate switch definitions

    usage: gen_switch.pl [OPTIONS]

    OPTIONS
      --stream                Handle input files as word streams.
      --no-stream             Handle input files line-oriented.

    USED SWITCH OPTIONS
      -u, --used        file  Parse used switches from file.
      -Dsymbol[=value]        Add symbol to used switch defined table.
      -Usymbol                Add symbol to used switch undefined table.

    KNOWN SWITCH OPTIONS
      -k, --known       file  Parse known switches from file.
                              Defined symbols which do not appear in the
                              used switch defined table are added to the
                              used switch undefined table.

    OUTPUT OPTIONS
      -o, --output      file  Write output to file.
      -s, --swap              Swap defined and undefined switches before
                              output.
      --undef-only            Print only undefined switches (after swap).
      -d, --def-only          Print only defined switches (after swap).

--------------------------------------------------
DEVELOPMENT/MODIFICATIONS
--------------------------------------------------

Use `gen_switch__.pl` and the Code package tree for
development/modifications.

The file `gen_switch.pl` is generated from `gen_switch__.pl` and the Code
package tree as a standalone perl program which does not need any
non-standard external packages.

==================================================
Code Cleaner
==================================================

The code cleaner application `clean_file.pl` is modeled after the
existing code cleaner. The default options are choosen to provide best
matching output for easy verification. (See `doc/*/cond-use-case` for
use cases).

--------------------------------------------------
INSTALLATION
--------------------------------------------------

Copy `clean_file.pl` somewhere in your path or use it with a fully
qualified pathname.

--------------------------------------------------
USAGE
--------------------------------------------------

::

    clean_file.pl - clean c-sources evaluating #if blocks based on symbol tables

    usage: clean_file.pl [OPTIONS] [ file-or-dir-name .. ]

    OPTIONS
      -i, --input        filelist Read input files from filelist.
      -s, --switches     deffile  File with switch definitions.
                                  If this option appears multiple times,
                                  all stated deffiles are parsed.
      -Dsymbol[=value]            Define symbol with optional value.
      -Usymbol                    Undefine symbol.
      --show-unknown-symbols      Show a list of unknown symbols
                                  after processing all files.

      -o, --output       output   Print to outfile. If several
                                  file-names are specified or if the
                                  single input filename is a directory,
                                  output is assumed to be a directory.
      -p, --preserve              Preserve time stamps.

      --allow-nested-comments     Allow nested comments.
      -w, --warn-dos-eol          Warn about DOS end of line (CR/LF).

      -r, --rewrite-cond          Rewrite tainted `#if/#else/#endif'.
      -a, --rewrite-all           Rewrite all `#if/#else/#endif'.
      -c, --rem-cond              Remove `#if/#else/#endif' where possible.
      -n, --numbers               Recognize numerical coniditionals.
                                  Remove `#if 0' code parts. Recognize
                                  `#if 1' conditionals.
      -u, --reverse-logic         Exchange defined/undefined table.
      -d, --defined-only          Use only defined symbol table. (CPP mode).

      -q, --quiet                 Suppress all warnings and non-fatal
                                  errors.
      -t, --trace[=level]         Turn tracing on (set to level).
      -l, --lex-debug             Switch on lex debugging.
      -y, --yapp-debug            Switch on yapp debugging.

    OPTIONS FOR FILE SELECTION
      -m, --match-rx     perl-rx  Perl regex that a source file must match.
                                  default: '[.]([ch][^.]*)$'
      -k, --skip-rx      perl-rx  Perl regex that a source file may not match.
                                  default: '[.](cla|cmm|cnf|cvsignore)$'

    The MATCH REGEXP is applied to the filename first.
    - If it does NOT MATCH, the file is NOT USED as source file.
    - If it MATCHES, the filename is matched against the SKIP REGEXP.
      - If it MATCHES, the file is NOT USED as source file.
      - If it DOES NOT MATCH, the file is USED as source file.

--------------------------------------------------
DEVELOPMENT/MODIFICATIONS
--------------------------------------------------

Use `clean_file__.pl` and the Code package tree for
development/modifications.

The file `clean_file.pl` is generated from `clean_file__.pl` and the Code
package tree as a standalone perl program which does not need any
non-standard external packages.

.. ==================================================
.. :rem:`|||:sec:|||`\ Footnotes
.. ==================================================

:html:`<hr>`

.. \[#]

.. ==================================================
.. :rem:`|||:sec:|||`\ References
.. ==================================================

.. \||<-snap->|| include ^index-footer.snip$

:rem:`|||:sec:|||`\ **Copyright**

Copyright (C) 2012, Wolfgang Scherer, <Wolfgang.Scherer@gmx.de>.
See the document source for conditions of use under the GNU Free
Documentation License.

.. _`Wolfgang Scherer`: Wolfgang.Scherer@gmx.de

.. \||<-snip->|| stop

.. ==================================================
.. :rem:`|||:sec:|||`\ END
.. ==================================================
.. 
.. :ide-menu: Emacs IDE Main Menu - Buffer @BUFFER@
.. . M-x `eIDE-menu' ()(eIDE-menu "z")

.. :ide: DELIM: SNIPPETS (ABOUT)       |q|<- SYM ->||,   ||<- SYM ->||,  @| SYM @
.. . (let nil (symbol-tag-normalize-delimiter (cons (cons nil "||<-") (cons "->||" nil)) t) (symbol-tag-switch-delimiter-sets) (symbol-tag-normalize-delimiter (cons (cons nil "||<-") (cons "->||" nil)) t) (setq symbol-tag-match-rx "sn[i]p") (setq symbol-tag-enclose-delimiter-set (symbol-tag-normalize-delimiter (cons (cons nil "@|") (cons "@" nil)))))

.. :ide: DELIM: SNIPPETS (DOC)          ||<- SYM ->||,     |: SYM :|,     ` SYM `
.. . (let nil (symbol-tag-normalize-delimiter (cons (cons nil "|:") (cons ":|" nil)) t) (symbol-tag-switch-delimiter-sets) (symbol-tag-normalize-delimiter (cons (cons nil "||<-") (cons "->||" nil)) t) (setq symbol-tag-match-rx "sn[i]p") (setq symbol-tag-enclose-delimiter-set (symbol-tag-normalize-delimiter (cons (cons "\\(\\`\\|[^\\]\\)" "`") (cons "`" nil)))))

.. :ide: DELIM: SNIPPETS (SNIP DOC)     ||<- SYM ->||,     |: SYM :|,     @ SYM @
.. . (let nil (symbol-tag-normalize-delimiter (cons (cons nil "|:") (cons ":|" nil)) t) (symbol-tag-switch-delimiter-sets) (symbol-tag-normalize-delimiter (cons (cons nil "||<-") (cons "->||" nil)) t) (setq symbol-tag-match-rx "sn[i]p") (setq symbol-tag-enclose-delimiter-set (symbol-tag-normalize-delimiter (cons (cons nil "@") (cons "@" nil)))))

.. :ide: DELIM: SNIPPETS (FILLME)       ||<- SYM ->||,     :: SYM ::,     @ SYM @
.. . (let nil (symbol-tag-normalize-delimiter (cons (cons nil "::") (cons "::" nil)) t) (symbol-tag-switch-delimiter-sets) (symbol-tag-normalize-delimiter (cons (cons nil "||<-") (cons "->||" nil)) t) (setq symbol-tag-match-rx "sn[i]p") (setq symbol-tag-enclose-delimiter-set (symbol-tag-normalize-delimiter (cons (cons nil "@") (cons "@" nil)))))

.. :ide: DELIM: SNIPPETS (SUBST)        ||<- SYM ->||,      @ SYM @,      @ SYM @
.. . (let nil (symbol-tag-normalize-delimiter (cons (cons nil "@") (cons "@" nil)) t) (symbol-tag-switch-delimiter-sets) (symbol-tag-normalize-delimiter (cons (cons nil "||<-") (cons "->||" nil)) t) (setq symbol-tag-match-rx "sn[i]p") (setq symbol-tag-enclose-delimiter-set (symbol-tag-normalize-delimiter (cons (cons "[^\\]" "`") (cons "`" nil)))))

.. :ide: +#-
.. . Snippet Delimiter Sets ()

.. :ide: DELIM: ReST (links)              ` SYM `_,    .. _` SYM `,      ` SYM `
.. . (let nil (symbol-tag-normalize-delimiter (cons (cons "[^\\]" "`") (cons "`_" nil)) t) (symbol-tag-switch-delimiter-sets) (symbol-tag-normalize-delimiter (cons (cons nil ".. _`") (cons "`:" nil)) t) (setq symbol-tag-enclose-delimiter-set (symbol-tag-normalize-delimiter (cons (cons "\\(\\`\\|[^\\]\\)" "`") (cons "`" nil)))))

.. :ide: DELIM: STANDARD (GNU quoting)    |: SYM :|,       :: SYM ::,     ` SYM '
.. . (let nil (symbol-tag-normalize-delimiter (cons (cons nil "::") (cons "::" nil)) t) (symbol-tag-switch-delimiter-sets) (symbol-tag-normalize-delimiter (cons (cons nil "|:") (cons ":|" nil)) t) (setq symbol-tag-enclose-delimiter-set (symbol-tag-normalize-delimiter (cons (cons nil "`") (cons "'" nil)))))

.. :ide: DELIM: STANDARD (ReST quoting)   |: SYM :|,       :: SYM ::,     ` SYM `
.. . (let nil (symbol-tag-normalize-delimiter (cons (cons nil "::") (cons "::" nil)) t) (symbol-tag-switch-delimiter-sets) (symbol-tag-normalize-delimiter (cons (cons nil "|:") (cons ":|" nil)) t) (setq symbol-tag-enclose-delimiter-set (symbol-tag-normalize-delimiter (cons (cons "[^\\]" "`") (cons "`" nil)))))

.. :ide: +#-
.. . Delimiter Sets ()

.. :ide: COMPILE: render reST as LaTeX
.. . (let* ((fp (buffer-file-name)) (fn (file-name-nondirectory fp))) (save-match-data (if (string-match-t "[.][^.]*$" fn) (setq fn (replace-match "" nil t fn)))) (let ((args (concat " " fp " | ws_rst2latex.py --traceback | tee " fn ".tex"))) (save-buffer) (compile (concat "PATH=\".:$PATH\"; cat " args))))

.. :ide: COMPILE: render reST as MAN
.. . (let* ((fp (buffer-file-name)) (fn (file-name-nondirectory fp))) (save-match-data (if (string-match-t "[.][^.]*$" fn) (setq fn (replace-match "" nil t fn)))) (let ((args (concat " " fp " | ws_rst2man.py --traceback "))) (save-buffer) (compile (concat "PATH=\".:$PATH\"; cat " args))))

.. :ide: COMPILE: render reST as TXT (via MAN)
.. . (let* ((fp (buffer-file-name)) (fn (file-name-nondirectory fp))) (save-match-data (if (string-match-t "[.][^.]*$" fn) (setq fn (replace-match "" nil t fn)))) (let ((args (concat " " fp " | ws_rst2man.py --traceback | man -l -"))) (save-buffer) (compile (concat "PATH=\".:$PATH\"; cat " args))))

.. :ide: COMPILE: render reST as ODT --strip-comments
.. . (let* ((fp (buffer-file-name)) (fn (file-name-nondirectory fp))) (save-match-data (if (string-match-t "[.][^.]*$" fn) (setq fn (replace-match "" nil t fn)))) (let ((args (concat " " fp " | ws_rst2odt.py --traceback --strip-comments | cat >" fn ".odt "))) (save-buffer) (compile (concat "PATH=\".:$PATH\"; cat " args))))

.. :ide: COMPILE: render reST as LaTeX, compile PDF and view with gv
.. . (let* ((fp (buffer-file-name)) (fn (file-name-nondirectory fp))) (save-match-data (if (string-match-t "[.][^.]*$" fn) (setq fn (replace-match "" nil t fn)))) (let ((args (concat " " fp " | ws_rst2latex.py --traceback | tee " fn ".tex && pdflatex '\\nonstopmode\\input " fn ".tex' && gv " fn ".pdf"))) (save-buffer) (compile (concat "PATH=\".:$PATH\"; cat " args))))

.. :ide: COMPILE: render reST as PDF
.. . (let* ((fp (buffer-file-name)) (fn (file-name-nondirectory fp))) (save-match-data (if (string-match-t "[.][^.]*$" fn) (setq fn (replace-match "" nil t fn)))) (let ((args (concat " " fp " | ws_rst2pdf -e ws_docutils.raw_role >" fn ".pdf"))) (save-buffer) (compile (concat "PATH=\".:$PATH\"; cat " args))))

.. :ide: COMPILE: render reST as HTML
.. . (let* ((fp (buffer-file-name)) (fn (file-name-nondirectory fp))) (save-match-data (if (string-match-t "[.][^.]*$" fn) (setq fn (replace-match "" nil t fn)))) (let ((args (concat " " fp " | ws_rst2html.py --traceback --cloak-email-addresses | tee " fn ".html "))) (save-buffer) (compile (concat "PATH=\".:$PATH\"; cat " args))))

.. :ide: COMPILE: render reST as pseudoXML
.. . (let* ((fp (buffer-file-name)) (fn (file-name-nondirectory fp))) (save-match-data (if (string-match-t "[.][^.]*$" fn) (setq fn (replace-match "" nil t fn)))) (let ((args (concat " --traceback " fp " 2>&1 #| tee " fn ".pxml"))) (save-buffer) (compile (concat "PATH=\".:$PATH\"; ws_rst2pseudoxml.py " args))))

.. :ide: +#-
.. . Process ()

.. :ide: QUO: ~~ Subsubsection ~~
.. . (insert "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\:rem\:`|\:sec\:|`\\ ::fillme\::\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n" )

.. :ide: QUO: -- Subsection --
.. . (insert "--------------------------------------------------\n\:rem\:`||\:sec\:||`\\ ::fillme\::\n--------------------------------------------------\n" )

.. :ide: QUO: == Section ==
.. . (insert "==================================================\n\:rem\:`|||\:sec\:|||`\\ ::fillme\::\n==================================================\n" )

.. :ide: +#-
.. . Sections ()

.. :ide: MENU-OUTLINE:  `|||:section:|||' (default)
.. . (x-eIDE-menu-outline "sec" '("|:" ":|") (cons (cons "^" ".. ") (cons nil nil)) "\\(_`[^`\n]+`\\|\\[[^]\n]+\\]\\|[|][^|\n]+[|]\\|[^:\n]+::\\)")

.. 
.. Local Variables:
.. mode: rst
.. snip-mode: rst
.. truncate-lines: t
.. symbol-tag-symbol-regexp: "[-0-9A-Za-z_#]\\([-0-9A-Za-z_. ]*[-0-9A-Za-z_]\\|\\)"
.. symbol-tag-auto-comment-mode: nil
.. symbol-tag-srx-is-safe-with-nil-delimiters: nil
.. End: