exec: fix missing documentation warnings
[nit.git] / lib / standard / exec.nit
index f71ce54..1ee3095 100644 (file)
@@ -5,7 +5,7 @@
 #
 # This file is free software, which comes along with NIT.  This software 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 
+# without  even  the implied warranty of  MERCHANTABILITY or  FITNESS FOR A
 # PARTICULAR PURPOSE.  You can modify it is you want,  provided this header
 # is kept unaltered, and a notification of the changes is added.
 # You  are  allowed  to  redistribute it and sell it, alone or is a part of
@@ -13,7 +13,7 @@
 
 # Invocation and management of operating system sub-processes.
 # Standard input and output can be handled through streams.
-package exec 
+module exec
 
 import stream
 
@@ -31,7 +31,7 @@ class Process
                data.wait
                assert is_finished
        end
-       
+
        # The status once finished
        fun status: Int
        do
@@ -39,34 +39,51 @@ class Process
                return data.status
        end
 
+       # The executable run
+       # Is a filepath, or a executable found in PATH
+       var command: String
+
+       # The arguments of the command
+       # Starts with the first real arguments---ie. does not include the progname (`argv[0]`, in C)
+       var arguments: nullable Array[String]
+
        # Launch a command with some arguments
        init(command: String, arguments: String...)
        do
-               execute(command, arguments, 0)
+               self.command = command
+               self.arguments = arguments
+               execute
        end
 
-       # Launch a simple command without arguments
-       init init_(command: String)
+       # Launch a simple command with arguments passed as an array
+       init from_a(command: String, arguments: nullable Array[String])
        do
-               execute(command, null, 0)
+               self.command = command
+               self.arguments = arguments
+               execute
        end
 
+       # flags used internally to know whith pipe to open
+       private fun pipeflags: Int do return 0
+
        # Internal code to handle execution
-       protected init execute(command: String, arguments: nullable Array[String], pipeflags: Int)
+       protected fun execute
        do
-               var args = new Buffer
+               # The pass the arguments as a big C string where elements are separated with '\0'
+               var args = new FlatBuffer
                var l = 1 # Number of elements in args
                args.append(command)
                if arguments != null then
                        for a in arguments do
                                args.add('\0')
+                               #a.output_class_name
                                args.append(a)
                        end
                        l += arguments.length
                end
                data = basic_exec_execute(command.to_cstring, args.to_s.to_cstring, l, pipeflags)
        end
-       
+
        private var data: NativeProcess
        private fun basic_exec_execute(p: NativeString, av: NativeString, ac: Int, pf: Int): NativeProcess is extern "exec_Process_Process_basic_exec_execute_4"
 end
@@ -75,23 +92,21 @@ end
 class IProcess
        super Process
        super IStream
-       var stream_in: FDIStream
-       
+
+       # File Descriptor used for the input.
+       var stream_in: FDIStream is noinit
+
        redef fun close do stream_in.close
-       
+
        redef fun read_char do return stream_in.read_char
 
        redef fun eof do return stream_in.eof
 
-       init(command: String, arguments: String...)
-       do
-               execute(command, arguments, 2)
-               stream_in = new FDIStream(data.out_fd)
-       end
-       
-       init init_(command: String)
+       redef fun pipeflags do return 2
+
+       redef fun execute
        do
-               execute(command, null, 2)
+               super
                stream_in = new FDIStream(data.out_fd)
        end
 end
@@ -100,23 +115,21 @@ end
 class OProcess
        super Process
        super OStream
-       var stream_out: OStream
+
+       # File Descriptor used for the output.
+       var stream_out: OStream is noinit
 
        redef fun close do stream_out.close
 
        redef fun is_writable do return stream_out.is_writable
 
        redef fun write(s) do stream_out.write(s)
-       
-       init(command: String, arguments: String...)
-       do
-               execute(command, arguments, 1)
-               stream_out = new FDOStream(data.in_fd)
-       end
-       
-       init init_(command: String)
+
+       redef fun pipeflags do return 1
+
+       redef fun execute
        do
-               execute(command, null, 1)
+               super
                stream_out = new FDOStream(data.in_fd)
        end
 end
@@ -133,18 +146,11 @@ class IOProcess
                stream_out.close
        end
 
-       init(command: String, arguments: String...)
-       do
-               execute(command, arguments, 3)
-               stream_in = new FDIStream(data.out_fd)
-               stream_out = new FDOStream(data.in_fd)
-       end
-       
-       init init_(command: String)
+       redef fun pipeflags do return 3
+
+       redef fun execute
        do
-               execute(command, null, 3)
-               stream_in = new FDIStream(data.out_fd)
-               stream_out = new FDOStream(data.in_fd)
+               super
        end
 end
 
@@ -152,15 +158,18 @@ redef class Sys
        # Execute a shell command and return its error code
        fun system(command: String): Int
        do
-               return command.to_cstring.system        
+               return command.to_cstring.system
        end
 end
 
 redef class NativeString
+       # Execute self as a shell command.
+       #
+       # See the posix function system(3).
        fun system: Int is extern "string_NativeString_NativeString_system_0"
 end
 
-private extern NativeProcess
+private extern class NativeProcess
        fun id: Int is extern "exec_NativeProcess_NativeProcess_id_0"
        fun is_finished: Bool is extern "exec_NativeProcess_NativeProcess_is_finished_0"
        fun status: Int is extern "exec_NativeProcess_NativeProcess_status_0"