User:Timothee Flutre/Notebook/Postdoc/2012/05/16

From OpenWetWare

(Difference between revisions)
Jump to: navigation, search
(Typical templates for Python scripts, C++ programs and others: use preprocessing macros date and time in c++)
(Typical templates for Python scripts, C++ programs and others: update C++)
(23 intermediate revisions not shown.)
Line 8: Line 8:
==Typical templates for Python scripts, C++ programs and others==
==Typical templates for Python scripts, C++ programs and others==
-
It is always rewarding on the long term to start any piece of computer software with a minimum amount of generic code (verbose, command-line options, help message, license, etc). But it's a pain to write all this every time, right? So below are my typical templates for any Python script, C++ programs and others.
+
It is always rewarding on the long term to start any piece of computer software with a minimum amount of generic code (verbose, command-line options, help message, license, etc). But it's a pain to write all this every time, right? So below are my typical templates for any Python script, C++ program, Beamer presentation, Bash script, etc.
 +
 
 +
* '''Easy user documentation''': I'm a firm believer that it is necessary to add some user documentation, even  minimal, to any program. An easy way to do this is to simply generate such documentation from the "help" message, as long as it is "properly" formatted (see [http://www.gnu.org/s/help2man/ help2man]). The following commands work for any programming language:
 +
 
 +
<nowiki>
 +
help2man -o myprogram.man ./myprogram
 +
man ./myprogram.man
 +
groff -mandoc myprogram.man > myprogram.ps
 +
ps2pdf myprogram.ps myprogram.pdf
 +
</nowiki>
* '''Python''': it is assumed that the code below is copied into a file named "MyClass.py".
* '''Python''': it is assumed that the code below is copied into a file named "MyClass.py".
Line 15: Line 24:
#!/usr/bin/env python
#!/usr/bin/env python
-
# Author: Timothee Flutre
 
-
# License: GPL-3
 
# Aim: does this and that
# Aim: does this and that
-
# help2man -o MyClass.man ./MyClass.py
+
# choose between:
-
# groff -mandoc MyClass.man > MyClass.ps
+
# Author: Timothee Flutre
 +
# Not copyrighted -- provided to the public domain
 +
# or:
 +
# Copyright (C) 2011-2013 Timothee Flutre
 +
# License: GPLv3+
import sys
import sys
Line 45: Line 56:
         msg += " -V, --version\toutput version information and exit\n"
         msg += " -V, --version\toutput version information and exit\n"
         msg += " -v, --verbose\tverbosity level (0/default=1/2/3)\n"
         msg += " -v, --verbose\tverbosity level (0/default=1/2/3)\n"
-
         msg += " -i\tinput"
+
         msg += " -i\tinput\n"
         msg += "\n"
         msg += "\n"
         msg += "Examples:\n"
         msg += "Examples:\n"
Line 52: Line 63:
          
          
     def version(self):
     def version(self):
-
         msg = "%s 0.1\n" % os.path.basename(sys.argv[0])
+
         msg = "%s 1.0\n" % os.path.basename(sys.argv[0])
         msg += "\n"
         msg += "\n"
 +
        msg += "Written by Timothee Flutre.\n"
 +
        msg += "\n"
 +
# choose between:
 +
        msg += "Not copyrighted -- provided to the public domain\n"
 +
# or:
 +
        msg += "Copyright (C) 2011-2013 Timothee Flutre.\n"
         msg += "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>\n"
         msg += "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>\n"
         msg += "This is free software; see the source for copying conditions.  There is NO\n"
         msg += "This is free software; see the source for copying conditions.  There is NO\n"
Line 100: Line 117:
          
          
         if self.verbose > 0:
         if self.verbose > 0:
-
            msg = "START %s" % time.strftime("%Y-%m-%d %H:%M:%S")
 
             startTime = time.time()
             startTime = time.time()
 +
            msg = "START %s %s" % (os.path.basename(sys.argv[0]),
 +
                                  time.strftime("%Y-%m-%d %H:%M:%S"))
 +
            msg += "\ncmd-line: %s" % ' '.join(sys.argv)
             print msg; sys.stdout.flush()
             print msg; sys.stdout.flush()
              
              
Line 107: Line 126:
          
          
         if self.verbose > 0:
         if self.verbose > 0:
-
             msg = "END %s" % time.strftime("%Y-%m-%d %H:%M:%S")
+
             msg = "END %s %s" % (os.path.basename(sys.argv[0]),
 +
                                time.strftime("%Y-%m-%d %H:%M:%S"))
             endTime = time.time()
             endTime = time.time()
             runLength = datetime.timedelta(seconds=
             runLength = datetime.timedelta(seconds=
Line 121: Line 141:
</nowiki>
</nowiki>
-
* '''C++''': it is assumed that the code below is copied into a file named "myprogram.cpp" and that the file "[https://github.com/timflutre/quantgen/blob/master/utils.cpp utils.cpp]" is present in the same directory, along with the corresponding header <nowiki>utils.h</nowiki>.
+
* '''C++''': it is assumed that the code below is copied into a file named "myprogram.cpp" and that the file "[http://github.com/timflutre/quantgen/blob/master/utils_io.cpp utils_io.cpp]" is present in the same directory, along with its header [http://github.com/timflutre/quantgen/blob/master/utils_io.hpp utils_io.hpp].
  <nowiki>
  <nowiki>
Line 127: Line 147:
  *
  *
  *  `myprogram' does this and that.
  *  `myprogram' does this and that.
-
  *  Copyright (C) 2011,2012 Timothee Flutre
+
  *  Copyright (C) 2011-2013 Timothee Flutre
  *
  *
  *  This program is free software: you can redistribute it and/or modify
  *  This program is free software: you can redistribute it and/or modify
Line 142: Line 162:
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  *
-
  *  g++ -Wall -g utils.cpp myprogram.cpp -lgsl -lgslcblas -lz -o myprogram
+
  *  g++ -Wall -g utils_io.cpp myprogram.cpp -lgsl -lgslcblas -lz -o myprogram
-
*  help2man -o myprogram.man ./myprogram
+
-
*  groff -mandoc myprogram.man > myprogram.ps
+
*/
*/
Line 155: Line 173:
using namespace std;
using namespace std;
-
#include "utils.h"
+
#include "utils_io.hpp"
 +
 
 +
#ifndef VERSION
 +
#define VERSION "1.0"
 +
#endif
/** \brief Display the help on stdout.
/** \brief Display the help on stdout.
*/
*/
-
void help (char ** argv)
+
void help(char ** argv)
{
{
   cout << "`" << argv[0] << "'"
   cout << "`" << argv[0] << "'"
Line 170: Line 192:
       << "  -V, --version\toutput version information and exit" << endl
       << "  -V, --version\toutput version information and exit" << endl
       << "  -v, --verbose\tverbosity level (0/default=1/2/3)" << endl
       << "  -v, --verbose\tverbosity level (0/default=1/2/3)" << endl
-
       << " -i, --in\tinput" << endl
+
       << "     --in\tinput" << endl
       << endl
       << endl
       << "Examples:" << endl
       << "Examples:" << endl
-
       << "  " << argv[0] << " -i <input>" << endl
+
       << "  " << argv[0] << " --in <input>" << endl
       << endl
       << endl
       << "Remarks:" << endl
       << "Remarks:" << endl
Line 182: Line 204:
/** \brief Display version and license information on stdout.
/** \brief Display version and license information on stdout.
  */
  */
-
void version (char ** argv)
+
void version(char ** argv)
{
{
-
   cout << argv[0] << " " << __DATE__ << " " << __TIME__ << endl
+
   cout << argv[0] << " " << VERSION << endl
       << endl
       << endl
-
       << "Copyright (C) 2011,2012 T. Flutre." << endl
+
       << "Copyright (C) 2011-2013 Timothee Flutre." << endl
       << "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>" << endl
       << "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>" << endl
       << "This is free software; see the source for copying conditions.  There is NO" << endl
       << "This is free software; see the source for copying conditions.  There is NO" << endl
       << "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE." << endl
       << "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE." << endl
       << endl
       << endl
-
       << "Written by T. Flutre." << endl;
+
       << "Written by Timothee Flutre." << endl;
}
}
Line 198: Line 220:
  */
  */
void
void
-
parseArgs (
+
parseCmdLine(
   int argc,
   int argc,
   char ** argv,
   char ** argv,
Line 205: Line 227:
{
{
   int c = 0;
   int c = 0;
-
   while (true)
+
   while(true)
   {
   {
     static struct option long_options[] =
     static struct option long_options[] =
Line 212: Line 234:
         {"version", no_argument, 0, 'V'},
         {"version", no_argument, 0, 'V'},
         {"verbose", required_argument, 0, 'v'},
         {"verbose", required_argument, 0, 'v'},
-
         {"input", required_argument, 0, 'i'},
+
         {"in", required_argument, 0, 0},
         {0, 0, 0, 0}
         {0, 0, 0, 0}
       };
       };
     int option_index = 0;
     int option_index = 0;
-
     c = getopt_long (argc, argv, "hVv:i:",
+
     c = getopt_long(argc, argv, "hVv:",
-
                    long_options, &option_index);
+
                    long_options, &option_index);
-
     if (c == -1)
+
     if(c == -1)
       break;
       break;
-
     switch (c)
+
     switch(c)
     {
     {
     case 0:
     case 0:
-
       if (long_options[option_index].flag != 0)
+
       if(long_options[option_index].flag != 0)
         break;
         break;
 +
      if(strcmp(long_options[option_index].name, "in") == 0)
 +
      {
 +
        input = optarg;
 +
        break;
 +
      }
     case 'h':
     case 'h':
       help (argv);
       help (argv);
-
       exit (0);
+
       exit(0);
     case 'V':
     case 'V':
-
       version (argv);
+
       version(argv);
-
       exit (0);
+
       exit(0);
     case 'v':
     case 'v':
       verbose = atoi(optarg);
       verbose = atoi(optarg);
-
      break;
 
-
    case 'i':
 
-
      input = optarg;
 
       break;
       break;
     case '?':
     case '?':
-
       printf ("\n"); help (argv);
+
       printf("\n"); help(argv);
-
       abort ();
+
       abort();
     default:
     default:
-
       printf ("\n"); help (argv);
+
       printf("\n"); help(argv);
-
       abort ();
+
       abort();
     }
     }
   }
   }
-
   if (input.empty())
+
   if(input.empty())
   {
   {
-
     printCmdLine (argc, argv);
+
     getCmdLine(argc, argv);
-
     fprintf (stderr, "ERROR: missing compulsory option -i\n\n");
+
     fprintf(stderr, "ERROR: missing compulsory option --in\n\n");
-
     help (argv);
+
     help(argv);
-
     exit (1);
+
     exit(1);
   }
   }
-
   if (! doesFileExist (input))
+
   if(! doesFileExist(input))
   {
   {
-
     printCmdLine (argc, argv);
+
     getCmdLine(argc, argv);
-
     fprintf (stderr, "ERROR: can't find '%s'\n\n", input.c_str());
+
     fprintf(stderr, "ERROR: can't find '%s'\n\n", input.c_str());
-
     help (argv);
+
     help(argv);
-
     exit (1);
+
     exit(1);
   }
   }
}
}
-
int main (int argc, char ** argv)
+
int main(int argc, char ** argv)
{
{
   string input;
   string input;
   int verbose = 1;
   int verbose = 1;
    
    
-
   parseArgs (argc, argv, input, verbose);
+
   parseCmdLine(argc, argv, input, verbose);
    
    
   time_t startRawTime, endRawTime;
   time_t startRawTime, endRawTime;
-
   if (verbose > 0)
+
   if(verbose > 0)
   {
   {
-
     time (&startRawTime);
+
     time(&startRawTime);
-
     cout << "START " << argv[0] << " (" << time2string (startRawTime) << ")"
+
     cout << "START " << basename(argv[0])
-
         << endl << flush;
+
        << " " << getDateTime(startRawTime) << endl
-
    printCmdLine (argc, argv);
+
        << "version " << VERSION << " compiled " << __DATE__
 +
         << " " << __TIME__ << endl
 +
        << "cmd-line: " << getCmdLine(argc, argv) << endl
 +
        << "cwd: " << getCurrentDirectory() << endl;
 +
    cout << flush;
   }
   }
    
    
   // ... specific code ...
   // ... specific code ...
    
    
-
   if (verbose > 0)
+
   if(verbose > 0)
   {
   {
-
     time (&endRawTime);
+
     time(&endRawTime);
-
     cout << "END " << argv[0] << " (" << time2string (endRawTime) << ")"
+
     cout << "END " << basename(argv[0])
-
        << endl
+
        << " " << getDateTime(endRawTime) << endl
-
         << "elapsed -> " << elapsedTime(startRawTime, endRawTime)
+
         << "elapsed -> " << getElapsedTime(startRawTime, endRawTime) << endl
-
        << endl
+
         << "max.mem -> " << getMaxMemUsedByProcess2Str() << endl;
-
         << "max.mem -> " << getMaxMemUsedByProcess () << " kB"
+
-
        << endl;
+
   }
   }
    
    
Line 294: Line 320:
</nowiki>
</nowiki>
-
* '''Latex-Beamer''': it is assumed that the code below is copied into a file named "mypresentation.tex". Several packages are assumed to be already installed. The current directory is also assumed to contain a directory named "figures" in which are saved all picture files included in the presentation.
+
* '''R''':
  <nowiki>
  <nowiki>
-
% Author: Timothée Flutre                                                                                                                                  
+
#!/usr/bin/env Rscript
 +
 
 +
# Aim: does this and that
 +
# choose between:
 +
# Author: Timothee Flutre
 +
# Not copyrighted -- provided to the public domain
 +
# or:
 +
# Copyright (C) 2011-2013 Timothee Flutre
 +
# License: GPLv3+
 +
 
 +
rm(list=ls())
 +
prog.name <- "myscript.R"
 +
 
 +
help <- function(){
 +
  txt <- paste0("`", prog.name, "' does this and that.\n")
 +
  txt <- paste0(txt, "\nUsage: ", prog.name, " [OPTIONS] ...\n")
 +
  txt <- paste0(txt, "\nOptions:\n")
 +
  txt <- paste0(txt, "  -h, --help\tdisplay the help and exit\n")
 +
  txt <- paste0(txt, "  -V, --version\toutput version information and exit\n")
 +
  txt <- paste0(txt, "  -v, --verbose\tverbosity level (0/default=1/2/3)\n")
 +
  txt <- paste0(txt, "  -i\t\tinput\n")
 +
  message(txt)
 +
}
 +
 
 +
version <- function(){
 +
  txt <- paste0(prog.name, " 1.0\n")
 +
  txt <- paste0(txt, "\n")
 +
  txt <- paste0(txt, "Written by Timothee Flutre.\n")
 +
  txt <- paste0(txt, "\n")
 +
# choose between:
 +
  txt <- paste0(txt, "Not copyrighted -- provided to the public domain\n")
 +
# or:
 +
  txt <- paste0(txt, "Copyright (C) 2011-2013 Timothee Flutre.\n")
 +
  txt <- paste0(txt, "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>\n")
 +
  txt <- paste0(txt, "This is free software; see the source for copying conditions.  There is NO\n")
 +
  txt <- paste0(txt, "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n")
 +
  message(txt)
 +
}
 +
 
 +
parseArgs <- function(params){
 +
  args <- commandArgs(trailingOnly=TRUE)
 +
  ## print(args)
 +
 
 +
  i <- 0
 +
  while(i < length(args)){ # use "while" loop for options with no argument
 +
    i <- i + 1
 +
    if(args[i] == "-h" || args[i] == "--help"){
 +
      help()
 +
      quit("no", status=0)
 +
    }
 +
    else if(args[i] == "-V" || args[i] == "--version"){
 +
      version()
 +
      quit("no", status=0)
 +
    }
 +
    else if(args[i] == "-v" || args[i] == "--verbose"){
 +
      params$verbose <- as.numeric(args[i+1])
 +
      i <- i + 1
 +
    }
 +
    else if(args[i] == "-i"){
 +
      params$in.file <- args[i+1]
 +
      i <- i + 1
 +
    }
 +
    else
 +
      stop(paste0("unknown option ", args[i]))
 +
  }
 +
 
 +
  if(params$verbose > 0){
 +
    message("parameters:")
 +
    print(params)
 +
  }
 +
 
 +
  return(params)
 +
}
 +
 
 +
checkParams <- function(params){
 +
  stopifnot(! is.null(params$input),
 +
            file.exists(params$input))
 +
 +
 
 +
main <- function(){
 +
  params <- list(verbose=1,
 +
                input=NULL)
 +
  params <- parseArgs(params)
 +
  checkParams(params)
 +
  if(params$verbose > 0)
 +
    message(paste0("START ", prog.name, " (", date(), ")"))
 +
 
 +
  ## ... specific code ...
 +
 
 +
  if(params$verbose > 0)
 +
    message(paste0("END ", prog.name, " (", date(), ")"))
 +
}
 +
 
 +
system.time(main())
 +
print(object.size(x=lapply(ls(), get)), units="Kb")
 +
</nowiki>
 +
 
 +
* '''Bash''': sometimes it's easier to write a script in bash rather than in python. This is especially the case when one wants to use pipes, eg. <nowiki>zcat data.txt.gz | awk '{print $1}'</nowiki>, or when one wants to use a [http://en.wikipedia.org/wiki/Glob_%28programming%29 glob] to pass multiple files to the script, eg. <nowiki>./myscript.bash -i "input*.txt"</nowiki>.
 +
 
 +
<nowiki>
 +
#!/usr/bin/env bash
 +
 
 +
# Aim: does this and that
 +
# choose between:
 +
# Author: Timothee Flutre
 +
# Not copyrighted -- provided to the public domain
 +
# or:
 +
# Copyright (C) 2011-2013 Timothee Flutre
 +
# License: GPLv3+
 +
 
 +
function help () {
 +
    msg="\`${0##*/}' does this and that.\n"
 +
    msg+="\n"
 +
    msg+="Usage: ${0##*/} [OPTIONS] ...\n"
 +
    msg+="\n"
 +
    msg+="Options:\n"
 +
    msg+="  -h, --help\tdisplay the help and exit\n"
 +
    msg+="  -V, --version\toutput version information and exit\n"
 +
    msg+="  -v, --verbose\tverbosity level (0/default=1/2/3)\n"
 +
    msg+="  -i, --in\tinput\n"
 +
    msg+="\n"
 +
    msg+="Examples:\n"
 +
    msg+="  ${0##*/} -i <input>\n"
 +
    echo -e "$msg"
 +
}
 +
 
 +
function version () {
 +
    msg="${0##*/} 1.0\n"
 +
    msg+="\n"
 +
    msg+="Written by Timothee Flutre.\n"
 +
    msg+="\n"
 +
# choose between:
 +
    msg += "Not copyrighted -- provided to the public domain\n"
 +
# or:
 +
    msg+="Copyright (C) 2011-2013 Timothee Flutre.\n"
 +
    msg+="License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>\n"
 +
    msg+="This is free software; see the source for copying conditions.  There is NO\n"
 +
    msg+="warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n"
 +
    echo -e "$msg"
 +
}
 +
 
 +
# http://www.linuxjournal.com/content/use-date-command-measure-elapsed-time
 +
function timer () {
 +
    if [[ $# -eq 0 ]]; then
 +
        echo $(date '+%s')
 +
    else
 +
        local startRawTime=$1
 +
        endRawTime=$(date '+%s')
 +
        if [[ -z "$startRawTime" ]]; then startRawTime=$endRawTime; fi
 +
        elapsed=$((endRawTime - startRawTime)) # in sec
 +
        nbDays=$((elapsed / 86400))
 +
        nbHours=$(((elapsed / 3600) % 24))
 +
        nbMins=$(((elapsed / 60) % 60))
 +
        nbSecs=$((elapsed % 60))
 +
        printf "%01dd %01dh %01dm %01ds" $nbDays $nbHours $nbMins $nbSecs
 +
    fi
 +
}
 +
 
 +
function parseArgs () {
 +
    TEMP=`getopt -o hVv:i: -l help,version,verbose:,in: \
 +
        -n "$0" -- "$@"`
 +
    if [ $? != 0 ] ; then echo "ERROR: getopt failed" >&2 ; exit 1 ; fi
 +
    eval set -- "$TEMP"
 +
    while true; do
 +
        case "$1" in
 +
            -h|--help) help; exit 0; shift;;
 +
            -V|--version) version; exit 0; shift;;
 +
            -v|--verbose) verbose=$2; shift 2;;
 +
            -i|--in) input=$2; shift 2;;
 +
            --) shift; break;;
 +
            *) echo "ERROR: options parsing failed"; exit 1;;
 +
        esac
 +
    done
 +
    if [ -z "${input}" ]; then
 +
        echo -e "ERROR: missing compulsory option -i\n"
 +
        help
 +
        exit 1
 +
    fi
 +
    if [ ! -f "${input}" ]; then
 +
        echo -e "ERROR: can't find '${input}'\n"
 +
        help
 +
        exit 1
 +
    fi
 +
}
 +
 
 +
verbose=1
 +
input=""
 +
parseArgs "$@"
 +
 
 +
if [ $verbose -gt "0" ]; then
 +
    startTime=$(timer)
 +
    msg="START ${0##*/} $(date +"%Y-%m-%d") $(date +"%H:%M:%S")"
 +
    msg+="\ncmd-line: $0 "$@ # comment if an option takes a glob as argument
 +
    echo -e $msg
 +
fi
 +
 
 +
# ... specific code ...
 +
 
 +
if [ $verbose -gt "0" ]; then
 +
    msg="END ${0##*/} $(date +"%Y-%m-%d") $(date +"%H:%M:%S")"
 +
    msg+=" ($(timer startTime))"
 +
    echo $msg
 +
fi
 +
</nowiki>
 +
 
 +
* '''Latex-Beamer''': it is assumed that the code below is copied into a file named "mypresentation.tex" and that several packages are already installed. The current directory is also assumed to contain a sub-directory named "figures" in which are saved all picture files included in the presentation.
 +
 
 +
<nowiki>
 +
% Copyright (C) 2012 Timothee Flutre.
\documentclass{beamer}
\documentclass{beamer}
\usepackage{amsmath}
\usepackage{amsmath}
-
\usepackage{bm} % to have mathematical symbols in bold                                                                                                      
+
\usepackage{bm} % to have mathematical symbols in bold
\usepackage{hyperref}
\usepackage{hyperref}
\hypersetup{colorlinks, linkcolor=black, urlcolor=gray}
\hypersetup{colorlinks, linkcolor=black, urlcolor=gray}
Line 308: Line 542:
\usepackage[francais]{babel}
\usepackage[francais]{babel}
\usepackage[utf8]{inputenc}
\usepackage[utf8]{inputenc}
-
 
\graphicspath{{./figures/}}
\graphicspath{{./figures/}}
-
%-----------------------------------------------------------------------------                                                                              
+
%-----------------------------------------------------------------------------
\setbeamertemplate{caption}[numbered]
\setbeamertemplate{caption}[numbered]
Line 330: Line 563:
       \usebeamerfont{section in head/foot}\insertshorttitle
       \usebeamerfont{section in head/foot}\insertshorttitle
     \end{beamercolorbox}
     \end{beamercolorbox}
-
     \begin{beamercolorbox}[wd=.27\paperwidth,ht=2.25ex,dp=1ex,right]{section in head/foot}%                                                                
+
     \begin{beamercolorbox}[wd=.27\paperwidth,ht=2.25ex,dp=1ex,right]{section in head/foot}%
       \usebeamerfont{section in head/foot}\insertshortdate{}\hspace*{2em}
       \usebeamerfont{section in head/foot}\insertshortdate{}\hspace*{2em}
       \insertframenumber{} / \inserttotalframenumber\hspace*{2ex}
       \insertframenumber{} / \inserttotalframenumber\hspace*{2ex}
Line 347: Line 580:
}
}
-
%-----------------------------------------------------------------------------                                                                              
+
%-----------------------------------------------------------------------------
\title[Short title]{Long title}
\title[Short title]{Long title}
Line 356: Line 589:
begin{document}
begin{document}
-
\begin{frame}                                                                                                                                              
+
\begin{frame}
-
\titlepage                                                                                                                                                  
+
\titlepage
-
\end{frame}                                                                                                                                                
+
\end{frame}                                                                                                                      
-
                                                                                                                                                           
+
-
\begin{frame}                                                                                                                                               
+
-
\frametitle{Outline}                                                                                                                                       
+
-
\tableofcontents                                                                                                                                           
+
-
\end{frame}                                                                                                                                                 
+
-
\section{First section}
+
\begin{frame}
 +
\frametitle{Outline}
 +
\tableofcontents
 +
\end{frame}
 +
\section{First section}
\begin{frame}
\begin{frame}
\frametitle{I.1.}
\frametitle{I.1.}
Line 379: Line 611:
\frametitle{II.1.}
\frametitle{II.1.}
\begin{center}
\begin{center}
-
%\includegraphics[width=0.95\textwidth,height=0.90\textheight,keepaspectratio=true]{myplot}%                                                                      
+
%\includegraphics[width=0.95\textwidth,height=0.90\textheight,keepaspectratio=true]{myplot}%
\end{center}
\end{center}
\end{frame}
\end{frame}
Line 385: Line 617:
end{document}
end{document}
</nowiki>
</nowiki>
-
 
<!-- ##### DO NOT edit below this line unless you know what you are doing. ##### -->
<!-- ##### DO NOT edit below this line unless you know what you are doing. ##### -->

Revision as of 12:45, 13 May 2013

Project name Main project page
Previous entry      Next entry

Typical templates for Python scripts, C++ programs and others

It is always rewarding on the long term to start any piece of computer software with a minimum amount of generic code (verbose, command-line options, help message, license, etc). But it's a pain to write all this every time, right? So below are my typical templates for any Python script, C++ program, Beamer presentation, Bash script, etc.

  • Easy user documentation: I'm a firm believer that it is necessary to add some user documentation, even minimal, to any program. An easy way to do this is to simply generate such documentation from the "help" message, as long as it is "properly" formatted (see help2man). The following commands work for any programming language:
help2man -o myprogram.man ./myprogram
man ./myprogram.man
groff -mandoc myprogram.man > myprogram.ps
ps2pdf myprogram.ps myprogram.pdf

  • Python: it is assumed that the code below is copied into a file named "MyClass.py".
#!/usr/bin/env python

# Aim: does this and that
# choose between:
# Author: Timothee Flutre
# Not copyrighted -- provided to the public domain
# or:
# Copyright (C) 2011-2013 Timothee Flutre
# License: GPLv3+

import sys
import os
import getopt
import time
import datetime
import math


class MyClass(object):
    
    def __init__(self):
        self.verbose = 1
        self.input = ""
        
        
    def help(self):
        msg = "`%s' does this and that.\n" % os.path.basename(sys.argv[0])
        msg += "\n"
        msg += "Usage: %s [OPTIONS] ...\n" % os.path.basename(sys.argv[0])
        msg += "\n"
        msg += "Options:\n"
        msg += " -h, --help\tdisplay the help and exit\n"
        msg += " -V, --version\toutput version information and exit\n"
        msg += " -v, --verbose\tverbosity level (0/default=1/2/3)\n"
        msg += " -i\tinput\n"
        msg += "\n"
        msg += "Examples:\n"
        print msg; sys.stdout.flush()
        
        
    def version(self):
        msg = "%s 1.0\n" % os.path.basename(sys.argv[0])
        msg += "\n"
        msg += "Written by Timothee Flutre.\n"
        msg += "\n"
# choose between:
        msg += "Not copyrighted -- provided to the public domain\n"
# or:
        msg += "Copyright (C) 2011-2013 Timothee Flutre.\n"
        msg += "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>\n"
        msg += "This is free software; see the source for copying conditions.  There is NO\n"
        msg += "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n"
        print msg; sys.stdout.flush()
        
        
    def setAttributesFromCmdLine(self):
        try:
            opts, args = getopt.getopt( sys.argv[1:], "hVv:i:",
                                        ["help", "version", "verbose="])
        except getopt.GetoptError, err:
            sys.stderr.write("%s\n" % str(err))
            self.help()
            sys.exit(2)
        for o, a in opts:
            if o == "-h" or o == "--help":
                self.help()
                sys.exit(0)
            elif o == "-V" or o == "--version":
                self.version()
                sys.exit(0)
            elif o == "-v" or o == "--verbose":
                self.verbose = int(a)
            elif o == "-i":
                 self.input = a
            else:
                assert False, "unhandled option"
                
                
    def checkAttributes(self):
        if self.input == "":
            msg = "ERROR: missing compulsory option -i"
            sys.stderr.write("%s\n\n" % msg)
            self.help()
            sys.exit(1)
        if not os.path.exists(self.input):
            msg = "ERROR: can't find '%s'" % self.input
            sys.stderr.write("%s\n\n" % msg)
            self.help()
            sys.exit(1)
            
            
    def run(self):
        self.checkAttributes()
        
        if self.verbose > 0:
            startTime = time.time()
            msg = "START %s %s" % (os.path.basename(sys.argv[0]),
                                   time.strftime("%Y-%m-%d %H:%M:%S"))
            msg += "\ncmd-line: %s" % ' '.join(sys.argv)
            print msg; sys.stdout.flush()
            
        # ... specific code ...
        
        if self.verbose > 0:
            msg = "END %s %s" % (os.path.basename(sys.argv[0]),
                                 time.strftime("%Y-%m-%d %H:%M:%S"))
            endTime = time.time()
            runLength = datetime.timedelta(seconds=
                                           math.floor(endTime - startTime))
            msg += " (%s)" % str(runLength)
            print msg; sys.stdout.flush()
            
            
if __name__ == "__main__":
    i = MyClass()
    i.setAttributesFromCmdLine()
    i.run()

  • C++: it is assumed that the code below is copied into a file named "myprogram.cpp" and that the file "utils_io.cpp" is present in the same directory, along with its header utils_io.hpp.
/** \file myprogram.cpp
 *
 *  `myprogram' does this and that.
 *  Copyright (C) 2011-2013 Timothee Flutre
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 *  g++ -Wall -g utils_io.cpp myprogram.cpp -lgsl -lgslcblas -lz -o myprogram
*/

#include <cmath>
#include <ctime>
#include <getopt.h>

#include <iostream>
#include <string>
using namespace std;

#include "utils_io.hpp"

#ifndef VERSION
#define VERSION "1.0"
#endif

/** \brief Display the help on stdout.
*/
void help(char ** argv)
{
  cout << "`" << argv[0] << "'"
       << " does this and that." << endl
       << endl
       << "Usage: " << argv[0] << " [OPTIONS] ..." << endl
       << endl
       << "Options:" << endl
       << "  -h, --help\tdisplay the help and exit" << endl
       << "  -V, --version\toutput version information and exit" << endl
       << "  -v, --verbose\tverbosity level (0/default=1/2/3)" << endl
       << "      --in\tinput" << endl
       << endl
       << "Examples:" << endl
       << "  " << argv[0] << " --in <input>" << endl
       << endl
       << "Remarks:" << endl
       << "  This is my typical template file for C++." << endl
    ;
}

/** \brief Display version and license information on stdout.
 */
void version(char ** argv)
{
  cout << argv[0] << " " << VERSION << endl
       << endl
       << "Copyright (C) 2011-2013 Timothee Flutre." << endl
       << "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>" << endl
       << "This is free software; see the source for copying conditions.  There is NO" << endl
       << "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE." << endl
       << endl
       << "Written by Timothee Flutre." << endl;
}

/** \brief Parse the command-line arguments and check the values of the 
 *  compulsory ones.
 */
void
parseCmdLine(
  int argc,
  char ** argv,
  string & input,
  int & verbose)
{
  int c = 0;
  while(true)
  {
    static struct option long_options[] =
      {
        {"help", no_argument, 0, 'h'},
        {"version", no_argument, 0, 'V'},
        {"verbose", required_argument, 0, 'v'},
        {"in", required_argument, 0, 0},
        {0, 0, 0, 0}
      };
    int option_index = 0;
    c = getopt_long(argc, argv, "hVv:",
                    long_options, &option_index);
    if(c == -1)
      break;
    switch(c)
    {
    case 0:
      if(long_options[option_index].flag != 0)
        break;
      if(strcmp(long_options[option_index].name, "in") == 0)
      {
        input = optarg;
        break;
      }
    case 'h':
      help (argv);
      exit(0);
    case 'V':
      version(argv);
      exit(0);
    case 'v':
      verbose = atoi(optarg);
      break;
    case '?':
      printf("\n"); help(argv);
      abort();
    default:
      printf("\n"); help(argv);
      abort();
    }
  }
  if(input.empty())
  {
    getCmdLine(argc, argv);
    fprintf(stderr, "ERROR: missing compulsory option --in\n\n");
    help(argv);
    exit(1);
  }
  if(! doesFileExist(input))
  {
    getCmdLine(argc, argv);
    fprintf(stderr, "ERROR: can't find '%s'\n\n", input.c_str());
    help(argv);
    exit(1);
  }
}

int main(int argc, char ** argv)
{
  string input;
  int verbose = 1;
  
  parseCmdLine(argc, argv, input, verbose);
  
  time_t startRawTime, endRawTime;
  if(verbose > 0)
  {
    time(&startRawTime);
    cout << "START " << basename(argv[0])
         << " " << getDateTime(startRawTime) << endl
         << "version " << VERSION << " compiled " << __DATE__
         << " " << __TIME__ << endl
         << "cmd-line: " << getCmdLine(argc, argv) << endl
         << "cwd: " << getCurrentDirectory() << endl;
    cout << flush;
  }
  
  // ... specific code ...
  
  if(verbose > 0)
  {
    time(&endRawTime);
    cout << "END " << basename(argv[0])
         << " " << getDateTime(endRawTime) << endl
         << "elapsed -> " << getElapsedTime(startRawTime, endRawTime) << endl
         << "max.mem -> " << getMaxMemUsedByProcess2Str() << endl;
  }
  
  return EXIT_SUCCESS;
}

  • R:
#!/usr/bin/env Rscript

# Aim: does this and that
# choose between:
# Author: Timothee Flutre
# Not copyrighted -- provided to the public domain
# or:
# Copyright (C) 2011-2013 Timothee Flutre
# License: GPLv3+

rm(list=ls())
prog.name <- "myscript.R"

help <- function(){
  txt <- paste0("`", prog.name, "' does this and that.\n")
  txt <- paste0(txt, "\nUsage: ", prog.name, " [OPTIONS] ...\n")
  txt <- paste0(txt, "\nOptions:\n")
  txt <- paste0(txt, "  -h, --help\tdisplay the help and exit\n")
  txt <- paste0(txt, "  -V, --version\toutput version information and exit\n")
  txt <- paste0(txt, "  -v, --verbose\tverbosity level (0/default=1/2/3)\n")
  txt <- paste0(txt, "  -i\t\tinput\n")
  message(txt)
}

version <- function(){
  txt <- paste0(prog.name, " 1.0\n")
  txt <- paste0(txt, "\n")
  txt <- paste0(txt, "Written by Timothee Flutre.\n")
  txt <- paste0(txt, "\n")
# choose between:
  txt <- paste0(txt, "Not copyrighted -- provided to the public domain\n")
# or:
  txt <- paste0(txt, "Copyright (C) 2011-2013 Timothee Flutre.\n")
  txt <- paste0(txt, "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>\n")
  txt <- paste0(txt, "This is free software; see the source for copying conditions.  There is NO\n")
  txt <- paste0(txt, "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n")
  message(txt)
}

parseArgs <- function(params){
  args <- commandArgs(trailingOnly=TRUE)
  ## print(args)
  
  i <- 0
  while(i < length(args)){ # use "while" loop for options with no argument
    i <- i + 1
    if(args[i] == "-h" || args[i] == "--help"){
      help()
      quit("no", status=0)
    }
    else if(args[i] == "-V" || args[i] == "--version"){
      version()
      quit("no", status=0)
    }
    else if(args[i] == "-v" || args[i] == "--verbose"){
      params$verbose <- as.numeric(args[i+1])
      i <- i + 1
    }
    else if(args[i] == "-i"){
      params$in.file <- args[i+1]
      i <- i + 1
    }
    else
      stop(paste0("unknown option ", args[i]))
  }
  
  if(params$verbose > 0){
    message("parameters:")
    print(params)
  }
  
  return(params)
}

checkParams <- function(params){
  stopifnot(! is.null(params$input),
            file.exists(params$input))
}  

main <- function(){
  params <- list(verbose=1,
                 input=NULL)
  params <- parseArgs(params)
  checkParams(params)
  if(params$verbose > 0)
    message(paste0("START ", prog.name, " (", date(), ")"))
  
  ## ... specific code ...
  
  if(params$verbose > 0)
    message(paste0("END ", prog.name, " (", date(), ")"))
}

system.time(main())
print(object.size(x=lapply(ls(), get)), units="Kb")

  • Bash: sometimes it's easier to write a script in bash rather than in python. This is especially the case when one wants to use pipes, eg. zcat data.txt.gz | awk '{print $1}', or when one wants to use a glob to pass multiple files to the script, eg. ./myscript.bash -i "input*.txt".
#!/usr/bin/env bash

# Aim: does this and that
# choose between:
# Author: Timothee Flutre
# Not copyrighted -- provided to the public domain
# or:
# Copyright (C) 2011-2013 Timothee Flutre
# License: GPLv3+

function help () {
    msg="\`${0##*/}' does this and that.\n"
    msg+="\n"
    msg+="Usage: ${0##*/} [OPTIONS] ...\n"
    msg+="\n"
    msg+="Options:\n"
    msg+="  -h, --help\tdisplay the help and exit\n"
    msg+="  -V, --version\toutput version information and exit\n"
    msg+="  -v, --verbose\tverbosity level (0/default=1/2/3)\n"
    msg+="  -i, --in\tinput\n"
    msg+="\n"
    msg+="Examples:\n"
    msg+="  ${0##*/} -i <input>\n"
    echo -e "$msg"
}

function version () {
    msg="${0##*/} 1.0\n"
    msg+="\n"
    msg+="Written by Timothee Flutre.\n"
    msg+="\n"
# choose between:
    msg += "Not copyrighted -- provided to the public domain\n"
# or:
    msg+="Copyright (C) 2011-2013 Timothee Flutre.\n"
    msg+="License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>\n"
    msg+="This is free software; see the source for copying conditions.  There is NO\n"
    msg+="warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n"
    echo -e "$msg"
}

# http://www.linuxjournal.com/content/use-date-command-measure-elapsed-time
function timer () {
    if [[ $# -eq 0 ]]; then
        echo $(date '+%s')
    else
        local startRawTime=$1
        endRawTime=$(date '+%s')
        if [[ -z "$startRawTime" ]]; then startRawTime=$endRawTime; fi
        elapsed=$((endRawTime - startRawTime)) # in sec
        nbDays=$((elapsed / 86400))
        nbHours=$(((elapsed / 3600) % 24))
        nbMins=$(((elapsed / 60) % 60))
        nbSecs=$((elapsed % 60))
        printf "%01dd %01dh %01dm %01ds" $nbDays $nbHours $nbMins $nbSecs
    fi
}

function parseArgs () {
    TEMP=`getopt -o hVv:i: -l help,version,verbose:,in: \
        -n "$0" -- "$@"`
    if [ $? != 0 ] ; then echo "ERROR: getopt failed" >&2 ; exit 1 ; fi
    eval set -- "$TEMP"
    while true; do
        case "$1" in
            -h|--help) help; exit 0; shift;;
            -V|--version) version; exit 0; shift;;
            -v|--verbose) verbose=$2; shift 2;;
            -i|--in) input=$2; shift 2;;
            --) shift; break;;
            *) echo "ERROR: options parsing failed"; exit 1;;
        esac
    done
    if [ -z "${input}" ]; then
        echo -e "ERROR: missing compulsory option -i\n"
        help
        exit 1
    fi
    if [ ! -f "${input}" ]; then
        echo -e "ERROR: can't find '${input}'\n"
        help
        exit 1
    fi
}

verbose=1
input=""
parseArgs "$@"

if [ $verbose -gt "0" ]; then
    startTime=$(timer)
    msg="START ${0##*/} $(date +"%Y-%m-%d") $(date +"%H:%M:%S")"
    msg+="\ncmd-line: $0 "$@ # comment if an option takes a glob as argument
    echo -e $msg
fi

# ... specific code ...

if [ $verbose -gt "0" ]; then
    msg="END ${0##*/} $(date +"%Y-%m-%d") $(date +"%H:%M:%S")"
    msg+=" ($(timer startTime))"
    echo $msg
fi

  • Latex-Beamer: it is assumed that the code below is copied into a file named "mypresentation.tex" and that several packages are already installed. The current directory is also assumed to contain a sub-directory named "figures" in which are saved all picture files included in the presentation.
% Copyright (C) 2012 Timothee Flutre.

\documentclass{beamer}
\usepackage{amsmath}
\usepackage{bm} % to have mathematical symbols in bold
\usepackage{hyperref}
\hypersetup{colorlinks, linkcolor=black, urlcolor=gray}
\usepackage{multirow}
\usepackage{tikz}
\usepackage[francais]{babel}
\usepackage[utf8]{inputenc}

\graphicspath{{./figures/}}

%-----------------------------------------------------------------------------

\setbeamertemplate{caption}[numbered]
\setbeamerfont{caption}{size=\scriptsize}
\setbeamertemplate{navigation symbols}{}
\setbeamercolor{alerted text}{fg=purple}

\setbeamertemplate{footline}
{
  \leavevmode
  \hbox{
    \hspace*{-0.06cm}
    \begin{beamercolorbox}[wd=.2\paperwidth,ht=2.25ex,dp=1ex,center]{author in head/foot}
      \usebeamerfont{author in head/foot}\insertshortauthor \hspace*{1em} \insertshortinstitute
    \end{beamercolorbox}
    \begin{beamercolorbox}[wd=.50\paperwidth,ht=2.25ex,dp=1ex,center]{section in head/foot}
      \usebeamerfont{section in head/foot}\insertshorttitle
    \end{beamercolorbox}
    \begin{beamercolorbox}[wd=.27\paperwidth,ht=2.25ex,dp=1ex,right]{section in head/foot}%
      \usebeamerfont{section in head/foot}\insertshortdate{}\hspace*{2em}
      \insertframenumber{} / \inserttotalframenumber\hspace*{2ex}
    \end{beamercolorbox}
  }
  \vskip0pt
}

\AtBeginSection[]
{
  \begin{frame}
    \frametitle{Outline}
    \addtocounter{framenumber}{-1}
    \tableofcontents[currentsection]
  \end{frame}
}

%-----------------------------------------------------------------------------

\title[Short title]{Long title}
\author[T. Flutre]{Timoth\'{e}e Flutre}
\institute[Short affiliation]{Long affiliation}
\date{\today}

begin{document}

\begin{frame}
\titlepage
\end{frame}                                                                                                                       

\begin{frame}
\frametitle{Outline}
\tableofcontents
\end{frame}

\section{First section}
\begin{frame}
\frametitle{I.1.}
\begin{itemize}
\item 
\end{itemize}
\end{frame}

\section{Second section}

\begin{frame}
\frametitle{II.1.}
\begin{center}
%\includegraphics[width=0.95\textwidth,height=0.90\textheight,keepaspectratio=true]{myplot}%
\end{center}
\end{frame}

end{document}


Personal tools