store/[org.clojure/clojure "1.8.0"] clj::clojure.core/ns

Official Documentation

Add notes
Arities
==================================================
   [name docstring? attr-map? references*]

Docstring
==================================================
  Sets *ns* to the namespace named by name (unevaluated), creating it
  if needed.  references can be zero or more of: (:refer-clojure ...)
  (:require ...) (:use ...) (:import ...) (:load ...) (:gen-class)
  with the syntax of refer-clojure/require/use/import/load/gen-class
  respectively, except the arguments are unevaluated and need not be
  quoted. (:gen-class ...), when supplied, defaults to :name
  corresponding to the ns name, :main true, :impl-ns same as ns, and
  :init-impl-ns true. All options of gen-class are
  supported. The :gen-class directive is ignored when not
  compiling. If :gen-class is not supplied, when compiled only an
  nsname__init.class will be generated. If :refer-clojure is not used, a
  default (refer 'clojure.core) is used.  Use of ns is preferred to
  individual calls to in-ns/require/use/import:

  (ns foo.bar
    (:refer-clojure :exclude [ancestors printf])
    (:require (clojure.contrib sql combinatorics))
    (:use (my.lib this that))
    (:import (java.util Date Timer Random)
             (java.sql Connection Statement)))

Source

(defmacro ns
  "Sets *ns* to the namespace named by name (unevaluated), creating it
  if needed.  references can be zero or more of: (:refer-clojure ...)
  (:require ...) (:use ...) (:import ...) (:load ...) (:gen-class)
  with the syntax of refer-clojure/require/use/import/load/gen-class
  respectively, except the arguments are unevaluated and need not be
  quoted. (:gen-class ...), when supplied, defaults to :name
  corresponding to the ns name, :main true, :impl-ns same as ns, and
  :init-impl-ns true. All options of gen-class are
  supported. The :gen-class directive is ignored when not
  compiling. If :gen-class is not supplied, when compiled only an
  nsname__init.class will be generated. If :refer-clojure is not used, a
  default (refer 'clojure.core) is used.  Use of ns is preferred to
  individual calls to in-ns/require/use/import:

  (ns foo.bar
    (:refer-clojure :exclude [ancestors printf])
    (:require (clojure.contrib sql combinatorics))
    (:use (my.lib this that))
    (:import (java.util Date Timer Random)
             (java.sql Connection Statement)))"
  {:arglists '([name docstring? attr-map? references*])
   :added "1.0"}
  [name & references]
  (let [process-reference
        (fn [[kname & args]]
          `(~(symbol "clojure.core" (clojure.core/name kname))
             ~@(map #(list 'quote %) args)))
        docstring  (when (string? (first references)) (first references))
        references (if docstring (next references) references)
        name (if docstring
               (vary-meta name assoc :doc docstring)
               name)
        metadata   (when (map? (first references)) (first references))
        references (if metadata (next references) references)
        name (if metadata
               (vary-meta name merge metadata)
               name)
        gen-class-clause (first (filter #(= :gen-class (first %)) references))
        gen-class-call
          (when gen-class-clause
            (list* `gen-class :name (.replace (str name) \- \_) :impl-ns name :main true (next gen-class-clause)))
        references (remove #(= :gen-class (first %)) references)
        ;ns-effect (clojure.core/in-ns name)
        name-metadata (meta name)]
    `(do
       (clojure.core/in-ns '~name)
       ~@(when name-metadata
           `((.resetMeta (clojure.lang.Namespace/find '~name) ~name-metadata)))
       (with-loading-context
        ~@(when gen-class-call (list gen-class-call))
        ~@(when (and (not= name 'clojure.core) (not-any? #(= :refer-clojure (first %)) references))
            `((clojure.core/refer '~'clojure.core)))
        ~@(map process-reference references))
        (if (.equals '~name 'clojure.core) 
          nil
          (do (dosync (commute @#'*loaded-libs* conj '~name)) nil)))))

Example 1

Edit
;; This example will illustrate changing between namespaces at the repl

;; At the repl, the ns macro can be used to create a namespace, but it is used to change the current namespace (be careful of typos)
(ns demo.namespace)
;; => nil
;; The prompt at the repl is now "demo.namespace" reflecting that the current namespace is no longer "user".

;; Add a new function to demo.namespace
(defn foo []
  (prn "Hello from demo.namespace"))
;; => #'demo.namespace/foo

;; From within "demo.namespace" we can use foo without qualifying it
(foo)
;; > "Hello from demo.namespace"
;; => nil

;; Switch back to the "user" namespace
(ns user)
;; => nil

;; We can no longer use "foo" without qualification
(foo)
;; => java.lang.Exception: Unable to resolve symbol: foo in this context (NO_SOURCE_FILE:4)

(demo.namespace/foo)
;; > "Hello from demo.namespace"
;; => nil

;; The public symbols of "demo.namespace" can be "referred into" the "user" namespace if desired
(refer 'demo.namespace)
;; => nil

;; foo is now an alias in the "user" namespace which refers to the "demo.namespace/foo" symbol
(foo)
;; > "Hello from demo.namespace"
;; => nil

Example 2

Edit
;; Let's create a namespace and then assign it as the current namespace
(create-ns 'my-new-namespace)
;; => #<Namespace my-new-namespace>

(ns 'my-new-namespace)
;; => java.lang.ClassCastException: clojure.lang.PersistentList cannot be cast to clojure.lang.Symbol (NO_SOURCE_FILE:26)
;; oops, this is not the way to do it; if create-ns needs a symbol, ns does not

(ns my-new-namespace)
;; => nil

;; it worked as the current namespace is our newly created one

Example 3

Edit
;; In clojure 1.4 and higher you can use the refer function from within
;; a require which is equivalent to (:use foo only [...]) but still 
;; allows you to reference the required namespace:
(ns my.ns.example
  (:require [my.lib :refer [function1 function2]]))

;; And :refer :all is equivalent to :use :
(ns my.ns.example
  (:require [my.lib :refer :all]))

Example 4

Edit
(ns rosettacode.24game
  (:require [clojure.string :as str])
  (:use clojure.test))

(deftest test
  (is (= "ABC" (str/capitalize "abc"))))

Example 5

Edit
;; Generate a Java class
(ns org.clojuredocs.test
  (:gen-class))

(defn -main [] (prn "Hello, World!"))

;; After compilation:
sh$ java -cp classes org.clojuredocs.test
Hello, World!

Example 6

Edit
(ns foo.bar
  (:refer-clojure :exclude [ancestors printf])
  (:require [clojure.contrib sql sql.tests])
  (:use [my.lib this that])
  (:import [java.util Date Timer Random]
           (java.sql Connection Statement)))

Example 7

Edit
;; Multiple required namespaces with aliases
(ns demo.namespace
  (:require [com.example.httplib :as httplib]
            [com.example.otherlib :as otherlib]))

Example 8

Edit
;; Generating a class so we can call Clojure from Java 
(ns com.domain.tiny
  (:gen-class
   :name com.domain.tiny
   :methods [#^{:static true} [binomial [int int] double]]))

(defn binomial
  "Calculate the binomial coefficient."
  [n k]
  (let [a (inc n)]
    (loop [b 1
           c 1]
      (if (> b k)
        c
        (recur (inc b) (* (/ (- a b) b) c))))))

(defn -binomial
  "A Java-callable wrapper around the 'binomial' function."
  [n k]
  (binomial n k))

(defn -main []
  (println (str "(binomial 5 3): " (binomial 5 3)))
  (println (str "(binomial 10042 111): " (binomial 10042 111))))

;; // Calling from Java
;; import com.domain.tiny;
;;
;; public class Main {
;;   public static void main(String[] args) {
;;     System.out.println("(binomial 5 3): " + tiny.binomial(5, 3));
;;     System.out.println("(binomial 10042, 111): " + tiny.binomial(10042, 111));
;;   }
;; }

;; The result was:
;; (binomial 5 3): 10.0
;; (binomial 10042, 111): 4.9068389575068143E263

Uses on crossclj