#+OPTIONS: toc:nil

[[travis-build:aki2o/log4e#master]]

* What's this?
  
  This is a extension of Emacs provides logging framework for Elisp.  

  
* Feature

*** Define function for logging automatically

    Write the following sexp in your elisp file.  

#+BEGIN_SRC lisp
(log4e:deflogger "hoge" "%t [%l] %m" "%H:%M:%S")
#+END_SRC

    Then, you can use the following function/command.  
    
    - hoge--log-fatal
    - hoge--log-error
    - hoge--log-warn
    - hoge--log-info
    - hoge--log-debug
    - hoge--log-trace
    - hoge--log
    - hoge--log-fatal*
    - hoge--log-error*
    - hoge--log-warn*
    - hoge--log-info*
    - hoge--log-debug*
    - hoge--log-trace*
    - hoge--log*
    - hoge--log-set-level
    - hoge--log-enable-logging
    - hoge--log-disable-logging
    - hoge--log-enable-debugging
    - hoge--log-disable-debugging
    - hoge--log-enable-messaging
    - hoge--log-disable-messaging
    - hoge--log-debugging-p
    - hoge--log-set-coding-system
    - hoge--log-set-author-mail-address
    - hoge--log-clear-log
    - hoge--log-open-log
    - hoge--log-open-log-if-debug

    For detail, see Usage section.  

*** font-lock on logging buffer

    Here is the image of logging buffer.

    [[file:image/demo1.png][demo1]]

    The following face is used for font-lock on logging buffer.  

    - font-lock-doc-face
    - font-lock-keyword-face
    - font-lock-string-face
    - font-lock-warning-face

*** key binding on logging buffer

    The mode of logging buffer is log4e-mode which is based view-mode.  
    The following binding is added.  
    
    - =J= log4e:next-log ... move to head of next log
    - =K= log4e:previous-log ... move to head of previous log


* Install
  
*** If use package.el

    2013/07/19 It's available by using melpa.  
    
*** If use el-get.el

    2013/07/26 It's available. But, master branch only.  

*** If use auto-install.el
    
    #+BEGIN_SRC lisp
(auto-install-from-url "https://raw.github.com/aki2o/log4e/master/log4e.el")
    #+END_SRC
    
*** Manually
    
    Download log4e.el and put it on your load-path.  
      
      
* Usage

  For example, develop elisp with prefix "hoge".

*** Initially
    
    Write the following in the elisp.

    #+BEGIN_SRC lisp
(require 'log4e)
(log4e:deflogger "hoge" "%t [%l] %m" "%H:%M:%S" '((fatal . "fatal")
                                                  (error . "error")
                                                  (warn  . "warn")
                                                  (info  . "info")
                                                  (debug . "debug")
                                                  (trace . "trace")))
    #+END_SRC

    =log4e:deflogger= receives the following arguments.  
    
    1. The elisp prefix.
    2. Format of log. The following words has a special meaning in it.
       - %t ... Replaced with the 3rd argument.
       - %l ... Replaced with LogLevel.
       - %m ... Replaced with given message by the logging function. About them, see Coding section below.
    3. Format of time. This value is passed to `format-time-string` and replaced with its returend.
    4. Alist of the logging function name. This is optional. If nil, This value is `log4e-default-logging-function-name-alist`.

*** Coding

    Develop the elisp with logging.  

    #+BEGIN_SRC lisp
(defun hoge-do-hoge (hoge)
  (if (not (stringp hoge))
      (progn (hoge--fatal "failed do hoge : hoge is '%s'" hoge)
             (hoge--log-open-log-if-debug))
    (hoge--debug "start do hoge about '%s'" hoge)
    (message "hoge!")
    (hoge--info "done hoge about '%s'" hoge)))
    #+END_SRC

    The logging functions are named by the 4th argument of =log4e:deflogger=.  
    The arguments of them are passed to =format= and its returned is used for the message part of log.  
    The returned of them is always nil.

*** Enable/Disable logging

    By default, logging is disabled.  
    For doing logging, use =hoge--log-enable-logging=.  
    If you want to do logging anytime, write =hoge--log-enable-logging= in the elisp.  
    For stopping logging, use =hoge--log-disable-logging=.

*** Set range of logging level

    By default, The logging range is from 'info' to 'fatal'.  
    So, eval the following ...
    
    #+BEGIN_SRC lisp
(hoge-do-hoge "HOGEGE")
(hoge--log-open-log)
    #+END_SRC
    
    Then, the buffer is displayed that named ' \*log4e-hoge\*'. And the string is like the following.

    #+BEGIN_SRC
12:34:56 [INFO ] done hoge about 'HOGEGE'
    #+END_SRC

    If you change the logging range, eval the following sexp.
    
    #+BEGIN_SRC lisp
(hoge--log-set-level 'debug 'fatal)
    #+END_SRC
    
    Then, eval the following ...
    
    #+BEGIN_SRC lisp
(hoge-do-hoge "FUGAGA")
(hoge--log-open-log)
    #+END_SRC

    Then, the buffer is displayed that named ' \*log4e-hoge\*'. And the string is like the following.

    #+BEGIN_SRC
12:34:56 [INFO ] done hoge about 'HOGEGE'
12:35:43 [DEBUG] start do hoge about 'FUGAGA'
12:35:43 [INFO ] done hoge about 'FUGAGA'
    #+END_SRC

    If you change the logging range anytime, write =hoge--log-set-level= in the elisp.  
    =hoge--log-set-level= receive the following arguments.
    
    1. The lowest level for doing logging. Its list is 'trace', 'debug', 'info', 'warn', 'error' and 'fatal'.
    2. The highest level for doing logging. This is optional. If nil, This value is 'fatal'.

*** For debug

    When you debug the elisp, eval the following ...
    
    #+BEGIN_SRC lisp
(hoge--log-enable-debugging)
(hoge-do-hoge 'hogege)
    #+END_SRC

    Then, the buffer is displayed that named ' \*log4e-hoge\*'. And the string is like the following.

    #+BEGIN_SRC
12:34:56 [INFO ] done hoge about 'HOGEGE'
12:35:43 [DEBUG] start do hoge about 'FUGAGA'
12:35:43 [INFO ] done hoge about 'FUGAGA'
12:54:32 [FATAL] failed do hoge : hoge is 'hogege'
    #+END_SRC

    If you want to stop debugging, use =hoge--log-disable-debugging=.  
    If you want to verify activity of debugging in the elisp, use =hoge--log-debugging-p=.
    
    By using =hoge--log-enable-debugging=, logging is enabled too.

*** Dump log into other buffer

    You are able to dump the same log into other area with logging to standard log buffer
    by =hoge--log-enable-messaging=.  
    The command receives an argument as a buffer. In default, it's echo area.  
    For stopping to dump, use =hoge--log-disable-messaging=.  

*** Inhibit logging statement evaluation

    Arguments of logging function are evaluated even if the logging level is not a logging range
    or logging is disabled like the following code.  

    #+BEGIN_SRC lisp
(hoge--log-set-level 'info 'fatal)
(hoge--log-disable-logging)
(hoge--debug "%s" (very-big-cost-function)) ; <= This is done in any situation
(some-action)                               ; <= This will be not started until very-big-cost-function is finished
    #+END_SRC

    In the case, you are able to inhibit the evaluation using a macro version of the logging function
    like the following code.  

    #+BEGIN_SRC lisp
(hoge--log-set-level 'info 'fatal)
(hoge--log-disable-logging)
(hoge--debug* "%s" (very-big-cost-function)) ; <= This is done only if this should be logged
(some-action)                                ; <= This will be started soon
    #+END_SRC

    But, if the macro version is used frequently, the compiled file size might come big.  

*** Free log level function

    If you want to do logging with changing log level by some condition locally, use =hoge--log=.  
    =hoge--log= is base of the logging function. About them, see Coding section above.  
    It receive a log level as 1st argument.

*** Insert logging statement quickly

    You are able to insert logging statement quickly using =log4e:insert-start-log-quickly=.  

    [[file:image/insert1.png][insert1]]

    [[file:image/insert2.png][insert2]]

    If you want to bind some key to the command,
    write like the following in your .emacs or site-start.el file.  
    
    #+BEGIN_SRC lisp
(define-key emacs-lisp-mode-map (kbd "C-\\") 'log4e:insert-start-log-quickly)
    #+END_SRC

*** Clean log buffer

    If you want to clear the log buffer named ' \*log4e-hoge\*', use =hoge--log-clear-log=.  

  
* Tested On
  
  - Emacs ... GNU Emacs 23.3.1 (i386-mingw-nt5.1.2600) of 2011-08-15 on GNUPACK
    
    
  *Enjoy!!!*