miriad 4.1.0.0

data/README

@@ -0,0 +1,103 @@
+--
+
+$Id: README 903 2008-04-17 23:05:44Z davidm $
+
+This file includes an RDoc hack so that links can be made to open up into a new
+frame rather then the current frame.
+
+The "trick" is to append ``"target="_top'' to the URL.
+
+++
+
+= MIRIAD-Ruby
+
+== Introduction
+
+The MIRIAD-Ruby package...
+
+1. Makes MIRIAD datasets accessible from Ruby by wrapping the {MIRIAD
+   UVIO}[link:classes/Miriad/Uvio.html] routines.
+
+2. Makes Ruby usable with MIRIAD datasets by adding convenience, utility, and
+   astronomy related methods to Ruby classes.
+
+== Installation
+
+MIRIAD-Ruby can be installed in three easy steps.
+
+1. Install Ruby.  See the {Ruby Download Page
+   }[http://www.ruby-lang.org/en/downloads/"target="_top] for instructions.
+
+2. Install RubyGems (for Ruby < 1.9.0)  See the {RubyGems web site
+   }[http://www.rubygems.org/"target="_top] for instructions.
+
+3. Install MIRIAD-Ruby by running...
+
+   <tt>gem install miriad</tt>
+
+   or
+
+   <tt>sudo gem install miriad</tt>
+
+== Documentation
+
+You are reading part of it!
+
+=== On the web
+
+The latest documentation is published on the {MIRIAD-Ruby Home
+Page}[http://miriad.rubyforge.org/"target="_top]
+
+=== At your local site
+
+The MIRIAD-Ruby gem contains full documentation, which will be installed along
+with the gem (unless you specified <tt>--no-rdoc</tt> or <tt>--no-ri</tt>, but
+why would you do that?).
+
+To view the local HTML documentation generated from the RDoc comments:
+
+1. Run <tt>gem server</tt>.
+
+2. Point your browser at <tt>http</tt><tt>://localhost:8808/</tt>
+
+3. Find the +miriad+ entry.
+
+4. Click on the [rdoc] link.
+
+To view the local +ri+ documentation (kind if like +man+ or +info+ for Ruby),
+just run <tt>ri <em>class_or_method</em></tt>.  For example, to find out about
+all the ways to call <tt>read()</tt>, type <tt>ri Miriad::Uvio#read</tt>.
+
+== Further Reading
+
+Additional information about MIRIAD-Ruby can be found at:
+
+* {The MIRIAD-Ruby Rubyforge Project Page
+  }[http://rubyforge.org/projects/miriad/"target="_top]
+
+Additional information about MIRIAD can be found at:
+
+* {The Australia Compact Array web page
+  }[http://www.atnf.csiro.au/computing/software/miriad/"target="_top]
+
+* {The MIRIAD Software Page at the University of Maryland
+  }[http://bima.astro.umd.edu/miriad/"target="_top]
+
+== Acknowledgements
+
+The MIRAD-Ruby package is distributed with a snapshot of MIRIAD's lower level
+I/O routines writtin in ANSI C.  Most of the MIRIAD functionality provided by
+MIRIAD-Ruby is actually performed by this C code, which MIRIAD-Ruby wraps and
+exposes to Ruby.
+
+Much of the documentation for the {Miriad::Uvio}[link:classes/Miriad/Uvio.html]
+routines was transcribed into Rdoc format from {The _Miriad_ Programmer's Guide
+}[http://www.atnf.csiro.au/computing/software/miriad/progguide/progguide.html"target="_top].
+
+Authors too numerous to list (and too likely to prefer anonymity) have
+contributed to both the C code and the documentation.  If you are one of them
+and would like to be mentioned here, please file a bug report on the
+MIRIAD-Ruby Rubyforge project page.
+  
+--
+# vim: set expandtab ts=2 sw=2 smarttab syntax=ruby autoindent fo+=taroq2 :

data/Rakefile

@@ -0,0 +1,82 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+def run_swig
+  sh("swig -ruby -autorename -o ext/miriad_wrap.c ext/miriad.i")
+end
+
+# The SWIG-generated wrapper must exist before creating the gemspec
+# otherwise it will not be included in the gem!
+run_swig unless test ?e, 'ext/miriad_wrap.c'
+
+spec = Gem::Specification.new do |s|
+  # Basics
+  s.name = 'miriad'
+  s.version = '4.1.0.0'
+  s.summary = 'Ruby interface to MIRIAD'
+  s.description = <<-EOS
+    The MIRIAD-Ruby package...
+
+    1. Makes MIRIAD datasets accessible from Ruby by wrapping
+       the MIRIAD UVIO routines.
+
+    2. Makes Ruby usable with MIRIAD datasets by adding convenience,
+       utility, and astronomy related methods to Ruby classes.
+    EOS
+
+  #s.platform = Gem::Platform::Ruby
+  s.required_ruby_version = '>= 1.8.6'
+  #s.requirements << 'a prerequisite'
+  s.add_dependency('narray', '>= 0.5.9')
+
+  # About
+  s.authors = 'David MacMahon'
+  s.email = 'davidm@astro.berkeley.edu'
+  s.homepage = 'http://miriad.rubyforge.org/'
+  s.rubyforge_project = 'miriad' 
+
+  # Files, Libraries, and Extensions
+  s.files = FileList[
+    'README',
+    'Rakefile',
+    'lib/miriad.rb',
+    'ext/*.c',
+    'ext/*.h',
+    'ext/*.i',
+    'ext/*.in',
+    'ext/extconf.rb',
+    'ext/*.swg'
+  ].to_a
+  s.files.delete 'ext/maxdimc.h'
+  s.require_paths = ['lib', 'ext']
+  #s.autorequire = nil
+  #s.bindir = 'bin'
+  #s.executables = []
+  #s.default_executable = nil
+
+  # C compilation
+  s.extensions << 'ext/extconf.rb'
+
+  # Documentation
+  s.rdoc_options = ['-x', 'ext/.*.c', '-m', 'README', '-t', "MIRIAD-Ruby Documentation"]
+  s.has_rdoc = true
+  s.extra_rdoc_files = %w[README ext/miriad_ruby.c]
+
+  # Testing TODO
+  #s.test_files = []
+end
+
+file "ext/miriad_wrap.c" => %w[ext/miriad.i ext/miriad_ruby.i ext/narray_ruby.swg] do |t|
+  sh("swig -ruby -autorename -o #{t.name} #{t.prerequisites[0]}")
+end
+
+desc "Run SWIG to generate the wrapper code."
+task :swig => "ext/miriad_wrap.c"
+
+task "pkg" => :swig
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  task pkg.package_dir_path => :swig
+  pkg.need_zip = true
+  pkg.need_tar = true
+end

data/ext/bug.c

@@ -0,0 +1,341 @@
+/************************************************************************/
+/*									*/
+/* This handles errors and can abort your program.			*/
+/*									*/
+/*  History:								*/
+/*    rjs,mjs ????    Very mixed history. Created, destroyed, rewritten.*/
+/*    rjs     26aug93 Call habort_c.					*/
+/*    rjs     14jul98 Add a caste operation in errmsg_c, to attempt	*/
+/*		      to appease some compilers.			*/
+/*    pjt     23sep01 darwin						*/
+/*    pjt      4dec01 bypass fatal errors (for alien clients) if req'd  */
+/*                    through the new bugrecover_c() routine            */
+/*    pjt     17jun02 prototypes for MIR4                               */
+/*    pjt/ram  5dec03 using strerror() for unix                         */
+/*    pjt      1jan05 bugv_c: finally, a real stdargs version!!!        */
+/*                    though cannot be exported to Fortran              */
+/*    pjt     26mar07 bugmessage_c: retrieve last fatal bug message     */
+/*    pjt     27mar07 bugseverity_c: also overhauled bug recovery       */
+/*                    and removed VMS specific code                     */
+/*    pjt     17may07 removed old-non ANSI declaration                  */
+/*    pjt      5dec07 add Name to bug output - why took us so long?     */
+/*    pkgw     6mar08 declare Name as static to prevent symbol clashes  */
+/************************************************************************/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <stdarg.h>
+#include "miriad.h"
+
+/*
+ * Added by MIRIAD-Ruby
+ */
+#ifdef MIRIAD_RUBY
+#include "ruby.h"
+
+extern VALUE mirlib_eMirlibError;
+
+#define fprintf(io,fmt,...) \
+  do { \
+    switch(s) { \
+      case 'i': case 'I': \
+      case 'w': case 'W': \
+        fprintf(io,fmt,__VA_ARGS__); \
+        break; \
+      default: \
+        rb_raise(mirlib_eMirlibError,fmt,__VA_ARGS__); \
+    } \
+  } while(0)
+
+#define exit(never)
+#endif /* MIRIAD_RUBY */
+
+static char *errmsg_c(int n);
+static int  handle_bug_cleanup(int d, char s, Const char *m);
+
+static char *Name = NULL;     /* a slot to store the program name       */
+int reentrant=0;              /* keep track of state                    */
+
+typedef void (*proc)(void);  /* helper definition for function pointers */
+
+static proc bug_cleanup=NULL; /* external bug handler, if any           */
+static char *bug_message=0;   /* last message                           */ 
+static char bug_severity=0;   /* last severity level (i,w,e or f)       */
+
+
+#define MAXMSG 256
+static char msg[MAXMSG];      /* formatted message for bugv_c()         */
+
+
+/************************************************************************/
+char *bugmessage_c(void)
+/** bugmessage_c -- return last fatal error message string              */
+/*& pjt                                                                 */
+/*: error-handling                                                      */
+/*+                                                                    
+    This routine does not have a FORTRAN counterpart, as it is normally 
+    only called by C clients who have set their own error handler if
+    for some reason they don't like the MIRIAD one (e.g. C++ or java
+    exceptions, or NEMO's error handler. This way the bugrecover handler
+    can call this routine to retrieve the last fatal error message. 
+
+    bugrecover_c(my_handler);
+    
+    void my_handler(void) {
+       char *m = bugmessage_c();
+       printf("RECOVERED: %s\n",m);
+    }
+    ..                                                                  */
+/*--                                                                    */
+/*----------------------------------------------------------------------*/
+{
+  return bug_message;
+}
+
+/************************************************************************/
+char bugseverity_c(void)
+/** bugseverity_c -- return last severity level                         */
+/*& pjt                                                                 */
+/*: error-handling                                                      */
+/*+                                                                    
+    This routine does not have a FORTRAN counterpart, as it is normally 
+    only called by C clients who have set their own error handler if
+    for some reason they don't like the MIRIAD one (e.g. C++ or java
+    exceptions, or NEMO's error handler. This way the bugrecover handler
+    can call this routine to retrieve the last severity level 
+
+    bugrecover_c(my_handler);
+    
+    void my_handler(void) {
+       char  s = bugseverity_c();
+       char *m = bugmessage_c();
+       printf("RECOVERED: (%c) %s\n",s,m);
+       if (s=='f') exit(1);
+    }
+    ..                                                                  */
+/*--                                                                    */
+/*----------------------------------------------------------------------*/
+{
+  return bug_severity;
+}
+
+/************************************************************************/
+void bugrecover_c(void (*cl)(void))
+/** bugrecover_c -- bypass fatal bug calls for alien clients            */
+/*& pjt                                                                 */
+/*: error-handling                                                      */
+/*+                                                                    
+    This routine does not have a FORTRAN counterpart, as it is normally 
+    only called by C clients who need to set their own error handler if
+    for some reason they don't like the MIRIAD one (e.g. C++ or java
+    exceptions, or NEMO's error handler 
+    Example of usage:
+
+    void my_handler(void) {
+        ....
+    }
+
+
+    ..
+    bugrecover_c(my_handler);
+    ..                                                                  */
+/*--                                                                    */
+/*----------------------------------------------------------------------*/
+{
+    bug_cleanup = cl;
+    if (bug_message) free(bug_message);
+    bug_message = strdup("no bug_message has been set yet");
+}
+
+/************************************************************************/
+void buglabel_c(Const char *name)
+/** buglabel -- Give the "program name" to be used as a label in messages. */
+/*& pjt									*/
+/*: error-handling							*/
+/*+ FORTRAN call sequence:
+	subroutine buglabel(name)
+
+	implicit none
+	character name*(*)
+
+  Give the name that is to be used as a label in error messages. Usually
+  this is the program name and should be set by the user interface.
+
+  Input:
+    name	The name to be given as a label in error messages.	*/
+/*--									*/
+/*----------------------------------------------------------------------*/
+{
+  if(Name != NULL)free(Name);
+  Name = malloc(strlen(name)+1);
+  strcpy(Name,name);
+}
+/************************************************************************/
+void bug_c(char s,Const char *m)
+/** bug -- Issue an error message, given by the caller.			*/
+/*& pjt									*/
+/*: error-handling							*/
+/*+ FORTRAN call sequence:
+	subroutine bug(severity,message)
+
+	implicit none
+	character severity*1
+	character message*(*)
+
+  Output the error message given by the caller, and abort if needed.
+
+  Input:
+    severity	Error severity. Can be one of 'i', 'w', 'e' or 'f'
+		for "informational", "warning", "error", or "fatal"
+    message	The error message text.					*/
+/*--									*/
+/*----------------------------------------------------------------------*/
+{
+  char *p;
+  int doabort;
+
+  doabort = 0;
+  if      (s == 'i' || s == 'I') p = "Informational";
+  else if (s == 'w' || s == 'W') p = "Warning";
+  else if (s == 'e' || s == 'E') p = "Error";
+  else {doabort = 1;		 p = "Fatal Error"; }
+
+  if (!bug_cleanup)
+  {
+    if ( Name == NULL )
+      buglabel_c("(NOT SET)");
+    fprintf(stderr,"### %s [%s]:  %s\n",p,Name,m);
+  }
+
+  if(doabort){
+    reentrant = !reentrant;
+    if(reentrant)habort_c();
+    if (!handle_bug_cleanup(doabort,s,m))
+      exit(1);
+  } else
+    handle_bug_cleanup(doabort,s,m);
+    
+}
+/************************************************************************/
+void bugv_c(char s,Const char *m, ...)
+/** bugv_c -- Issue a dynamic error message, given by the caller.	*/
+/*& pjt									*/
+/*: error-handling							*/
+/*+ C call sequence:
+	bugv_c(severity,message,....)
+
+  Output the error message given by the caller, and abort if needed.
+  Note this routine has no counterpart in FORTRAN.
+
+  Input:
+    severity	Error severity character. 
+                Can be one of 'i', 'w', 'e' or 'f'
+		for "informational", "warning", "error", or "fatal"
+    message	The error message string, can contain %-printf style 
+                directives, as used by the following arguments.
+     ...         Optional argument, in the printf() style               */
+/*--									*/
+/*----------------------------------------------------------------------*/
+{
+  va_list ap;
+  char *p;
+  int doabort,len;
+
+  doabort = 0;
+  if      (s == 'i' || s == 'I') p = "Informational";
+  else if (s == 'w' || s == 'W') p = "Warning";
+  else if (s == 'e' || s == 'E') p = "Error";
+  else {doabort = 1;		 p = "Fatal Error"; }
+
+  va_start(ap,m);
+
+  if ( Name == NULL )
+    buglabel_c("(NOT SET)");
+
+  snprintf(msg,MAXMSG,"### %s [%s]: ",p,Name);
+  len = strlen(msg);
+  vsnprintf(&msg[len],MAXMSG-len,m,ap);
+  va_end(ap);
+
+  if (!bug_cleanup)
+    fprintf(stderr,"%s\n",msg);
+
+  if(doabort){
+    reentrant = !reentrant;
+    if(reentrant)habort_c();
+    if (!handle_bug_cleanup(doabort,s,&msg[len]))
+      exit(1);
+  } else
+    handle_bug_cleanup(doabort,s,&msg[len]);
+  
+}
+
+/************************************************************************/
+void bugno_c(char s,int n)
+/** bugno -- Issue an error message, given a system error number.	*/
+/*& pjt									*/
+/*: error-handling							*/
+/*+ FORTRAN call sequence:
+	subroutine bugno(severity,errno)
+
+	implicit none
+	character severity*1
+	integer errno
+
+  Output the error message associated with a particular error number.
+
+  Input:
+    severity	Error severity. Can be one of 'i', 'w', 'e' or 'f'
+		for "informational", "warning", "error", or "fatal"
+    errno	host error number.					*/
+/*--									*/
+/*----------------------------------------------------------------------*/
+{
+  if (n == -1)bug_c(s,"End of file detected");
+  else bug_c(s,errmsg_c(n));
+}
+/************************************************************************/
+#define HAVE_STRERROR 1
+static char *errmsg_c(int n)
+/*
+  Return the error message associated with some error number.
+------------------------------------------------------------------------*/
+{
+/* check for linux leaves this compat with old style build
+ * this should be removed in favor of HAVE_STRERROR once
+ * is only supported using autotools/configure
+ */
+#if defined(linux) || (defined(HAVE_STRERROR) && HAVE_STRERROR)
+  /* new POSIX.1 style, 20 years old now... (1988) */
+  return strerror(n);
+#else
+  /* very old style code -- stdio.h is supposed to supply this */
+#  if 0
+  extern int sys_nerr;
+  extern char *sys_errlist[];
+#  endif
+  if(n > 0 && n <= sys_nerr)return((char *)sys_errlist[n]);
+  else {
+    sprintf(msg,"Unknown error with number %d detected.",n);
+    return msg;
+  }
+#endif
+}
+/************************************************************************/
+static int handle_bug_cleanup(int doabort, char s, Const char *m)
+/*
+  Handle cleaning up a bug 
+------------------------------------------------------------------------*/
+{
+  if (bug_cleanup) {
+    if (bug_message) free(bug_message);
+    bug_message = strdup(m);      /* save last message */
+    bug_severity = s;             /* save last severity */
+    (*bug_cleanup)();             /* call handler ; this may exit */
+    if (doabort)                  /* if it got here, handler didn't exit */
+      fprintf(stderr,"### handle_bug_cleanup: WARNING: code should not come here\n",0);
+    return 1;
+  }
+  return 0;
+}