[svn:parrot] r39518 - in trunk: . config/gen/makefiles runtime/parrot/library/NCI

japhb at svn.parrot.org japhb at svn.parrot.org
Fri Jun 12 07:36:36 UTC 2009


Author: japhb
Date: Fri Jun 12 07:36:33 2009
New Revision: 39518
URL: https://trac.parrot.org/parrot/changeset/39518

Log:
Deprecate r/t/l/NCI/call_toolkit_init.* in favor of .../NCI/Utils.*

Added:
   trunk/runtime/parrot/library/NCI/Utils.pir
Modified:
   trunk/DEPRECATED.pod
   trunk/MANIFEST
   trunk/config/gen/makefiles/root.in

Modified: trunk/DEPRECATED.pod
==============================================================================
--- trunk/DEPRECATED.pod	Fri Jun 12 05:35:20 2009	(r39517)
+++ trunk/DEPRECATED.pod	Fri Jun 12 07:36:33 2009	(r39518)
@@ -362,6 +362,10 @@
 
 L<https://trac.parrot.org/parrot/ticket/508>
 
+=item NCI::call_toolkit_init [eligible in 1.5]
+
+L<https://trac.parrot.org/parrot/ticket/753>
+
 =back
 
 =head1 Footnotes

Modified: trunk/MANIFEST
==============================================================================
--- trunk/MANIFEST	Fri Jun 12 05:35:20 2009	(r39517)
+++ trunk/MANIFEST	Fri Jun 12 07:36:33 2009	(r39518)
@@ -1,7 +1,7 @@
 # ex: set ro:
 # $Id$
 #
-# generated by tools/dev/mk_manifest_and_skip.pl Fri Jun 12 02:43:29 2009 UT
+# generated by tools/dev/mk_manifest_and_skip.pl Fri Jun 12 07:16:58 2009 UT
 #
 # See below for documentation on the format of this file.
 #
@@ -1159,6 +1159,7 @@
 runtime/parrot/library/MIME/Base64.pir                      [library]
 runtime/parrot/library/Math/Rand.pir                        [library]
 runtime/parrot/library/Math/Random/mt19937ar.pir            [library]
+runtime/parrot/library/NCI/Utils.pir                        [library]
 runtime/parrot/library/NCI/call_toolkit_init.pir            [library]
 runtime/parrot/library/OpenGL.pir                           [library]
 runtime/parrot/library/P6object.pir                         [library]

Modified: trunk/config/gen/makefiles/root.in
==============================================================================
--- trunk/config/gen/makefiles/root.in	Fri Jun 12 05:35:20 2009	(r39517)
+++ trunk/config/gen/makefiles/root.in	Fri Jun 12 07:36:33 2009	(r39518)
@@ -257,6 +257,7 @@
     $(LIBRARY_DIR)/Math/Random/mt19937ar.pbc \
     $(LIBRARY_DIR)/Math/Rand.pbc \
     $(LIBRARY_DIR)/MIME/Base64.pbc \
+    $(LIBRARY_DIR)/NCI/Utils.pbc \
     $(LIBRARY_DIR)/NCI/call_toolkit_init.pbc \
     $(LIBRARY_DIR)/ncurses.pbc \
 #IF(has_opengl):    $(LIBRARY_DIR)/OpenGL.pbc \

Added: trunk/runtime/parrot/library/NCI/Utils.pir
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/runtime/parrot/library/NCI/Utils.pir	Fri Jun 12 07:36:33 2009	(r39518)
@@ -0,0 +1,161 @@
+# Copyright (C) 2008-2009, Parrot Foundation.
+# $Id: $
+
+=head1 TITLE
+
+NCI/Utils.pir - Utility functions to make Parrot NCI work easier
+
+=head1 SYNOPSIS
+
+  # Perl 6:
+    # Load this library and the NCI wrapper for a framework/toolkit
+    use NCI::Utils:from<parrot>;
+    use FooTK:from<parrot>;
+
+    sub MAIN(*@ARGS is rw) {
+	# Call toolkit's init function, overwriting @ARGS with mangled copy
+        @ARGS = call_toolkit_init(&fooInit, @ARGS, $*PROGRAM_NAME);
+
+	# Alternately, you can save both the original @ARGS and mangled copy
+	my @mangled_args = call_toolkit_init(&fooInit, @ARGS);
+
+        # ...
+    }
+
+  # PIR:
+    .sub main :main
+        .param pmc argv
+
+        # Load this library and the NCI wrapper for a framework/toolkit
+	load_bytecode 'NCI/Utils.pbc'
+	load_bytecode 'FooTK.pbc'
+
+	# Find Subs for call_toolkit_init() and the toolkit's init function
+        .local pmc call_toolkit_init, fooInit
+	call_toolkit_init = get_global ['NCI';'Utils'], 'call_toolkit_init'
+	fooInit           = get_global ['FooTK'],       'fooInit'
+
+	# Call toolkit's init function, overwriting argv with mangled copy
+	argv = call_toolkit_init(fooInit, argv)
+
+	# Alternately, you can save both the original argv and mangled copy
+	.local pmc mangled_argv
+	mangled_argv = call_toolkit_init(fooInit, argv)
+
+        # ...
+    .end
+
+=head1 DESCRIPTION
+
+Some Parrot NCI coding tasks are relatively common, but usually result in
+a relatively grotty bit of code that no one should have to write twice.
+Hence this library, which provides utilities to handle these common tasks
+more cleanly (or at least collect all the grotty code in one place).
+
+Currently, there is just one such utility implemented:
+
+=over 4
+
+=item new_argv = call_toolkit_init(pmc init_func, pmc orig_argv, string program_name?)
+
+Call an NCI void function with params C<(&argc, argv)> (and thus having
+Parrot signature C<'v3p'>).  This is a very common signature for toolkit
+(AKA framework) init functions that want to filter out command line
+options that the toolkit itself should process.  Since it is expected
+that the init call will remove some arguments, C<call_toolkit_init>
+returns an updated C<argv>.  C<orig_argv> is never changed; the NCI call
+is performed using a copy.  When calling from an HLL that removes the
+program name from C<argv> automatically, provide the program_name argument
+so that C<call_toolkit_init()> can adjust C<argv> alignment internally;
+this will tend to make the toolkit init function much happier.
+
+=back
+
+=cut
+
+
+.namespace ['NCI'; 'Utils']
+
+.include 'datatypes.pasm'
+
+.sub _init_nci_utils :load
+    # Mark all functions for export
+    .local pmc parrot
+    load_language 'parrot'
+    parrot = compreg 'parrot'
+    parrot.'export'('call_toolkit_init')
+.end
+
+.sub call_toolkit_init
+    .param pmc    init_func
+    .param pmc    orig_argv
+    .param string program_name     :optional
+    .param int    has_program_name :opt_flag
+
+    # If program name supplied separately, stuff it into front of argv
+    unless has_program_name goto argv_includes_program_name
+    unshift orig_argv, program_name
+  argv_includes_program_name:
+
+    # Calculate argc
+    .local int count
+    .local pmc argc
+    count = orig_argv
+    argc  = new 'Integer'
+    argc  = count
+
+    # Declare structure of a raw C string array with proper element count
+    .local pmc argv_decl
+    argv_decl = new 'ResizablePMCArray'
+    push argv_decl, .DATATYPE_CSTR
+    push argv_decl, count
+    push argv_decl, 0
+    # XXX: This is unportably wrong; it assumes sizeof(INT) = sizeof(PTR)
+    push argv_decl, .DATATYPE_INT
+    push argv_decl, 0
+    push argv_decl, 0
+
+    # Create C string array from struct declaration and Parrot string array
+    .local pmc argv
+    .local int i
+    argv = new 'ManagedStruct', argv_decl
+    i = 0
+  argv_loop:
+    unless i < count goto add_null
+    # It seems like this should be possible in one op
+    $S0 = orig_argv[i]
+    argv[0;i] = $S0
+    inc i
+    goto argv_loop
+  add_null:
+    # XXX: This is unportably wrong; it assumes sizeof(INT) = sizeof(PTR)
+    argv[1] = 0
+
+    # Call the NCI framework init function
+    init_func(argc, argv)
+
+    # Build a new_argv array to match the init function's return
+    .local int new_count
+    .local pmc new_argv
+    new_count = argc
+    new_argv  = new 'ResizableStringArray'
+    # If program_name was supplied separately from argv, skip it on output
+    i = has_program_name
+  new_argv_loop:
+    unless i < new_count goto done
+    $S0 = argv[0;i]
+    push new_argv, $S0
+    inc i
+    goto new_argv_loop
+
+    # Finally, return the new (and adjusted) argv
+  done:
+    .return (new_argv)
+.end
+
+
+# Local Variables:
+#   mode: pir
+#   fill-column: 100
+# End:
+# vim: expandtab shiftwidth=4 ft=pir:


More information about the parrot-commits mailing list