Embedding CRuby interpreter without internal headers has been difficult

for few years because:
* NODE is no longer accessible.
* rb_iseq_eval_main crashes without preparing with rb_thread_t.
* some existing APIs calls exit(3) without giving the opportunity to
  finalize or handle errors to the client.
* No general-purpose function to compile a source to an iseq are
  published in the public headers.

This commit solves the problems.

	* include/ruby/ruby.h: Grouped APIs for embedding CRuby interpreter.
	  (ruby_setup, ruby_compile_main_from_file,
	  ruby_compile_main_from_string, ruby_eval_main,
	  ruby_set_script_name): new APIs to embed CRuby.
	  (ruby_opaque_t) Opaque pointer to an internal data, to NODE or iseq
	  in particular.

	* eval.c (ruby_setup): Similar to ruby_init but returns an error code
	  instead of exit(3) on error.
	  (ruby_eval_main): Similar to ruby_exec_node but returns the
	  evaluation result.
	  (ruby_eval_main_internal): renamed from ruby_exec_internal.

	* ruby.c (toplevel_context): new helper function.
	  (PREPARE_EVAL_MAIN): moved.
	  (process_options): refactored with new functions.
	  (parse_and_compile_main) new helper funciton.
	  (ruby_compile_main_from_file, ruby_compile_main_from_string) new API
	  (ruby_set_script_name): new API.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@36079 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

2 files changed, 83 insertions, 40 deletions

diff --git a/include/ruby/intern.h b/include/ruby/intern.h
index 54b16961c5..308a1a94db 100644
--- a/include/ruby/intern.h
+++ b/include/ruby/intern.h
@@ -386,9 +386,6 @@ VALUE rb_protect(VALUE (*)(VALUE), VALUE, int*);
 void rb_set_end_proc(void (*)(VALUE), VALUE);
 void rb_mark_end_proc(void);
 void rb_exec_end_proc(void);
-void ruby_finalize(void);
-NORETURN(void ruby_stop(int));
-int ruby_cleanup(volatile int);
 DEPRECATED(void rb_gc_mark_threads(void));
 void rb_thread_schedule(void);
 void rb_thread_wait_fd(int);
@@ -432,10 +429,7 @@ VALUE rb_file_directory_p(VALUE,VALUE);
 VALUE rb_str_encode_ospath(VALUE);
 int rb_is_absolute_path(const char *);
 /* gc.c */
-void ruby_set_stack_size(size_t);
 NORETURN(void rb_memerror(void));
-int ruby_stack_check(void);
-size_t ruby_stack_length(VALUE**);
 int rb_during_gc(void);
 void rb_gc_mark_locations(VALUE*, VALUE*);
 void rb_mark_tbl(struct st_table*);
@@ -451,7 +445,6 @@ void rb_gc_call_finalizer_at_exit(void);
 VALUE rb_gc_enable(void);
 VALUE rb_gc_disable(void);
 VALUE rb_gc_start(void);
-#define Init_stack(addr) ruby_init_stack(addr)
 void rb_gc_set_params(void);
 /* hash.c */
 void st_foreach_safe(struct st_table *, int (*)(ANYARGS), st_data_t);
@@ -662,12 +655,6 @@ int rb_reg_options(VALUE);
 RUBY_EXTERN VALUE rb_argv0;
 VALUE rb_get_argv(void);
 void *rb_load_file(const char*);
-void ruby_script(const char*);
-void ruby_prog_init(void);
-void ruby_set_argv(int, char**);
-void *ruby_process_options(int, char**);
-void ruby_init_loadpath(void);
-void ruby_incpush(const char*);
 /* signal.c */
 VALUE rb_f_kill(int, VALUE*);
 void rb_gc_mark_trap_list(void);
@@ -675,7 +662,6 @@ void rb_gc_mark_trap_list(void);
 #define posix_signal ruby_posix_signal
 RETSIGTYPE (*posix_signal(int, RETSIGTYPE (*)(int)))(int);
 #endif
-void ruby_sig_finalize(void);
 void rb_trap_exit(void);
 void rb_trap_exec(void);
 const char *ruby_signal_name(int);
@@ -929,9 +915,6 @@ VALUE rb_cv_get(VALUE, const char*);
 void rb_define_class_variable(VALUE, const char*, VALUE);
 VALUE rb_mod_class_variables(VALUE);
 VALUE rb_mod_remove_cvar(VALUE, VALUE);
-/* version.c */
-void ruby_show_version(void);
-void ruby_show_copyright(void);
 
 ID rb_frame_callee(void);
 VALUE rb_str_succ(VALUE);
diff --git a/include/ruby/ruby.h b/include/ruby/ruby.h
index 06c2a7fdd4..39996483d9 100644
--- a/include/ruby/ruby.h
+++ b/include/ruby/ruby.h
@@ -1229,21 +1229,6 @@ NORETURN(void rb_throw_obj(VALUE,VALUE));
 
 VALUE rb_require(const char*);
 
-#ifdef __ia64
-void ruby_init_stack(volatile VALUE*, void*);
-#define ruby_init_stack(addr) ruby_init_stack((addr), rb_ia64_bsp())
-#else
-void ruby_init_stack(volatile VALUE*);
-#endif
-#define RUBY_INIT_STACK \
-    VALUE variable_in_this_stack_frame; \
-    ruby_init_stack(&variable_in_this_stack_frame);
-void ruby_init(void);
-void *ruby_options(int, char**);
-int ruby_run_node(void *);
-int ruby_exec_node(void *);
-int ruby_executable_node(void *n, int *status);
-
 RUBY_EXTERN VALUE rb_mKernel;
 RUBY_EXTERN VALUE rb_mComparable;
 RUBY_EXTERN VALUE rb_mEnumerable;
@@ -1400,14 +1385,6 @@ rb_special_const_p(VALUE obj)
 static char *dln_libs_to_be_linked[] = { EXTLIB, 0 };
 #endif
 
-#if (defined(__APPLE__) || defined(__NeXT__)) && defined(__MACH__)
-#define RUBY_GLOBAL_SETUP /* use linker option to link startup code with ObjC support */
-#else
-#define RUBY_GLOBAL_SETUP
-#endif
-
-void ruby_sysinit(int *, char ***);
-
 #define RUBY_VM 1 /* YARV */
 #define HAVE_NATIVETHREAD
 int ruby_native_thread_p(void);
@@ -1495,6 +1472,89 @@ int ruby_vsnprintf(char *str, size_t n, char const *fmt, va_list ap);
 #include "ruby/subst.h"
 #endif
 
+/**
+ * @defgroup embed CRuby Embedding APIs
+ * CRuby interpreter APIs. These are APIs to embed MRI interpreter into your
+ * program.
+ * These functions are not a part of Ruby extention library API.
+ * Extension libraries of Ruby should not depend on these functions.
+ * @{
+ */
+
+/*! Opaque pointer to an inner data structure.
+ *
+ * You do not have to know what the actual data type this pointer points.
+ * It often changes for internal improvements.
+ */
+typedef void *ruby_opaque_t;
+
+/*! @deprecated You no longer need to use this macro. */ 
+#if (defined(__APPLE__) || defined(__NeXT__)) && defined(__MACH__)
+#define RUBY_GLOBAL_SETUP /* use linker option to link startup code with ObjC support */
+#else
+#define RUBY_GLOBAL_SETUP
+#endif
+
+/** @defgroup ruby1 ruby(1) implementation
+ * A part of the implementation of ruby(1) command.
+ * Other programs that embed Ruby interpreter do not always need to use these
+ * functions.
+ * @{
+ */
+
+void ruby_sysinit(int *argc, char ***argv);
+void ruby_init(void);
+ruby_opaque_t ruby_options(int argc, char** argv);
+int ruby_executable_node(ruby_opaque_t n, int *status);
+int ruby_run_node(ruby_opaque_t n);
+
+/* version.c */
+void ruby_show_version(void);
+void ruby_show_copyright(void);
+
+
+/*! A convenience macro to call ruby_init_stack(). Must be placed just after
+ *  variable declarations */
+#define RUBY_INIT_STACK \
+    VALUE variable_in_this_stack_frame; \
+    ruby_init_stack(&variable_in_this_stack_frame);
+/*! @} */
+
+#ifdef __ia64
+void ruby_init_stack(volatile VALUE*, void*);
+#define ruby_init_stack(addr) ruby_init_stack((addr), rb_ia64_bsp())
+#else
+void ruby_init_stack(volatile VALUE*);
+#endif
+#define Init_stack(addr) ruby_init_stack(addr)
+
+int ruby_setup(void);
+int ruby_cleanup(volatile int);
+
+void ruby_finalize(void);
+NORETURN(void ruby_stop(int));
+
+void ruby_set_stack_size(size_t);
+int ruby_stack_check(void);
+size_t ruby_stack_length(VALUE**);
+
+ruby_opaque_t ruby_compile_main_from_file(VALUE fname, const char* path, VALUE* error);
+ruby_opaque_t ruby_compile_main_from_string(VALUE fname, VALUE string, VALUE* error);
+int ruby_exec_node(ruby_opaque_t n);
+int ruby_eval_main(ruby_opaque_t n, VALUE *result);
+
+void ruby_script(const char* name);
+void ruby_set_script_name(VALUE name);
+
+void ruby_prog_init(void);
+void ruby_set_argv(int, char**);
+void *ruby_process_options(int, char**);
+void ruby_init_loadpath(void);
+void ruby_incpush(const char*);
+void ruby_sig_finalize(void);
+
+/*! @} */
+
 #if defined(__cplusplus)
 #if 0
 { /* satisfy cc-mode */