service/protocol-plugin/lib/cpluff/examples/cpfile/README.txt

   1 C-PLUFF FILE COMMAND EXAMPLE
   2 ============================
   3
   4 Overview
   5 --------
   6
   7 On UNIX systems the file(1) utility can be used to determine file type and
   8 to get information about contents of a file. Here are couple of examples
   9 of file usage in a Linux environment.
  10
  11   $ file /sbin/init
  12   /sbin/init: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV),
  13   for GNU/Linux 2.4.1, dynamically linked (uses shared libs), for
  14   GNU/Linux 2.4.1, stripped
  15
  16   $ file COPYRIGHT.txt
  17   COPYRIGHT.txt: ASCII English text
  18
  19 This example shows how a simplistic file clone could be implemented as an
  20 extensible application based on C-Pluff. We will call the resulting
  21 utility cpfile. It can recognize some special files and some file types
  22 based on file extension. But it could be further extended to recognize
  23 files based on their content by deploying a suitable plug-in. Notice that
  24 the focus here was on creating a straightforward example rather than an
  25 efficient one.
  26
  27
  28 Architecture
  29 ------------
  30
  31 This example uses the generic plug-in loader, cpluff-loader, as the main
  32 program. The executable cpfile installed into the bin directory is just
  33 a shell script invoking the cpluff-loader. All program logic is included
  34 in plug-ins.
  35
  36 The included plug-ins are:
  37
  38   org.c-pluff.examples.cpfile.core
  39
  40     This plug-in is the one initially started via cpluff-loader. It
  41     contains the core application logic and provides an extension point
  42     for file classifiers. The plug-in itself does not include any file
  43     classifiers. Instead it uses file classifiers registered as
  44     extensions by other plug-ins and then tries them one at a time in
  45     order of decreasing priority until a matching classification is
  46     found or no more classifiers are left.
  47
  48   org.c-pluff.examples.cpfile.special
  49
  50     This plug-in provides a file classifier which uses lstat(2) on the
  51     file to be classified to see if it is a special file such as a
  52     directory or a symbolic link. It also checks for the existence of
  53     the file.
  54
  55   org.c-pluff.examples.cpfile.extension
  56
  57     This plug-in provides a file classifier which checks the file name
  58     for known extensions. The plug-in provides an extension point for
  59     file extensions. The file extensions registered as extensions are
  60     then matched against the file name. The plug-in itself includes an
  61     extension for text files.
  62
  63   org.c-pluff.examples.cpfile.cext
  64
  65     This plug-in does not include a runtime library at all. Instead, it
  66     just registers some file types and file extensions related to
  67     C program source files.
  68
  69 Having build and installed the example, you can experiment with different
  70 plug-in configurations by adding and removing plug-ins into cpfile/plugins
  71 directory in the library directory. The core plug-in must be always
  72 included for the application to work as intended.
  73
  74 You can create a new plug-in for the example by creating a new
  75 subdirectory in the plugins source directory and adding it to SUBDIRS
  76 variable in Makefile.am in the plugins source directory.
  77
  78
  79 Example runs
  80 ------------
  81
  82 Here are couple of examples of using the resulting cpfile application.
  83
  84   $ cpfile /tmp/testdir
  85   C-Pluff Loader, version 0.1.0
  86   C-Pluff Library, version 0.1.0 for i686-pc-linux-gnu
  87   /tmp/testdir: directory
  88
  89   $ cpfile /tmp/test.foo
  90   C-Pluff Loader, version 0.1.0
  91   C-Pluff Library, version 0.1.0 for i686-pc-linux-gnu
  92   /tmp/test.foo: unknown file type
  93
  94   $ cpfile /tmp/test.c
  95   C-Pluff Loader, version 0.1.0
  96   C-Pluff Library, version 0.1.0 for i686-pc-linux-gnu
  97   /tmp/test.c: C source file
  98
  99   $ cpfile /tmp/test.nonexisting
 100   C-Pluff Loader, version 0.1.0
 101   C-Pluff Library, version 0.1.0 for i686-pc-linux-gnu
 102   /tmp/test.nonexisting: stat failed: No such file or directory
 103
 104 You can make cpfile more quiet by giving it -q option, or more verbose by
 105 giving it -v option (repeated for more verbosity up to -vvv). Actually,
 106 these options are processed by cpluff-loader which configures logging
 107 accordingly.
 108
 109   $ cpfile -q /tmp/test.c
 110   /tmp/test.c: C source file
 111
 112   $ cpfile -vv /tmp/test.c
 113   C-Pluff Loader, version 0.1.0
 114   C-Pluff Library, version 0.1.0 for i686-pc-linux-gnu
 115   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.core has been installed.
 116   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.extension has been installed.
 117   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.cext has been installed.
 118   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.special has been installed.
 119   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.core runtime has been loaded.
 120   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.core is starting.
 121   C-Pluff: INFO: [org.c-pluff.examples.cpfile.core] Plug-in org.c-pluff.examples.cpfile.extension runtime has been loaded.
 122   C-Pluff: INFO: [org.c-pluff.examples.cpfile.core] Plug-in org.c-pluff.examples.cpfile.extension is starting.
 123   C-Pluff: INFO: [org.c-pluff.examples.cpfile.core] Plug-in org.c-pluff.examples.cpfile.extension has been started.
 124   C-Pluff: INFO: [org.c-pluff.examples.cpfile.core] Plug-in org.c-pluff.examples.cpfile.special runtime has been loaded.
 125   C-Pluff: INFO: [org.c-pluff.examples.cpfile.core] Plug-in org.c-pluff.examples.cpfile.special has been started.
 126   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.core has been started.
 127   /tmp/test.c: C source file
 128   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.core is stopping.
 129   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.core has been stopped.
 130   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.special has been stopped.
 131   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.extension has been stopped.
 132   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.core runtime has been unloaded.
 133   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.core has been uninstalled.
 134   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.extension runtime has been unloaded.
 135   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.extension has been uninstalled.
 136   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.cext has been uninstalled.
 137   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.special runtime has been unloaded.
 138   C-Pluff: INFO: [loader] Plug-in org.c-pluff.examples.cpfile.special has been uninstalled.