Add @__DIR__ and document use in pkgs. Fix #12120

Add test.

Add docs.

Move docstrings for @__FILE__ and @__DIR__ inline.

Missing paren.

Rephrase example.

base/docs/helpdb/Base.jl

@@ -2364,15 +2364,6 @@ in the requested `mime` format and simply returns `x`.
 """
 reprmime
 
-"""
-    @__FILE__ -> AbstractString
-
-`@__FILE__` expands to a string with the absolute file path of the file containing the
-macro. Returns `nothing` if run from a REPL or an empty string if evaluated by
-`julia -e <expr>`. Alternatively see [`PROGRAM_FILE`](:data:`PROGRAM_FILE`).
-"""
-:@__FILE__
-
 """
     !(x)
 

base/exports.jl

@@ -1328,6 +1328,7 @@ export
 # Macros
     # parser internal
     @__FILE__,
+    @__DIR__,
     @int128_str,
     @uint128_str,
     @big_str,

base/loading.jl

@@ -494,8 +494,24 @@ function source_dir()
     p === nothing ? p : dirname(p)
 end
 
+"""
+    @__FILE__ -> AbstractString
+
+`@__FILE__` expands to a string with the absolute file path of the file containing the
+macro. Returns `nothing` if run from a REPL or an empty string if evaluated by
+`julia -e <expr>`. Alternatively see [`PROGRAM_FILE`](:data:`PROGRAM_FILE`).
+"""
 macro __FILE__() source_path() end
 
+"""
+    @__DIR__ -> AbstractString
+
+`@__DIR__` expands to a string with the directory part of the absolute path of the file
+containing the macro. Returns `nothing` if run from a REPL or an empty string if
+evaluated by `julia -e <expr>`.
+"""
+macro __DIR__() source_dir() end
+
 """
     include(path::AbstractString)
 

doc/manual/packages.rst

@@ -771,6 +771,16 @@ testing service, and an ``appveyor.yml`` file for using `AppVeyor <https://www.a
 the Travis and AppVeyor websites for your package repository, but once you've done that, it will already have working tests.
 Of course, all the default testing does is verify that ``using FooBar`` in Julia works.
 
+Loading Static Non-Julia Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your package code needs to load static files which are not Julia code, e.g. an external library or data files, and are
+located within the package directory, use the ``@__DIR__`` macro to determine the directory of the current source file.
+For example if ``FooBar/src/FooBar.jl`` needs to load ``FooBar/data/foo.csv``, use the following code::
+
+    datapath = joinpath(@__DIR__, "..", "data")
+    foo = readcsv(joinpath(datapath, "foo.csv"))
+
 Making Your Package Available
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/stdlib/file.rst

@@ -355,6 +355,12 @@
 
    ``@__FILE__`` expands to a string with the absolute file path of the file containing the macro. Returns ``nothing`` if run from a REPL or an empty string if evaluated by ``julia -e <expr>``\ . Alternatively see :data:`PROGRAM_FILE`\ .
 
+.. function:: @__DIR__ -> AbstractString
+
+   .. Docstring generated from Julia source
+
+   ``@__DIR__`` expands to a string with the directory part of the absolute path of the file containing the macro. Returns ``nothing`` if run from a REPL or an empty string if evaluated by ``julia -e <expr>``\ .
+
 .. function:: @__LINE__ -> Int
 
    .. Docstring generated from Julia source

test/loading.jl

@@ -11,6 +11,9 @@ thefname = "the fname!//\\&\1*"
 @test basename(@__FILE__) == "loading.jl"
 @test isabspath(@__FILE__)
 
+@test isdir(@__DIR__)
+@test @__DIR__() == dirname(@__FILE__)
+
 # Issue #5789 and PR #13542:
 let true_filename = "cAsEtEsT.jl", lowered_filename="casetest.jl"
     touch(true_filename)