platform macros with (ternary operator) else clauses, of the form @windows? a : b

Author: vtjnash

base/exports.jl

@@ -1247,6 +1247,10 @@ export
     @allocated,
     @profile,
     @which,
+    @windows,
+    @unix,
+    @osx,
+    @linux,
     @windows_only,
     @unix_only,
     @osx_only,

base/osutils.jl

@@ -7,20 +7,43 @@ function is_unix(os::Symbol)
     end
 end
 
-macro windows_only(ex)
-    OS_NAME == :Windows ? esc(ex) : nothing
+os_name(os::Symbol) = string(os)
+
+macro _os_test(qm,ex,test)
+    esc(quote
+        @assert $qm == :?
+        @assert isa($ex,Expr)
+        @assert $ex.head == :(:)
+        @assert length($ex.args) == 2
+        if $test
+            return esc($ex.args[1])
+        else
+            return esc($ex.args[2])
+        end
+    end)
+end
+macro windows(qm,ex)
+    @_os_test qm ex OS_NAME===:Windows
+end
+macro unix(qm,ex)
+    @_os_test qm ex is_unix(OS_NAME)
+end
+macro osx(qm,ex)
+    @_os_test qm ex OS_NAME===:Darwin
+end
+macro linux(qm,ex)
+    @_os_test qm ex is_unix(OS_NAME) && OS_NAME!==:Darwin
 end
 
+macro windows_only(ex)
+    @windows? esc(ex) : nothing
+end
 macro unix_only(ex)
-    is_unix(OS_NAME) ? esc(ex) : nothing
+    @unix? esc(ex) : nothing
 end
-
 macro osx_only(ex)
-    OS_NAME == :Darwin ? esc(ex) : nothing
+    @osx? esc(ex) : nothing
 end
-
 macro linux_only(ex)
-    is_unix(OS_NAME) && OS_NAME != :Darwin ? esc(ex) : nothing
+    @linux? esc(ex) : nothing
 end
-
-os_name(os::Symbol) = string(os)

doc/helpdb.jl

@@ -407,7 +407,7 @@
 
    The byte offset of each field of a type relative to the data start.
    For example, we could use it in the following manner to summarize
-   information about the struct type:
+   information about a struct type:
 
       structinfo(T) = [zip(fieldoffsets(T),names(T),T.types)...]
       structinfo(Stat)
@@ -5133,6 +5133,39 @@
 
 "),
 
+("System","Base","@unix","@unix()
+
+   Given \"@unix? a : b\", do \"a\" on Unix systems (including Linux
+   and OS X) and \"b\" elsewhere. See documentation for Handling
+   Platform Variations in the Calling C and Fortran Code section of
+   the manual.
+
+"),
+
+("System","Base","@osx","@osx()
+
+   Given \"@osx? a : b\", do \"a\" on OS X and \"b\" elsewhere. See
+   documentation for Handling Platform Variations in the Calling C and
+   Fortran Code section of the manual.
+
+"),
+
+("System","Base","@linux","@linux()
+
+   Given \"@linux? a : b\", do \"a\" on Linux and \"b\" elsewhere. See
+   documentation for Handling Platform Variations in the Calling C and
+   Fortran Code section of the manual.
+
+"),
+
+("System","Base","@windows","@windows()
+
+   Given \"@windows? a : b\", do \"a\" on Windows and \"b\" elsewhere.
+   See documentation for Handling Platform Variations in the Calling C
+   and Fortran Code section of the manual.
+
+"),
+
 ("C Interface","Base","ccall","ccall((symbol, library) or fptr, RetType, (ArgType1, ...), ArgVar1, ...)
 
    Call function in C-exported shared library, specified by (function

doc/manual/calling-c-and-fortran-code.rst

@@ -417,3 +417,32 @@ C++
 
 Limited support for C++ is provided by the `Cpp <http://github.com/timholy/Cpp.jl>`_ 
 and `Clang <https://github.com/ihnorton/Clang.jl>`_ packages.
+
+Handling Platform Variations
+----------------------------
+
+When dealing with platform libraries, it is often necessary to provide special cases
+for various platforms. The variable ``OS_NAME`` can be used to write these special
+cases. Additionally, there are several macros intended to make this easier:
+``@windows``, ``@unix``, ``@linux``, and ``@osx``. Note that linux and osx are mutually 
+exclusive subsets of unix. Their usage takes the form of a ternary conditional
+operator, as demonstrated in the following examples.
+
+Simple blocks::
+
+    ccall( (@windows? :_fopen : :fopen), ...)
+
+Complex blocks::
+
+    @linux? (
+             begin
+                 some_complicated_thing(a)
+             end
+           : begin
+                 some_different_thing(a)
+             end
+           )
+
+Chaining (parentheses optional, but recommended for readability)::
+
+    @windows? :a : (@osx? :b : :c)

doc/stdlib/base.rst

@@ -1145,8 +1145,6 @@ Text I/O
 Memory-mapped I/O
 -----------------
 
-Note: Currently not available on Windows.
-
 .. function:: mmap_array(type, dims, stream, [offset])
 
    Create an ``Array`` whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory.
@@ -3413,12 +3411,33 @@ System
 
    Reference to the singleton ``EnvHash``, providing a dictionary interface to system environment variables.
 
+.. function:: @unix
+
+   Given ``@unix? a : b``, do ``a`` on Unix systems (including Linux and OS X) and ``b`` elsewhere. See documentation
+   for Handling Platform Variations in the Calling C and Fortran Code section of the manual.
+
+.. function:: @osx
+
+   Given ``@osx? a : b``, do ``a`` on OS X and ``b`` elsewhere. See documentation for Handling Platform Variations 
+   in the Calling C and Fortran Code section of the manual.
+
+.. function:: @linux
+
+   Given ``@linux? a : b``, do ``a`` on Linux and ``b`` elsewhere. See documentation for Handling Platform Variations 
+   in the Calling C and Fortran Code section of the manual.
+
+.. function:: @windows
+
+   Given ``@windows? a : b``, do ``a`` on Windows and ``b`` elsewhere. See documentation for Handling Platform Variations
+   in the Calling C and Fortran Code section of the manual.
+
 C Interface
 -----------
 
 .. function:: ccall((symbol, library) or fptr, RetType, (ArgType1, ...), ArgVar1, ...)
 
-   Call function in C-exported shared library, specified by (function name, library) tuple (String or :Symbol). Alternatively, ccall may be used to call a function pointer returned by dlsym, but note that this usage is generally discouraged to facilitate future static compilation.
+   Call function in C-exported shared library, specified by (function name, library) tuple (String or :Symbol). Alternatively,
+   ccall may be used to call a function pointer returned by dlsym, but note that this usage is generally discouraged to facilitate future static compilation.
 
 .. function:: cglobal((symbol, library) or ptr [, Type=Void])