diff options
Diffstat (limited to 'research/flossing/external')
135 files changed, 9298 insertions, 0 deletions
diff --git a/research/flossing/external/GradientFlossing/README.md b/research/flossing/external/GradientFlossing/README.md new file mode 100644 index 0000000..962c955 --- /dev/null +++ b/research/flossing/external/GradientFlossing/README.md @@ -0,0 +1,79 @@ +# Gradient Flossing: Improving Gradient Descent through Dynamic Control of Jacobians + +This repository contains the implementation code for manuscript: <br> +__Gradient Flossing: Improving Gradient Descent through Dynamic Control of Jacobians__ <br> +## Overview +In this work we show that RNN training can be improved by pushing Lyapunov exponents of the forward pass to zero during or before training. + +## Installation + +#### Prerequisites +- Download [Julia](https://julialang.org/downloads/) + +#### Dependencies +- Julia (1.6) +- Flux, BackwardsLinalg + +## Getting started +To install the required packages, run the following in the julia REPL after installing Julia: + +``` +using Pkg + +for pkg in ["Flux", "BackwardsLinalg"] + Pkg.add(pkg) +end +``` + +For example, to train an RNN on tracking delayed XOR task, run: +``` +include("GradientFlossing_ExampleCode.jl") +# setting parameters: +N, E, Ef, Ei, Ep, Ni, B, S, T, Tp, Ti, sIC, sIn, sNet, sONS, lr, b1, b2, IC, g, gbar, I1, delay, wsS, wsM, wrS, wrM, bS, bM, nLE, task, intype, Lwnt= +80, 3001, 100, 500, 500, 2, 16, 1, 300, 55, 300, 1,1,1,1, 0.001f0, 0.9, 0.999, 1, 1.0, 0.0, 1.0,10, 1.0f0, 0.0f0, 1.0f0, 0.0f0, 0.1f0, 0.0f0,75, -1, 3, 0.0 + +trainRNNflossing(N, E, Ef, Ei, Ep, Ni, B, S, T, Tp, Ti, sIC, sIn, sNet, sONS, lr, b1, b2, IC, g, gbar, I1, delay, wsS, wsM, wrS, wrM, bS, bM, nLE, task, intype, Lwnt) +``` + +## Repository Overview +_GradientFlossing_ExampleCode.jl_:\ +Example scripts for training networks with gradient flossing before training, with gradient flossing before and during training and without gradient flossing. + + +_GradientFlossing_XOR.jl_:\ +Generates input and target output for copy task and delayed XOR task. + +<!--- + +runOneStimulus.jl trains an RNN on tracking one OU-signal showing that the network becomes more tightly balanced over training epochs.\ +runTwoStimuli.jl trains an RNN on two OU-signal stimulus showing that the network becomes more tightly balanced over training epochs and breaks up into two weakly-connected subnetworks.\ +runTheeStimuli.jl trains an RNN on two OU-signal stimulus showing that the network becomes more tightly balanced over training epochs and breaks up into three weakly-connected subnetworks.\ + +--> + + +<!--- + +### Training dynamics of eigenvalues: +Here is a visualization of the recurrent weight matrix and the eigenvalues throughout across training epochs. + +--> + + +### Implementation details +A full specification of packages used and their versions can be found in _packages.txt_ .\ +For learning rates the default ADAM parameters were used to avoid any impression of fine-tuning.\ +All simulations were run on a single CPU and took on the order of minutes to a few of hours. + + + +<!--- +### figures/ +Contains all figures of the main text and the supplement. +--> + + +<!--- +### tex/ +Contains the raw text of the main text and the supplement. +--> diff --git a/research/flossing/external/julia-1.6.7/LICENSE.md b/research/flossing/external/julia-1.6.7/LICENSE.md new file mode 100644 index 0000000..7912722 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/LICENSE.md @@ -0,0 +1,26 @@ +MIT License + +Copyright (c) 2009-2021: Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors: https://github.com/JuliaLang/julia/contributors + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +end of terms and conditions + +Please see THIRDPARTY.md for license information for other software used in this project. diff --git a/research/flossing/external/julia-1.6.7/share/julia/base/ryu/LICENSE.md b/research/flossing/external/julia-1.6.7/share/julia/base/ryu/LICENSE.md new file mode 100644 index 0000000..74c7186 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/base/ryu/LICENSE.md @@ -0,0 +1,25 @@ +The code in this directory (base/ryu) is a derivative based on the work in the https://github.com/ulfjack/ryu repository, which allows the use of the Boost software license, included below. + +Boost Software License - Version 1.0 - August 17th, 2003 + +Permission is hereby granted, free of charge, to any person or organization +obtaining a copy of the software and accompanying documentation covered by +this license (the "Software") to use, reproduce, display, distribute, +execute, and transmit the Software, and to prepare derivative works of the +Software, and to permit third-parties to whom the Software is furnished to +do so, all subject to the following: + +The copyright notices in the Software and this entire statement, including +the above license grant, this restriction and the following disclaimer, +must be included in all copies of the Software, in whole or in part, and +all derivative works of the Software, unless such copies or derivative +works are solely in the form of machine-executable object code generated by +a source language processor. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT +SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE +FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE.
\ No newline at end of file diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/ArgTools/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/ArgTools/README.md new file mode 100644 index 0000000..a0415d7 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/ArgTools/README.md @@ -0,0 +1,431 @@ +# ArgTools + +[](https://travis-ci.org/JuliaIO/ArgTools.jl) +[](https://codecov.io/gh/JuliaIO/ArgTools.jl) + +`ArgTools` provides tools for creating consistent, flexible APIs that work with +various kinds of function arguments. In the current version, it helps deal with +arguments that are, at their core, IO handles, but which you'd like to allow the +user to specify directly as file names, commands, pipelines, or, of course, as +raw IO handles. For write arguments, it's also possible to use `nothing` and +write to a temporary file whose path is returned. + +## API + +There are two parts to the `ArgTools` API: + +1. Functions and types for helping define flexible function APIs. +2. Functions for helping to test APIs defined with above. + +While it's great to be able to define a flexibile API, if you're not sure that +it works the way it's supposed to, what's the benefit. Since it's can be quite +verbose to test such a combinatorial explosion of methods, `ArgTools` also +provides tools to help testing all the ways your tools can be called to make +sure everything is working as intented. + +### Argument Handling + +The API for helping defing flexible function signatures consists of two types +and four helper functions: `ArgRead` and `ArgWrite`; `arg_read`, `arg_write`, +`arg_isdir` and `arg_mkdir`. + +<!-- BEGIN: copied from inline doc strings --> + +#### ArgRead + +```jl +ArgRead = Union{AbstractString, AbstractCmd, IO} +``` +The `ArgRead` types is a union of the types that the `arg_read` function knows +how to convert into readable IO handles. See [`arg_read`](@ref) for details. + +#### ArgWrite + +```jl +ArgWrite = Union{AbstractString, AbstractCmd, IO} +``` +The `ArgWrite` types is a union of the types that the `arg_write` function knows +how to convert into writeable IO handles, except for `Nothing` which `arg_write` +handles by generating a temporary file. See [`arg_write`](@ref) for details. + +#### arg_read + +```jl +arg_read(f::Function, arg::ArgRead) -> f(arg_io) +``` +The `arg_read` function accepts an argument `arg` that can be any of these: + +- `AbstractString`: a file path to be opened for reading +- `AbstractCmd`: a command to be run, reading from its standard output +- `IO`: an open IO handle to be read from + +Whether the body returns normally or throws an error, a path which is opened +will be closed before returning from `arg_read` and an `IO` handle will be +flushed but not closed before returning from `arg_read`. + +#### arg_write + +```jl +arg_write(f::Function, arg::ArgWrite) -> arg +arg_write(f::Function, arg::Nothing) -> tempname() +``` +The `arg_write` function accepts an argument `arg` that can be any of these: + +- `AbstractString`: a file path to be opened for writing +- `AbstractCmd`: a command to be run, writing to its standard input +- `IO`: an open IO handle to be written to +- `Nothing`: a temporary path should be written to + +If the body returns normally, a path that is opened will be closed upon +completion; an IO handle argument is left open but flushed before return. If the +argument is `nothing` then a temporary path is opened for writing and closed +open completion and the path is returned from `arg_write`. In all other cases, +`arg` itself is returned. This is a useful pattern since you can consistently +return whatever was written, whether an argument was passed or not. + +If there is an error during the evaluation of the body, a path that is opened by +`arg_write` for writing will be deleted, whether it's passed in as a string or a +temporary path generated when `arg` is `nothing`. + +#### arg_isdir + +```jl +arg_isdir(f::Function, arg::AbstractString) -> f(arg) +``` +The `arg_isdir` function takes `arg` which must be the path to an existing +directory (an error is raised otherwise) and passes that path to `f` finally +returning the result of `f(arg)`. This is definitely the least useful tool +offered by `ArgTools` and mostly exists for symmetry with `arg_mkdir` and to +give consistent error messages. + +#### arg_mkdir + +```jl +arg_mkdir(f::Function, arg::AbstractString) -> arg +arg_mkdir(f::Function, arg::Nothing) -> mktempdir() +``` +The `arg_mkdir` function takes `arg` which must either be one of: + +- a path to an already existing empty directory, +- a non-existent path which can be created as a directory, or +- `nothing` in which case a temporary directory is created. + +In all cases the path to the directory is returned. If an error occurs during +`f(arg)`, the directory is returned to its original state: if it already existed +but was empty, it will be emptied; if it did not exist it will be deleted. + +<!-- END: copied from inline doc strings --> + +### Function Testing + +Using `ArgTools` is easy; thoroughly testing flexible functions defined using +`ArgTools` is a bit trickier, but the package includes testing tools that help. +The API for testing functions defined with the argument handling API consists +of two functions and a macro: `arg_readers`, `arg_writers` and `@arg_test`. + +<!-- BEGIN: copied from inline doc strings --> + +#### arg_readers + +```jl +arg_readers(arg :: AbstractString, [ type = ArgRead ]) do arg::Function + ## pre-test setup ## + @arg_test arg begin + arg :: ArgRead + ## test using `arg` ## + end + ## post-test cleanup ## +end +``` + +The `arg_readers` function takes a path to be read and a single-argument do +block, which is invoked once for each test reader type that `arg_read` can +handle. If the optional `type` argument is given then the do block is only +invoked for readers that produce arguments of that type. + +The `arg` passed to the do block is not the argument value itself, because some +of test argument types need to be initialized and finalized for each test case. +Consider an open file handle argument: once you've used it for one test, you +can't use it again; you need to close it and open the file again for the next +test. This function `arg` can be converted into an `ArgRead` instance using +`@arg_test arg begin ... end`. + +#### arg_writers + +```jl +arg_writers([ type = ArgWrite ]) do path::String, arg::Function + ## pre-test setup ## + @arg_test arg begin + arg :: ArgWrite + ## test using `arg` ## + end + ## post-test cleanup ## +end +``` + +The `arg_writers` function takes a do block, which is invoked once for each test +writer type that `arg_write` can handle with a temporary (non-existent) `path` +and `arg` which can be converted into various writable argument types which +write to `path`. If the optional `type` argument is given then the do block is +only invoked for writers that produce arguments of that type. + +The `arg` passed to the do block is not the argument value itself, because some +of test argument types need to be initialized and finalized for each test case. +Consider an open file handle argument: once you've used it for one test, you +can't use it again; you need to close it and open the file again for the next +test. This function `arg` can be converted into an `ArgWrite` instance using +`@arg_test arg begin ... end`. + +There is also an `arg_writers` method that takes a path name like `arg_readers`: + +```jl +arg_writers(path::AbstractString, [ type = ArgWrite ]) do arg::Function + ## pre-test setup ## + @arg_test arg begin + arg :: ArgWrite + ## test using `arg` ## + end + ## post-test cleanup ## +end +``` + +This method is useful if you need to specify `path` instead of using path name +generated by `tempname()`. Since `path` is passed from outside of `arg_writers`, +the path is not an argument to the do block in this form. + +#### @arg_test + +```jl +@arg_test arg1 arg2 ... body +``` + +The `@arg_test` macro is used to convert `arg` functions provided by +`arg_readers` and `arg_writers` into actual argument values. When you write +`@arg_test arg body` it is equivalent to `arg(arg -> body)`. + +<!-- END: copied from inline doc strings --> + +## Examples + +The examples, like the API, are split into two parts: + +1. An example of defining a function with a flexible API using the main API; +2. Examples of how to thoroughly test that function using the test utilities. + +### Usage Example + +The best explanation may be an example, which is also used for testing: + +```jl +using ArgTools + +function send_data(src::ArgRead, dst::Union{ArgWrite, Nothing} = nothing) + arg_read(src) do src_io + arg_write(dst) do dst_io + buffer = Vector{UInt8}(undef, 2*1024*1024) + while !eof(src_io) + n = readbytes!(src_io, buffer) + write(dst_io, view(buffer, 1:n)) + end + end + end +end +``` + +This defines the `send_data` function which reads data from a source and writes +it to a destination, specified by the `src` and `dst` arguments, respectively. +Thanks to `ArgTools`, this relatively simple definition acts as a swiss-army +knife for sending data from a source to a destination. Here are some examples: + +```jl +julia> cd(mktempdir()) + +julia> write("hello.txt", "Hello, world.\n") +14 + +julia> run(`cat hello.txt`); +Hello, world. + +julia> send_data("hello.txt", "hello_copy.txt") +"hello_copy.txt" + +julia> run(`cat $ans`); +Hello, world. + +julia> rm("hello_copy.txt") + +julia> send_data("hello.txt", stdout); +Hello, world. + +julia> send_data("hello.txt", pipeline(`gzip -9`, "hello.gz")); + +julia> run(`gzcat hello.gz`); +Hello, world. + +julia> hello_copy = send_data(`gzcat hello.gz`) +"/var/folders/4g/b8p546px3nd550b3k288mhp80000gp/T/jl_cguepi" + +julia> run(`cat $hello_copy`); +Hello, world. +``` + +To understand the definition of `send_data`, let's work from the inside out: + +* The main body of the function operates on the `src_io` and `dst_io` IO + handles, using a buffer to read data from the former to the latter in 2MiB + blocks. + +* The calls to `arg_read` and `arg_write` transform the `src` and `dst` + arguments from various types to `src_io` and `dst_io` IO handles. This allows + the inner body to handle the core case of dealing with IO handles, without + having to worry about the various possible incoming argument types. See the API + section below for more details about how `arg_read` and `arg_write` work on + different types. + +* The arguments to `send_data` are `src::ArgRead` and `dst::ArgWrite` where + `dst` is optional and defaults to `nothing` if not given. The `ArgRead` type is + a union including all the types that `arg_read` knows how to handle. Similarly, + the `ArgWrite` type is a union including the types that `arg_write` knows how to + handle, except for `nothing` which must be explicitly opted into, for which + `arg_write` creates a temporary file and returns its path. + +Taken altogether, this allows the `send_data` function to work with a combinatoral +explosion of type signatures: + +* `send_data(src::AbstractString)` +* `send_data(src::AbstractCmd)` +* `send_data(src::IO)` +* `send_data(src::AbstractString, dst::AbstractString)` +* `send_data(src::AbstractCmd, dst::AbstractString)` +* `send_data(src::IO, dst::AbstractString)` +* `send_data(src::AbstractString, dst::AbstractCmd)` +* `send_data(src::AbstractCmd, dst::AbstractCmd)` +* `send_data(src::IO, dst::AbstractCmd)` +* `send_data(src::AbstractString, dst::IO)` +* `send_data(src::AbstractCmd, dst::IO)` +* `send_data(src::IO, dst::IO)` + +Each combination guarantees the proper initialization and cleanup of its +arguments whether it is opening a file and closing it upon completion or error, +or creating a temporary output file and returning it upon completion or deleting +it on error. If the arguments are commands or pipelines, those are correctly +opened with the necessary read/write options. + +### Testing Example + +Now that we've defined the `send_data` function, we must test it. But it has so +many different kinds of arguments that it can accept, how do we produce tests +for all of these combinations? `ArgTools` also offers tools to help with testing +APIs that it lets you define. The example tests assume that the above definition +of `send_data` has already been evaluated in the same Julia session. + +```jl +using Test + +# create a source file +src_file = tempname() +data = rand(UInt8, 666) +write(src_file, data) + +print_sig(args...) = + println("send_data(", join(map(typeof, args), ", "), ")") + +arg_readers(src_file) do src + # test 1-arg methods + @arg_test src begin + print_sig(src) + dst_file = send_data(src) + @test data == read(dst_file) + rm(dst_file) + end + + # test 2-arg methods + arg_writers() do dst_file, dst + @arg_test src dst begin + print_sig(src, dst) + @test dst == send_data(src, dst) + end + @test data == read(dst_file) + end +end + +# cleanup +rm(src_file) +``` + +Evaluating this testing code prints the following output: +```jl +send_data(String) +send_data(String, String) +send_data(String, Cmd) +send_data(String, Base.CmdRedirect) +send_data(String, IOStream) +send_data(String, Base.Process) +send_data(Cmd) +send_data(Cmd, String) +send_data(Cmd, Cmd) +send_data(Cmd, Base.CmdRedirect) +send_data(Cmd, IOStream) +send_data(Cmd, Base.Process) +send_data(Base.CmdRedirect) +send_data(Base.CmdRedirect, String) +send_data(Base.CmdRedirect, Cmd) +send_data(Base.CmdRedirect, Base.CmdRedirect) +send_data(Base.CmdRedirect, IOStream) +send_data(Base.CmdRedirect, Base.Process) +send_data(IOStream) +send_data(IOStream, String) +send_data(IOStream, Cmd) +send_data(IOStream, Base.CmdRedirect) +send_data(IOStream, IOStream) +send_data(IOStream, Base.Process) +send_data(Base.Process) +send_data(Base.Process, String) +send_data(Base.Process, Cmd) +send_data(Base.Process, Base.CmdRedirect) +send_data(Base.Process, IOStream) +send_data(Base.Process, Base.Process) +``` + +Test code doesn't isn't normally this verbose, but for this example it may be +helpful to understand what's happening. What this output shows is the various +ways in which this short bit of code tests invoking the `send_data` function. +Here are some details about what's happening: + +* The call to `arg_readers(src_file)` evaluates the attached do block with five + different `arg` values, which can be converted to readable arguments of the + types: `String`, `Cmd`, `CmdRedirect`, `IOStream` and `Process`. + +* The call to `@arg_test src begin ... end` converts `src` into a readable + arguments of those same types and closes or finalizes each at the end. + +* The call to `arg_writers()` evaluates the attached do block with five + different `arg` values, which can be converted to writable arguments of the + types: `String`, `Cmd`, `CmdRedirect`, `IOStream` and `Process`. + +* The call to `@arg_test src dst begin ... end` converts `src` into a readable + arguments and `dst` into writeable arguments of the same set of types, and + closes or otherwise finalizes each one at the end of the block. + +This example test code illustrates some of the reasoning features of the testing +API which might initially seem puzzling. For example, it shows why `arg_readers` +and `arg_writers` don't simply produce argument values that can be passed to the +function being tested, instead requiring conversion by the `@arg_test` macro. +There are two reasons: + +1. The same value returned from `arg_readers` or `arg_writers` may need to be + used in multiple tests and some argument types, such as IO handles, need to + be initialized before each test and finalized after. The `@arg_test` block + delimits where initialization and finalization occur. + +2. Sometimes operations need to be done after the `@arg_test` block but before + the end of the enclosing `arg_readers` or `arg_writers` block. Testing that + `dst_file` has the expected contents, i.e. `@test data == read(dst_file)`, + will not work reliably inside of the `@arg_test` block: data is not guaranteed + to have been fully written to `dst_file` until `dst` is finalized. This is an + issue when `dst` is an already-opened process, for example: `arg_write` leaves + the process open since it recieved it that way (you might want to write more + data to it), and while it does flush the handle, there is no guarantee that + the process will get data to its final destination until the process has + exited. Putting the test after the `@arg_test` block ensures that the process + has terminated, so we can reliably test the contents of `dst_file`. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Artifacts/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Artifacts/docs/src/index.md new file mode 100644 index 0000000..80f4c62 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Artifacts/docs/src/index.md @@ -0,0 +1,21 @@ +# Artifacts + +```@meta +DocTestSetup = :(using Artifacts) +``` + +Starting with Julia 1.6, the artifacts support has moved from `Pkg.jl` to Julia itself. +Until proper documentation can be added here, you can learn more about artifacts in the +`Pkg.jl` manual at <https://julialang.github.io/Pkg.jl/v1/artifacts/>. + +!!! compat "Julia 1.6" + Julia's artifacts API requires at least Julia 1.6. In Julia + versions 1.3 to 1.5, you can use `Pkg.Artifacts` instead. + + +```@docs +Artifacts.artifact_meta +Artifacts.artifact_hash +Artifacts.find_artifacts_toml +Artifacts.@artifact_str +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Base64/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Base64/docs/src/index.md new file mode 100644 index 0000000..6bc647f --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Base64/docs/src/index.md @@ -0,0 +1,10 @@ +# Base64 + +```@docs +Base64.Base64 +Base64.Base64EncodePipe +Base64.base64encode +Base64.Base64DecodePipe +Base64.base64decode +Base64.stringmime +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/CRC32c/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/CRC32c/docs/src/index.md new file mode 100644 index 0000000..1304709 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/CRC32c/docs/src/index.md @@ -0,0 +1,6 @@ +# CRC32c + +```@docs +CRC32c.crc32c +CRC32c.crc32c(::IO, ::Integer, ::UInt32) +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Dates/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Dates/docs/src/index.md new file mode 100644 index 0000000..975c087 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Dates/docs/src/index.md @@ -0,0 +1,826 @@ +# Dates + +```@meta +DocTestSetup = :(using Dates) +``` + +The `Dates` module provides two types for working with dates: [`Date`](@ref) and [`DateTime`](@ref), +representing day and millisecond precision, respectively; both are subtypes of the abstract [`TimeType`](@ref). +The motivation for distinct types is simple: some operations are much simpler, both in terms of +code and mental reasoning, when the complexities of greater precision don't have to be dealt with. +For example, since the [`Date`](@ref) type only resolves to the precision of a single date (i.e. +no hours, minutes, or seconds), normal considerations for time zones, daylight savings/summer +time, and leap seconds are unnecessary and avoided. + +Both [`Date`](@ref) and [`DateTime`](@ref) are basically immutable [`Int64`](@ref) wrappers. +The single `instant` field of either type is actually a `UTInstant{P}` type, which +represents a continuously increasing machine timeline based on the UT second [^1]. The +[`DateTime`](@ref) type is not aware of time zones (*naive*, in Python parlance), +analogous to a *LocalDateTime* in Java 8. Additional time zone functionality +can be added through the [TimeZones.jl package](https://github.com/JuliaTime/TimeZones.jl/), which +compiles the [IANA time zone database](http://www.iana.org/time-zones). Both [`Date`](@ref) and +[`DateTime`](@ref) are based on the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard, which follows the proleptic Gregorian calendar. +One note is that the ISO 8601 standard is particular about BC/BCE dates. In general, the last +day of the BC/BCE era, 1-12-31 BC/BCE, was followed by 1-1-1 AD/CE, thus no year zero exists. +The ISO standard, however, states that 1 BC/BCE is year zero, so `0000-12-31` is the day before +`0001-01-01`, and year `-0001` (yes, negative one for the year) is 2 BC/BCE, year `-0002` is 3 +BC/BCE, etc. + +[^1]: + The notion of the UT second is actually quite fundamental. There are basically two different notions + of time generally accepted, one based on the physical rotation of the earth (one full rotation + = 1 day), the other based on the SI second (a fixed, constant value). These are radically different! + Think about it, a "UT second", as defined relative to the rotation of the earth, may have a different + absolute length depending on the day! Anyway, the fact that [`Date`](@ref) and [`DateTime`](@ref) + are based on UT seconds is a simplifying, yet honest assumption so that things like leap seconds + and all their complexity can be avoided. This basis of time is formally called [UT](https://en.wikipedia.org/wiki/Universal_Time) + or UT1. Basing types on the UT second basically means that every minute has 60 seconds and every + day has 24 hours and leads to more natural calculations when working with calendar dates. + +## Constructors + +[`Date`](@ref) and [`DateTime`](@ref) types can be constructed by integer or [`Period`](@ref) +types, by parsing, or through adjusters (more on those later): + +```jldoctest +julia> DateTime(2013) +2013-01-01T00:00:00 + +julia> DateTime(2013,7) +2013-07-01T00:00:00 + +julia> DateTime(2013,7,1) +2013-07-01T00:00:00 + +julia> DateTime(2013,7,1,12) +2013-07-01T12:00:00 + +julia> DateTime(2013,7,1,12,30) +2013-07-01T12:30:00 + +julia> DateTime(2013,7,1,12,30,59) +2013-07-01T12:30:59 + +julia> DateTime(2013,7,1,12,30,59,1) +2013-07-01T12:30:59.001 + +julia> Date(2013) +2013-01-01 + +julia> Date(2013,7) +2013-07-01 + +julia> Date(2013,7,1) +2013-07-01 + +julia> Date(Dates.Year(2013),Dates.Month(7),Dates.Day(1)) +2013-07-01 + +julia> Date(Dates.Month(7),Dates.Year(2013)) +2013-07-01 +``` + +[`Date`](@ref) or [`DateTime`](@ref) parsing is accomplished by the use of format strings. Format +strings work by the notion of defining *delimited* or *fixed-width* "slots" that contain a period +to parse and passing the text to parse and format string to a [`Date`](@ref) or [`DateTime`](@ref) +constructor, of the form `Date("2015-01-01","y-m-d")` or `DateTime("20150101","yyyymmdd")`. + +Delimited slots are marked by specifying the delimiter the parser should expect between two subsequent +periods; so `"y-m-d"` lets the parser know that between the first and second slots in a date string +like `"2014-07-16"`, it should find the `-` character. The `y`, `m`, and `d` characters let the +parser know which periods to parse in each slot. + +Fixed-width slots are specified by repeating the period character the number of times corresponding +to the width with no delimiter between characters. So `"yyyymmdd"` would correspond to a date +string like `"20140716"`. The parser distinguishes a fixed-width slot by the absence of a delimiter, +noting the transition `"yyyymm"` from one period character to the next. + +Support for text-form month parsing is also supported through the `u` and `U` characters, for +abbreviated and full-length month names, respectively. By default, only English month names are +supported, so `u` corresponds to "Jan", "Feb", "Mar", etc. And `U` corresponds to "January", "February", +"March", etc. Similar to other name=>value mapping functions [`dayname`](@ref) and [`monthname`](@ref), +custom locales can be loaded by passing in the `locale=>Dict{String,Int}` mapping to the `MONTHTOVALUEABBR` +and `MONTHTOVALUE` dicts for abbreviated and full-name month names, respectively. + +One note on parsing performance: using the `Date(date_string,format_string)` function is fine +if only called a few times. If there are many similarly formatted date strings to parse however, +it is much more efficient to first create a [`Dates.DateFormat`](@ref), and pass it instead of +a raw format string. + +```jldoctest +julia> df = DateFormat("y-m-d"); + +julia> dt = Date("2015-01-01",df) +2015-01-01 + +julia> dt2 = Date("2015-01-02",df) +2015-01-02 +``` + +You can also use the `dateformat""` string macro. This macro creates the `DateFormat` object once when the macro is expanded and uses the same `DateFormat` object even if a code snippet is run multiple times. + +```jldoctest +julia> for i = 1:10^5 + Date("2015-01-01", dateformat"y-m-d") + end +``` + +A full suite of parsing and formatting tests and examples is available in [`stdlib/Dates/test/io.jl`](https://github.com/JuliaLang/julia/blob/master/stdlib/Dates/test/io.jl). + +## Durations/Comparisons + +Finding the length of time between two [`Date`](@ref) or [`DateTime`](@ref) is straightforward +given their underlying representation as `UTInstant{Day}` and `UTInstant{Millisecond}`, respectively. +The difference between [`Date`](@ref) is returned in the number of [`Day`](@ref), and [`DateTime`](@ref) +in the number of [`Millisecond`](@ref). Similarly, comparing [`TimeType`](@ref) is a simple matter +of comparing the underlying machine instants (which in turn compares the internal [`Int64`](@ref) values). + +```jldoctest +julia> dt = Date(2012,2,29) +2012-02-29 + +julia> dt2 = Date(2000,2,1) +2000-02-01 + +julia> dump(dt) +Date + instant: Dates.UTInstant{Day} + periods: Day + value: Int64 734562 + +julia> dump(dt2) +Date + instant: Dates.UTInstant{Day} + periods: Day + value: Int64 730151 + +julia> dt > dt2 +true + +julia> dt != dt2 +true + +julia> dt + dt2 +ERROR: MethodError: no method matching +(::Date, ::Date) +[...] + +julia> dt * dt2 +ERROR: MethodError: no method matching *(::Date, ::Date) +[...] + +julia> dt / dt2 +ERROR: MethodError: no method matching /(::Date, ::Date) + +julia> dt - dt2 +4411 days + +julia> dt2 - dt +-4411 days + +julia> dt = DateTime(2012,2,29) +2012-02-29T00:00:00 + +julia> dt2 = DateTime(2000,2,1) +2000-02-01T00:00:00 + +julia> dt - dt2 +381110400000 milliseconds +``` + +## Accessor Functions + +Because the [`Date`](@ref) and [`DateTime`](@ref) types are stored as single [`Int64`](@ref) values, date +parts or fields can be retrieved through accessor functions. The lowercase accessors return the +field as an integer: + +```jldoctest tdate +julia> t = Date(2014, 1, 31) +2014-01-31 + +julia> Dates.year(t) +2014 + +julia> Dates.month(t) +1 + +julia> Dates.week(t) +5 + +julia> Dates.day(t) +31 +``` + +While propercase return the same value in the corresponding [`Period`](@ref) type: + +```jldoctest tdate +julia> Dates.Year(t) +2014 years + +julia> Dates.Day(t) +31 days +``` + +Compound methods are provided because it is more efficient to access multiple fields at the same time than individually: + +```jldoctest tdate +julia> Dates.yearmonth(t) +(2014, 1) + +julia> Dates.monthday(t) +(1, 31) + +julia> Dates.yearmonthday(t) +(2014, 1, 31) +``` + +One may also access the underlying `UTInstant` or integer value: + +```jldoctest tdate +julia> dump(t) +Date + instant: Dates.UTInstant{Day} + periods: Day + value: Int64 735264 + +julia> t.instant +Dates.UTInstant{Day}(Day(735264)) + +julia> Dates.value(t) +735264 +``` + +## Query Functions + +Query functions provide calendrical information about a [`TimeType`](@ref). They include information +about the day of the week: + +```jldoctest tdate2 +julia> t = Date(2014, 1, 31) +2014-01-31 + +julia> Dates.dayofweek(t) +5 + +julia> Dates.dayname(t) +"Friday" + +julia> Dates.dayofweekofmonth(t) # 5th Friday of January +5 +``` + +Month of the year: + +```jldoctest tdate2 +julia> Dates.monthname(t) +"January" + +julia> Dates.daysinmonth(t) +31 +``` + +As well as information about the [`TimeType`](@ref)'s year and quarter: + +```jldoctest tdate2 +julia> Dates.isleapyear(t) +false + +julia> Dates.dayofyear(t) +31 + +julia> Dates.quarterofyear(t) +1 + +julia> Dates.dayofquarter(t) +31 +``` + +The [`dayname`](@ref) and [`monthname`](@ref) methods can also take an optional `locale` keyword +that can be used to return the name of the day or month of the year for other languages/locales. +There are also versions of these functions returning the abbreviated names, namely +[`dayabbr`](@ref) and [`monthabbr`](@ref). +First the mapping is loaded into the `LOCALES` variable: + +```jldoctest tdate2 +julia> french_months = ["janvier", "février", "mars", "avril", "mai", "juin", + "juillet", "août", "septembre", "octobre", "novembre", "décembre"]; + +julia> french_monts_abbrev = ["janv","févr","mars","avril","mai","juin", + "juil","août","sept","oct","nov","déc"]; + +julia> french_days = ["lundi","mardi","mercredi","jeudi","vendredi","samedi","dimanche"]; + +julia> Dates.LOCALES["french"] = Dates.DateLocale(french_months, french_monts_abbrev, french_days, [""]); +``` + + The above mentioned functions can then be used to perform the queries: + +```jldoctest tdate2 +julia> Dates.dayname(t;locale="french") +"vendredi" + +julia> Dates.monthname(t;locale="french") +"janvier" + +julia> Dates.monthabbr(t;locale="french") +"janv" +``` + +Since the abbreviated versions of the days are not loaded, trying to use the +function `dayabbr` will error. + +```jldoctest tdate2 +julia> Dates.dayabbr(t;locale="french") +ERROR: BoundsError: attempt to access 1-element Vector{String} at index [5] +Stacktrace: +[...] +``` + + +## TimeType-Period Arithmetic + +It's good practice when using any language/date framework to be familiar with how date-period +arithmetic is handled as there are some [tricky issues](https://codeblog.jonskeet.uk/2010/12/01/the-joys-of-date-time-arithmetic/) +to deal with (though much less so for day-precision types). + +The `Dates` module approach tries to follow the simple principle of trying to change as +little as possible when doing [`Period`](@ref) arithmetic. This approach is also often known as +*calendrical* arithmetic or what you would probably guess if someone were to ask you the same +calculation in a conversation. Why all the fuss about this? Let's take a classic example: add +1 month to January 31st, 2014. What's the answer? Javascript will say [March 3](https://markhneedham.com/blog/2009/01/07/javascript-add-a-month-to-a-date/) +(assumes 31 days). PHP says [March 2](https://stackoverflow.com/questions/5760262/php-adding-months-to-a-date-while-not-exceeding-the-last-day-of-the-month) +(assumes 30 days). The fact is, there is no right answer. In the `Dates` module, it gives +the result of February 28th. How does it figure that out? Consider the classic 7-7-7 +gambling game in casinos. + +Now just imagine that instead of 7-7-7, the slots are Year-Month-Day, or in our example, 2014-01-31. +When you ask to add 1 month to this date, the month slot is incremented, so now we have 2014-02-31. +Then the day number is checked if it is greater than the last valid day of the new month; if it +is (as in the case above), the day number is adjusted down to the last valid day (28). What are +the ramifications with this approach? Go ahead and add another month to our date, `2014-02-28 + Month(1) == 2014-03-28`. +What? Were you expecting the last day of March? Nope, sorry, remember the 7-7-7 slots. As few +slots as possible are going to change, so we first increment the month slot by 1, 2014-03-28, +and boom, we're done because that's a valid date. On the other hand, if we were to add 2 months +to our original date, 2014-01-31, then we end up with 2014-03-31, as expected. The other ramification +of this approach is a loss in associativity when a specific ordering is forced (i.e. adding things +in different orders results in different outcomes). For example: + +```jldoctest +julia> (Date(2014,1,29)+Dates.Day(1)) + Dates.Month(1) +2014-02-28 + +julia> (Date(2014,1,29)+Dates.Month(1)) + Dates.Day(1) +2014-03-01 +``` + +What's going on there? In the first line, we're adding 1 day to January 29th, which results in +2014-01-30; then we add 1 month, so we get 2014-02-30, which then adjusts down to 2014-02-28. +In the second example, we add 1 month *first*, where we get 2014-02-29, which adjusts down to +2014-02-28, and *then* add 1 day, which results in 2014-03-01. One design principle that helps +in this case is that, in the presence of multiple Periods, the operations will be ordered by the +Periods' *types*, not their value or positional order; this means `Year` will always be added +first, then `Month`, then `Week`, etc. Hence the following *does* result in associativity and +Just Works: + +```jldoctest +julia> Date(2014,1,29) + Dates.Day(1) + Dates.Month(1) +2014-03-01 + +julia> Date(2014,1,29) + Dates.Month(1) + Dates.Day(1) +2014-03-01 +``` + +Tricky? Perhaps. What is an innocent `Dates` user to do? The bottom line is to be aware +that explicitly forcing a certain associativity, when dealing with months, may lead to some unexpected +results, but otherwise, everything should work as expected. Thankfully, that's pretty much the +extent of the odd cases in date-period arithmetic when dealing with time in UT (avoiding the "joys" +of dealing with daylight savings, leap seconds, etc.). + +As a bonus, all period arithmetic objects work directly with ranges: + +```jldoctest +julia> dr = Date(2014,1,29):Day(1):Date(2014,2,3) +Date("2014-01-29"):Day(1):Date("2014-02-03") + +julia> collect(dr) +6-element Vector{Date}: + 2014-01-29 + 2014-01-30 + 2014-01-31 + 2014-02-01 + 2014-02-02 + 2014-02-03 + +julia> dr = Date(2014,1,29):Dates.Month(1):Date(2014,07,29) +Date("2014-01-29"):Month(1):Date("2014-07-29") + +julia> collect(dr) +7-element Vector{Date}: + 2014-01-29 + 2014-02-28 + 2014-03-29 + 2014-04-29 + 2014-05-29 + 2014-06-29 + 2014-07-29 +``` + +## Adjuster Functions + +As convenient as date-period arithmetic is, often the kinds of calculations needed on dates +take on a *calendrical* or *temporal* nature rather than a fixed number of periods. Holidays are +a perfect example; most follow rules such as "Memorial Day = Last Monday of May", or "Thanksgiving += 4th Thursday of November". These kinds of temporal expressions deal with rules relative to the +calendar, like first or last of the month, next Tuesday, or the first and third Wednesdays, etc. + +The `Dates` module provides the *adjuster* API through several convenient methods that +aid in simply and succinctly expressing temporal rules. The first group of adjuster methods deal +with the first and last of weeks, months, quarters, and years. They each take a single [`TimeType`](@ref) +as input and return or *adjust to* the first or last of the desired period relative to the input. + +```jldoctest +julia> Dates.firstdayofweek(Date(2014,7,16)) # Adjusts the input to the Monday of the input's week +2014-07-14 + +julia> Dates.lastdayofmonth(Date(2014,7,16)) # Adjusts to the last day of the input's month +2014-07-31 + +julia> Dates.lastdayofquarter(Date(2014,7,16)) # Adjusts to the last day of the input's quarter +2014-09-30 +``` + +The next two higher-order methods, [`tonext`](@ref), and [`toprev`](@ref), generalize working +with temporal expressions by taking a `DateFunction` as first argument, along with a starting +[`TimeType`](@ref). A `DateFunction` is just a function, usually anonymous, that takes a single +[`TimeType`](@ref) as input and returns a [`Bool`](@ref), `true` indicating a satisfied +adjustment criterion. +For example: + +```jldoctest +julia> istuesday = x->Dates.dayofweek(x) == Dates.Tuesday; # Returns true if the day of the week of x is Tuesday + +julia> Dates.tonext(istuesday, Date(2014,7,13)) # 2014-07-13 is a Sunday +2014-07-15 + +julia> Dates.tonext(Date(2014,7,13), Dates.Tuesday) # Convenience method provided for day of the week adjustments +2014-07-15 +``` + +This is useful with the do-block syntax for more complex temporal expressions: + +```jldoctest +julia> Dates.tonext(Date(2014,7,13)) do x + # Return true on the 4th Thursday of November (Thanksgiving) + Dates.dayofweek(x) == Dates.Thursday && + Dates.dayofweekofmonth(x) == 4 && + Dates.month(x) == Dates.November + end +2014-11-27 +``` + +The [`Base.filter`](@ref) method can be used to obtain all valid dates/moments in a specified +range: + +```jldoctest +# Pittsburgh street cleaning; Every 2nd Tuesday from April to November +# Date range from January 1st, 2014 to January 1st, 2015 +julia> dr = Dates.Date(2014):Day(1):Dates.Date(2015); + +julia> filter(dr) do x + Dates.dayofweek(x) == Dates.Tue && + Dates.April <= Dates.month(x) <= Dates.Nov && + Dates.dayofweekofmonth(x) == 2 + end +8-element Vector{Date}: + 2014-04-08 + 2014-05-13 + 2014-06-10 + 2014-07-08 + 2014-08-12 + 2014-09-09 + 2014-10-14 + 2014-11-11 +``` + +Additional examples and tests are available in [`stdlib/Dates/test/adjusters.jl`](https://github.com/JuliaLang/julia/blob/master/stdlib/Dates/test/adjusters.jl). + +## Period Types + +Periods are a human view of discrete, sometimes irregular durations of time. Consider 1 month; +it could represent, in days, a value of 28, 29, 30, or 31 depending on the year and month context. +Or a year could represent 365 or 366 days in the case of a leap year. [`Period`](@ref) types are +simple [`Int64`](@ref) wrappers and are constructed by wrapping any `Int64` convertible type, i.e. `Year(1)` +or `Month(3.0)`. Arithmetic between [`Period`](@ref) of the same type behave like integers, and +limited `Period-Real` arithmetic is available. You can extract the underlying integer with +[`Dates.value`](@ref). + +```jldoctest +julia> y1 = Dates.Year(1) +1 year + +julia> y2 = Dates.Year(2) +2 years + +julia> y3 = Dates.Year(10) +10 years + +julia> y1 + y2 +3 years + +julia> div(y3,y2) +5 + +julia> y3 - y2 +8 years + +julia> y3 % y2 +0 years + +julia> div(y3,3) # mirrors integer division +3 years + +julia> Dates.value(Dates.Millisecond(10)) +10 +``` + +## Rounding + +[`Date`](@ref) and [`DateTime`](@ref) values can be rounded to a specified resolution (e.g., 1 +month or 15 minutes) with [`floor`](@ref), [`ceil`](@ref), or [`round`](@ref): + +```jldoctest +julia> floor(Date(1985, 8, 16), Dates.Month) +1985-08-01 + +julia> ceil(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15)) +2013-02-13T00:45:00 + +julia> round(DateTime(2016, 8, 6, 20, 15), Dates.Day) +2016-08-07T00:00:00 +``` + +Unlike the numeric [`round`](@ref) method, which breaks ties toward the even number by default, +the [`TimeType`](@ref)[`round`](@ref) method uses the `RoundNearestTiesUp` rounding mode. (It's +difficult to guess what breaking ties to nearest "even" [`TimeType`](@ref) would entail.) Further +details on the available `RoundingMode` s can be found in the [API reference](@ref stdlib-dates-api). + +Rounding should generally behave as expected, but there are a few cases in which the expected +behaviour is not obvious. + +### Rounding Epoch + +In many cases, the resolution specified for rounding (e.g., `Dates.Second(30)`) divides evenly +into the next largest period (in this case, `Dates.Minute(1)`). But rounding behaviour in cases +in which this is not true may lead to confusion. What is the expected result of rounding a [`DateTime`](@ref) +to the nearest 10 hours? + +```jldoctest +julia> round(DateTime(2016, 7, 17, 11, 55), Dates.Hour(10)) +2016-07-17T12:00:00 +``` + +That may seem confusing, given that the hour (12) is not divisible by 10. The reason that `2016-07-17T12:00:00` +was chosen is that it is 17,676,660 hours after `0000-01-01T00:00:00`, and 17,676,660 is divisible +by 10. + +As Julia [`Date`](@ref) and [`DateTime`](@ref) values are represented according to the ISO 8601 +standard, `0000-01-01T00:00:00` was chosen as base (or "rounding epoch") from which to begin the +count of days (and milliseconds) used in rounding calculations. (Note that this differs slightly +from Julia's internal representation of [`Date`](@ref) s using Rata Die notation; but since the +ISO 8601 standard is most visible to the end user, `0000-01-01T00:00:00` was chosen as the rounding +epoch instead of the `0000-12-31T00:00:00` used internally to minimize confusion.) + +The only exception to the use of `0000-01-01T00:00:00` as the rounding epoch is when rounding +to weeks. Rounding to the nearest week will always return a Monday (the first day of the week +as specified by ISO 8601). For this reason, we use `0000-01-03T00:00:00` (the first day of the +first week of year 0000, as defined by ISO 8601) as the base when rounding to a number of weeks. + +Here is a related case in which the expected behaviour is not necessarily obvious: What happens +when we round to the nearest `P(2)`, where `P` is a [`Period`](@ref) type? In some cases (specifically, +when `P <: Dates.TimePeriod`) the answer is clear: + +```jldoctest +julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Hour(2)) +2016-07-17T08:00:00 + +julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Minute(2)) +2016-07-17T08:56:00 +``` + +This seems obvious, because two of each of these periods still divides evenly into the next larger +order period. But in the case of two months (which still divides evenly into one year), the answer +may be surprising: + +```jldoctest +julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Month(2)) +2016-07-01T00:00:00 +``` + +Why round to the first day in July, even though it is month 7 (an odd number)? The key is that +months are 1-indexed (the first month is assigned 1), unlike hours, minutes, seconds, and milliseconds +(the first of which are assigned 0). + +This means that rounding a [`DateTime`](@ref) to an even multiple of seconds, minutes, hours, +or years (because the ISO 8601 specification includes a year zero) will result in a [`DateTime`](@ref) +with an even value in that field, while rounding a [`DateTime`](@ref) to an even multiple of months +will result in the months field having an odd value. Because both months and years may contain +an irregular number of days, whether rounding to an even number of days will result in an even +value in the days field is uncertain. + +See the [API reference](@ref stdlib-dates-api) for additional information +on methods exported from the `Dates` module. + +# [API reference](@id stdlib-dates-api) + +## Dates and Time Types + +```@docs +Dates.Period +Dates.CompoundPeriod +Dates.Instant +Dates.UTInstant +Dates.TimeType +Dates.DateTime +Dates.Date +Dates.Time +Dates.TimeZone +Dates.UTC +``` + +## Dates Functions + +```@docs +Dates.DateTime(::Int64, ::Int64, ::Int64, ::Int64, ::Int64, ::Int64, ::Int64) +Dates.DateTime(::Dates.Period) +Dates.DateTime(::Function, ::Any...) +Dates.DateTime(::Dates.TimeType) +Dates.DateTime(::AbstractString, ::AbstractString) +Dates.format(::Dates.TimeType, ::AbstractString) +Dates.DateFormat +Dates.@dateformat_str +Dates.DateTime(::AbstractString, ::Dates.DateFormat) +Dates.Date(::Int64, ::Int64, ::Int64) +Dates.Date(::Dates.Period) +Dates.Date(::Function, ::Any, ::Any, ::Any) +Dates.Date(::Dates.TimeType) +Dates.Date(::AbstractString, ::AbstractString) +Dates.Date(::AbstractString, ::Dates.DateFormat) +Dates.Time(::Int64::Int64, ::Int64, ::Int64, ::Int64, ::Int64) +Dates.Time(::Dates.TimePeriod) +Dates.Time(::Function, ::Any...) +Dates.Time(::Dates.DateTime) +Dates.now() +Dates.now(::Type{Dates.UTC}) +Base.eps(::Union{Type{DateTime}, Type{Date}, Type{Time}, TimeType}) +``` + +### Accessor Functions + +```@docs +Dates.year +Dates.month +Dates.week +Dates.day +Dates.hour +Dates.minute +Dates.second +Dates.millisecond +Dates.microsecond +Dates.nanosecond +Dates.Year(::Dates.TimeType) +Dates.Month(::Dates.TimeType) +Dates.Week(::Dates.TimeType) +Dates.Day(::Dates.TimeType) +Dates.Hour(::DateTime) +Dates.Minute(::DateTime) +Dates.Second(::DateTime) +Dates.Millisecond(::DateTime) +Dates.Microsecond(::Dates.Time) +Dates.Nanosecond(::Dates.Time) +Dates.yearmonth +Dates.monthday +Dates.yearmonthday +``` + +### Query Functions + +```@docs +Dates.dayname +Dates.dayabbr +Dates.dayofweek +Dates.dayofmonth +Dates.dayofweekofmonth +Dates.daysofweekinmonth +Dates.monthname +Dates.monthabbr +Dates.daysinmonth +Dates.isleapyear +Dates.dayofyear +Dates.daysinyear +Dates.quarterofyear +Dates.dayofquarter +``` + +### Adjuster Functions + +```@docs +Base.trunc(::Dates.TimeType, ::Type{Dates.Period}) +Dates.firstdayofweek +Dates.lastdayofweek +Dates.firstdayofmonth +Dates.lastdayofmonth +Dates.firstdayofyear +Dates.lastdayofyear +Dates.firstdayofquarter +Dates.lastdayofquarter +Dates.tonext(::Dates.TimeType, ::Int) +Dates.toprev(::Dates.TimeType, ::Int) +Dates.tofirst +Dates.tolast +Dates.tonext(::Function, ::Dates.TimeType) +Dates.toprev(::Function, ::Dates.TimeType) +``` + +### Periods + +```@docs +Dates.Period(::Any) +Dates.CompoundPeriod(::Vector{<:Dates.Period}) +Dates.value +Dates.default +``` + +### Rounding Functions + +`Date` and `DateTime` values can be rounded to a specified resolution (e.g., 1 month or 15 minutes) +with `floor`, `ceil`, or `round`. + +```@docs +Base.floor(::Dates.TimeType, ::Dates.Period) +Base.ceil(::Dates.TimeType, ::Dates.Period) +Base.round(::Dates.TimeType, ::Dates.Period, ::RoundingMode{:NearestTiesUp}) +``` + +Most `Period` values can also be rounded to a specified resolution: + +```@docs +Base.floor(::Dates.ConvertiblePeriod, ::T) where T <: Dates.ConvertiblePeriod +Base.ceil(::Dates.ConvertiblePeriod, ::Dates.ConvertiblePeriod) +Base.round(::Dates.ConvertiblePeriod, ::Dates.ConvertiblePeriod, ::RoundingMode{:NearestTiesUp}) +``` + +The following functions are not exported: + +```@docs +Dates.floorceil +Dates.epochdays2date +Dates.epochms2datetime +Dates.date2epochdays +Dates.datetime2epochms +``` + +### Conversion Functions + +```@docs +Dates.today +Dates.unix2datetime +Dates.datetime2unix +Dates.julian2datetime +Dates.datetime2julian +Dates.rata2datetime +Dates.datetime2rata +``` + +### Constants + +Days of the Week: + +| Variable | Abbr. | Value (Int) | +|:----------- |:----- |:----------- | +| `Monday` | `Mon` | 1 | +| `Tuesday` | `Tue` | 2 | +| `Wednesday` | `Wed` | 3 | +| `Thursday` | `Thu` | 4 | +| `Friday` | `Fri` | 5 | +| `Saturday` | `Sat` | 6 | +| `Sunday` | `Sun` | 7 | + +Months of the Year: + +| Variable | Abbr. | Value (Int) | +|:----------- |:----- |:----------- | +| `January` | `Jan` | 1 | +| `February` | `Feb` | 2 | +| `March` | `Mar` | 3 | +| `April` | `Apr` | 4 | +| `May` | `May` | 5 | +| `June` | `Jun` | 6 | +| `July` | `Jul` | 7 | +| `August` | `Aug` | 8 | +| `September` | `Sep` | 9 | +| `October` | `Oct` | 10 | +| `November` | `Nov` | 11 | +| `December` | `Dec` | 12 | + +```@meta +DocTestSetup = nothing +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/DelimitedFiles/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/DelimitedFiles/docs/src/index.md new file mode 100644 index 0000000..11e24f1 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/DelimitedFiles/docs/src/index.md @@ -0,0 +1,11 @@ +# Delimited Files + +```@docs +DelimitedFiles.readdlm(::Any, ::AbstractChar, ::Type, ::AbstractChar) +DelimitedFiles.readdlm(::Any, ::AbstractChar, ::AbstractChar) +DelimitedFiles.readdlm(::Any, ::AbstractChar, ::Type) +DelimitedFiles.readdlm(::Any, ::AbstractChar) +DelimitedFiles.readdlm(::Any, ::Type) +DelimitedFiles.readdlm(::Any) +DelimitedFiles.writedlm +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Distributed/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Distributed/docs/src/index.md new file mode 100644 index 0000000..1b1675e --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Distributed/docs/src/index.md @@ -0,0 +1,69 @@ +# Distributed Computing + +```@docs +Distributed.addprocs +Distributed.nprocs +Distributed.nworkers +Distributed.procs() +Distributed.procs(::Integer) +Distributed.workers +Distributed.rmprocs +Distributed.interrupt +Distributed.myid +Distributed.pmap +Distributed.RemoteException +Distributed.Future +Distributed.RemoteChannel +Distributed.fetch(::Distributed.Future) +Distributed.fetch(::RemoteChannel) +Distributed.remotecall(::Any, ::Integer, ::Any...) +Distributed.remotecall_wait(::Any, ::Integer, ::Any...) +Distributed.remotecall_fetch(::Any, ::Integer, ::Any...) +Distributed.remote_do(::Any, ::Integer, ::Any...) +Distributed.put!(::RemoteChannel, ::Any...) +Distributed.put!(::Distributed.Future, ::Any) +Distributed.take!(::RemoteChannel, ::Any...) +Distributed.isready(::RemoteChannel, ::Any...) +Distributed.isready(::Distributed.Future) +Distributed.AbstractWorkerPool +Distributed.WorkerPool +Distributed.CachingPool +Distributed.default_worker_pool +Distributed.clear!(::CachingPool) +Distributed.remote +Distributed.remotecall(::Any, ::AbstractWorkerPool, ::Any...) +Distributed.remotecall_wait(::Any, ::AbstractWorkerPool, ::Any...) +Distributed.remotecall_fetch(::Any, ::AbstractWorkerPool, ::Any...) +Distributed.remote_do(::Any, ::AbstractWorkerPool, ::Any...) +Distributed.@spawnat +Distributed.@fetch +Distributed.@fetchfrom +Distributed.@distributed +Distributed.@everywhere +Distributed.clear!(::Any, ::Any; ::Any) +Distributed.remoteref_id +Distributed.channel_from_id +Distributed.worker_id_from_socket +Distributed.cluster_cookie() +Distributed.cluster_cookie(::Any) +``` + +## Cluster Manager Interface + +This interface provides a mechanism to launch and manage Julia workers on different cluster environments. +There are two types of managers present in Base: `LocalManager`, for launching additional workers on the +same host, and `SSHManager`, for launching on remote hosts via `ssh`. TCP/IP sockets are used to connect +and transport messages between processes. It is possible for Cluster Managers to provide a different transport. + +```@docs +Distributed.ClusterManager +Distributed.WorkerConfig +Distributed.launch +Distributed.manage +Distributed.kill(::ClusterManager, ::Int, ::WorkerConfig) +Distributed.connect(::ClusterManager, ::Int, ::WorkerConfig) +Distributed.init_worker +Distributed.start_worker +Distributed.process_messages +Distributed.default_addprocs_params +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Downloads/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Downloads/README.md new file mode 100644 index 0000000..132a564 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Downloads/README.md @@ -0,0 +1,186 @@ +# Downloads + +[](https://travis-ci.com/JuliaLang/Downloads.jl) +[](https://codecov.io/gh/JuliaLang/Downloads.jl) + +The `Downloads` package provides a single function, `download`, which provides +cross-platform, multi-protocol, in-process download functionality implemented +with [libcurl](https://curl.haxx.se/libcurl/). It uses libcurl's multi-handle +callback API to present a Julian API: `download(url)` blocks the task in which +it occurs but yields to Julia's scheduler, allowing arbitrarily many tasks to +download URLs concurrently and efficiently. As of Julia 1.6, this package is a +standard library that is included with Julia, but this package can be used with +Julia 1.3 through 1.5 as well. + +## API + +The public API of `Downloads` consists of two functions and three types: + +- `download` — download a file from a URL, erroring if it can't be downloaded +- `request` — request a URL, returning a `Response` object indicating success +- `Response` — a type capturing the status and other metadata about a request +- `RequestError` — an error type thrown by `download` and `request` on error +- `Downloader` — an object encapsulating shared resources for downloading + +### download + +```jl +download(url, [ output = tempfile() ]; + [ method = "GET", ] + [ headers = <none>, ] + [ timeout = <none>, ] + [ progress = <none>, ] + [ verbose = false, ] + [ downloader = <default>, ] +) -> output +``` +- `url :: AbstractString` +- `output :: Union{AbstractString, AbstractCmd, IO}` +- `method :: AbstractString` +- `headers :: Union{AbstractVector, AbstractDict}` +- `timeout :: Real` +- `progress :: (total::Integer, now::Integer) --> Any` +- `verbose :: Bool` +- `downloader :: Downloader` + +Download a file from the given url, saving it to `output` or if not specified, a +temporary path. The `output` can also be an `IO` handle, in which case the body +of the response is streamed to that handle and the handle is returned. If +`output` is a command, the command is run and output is sent to it on stdin. + +If the `downloader` keyword argument is provided, it must be a `Downloader` +object. Resources and connections will be shared between downloads performed by +the same `Downloader` and cleaned up automatically when the object is garbage +collected or there have been no downloads performed with it for a grace period. +See `Downloader` for more info about configuration and usage. + +If the `headers` keyword argument is provided, it must be a vector or dictionary +whose elements are all pairs of strings. These pairs are passed as headers when +downloading URLs with protocols that supports them, such as HTTP/S. + +The `timeout` keyword argument specifies a timeout for the download in seconds, +with a resolution of milliseconds. By default no timeout is set, but this can +also be explicitly requested by passing a timeout value of `Inf`. + +If the `progress` keyword argument is provided, it must be a callback funtion +which will be called whenever there are updates about the size and status of the +ongoing download. The callback must take two integer arguments: `total` and +`now` which are the total size of the download in bytes, and the number of bytes +which have been downloaded so far. Note that `total` starts out as zero and +remains zero until the server gives an indiation of the total size of the +download (e.g. with a `Content-Length` header), which may never happen. So a +well-behaved progress callback should handle a total size of zero gracefully. + +If the `verbose` optoin is set to true, `libcurl`, which is used to implement +the download functionality will print debugging information to `stderr`. + +### request + +```jl +request(url; + [ input = <none>, ] + [ output = <none>, ] + [ method = input ? "PUT" : output ? "GET" : "HEAD", ] + [ headers = <none>, ] + [ timeout = <none>, ] + [ progress = <none>, ] + [ verbose = false, ] + [ throw = true, ] + [ downloader = <default>, ] +) -> Union{Response, RequestError} +``` +- `url :: AbstractString` +- `input :: Union{AbstractString, AbstractCmd, IO}` +- `output :: Union{AbstractString, AbstractCmd, IO}` +- `method :: AbstractString` +- `headers :: Union{AbstractVector, AbstractDict}` +- `timeout :: Real` +- `progress :: (dl_total, dl_now, ul_total, ul_now) --> Any` +- `verbose :: Bool` +- `throw :: Bool` +- `downloader :: Downloader` + +Make a request to the given url, returning a `Response` object capturing the +status, headers and other information about the response. The body of the +reponse is written to `output` if specified and discarded otherwise. For HTTP/S +requests, if an `input` stream is given, a `PUT` request is made; otherwise if +an `output` stream is givven, a `GET` request is made; if neither is given a +`HEAD` request is made. For other protocols, appropriate default methods are +used based on what combination of input and output are requested. The following +options differ from the `download` function: + +- `input` allows providing a request body; if provided default to `PUT` request +- `progress` is a callback taking four integers for upload and download progress +- `throw` controls whether to throw or return a `RequestError` on request error + +Note that unlike `download` which throws an error if the requested URL could not +be downloaded (indicated by non-2xx status code), `request` returns a `Response` +object no matter what the status code of the response is. If there is an error +with getting a response at all, then a `RequestError` is thrown or returned. + +### Response + +```jl +struct Response + proto :: String + url :: String + status :: Int + message :: String + headers :: Vector{Pair{String,String}} +end +``` +`Response` is a type capturing the properties of a successful response to a +request as an object. It has the following fields: + +- `proto`: the protocol that was used to get the response +- `url`: the URL that was ultimately requested after following redirects +- `status`: the status code of the response, indicating success, failure, etc. +- `message`: a textual message describing the nature of the response +- `headers`: any headers that were returned with the response + +The meaning and availability of some of these responses depends on the protocol +used for the request. For many protocols, including HTTP/S and S/FTP, a 2xx +status code indicates a successful response. For responses in protocols that do +not support headers, the headers vector will be empty. HTTP/2 does not include a +status message, only a status code, so the message will be empty. + +### RequestError + +```jl +struct RequestError <: ErrorException + url :: String + code :: Int + message :: String + response :: Response +end +``` +`RequestError` is a type capturing the properties of a failed response to a +request as an exception object: + +- `url`: the original URL that was requested without any redirects +- `code`: the libcurl error code; `0` if a protocol-only error occurred +- `message`: the libcurl error message indicating what went wrong +- `response`: response object capturing what response info is available + +The same `RequestError` type is thrown by `download` if the request was +successful but there was a protocol-level error indicated by a status code that +is not in the 2xx range, in which case `code` will be zero and the `message` +field will be the empty string. The `request` API only throws a `RequestError` +if the libcurl error `code` is non-zero, in which case the included `response` +object is likely to have a `status` of zero and an empty message. There are, +however, situations where a curl-level error is thrown due to a protocol error, +in which case both the inner and outer code and message may be of interest. + +### Downloader + +```jl +Downloader(; [ grace::Real = 30 ]) +``` +`Downloader` objects are used to perform individual `download` operations. +Connections, name lookups and other resources are shared within a `Downloader`. +These connections and resources are cleaned up after a configurable grace period +(default: 30 seconds) since anything was downloaded with it, or when it is +garbage collected, whichever comes first. If the grace period is set to zero, +all resources will be cleaned up immediately as soon as there are no more +ongoing downloads in progress. If the grace period is set to `Inf` then +resources are not cleaned up until `Downloader` is garbage collected. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Downloads/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Downloads/docs/src/index.md new file mode 100644 index 0000000..23628fd --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Downloads/docs/src/index.md @@ -0,0 +1,9 @@ +# Downloads + +```@docs +Downloads.download +Downloads.request +Downloads.Response +Downloads.RequestError +Downloads.Downloader +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/FileWatching/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/FileWatching/docs/src/index.md new file mode 100644 index 0000000..3944f5d --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/FileWatching/docs/src/index.md @@ -0,0 +1,9 @@ +# [File Events](@id lib-filewatching) + +```@docs +FileWatching.poll_fd +FileWatching.poll_file +FileWatching.watch_file +FileWatching.watch_folder +FileWatching.unwatch_folder +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Future/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Future/docs/src/index.md new file mode 100644 index 0000000..dcb1a36 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Future/docs/src/index.md @@ -0,0 +1,9 @@ +# Future + +The `Future` module implements future behavior of already existing functions, +which will replace the current version in a future release of Julia. + +```@docs +Future.copy! +Future.randjump +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/InteractiveUtils/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/InteractiveUtils/docs/src/index.md new file mode 100644 index 0000000..a8a675e --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/InteractiveUtils/docs/src/index.md @@ -0,0 +1,28 @@ +# Interactive Utilities + +```@docs +InteractiveUtils.apropos +InteractiveUtils.varinfo +InteractiveUtils.versioninfo +InteractiveUtils.methodswith +InteractiveUtils.subtypes +InteractiveUtils.supertypes +InteractiveUtils.edit(::AbstractString, ::Integer) +InteractiveUtils.edit(::Any) +InteractiveUtils.@edit +InteractiveUtils.define_editor +InteractiveUtils.less(::AbstractString) +InteractiveUtils.less(::Any) +InteractiveUtils.@less +InteractiveUtils.@which +InteractiveUtils.@functionloc +InteractiveUtils.@code_lowered +InteractiveUtils.@code_typed +InteractiveUtils.code_warntype +InteractiveUtils.@code_warntype +InteractiveUtils.code_llvm +InteractiveUtils.@code_llvm +InteractiveUtils.code_native +InteractiveUtils.@code_native +InteractiveUtils.clipboard +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LazyArtifacts/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LazyArtifacts/docs/src/index.md new file mode 100644 index 0000000..9de6b21 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LazyArtifacts/docs/src/index.md @@ -0,0 +1,10 @@ +# Lazy Artifacts + +```@meta +DocTestSetup = :(using LazyArtifacts) +``` + +In order for a package to download artifacts lazily, `LazyArtifacts` must be +explicitly listed as a dependency of that package. + +For further information on artifacts, see [Artifacts](@ref). diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LibCURL/LICENSE.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LibCURL/LICENSE.md new file mode 100644 index 0000000..b6f1d7e --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LibCURL/LICENSE.md @@ -0,0 +1,23 @@ +LibCURL.jl is licensed under the MIT "Expat" License: + +> Copyright (c) 2013: JuliaWeb contributors +> +> Permission is hereby granted, free of charge, to any person obtaining +> a copy of this software and associated documentation files (the +> "Software"), to deal in the Software without restriction, including +> without limitation the rights to use, copy, modify, merge, publish, +> distribute, sublicense, and/or sell copies of the Software, and to +> permit persons to whom the Software is furnished to do so, subject to +> the following conditions: +> +> The above copyright notice and this permission notice shall be +> included in all copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +> LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +> OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +> WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LibCURL/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LibCURL/README.md new file mode 100644 index 0000000..14b256b --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LibCURL/README.md @@ -0,0 +1,72 @@ +LibCURL.jl +========== + +*Julia wrapper for libCURL* + +[](https://travis-ci.com/JuliaWeb/LibCURL.jl) +[](https://ci.appveyor.com/project/shashi/libcurl-jl) +[](http://codecov.io/github/JuliaWeb/LibCURL.jl?branch=master) + +--- +This is a simple Julia wrapper around http://curl.haxx.se/libcurl/ generated using [Clang.jl](https://github.com/ihnorton/Clang.jl). Please see the [libcurl API documentation](https://curl.haxx.se/libcurl/c/) for help on how to use this package. + +### Example (fetch a URL) + +```julia +using LibCURL + +# init a curl handle +curl = curl_easy_init() + +# set the URL and request to follow redirects +curl_easy_setopt(curl, CURLOPT_URL, "http://example.com") +curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1) + + +# setup the callback function to recv data +function curl_write_cb(curlbuf::Ptr{Cvoid}, s::Csize_t, n::Csize_t, p_ctxt::Ptr{Cvoid}) + sz = s * n + data = Array{UInt8}(undef, sz) + + ccall(:memcpy, Ptr{Cvoid}, (Ptr{Cvoid}, Ptr{Cvoid}, UInt64), data, curlbuf, sz) + println("recd: ", String(data)) + + sz::Csize_t +end + +c_curl_write_cb = @cfunction(curl_write_cb, Csize_t, (Ptr{Cvoid}, Csize_t, Csize_t, Ptr{Cvoid})) +curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, c_curl_write_cb) + + +# execute the query +res = curl_easy_perform(curl) +println("curl url exec response : ", res) + +# retrieve HTTP code +http_code = Array{Clong}(undef, 1) +curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, http_code) +println("httpcode : ", http_code) + +# release handle +curl_easy_cleanup(curl) + +``` + +### Binaries + +This package uses the [LibCURL_jll](https://github.com/JuliaBinaryWrappers/libCURL_jll.jl) binary package to install compiled libCURL binaries on all supported platforms. The following products are defined in the jll + +* `libcurl`: A `LibraryProduct` referencing the shared library +* `curl`: An `ExecutableProduct` referencing the binary + +This package also uses the [MozillaCACerts_jll](https://github.com/JuliaBinaryWrappers/MozillaCACerts_jll.jl) package to supply the Mozilla CA root certificate bundle. Note that the `cacert` symbol is re-exported from this package for ease of use. + +* `cacert`: A `FileProduct` referencing the Mozilla CA certificate bundle + +### SSL certificates + +Making SSL/TLS connections usually needs access to a CA certificate to validate peers. The Mozilla CA bundle can be used via this package. To use this certificate bundle, set the following option: + +```julia +curl_easy_setopt(curl, CURLOPT_CAINFO, LibCURL.cacert) +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LibGit2/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LibGit2/docs/src/index.md new file mode 100644 index 0000000..e53a933 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LibGit2/docs/src/index.md @@ -0,0 +1,161 @@ +# LibGit2 + +The LibGit2 module provides bindings to [libgit2](https://libgit2.org/), a portable C library that +implements core functionality for the [Git](https://git-scm.com/) version control system. +These bindings are currently used to power Julia's package manager. +It is expected that this module will eventually be moved into a separate package. + +### Functionality + +Some of this documentation assumes some prior knowledge of the libgit2 API. +For more information on some of the objects and methods referenced here, consult the upstream +[libgit2 API reference](https://libgit2.org/libgit2/#v0.25.1). + +```@docs +LibGit2.Buffer +LibGit2.CheckoutOptions +LibGit2.CloneOptions +LibGit2.DescribeOptions +LibGit2.DescribeFormatOptions +LibGit2.DiffDelta +LibGit2.DiffFile +LibGit2.DiffOptionsStruct +LibGit2.FetchHead +LibGit2.FetchOptions +LibGit2.GitAnnotated +LibGit2.GitBlame +LibGit2.GitBlob +LibGit2.GitCommit +LibGit2.GitHash +LibGit2.GitObject +LibGit2.GitRemote +LibGit2.GitRemoteAnon +LibGit2.GitRepo +LibGit2.GitRepoExt +LibGit2.GitRevWalker +LibGit2.GitShortHash +LibGit2.GitSignature +LibGit2.GitStatus +LibGit2.GitTag +LibGit2.GitTree +LibGit2.IndexEntry +LibGit2.IndexTime +LibGit2.BlameOptions +LibGit2.MergeOptions +LibGit2.ProxyOptions +LibGit2.PushOptions +LibGit2.RebaseOperation +LibGit2.RebaseOptions +LibGit2.RemoteCallbacks +LibGit2.SignatureStruct +LibGit2.StatusEntry +LibGit2.StatusOptions +LibGit2.StrArrayStruct +LibGit2.TimeStruct +LibGit2.add! +LibGit2.add_fetch! +LibGit2.add_push! +LibGit2.addblob! +LibGit2.author +LibGit2.authors +LibGit2.branch +LibGit2.branch! +LibGit2.checkout! +LibGit2.clone +LibGit2.commit +LibGit2.committer +LibGit2.count +LibGit2.counthunks +LibGit2.create_branch +LibGit2.credentials_callback +LibGit2.credentials_cb +LibGit2.default_signature +LibGit2.delete_branch +LibGit2.diff_files +LibGit2.entryid +LibGit2.entrytype +LibGit2.fetch +LibGit2.fetchheads +LibGit2.fetch_refspecs +LibGit2.fetchhead_foreach_cb +LibGit2.merge_base +LibGit2.merge!(::LibGit2.GitRepo; ::Any...) +LibGit2.merge!(::LibGit2.GitRepo, ::Vector{LibGit2.GitAnnotated}; ::LibGit2.MergeOptions, ::LibGit2.CheckoutOptions) +LibGit2.merge!(::LibGit2.GitRepo, ::Vector{LibGit2.GitAnnotated}, ::Bool; ::LibGit2.MergeOptions, ::LibGit2.CheckoutOptions) +LibGit2.ffmerge! +LibGit2.fullname +LibGit2.features +LibGit2.filename +LibGit2.filemode +LibGit2.gitdir +LibGit2.git_url +LibGit2.@githash_str +LibGit2.head +LibGit2.head! +LibGit2.head_oid +LibGit2.headname +LibGit2.init +LibGit2.is_ancestor_of +LibGit2.isbinary +LibGit2.iscommit +LibGit2.isdiff +LibGit2.isdirty +LibGit2.isorphan +LibGit2.isset +LibGit2.iszero +LibGit2.lookup_branch +LibGit2.map +LibGit2.mirror_callback +LibGit2.mirror_cb +LibGit2.message +LibGit2.merge_analysis +LibGit2.name +LibGit2.need_update +LibGit2.objtype +LibGit2.path +LibGit2.peel +LibGit2.posixpath +LibGit2.push +LibGit2.push!(::LibGit2.GitRevWalker, ::LibGit2.GitHash) +LibGit2.push_head! +LibGit2.push_refspecs +LibGit2.raw +LibGit2.read_tree! +LibGit2.rebase! +LibGit2.ref_list +LibGit2.reftype +LibGit2.remotes +LibGit2.remove! +LibGit2.reset +LibGit2.reset! +LibGit2.restore +LibGit2.revcount +LibGit2.set_remote_url +LibGit2.shortname +LibGit2.snapshot +LibGit2.split_cfg_entry +LibGit2.status +LibGit2.stage +LibGit2.tag_create +LibGit2.tag_delete +LibGit2.tag_list +LibGit2.target +LibGit2.toggle +LibGit2.transact +LibGit2.treewalk +LibGit2.upstream +LibGit2.update! +LibGit2.url +LibGit2.version +LibGit2.with +LibGit2.with_warn +LibGit2.workdir +LibGit2.GitObject(::LibGit2.GitTreeEntry) +LibGit2.UserPasswordCredential +LibGit2.SSHCredential +LibGit2.isfilled +LibGit2.CachedCredentials +LibGit2.CredentialPayload +LibGit2.approve +LibGit2.reject +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Libdl/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Libdl/docs/src/index.md new file mode 100644 index 0000000..62f9837 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Libdl/docs/src/index.md @@ -0,0 +1,15 @@ +# Dynamic Linker + +```@docs +Libdl.dlopen +Libdl.dlopen_e +Libdl.RTLD_NOW +Libdl.dlsym +Libdl.dlsym_e +Libdl.dlclose +Libdl.dlext +Libdl.dllist +Libdl.dlpath +Libdl.find_library +Libdl.DL_LOAD_PATH +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LinearAlgebra/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LinearAlgebra/docs/src/index.md new file mode 100644 index 0000000..52e7860 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/LinearAlgebra/docs/src/index.md @@ -0,0 +1,681 @@ +# [Linear Algebra](@id man-linalg) + +```@meta +DocTestSetup = :(using LinearAlgebra, SparseArrays, SuiteSparse) +``` + +In addition to (and as part of) its support for multi-dimensional arrays, Julia provides native implementations +of many common and useful linear algebra operations which can be loaded with `using LinearAlgebra`. Basic operations, such as [`tr`](@ref), [`det`](@ref), +and [`inv`](@ref) are all supported: + +```jldoctest +julia> A = [1 2 3; 4 1 6; 7 8 1] +3×3 Matrix{Int64}: + 1 2 3 + 4 1 6 + 7 8 1 + +julia> tr(A) +3 + +julia> det(A) +104.0 + +julia> inv(A) +3×3 Matrix{Float64}: + -0.451923 0.211538 0.0865385 + 0.365385 -0.192308 0.0576923 + 0.240385 0.0576923 -0.0673077 +``` + +As well as other useful operations, such as finding eigenvalues or eigenvectors: + +```jldoctest +julia> A = [-4. -17.; 2. 2.] +2×2 Matrix{Float64}: + -4.0 -17.0 + 2.0 2.0 + +julia> eigvals(A) +2-element Vector{ComplexF64}: + -1.0 - 5.0im + -1.0 + 5.0im + +julia> eigvecs(A) +2×2 Matrix{ComplexF64}: + 0.945905-0.0im 0.945905+0.0im + -0.166924+0.278207im -0.166924-0.278207im +``` + +In addition, Julia provides many [factorizations](@ref man-linalg-factorizations) which can be used to +speed up problems such as linear solve or matrix exponentiation by pre-factorizing a matrix into a form +more amenable (for performance or memory reasons) to the problem. See the documentation on [`factorize`](@ref) +for more information. As an example: + +```jldoctest +julia> A = [1.5 2 -4; 3 -1 -6; -10 2.3 4] +3×3 Matrix{Float64}: + 1.5 2.0 -4.0 + 3.0 -1.0 -6.0 + -10.0 2.3 4.0 + +julia> factorize(A) +LU{Float64, Matrix{Float64}} +L factor: +3×3 Matrix{Float64}: + 1.0 0.0 0.0 + -0.15 1.0 0.0 + -0.3 -0.132196 1.0 +U factor: +3×3 Matrix{Float64}: + -10.0 2.3 4.0 + 0.0 2.345 -3.4 + 0.0 0.0 -5.24947 +``` + +Since `A` is not Hermitian, symmetric, triangular, tridiagonal, or bidiagonal, an LU factorization may be the +best we can do. Compare with: + +```jldoctest +julia> B = [1.5 2 -4; 2 -1 -3; -4 -3 5] +3×3 Matrix{Float64}: + 1.5 2.0 -4.0 + 2.0 -1.0 -3.0 + -4.0 -3.0 5.0 + +julia> factorize(B) +BunchKaufman{Float64, Matrix{Float64}} +D factor: +3×3 Tridiagonal{Float64, Vector{Float64}}: + -1.64286 0.0 ⋅ + 0.0 -2.8 0.0 + ⋅ 0.0 5.0 +U factor: +3×3 UnitUpperTriangular{Float64, Matrix{Float64}}: + 1.0 0.142857 -0.8 + ⋅ 1.0 -0.6 + ⋅ ⋅ 1.0 +permutation: +3-element Vector{Int64}: + 1 + 2 + 3 +``` + +Here, Julia was able to detect that `B` is in fact symmetric, and used a more appropriate factorization. +Often it's possible to write more efficient code for a matrix that is known to have certain properties e.g. +it is symmetric, or tridiagonal. Julia provides some special types so that you can "tag" matrices as having +these properties. For instance: + +```jldoctest +julia> B = [1.5 2 -4; 2 -1 -3; -4 -3 5] +3×3 Matrix{Float64}: + 1.5 2.0 -4.0 + 2.0 -1.0 -3.0 + -4.0 -3.0 5.0 + +julia> sB = Symmetric(B) +3×3 Symmetric{Float64, Matrix{Float64}}: + 1.5 2.0 -4.0 + 2.0 -1.0 -3.0 + -4.0 -3.0 5.0 +``` + +`sB` has been tagged as a matrix that's (real) symmetric, so for later operations we might perform on it, +such as eigenfactorization or computing matrix-vector products, efficiencies can be found by only referencing +half of it. For example: + +```jldoctest +julia> B = [1.5 2 -4; 2 -1 -3; -4 -3 5] +3×3 Matrix{Float64}: + 1.5 2.0 -4.0 + 2.0 -1.0 -3.0 + -4.0 -3.0 5.0 + +julia> sB = Symmetric(B) +3×3 Symmetric{Float64, Matrix{Float64}}: + 1.5 2.0 -4.0 + 2.0 -1.0 -3.0 + -4.0 -3.0 5.0 + +julia> x = [1; 2; 3] +3-element Vector{Int64}: + 1 + 2 + 3 + +julia> sB\x +3-element Vector{Float64}: + -1.7391304347826084 + -1.1086956521739126 + -1.4565217391304346 +``` +The `\` operation here performs the linear solution. The left-division operator is pretty powerful and it's easy to write compact, readable code that is flexible enough to solve all sorts of systems of linear equations. + +## Special matrices + +[Matrices with special symmetries and structures](http://www2.imm.dtu.dk/pubdb/views/publication_details.php?id=3274) +arise often in linear algebra and are frequently associated with various matrix factorizations. +Julia features a rich collection of special matrix types, which allow for fast computation with +specialized routines that are specially developed for particular matrix types. + +The following tables summarize the types of special matrices that have been implemented in Julia, +as well as whether hooks to various optimized methods for them in LAPACK are available. + +| Type | Description | +|:----------------------------- |:--------------------------------------------------------------------------------------------- | +| [`Symmetric`](@ref) | [Symmetric matrix](https://en.wikipedia.org/wiki/Symmetric_matrix) | +| [`Hermitian`](@ref) | [Hermitian matrix](https://en.wikipedia.org/wiki/Hermitian_matrix) | +| [`UpperTriangular`](@ref) | Upper [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) | +| [`UnitUpperTriangular`](@ref) | Upper [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) with unit diagonal | +| [`LowerTriangular`](@ref) | Lower [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) | | +| [`UnitLowerTriangular`](@ref) | Lower [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) with unit diagonal | +| [`UpperHessenberg`](@ref) | Upper [Hessenberg matrix](https://en.wikipedia.org/wiki/Hessenberg_matrix) +| [`Tridiagonal`](@ref) | [Tridiagonal matrix](https://en.wikipedia.org/wiki/Tridiagonal_matrix) | +| [`SymTridiagonal`](@ref) | Symmetric tridiagonal matrix | +| [`Bidiagonal`](@ref) | Upper/lower [bidiagonal matrix](https://en.wikipedia.org/wiki/Bidiagonal_matrix) | +| [`Diagonal`](@ref) | [Diagonal matrix](https://en.wikipedia.org/wiki/Diagonal_matrix) | +| [`UniformScaling`](@ref) | [Uniform scaling operator](https://en.wikipedia.org/wiki/Uniform_scaling) | + +### Elementary operations + +| Matrix type | `+` | `-` | `*` | `\` | Other functions with optimized methods | +|:----------------------------- |:--- |:--- |:--- |:--- |:----------------------------------------------------------- | +| [`Symmetric`](@ref) | | | | MV | [`inv`](@ref), [`sqrt`](@ref), [`exp`](@ref) | +| [`Hermitian`](@ref) | | | | MV | [`inv`](@ref), [`sqrt`](@ref), [`exp`](@ref) | +| [`UpperTriangular`](@ref) | | | MV | MV | [`inv`](@ref), [`det`](@ref) | +| [`UnitUpperTriangular`](@ref) | | | MV | MV | [`inv`](@ref), [`det`](@ref) | +| [`LowerTriangular`](@ref) | | | MV | MV | [`inv`](@ref), [`det`](@ref) | +| [`UnitLowerTriangular`](@ref) | | | MV | MV | [`inv`](@ref), [`det`](@ref) | +| [`UpperHessenberg`](@ref) | | | | MM | [`inv`](@ref), [`det`](@ref) | +| [`SymTridiagonal`](@ref) | M | M | MS | MV | [`eigmax`](@ref), [`eigmin`](@ref) | +| [`Tridiagonal`](@ref) | M | M | MS | MV | | +| [`Bidiagonal`](@ref) | M | M | MS | MV | | +| [`Diagonal`](@ref) | M | M | MV | MV | [`inv`](@ref), [`det`](@ref), [`logdet`](@ref), [`/`](@ref) | +| [`UniformScaling`](@ref) | M | M | MVS | MVS | [`/`](@ref) | + +Legend: + +| Key | Description | +|:---------- |:------------------------------------------------------------- | +| M (matrix) | An optimized method for matrix-matrix operations is available | +| V (vector) | An optimized method for matrix-vector operations is available | +| S (scalar) | An optimized method for matrix-scalar operations is available | + +### Matrix factorizations + +| Matrix type | LAPACK | [`eigen`](@ref) | [`eigvals`](@ref) | [`eigvecs`](@ref) | [`svd`](@ref) | [`svdvals`](@ref) | +|:----------------------------- |:------ |:------------- |:----------------- |:----------------- |:------------- |:----------------- | +| [`Symmetric`](@ref) | SY | | ARI | | | | +| [`Hermitian`](@ref) | HE | | ARI | | | | +| [`UpperTriangular`](@ref) | TR | A | A | A | | | +| [`UnitUpperTriangular`](@ref) | TR | A | A | A | | | +| [`LowerTriangular`](@ref) | TR | A | A | A | | | +| [`UnitLowerTriangular`](@ref) | TR | A | A | A | | | +| [`SymTridiagonal`](@ref) | ST | A | ARI | AV | | | +| [`Tridiagonal`](@ref) | GT | | | | | | +| [`Bidiagonal`](@ref) | BD | | | | A | A | +| [`Diagonal`](@ref) | DI | | A | | | | + +Legend: + +| Key | Description | Example | +|:------------ |:------------------------------------------------------------------------------------------------------------------------------- |:-------------------- | +| A (all) | An optimized method to find all the characteristic values and/or vectors is available | e.g. `eigvals(M)` | +| R (range) | An optimized method to find the `il`th through the `ih`th characteristic values are available | `eigvals(M, il, ih)` | +| I (interval) | An optimized method to find the characteristic values in the interval [`vl`, `vh`] is available | `eigvals(M, vl, vh)` | +| V (vectors) | An optimized method to find the characteristic vectors corresponding to the characteristic values `x=[x1, x2,...]` is available | `eigvecs(M, x)` | + +### The uniform scaling operator + +A [`UniformScaling`](@ref) operator represents a scalar times the identity operator, `λ*I`. The identity +operator `I` is defined as a constant and is an instance of `UniformScaling`. The size of these +operators are generic and match the other matrix in the binary operations [`+`](@ref), [`-`](@ref), +[`*`](@ref) and [`\`](@ref). For `A+I` and `A-I` this means that `A` must be square. Multiplication +with the identity operator `I` is a noop (except for checking that the scaling factor is one) +and therefore almost without overhead. + +To see the `UniformScaling` operator in action: + +```jldoctest +julia> U = UniformScaling(2); + +julia> a = [1 2; 3 4] +2×2 Matrix{Int64}: + 1 2 + 3 4 + +julia> a + U +2×2 Matrix{Int64}: + 3 2 + 3 6 + +julia> a * U +2×2 Matrix{Int64}: + 2 4 + 6 8 + +julia> [a U] +2×4 Matrix{Int64}: + 1 2 2 0 + 3 4 0 2 + +julia> b = [1 2 3; 4 5 6] +2×3 Matrix{Int64}: + 1 2 3 + 4 5 6 + +julia> b - U +ERROR: DimensionMismatch("matrix is not square: dimensions are (2, 3)") +Stacktrace: +[...] +``` + +If you need to solve many systems of the form `(A+μI)x = b` for the same `A` and different `μ`, it might be beneficial +to first compute the Hessenberg factorization `F` of `A` via the [`hessenberg`](@ref) function. +Given `F`, Julia employs an efficient algorithm for `(F+μ*I) \ b` (equivalent to `(A+μ*I)x \ b`) and related +operations like determinants. + + +## [Matrix factorizations](@id man-linalg-factorizations) + +[Matrix factorizations (a.k.a. matrix decompositions)](https://en.wikipedia.org/wiki/Matrix_decomposition) +compute the factorization of a matrix into a product of matrices, and are one of the central concepts +in linear algebra. + +The following table summarizes the types of matrix factorizations that have been implemented in +Julia. Details of their associated methods can be found in the [Standard functions](@ref) section +of the Linear Algebra documentation. + +| Type | Description | +|:------------------ |:-------------------------------------------------------------------------------------------------------------- | +| `BunchKaufman` | Bunch-Kaufman factorization | +| `Cholesky` | [Cholesky factorization](https://en.wikipedia.org/wiki/Cholesky_decomposition) | +| `CholeskyPivoted` | [Pivoted](https://en.wikipedia.org/wiki/Pivot_element) Cholesky factorization | +| `LDLt` | [LDL(T) factorization](https://en.wikipedia.org/wiki/Cholesky_decomposition#LDL_decomposition) | +| `LU` | [LU factorization](https://en.wikipedia.org/wiki/LU_decomposition) | +| `QR` | [QR factorization](https://en.wikipedia.org/wiki/QR_decomposition) | +| `QRCompactWY` | Compact WY form of the QR factorization | +| `QRPivoted` | Pivoted [QR factorization](https://en.wikipedia.org/wiki/QR_decomposition) | +| `LQ` | [QR factorization](https://en.wikipedia.org/wiki/QR_decomposition) of `transpose(A)` | +| `Hessenberg` | [Hessenberg decomposition](http://mathworld.wolfram.com/HessenbergDecomposition.html) | +| `Eigen` | [Spectral decomposition](https://en.wikipedia.org/wiki/Eigendecomposition_of_a_matrix) | +| `GeneralizedEigen` | [Generalized spectral decomposition](https://en.wikipedia.org/wiki/Eigendecomposition_of_a_matrix#Generalized_eigenvalue_problem) | +| `SVD` | [Singular value decomposition](https://en.wikipedia.org/wiki/Singular_value_decomposition) | +| `GeneralizedSVD` | [Generalized SVD](https://en.wikipedia.org/wiki/Generalized_singular_value_decomposition#Higher_order_version) | +| `Schur` | [Schur decomposition](https://en.wikipedia.org/wiki/Schur_decomposition) | +| `GeneralizedSchur` | [Generalized Schur decomposition](https://en.wikipedia.org/wiki/Schur_decomposition#Generalized_Schur_decomposition) | + +## Standard functions + +Linear algebra functions in Julia are largely implemented by calling functions from [LAPACK](http://www.netlib.org/lapack/). Sparse matrix factorizations call functions from [SuiteSparse](http://suitesparse.com). Other sparse solvers are available as Julia packages. + +```@docs +Base.:*(::AbstractMatrix, ::AbstractMatrix) +Base.:\(::AbstractMatrix, ::AbstractVecOrMat) +LinearAlgebra.SingularException +LinearAlgebra.PosDefException +LinearAlgebra.ZeroPivotException +LinearAlgebra.dot +LinearAlgebra.dot(::Any, ::Any, ::Any) +LinearAlgebra.cross +LinearAlgebra.factorize +LinearAlgebra.Diagonal +LinearAlgebra.Bidiagonal +LinearAlgebra.SymTridiagonal +LinearAlgebra.Tridiagonal +LinearAlgebra.Symmetric +LinearAlgebra.Hermitian +LinearAlgebra.LowerTriangular +LinearAlgebra.UpperTriangular +LinearAlgebra.UnitLowerTriangular +LinearAlgebra.UnitUpperTriangular +LinearAlgebra.UpperHessenberg +LinearAlgebra.UniformScaling +LinearAlgebra.I +LinearAlgebra.UniformScaling(::Integer) +LinearAlgebra.Factorization +LinearAlgebra.LU +LinearAlgebra.lu +LinearAlgebra.lu! +LinearAlgebra.Cholesky +LinearAlgebra.CholeskyPivoted +LinearAlgebra.cholesky +LinearAlgebra.cholesky! +LinearAlgebra.lowrankupdate +LinearAlgebra.lowrankdowndate +LinearAlgebra.lowrankupdate! +LinearAlgebra.lowrankdowndate! +LinearAlgebra.LDLt +LinearAlgebra.ldlt +LinearAlgebra.ldlt! +LinearAlgebra.QR +LinearAlgebra.QRCompactWY +LinearAlgebra.QRPivoted +LinearAlgebra.qr +LinearAlgebra.qr! +LinearAlgebra.LQ +LinearAlgebra.lq +LinearAlgebra.lq! +LinearAlgebra.BunchKaufman +LinearAlgebra.bunchkaufman +LinearAlgebra.bunchkaufman! +LinearAlgebra.Eigen +LinearAlgebra.GeneralizedEigen +LinearAlgebra.eigvals +LinearAlgebra.eigvals! +LinearAlgebra.eigmax +LinearAlgebra.eigmin +LinearAlgebra.eigvecs +LinearAlgebra.eigen +LinearAlgebra.eigen! +LinearAlgebra.Hessenberg +LinearAlgebra.hessenberg +LinearAlgebra.hessenberg! +LinearAlgebra.Schur +LinearAlgebra.GeneralizedSchur +LinearAlgebra.schur +LinearAlgebra.schur! +LinearAlgebra.ordschur +LinearAlgebra.ordschur! +LinearAlgebra.SVD +LinearAlgebra.GeneralizedSVD +LinearAlgebra.svd +LinearAlgebra.svd! +LinearAlgebra.svdvals +LinearAlgebra.svdvals! +LinearAlgebra.Givens +LinearAlgebra.givens +LinearAlgebra.triu +LinearAlgebra.triu! +LinearAlgebra.tril +LinearAlgebra.tril! +LinearAlgebra.diagind +LinearAlgebra.diag +LinearAlgebra.diagm +LinearAlgebra.rank +LinearAlgebra.norm +LinearAlgebra.opnorm +LinearAlgebra.normalize! +LinearAlgebra.normalize +LinearAlgebra.cond +LinearAlgebra.condskeel +LinearAlgebra.tr +LinearAlgebra.det +LinearAlgebra.logdet +LinearAlgebra.logabsdet +Base.inv(::AbstractMatrix) +LinearAlgebra.pinv +LinearAlgebra.nullspace +Base.kron +Base.kron! +LinearAlgebra.exp(::StridedMatrix{<:LinearAlgebra.BlasFloat}) +Base.:^(::AbstractMatrix, ::Number) +Base.:^(::Number, ::AbstractMatrix) +LinearAlgebra.log(::StridedMatrix) +LinearAlgebra.sqrt(::StridedMatrix{<:Real}) +LinearAlgebra.cos(::StridedMatrix{<:Real}) +LinearAlgebra.sin(::StridedMatrix{<:Real}) +LinearAlgebra.sincos(::StridedMatrix{<:Real}) +LinearAlgebra.tan(::StridedMatrix{<:Real}) +LinearAlgebra.sec(::StridedMatrix) +LinearAlgebra.csc(::StridedMatrix) +LinearAlgebra.cot(::StridedMatrix) +LinearAlgebra.cosh(::StridedMatrix) +LinearAlgebra.sinh(::StridedMatrix) +LinearAlgebra.tanh(::StridedMatrix) +LinearAlgebra.sech(::StridedMatrix) +LinearAlgebra.csch(::StridedMatrix) +LinearAlgebra.coth(::StridedMatrix) +LinearAlgebra.acos(::StridedMatrix) +LinearAlgebra.asin(::StridedMatrix) +LinearAlgebra.atan(::StridedMatrix) +LinearAlgebra.asec(::StridedMatrix) +LinearAlgebra.acsc(::StridedMatrix) +LinearAlgebra.acot(::StridedMatrix) +LinearAlgebra.acosh(::StridedMatrix) +LinearAlgebra.asinh(::StridedMatrix) +LinearAlgebra.atanh(::StridedMatrix) +LinearAlgebra.asech(::StridedMatrix) +LinearAlgebra.acsch(::StridedMatrix) +LinearAlgebra.acoth(::StridedMatrix) +LinearAlgebra.lyap +LinearAlgebra.sylvester +LinearAlgebra.issuccess +LinearAlgebra.issymmetric +LinearAlgebra.isposdef +LinearAlgebra.isposdef! +LinearAlgebra.istril +LinearAlgebra.istriu +LinearAlgebra.isdiag +LinearAlgebra.ishermitian +Base.transpose +LinearAlgebra.transpose! +LinearAlgebra.Transpose +Base.adjoint +LinearAlgebra.adjoint! +LinearAlgebra.Adjoint +Base.copy(::Union{Transpose,Adjoint}) +LinearAlgebra.stride1 +LinearAlgebra.checksquare +LinearAlgebra.peakflops +``` + +## Low-level matrix operations + +In many cases there are in-place versions of matrix operations that allow you to supply +a pre-allocated output vector or matrix. This is useful when optimizing critical code in order +to avoid the overhead of repeated allocations. These in-place operations are suffixed with `!` +below (e.g. `mul!`) according to the usual Julia convention. + +```@docs +LinearAlgebra.mul! +LinearAlgebra.lmul! +LinearAlgebra.rmul! +LinearAlgebra.ldiv! +LinearAlgebra.rdiv! +``` + +## BLAS functions + +In Julia (as in much of scientific computation), dense linear-algebra operations are based on +the [LAPACK library](http://www.netlib.org/lapack/), which in turn is built on top of basic linear-algebra +building-blocks known as the [BLAS](http://www.netlib.org/blas/). There are highly optimized +implementations of BLAS available for every computer architecture, and sometimes in high-performance +linear algebra routines it is useful to call the BLAS functions directly. + +`LinearAlgebra.BLAS` provides wrappers for some of the BLAS functions. Those BLAS functions +that overwrite one of the input arrays have names ending in `'!'`. Usually, a BLAS function has +four methods defined, for [`Float64`](@ref), [`Float32`](@ref), `ComplexF64`, and `ComplexF32` arrays. + +### [BLAS character arguments](@id stdlib-blas-chars) +Many BLAS functions accept arguments that determine whether to transpose an argument (`trans`), +which triangle of a matrix to reference (`uplo` or `ul`), +whether the diagonal of a triangular matrix can be assumed to +be all ones (`dA`) or which side of a matrix multiplication +the input argument belongs on (`side`). The possibilities are: + +#### [Multiplication order](@id stdlib-blas-side) +| `side` | Meaning | +|:-------|:--------------------------------------------------------------------| +| `'L'` | The argument goes on the *left* side of a matrix-matrix operation. | +| `'R'` | The argument goes on the *right* side of a matrix-matrix operation. | + +#### [Triangle referencing](@id stdlib-blas-uplo) +| `uplo`/`ul` | Meaning | +|:------------|:------------------------------------------------------| +| `'U'` | Only the *upper* triangle of the matrix will be used. | +| `'L'` | Only the *lower* triangle of the matrix will be used. | + +#### [Transposition operation](@id stdlib-blas-trans) +| `trans`/`tX` | Meaning | +|:-------------|:--------------------------------------------------------| +| `'N'` | The input matrix `X` is not transposed or conjugated. | +| `'T'` | The input matrix `X` will be transposed. | +| `'C'` | The input matrix `X` will be conjugated and transposed. | + +#### [Unit diagonal](@id stdlib-blas-diag) +| `diag`/`dX` | Meaning | +|:------------|:----------------------------------------------------------| +| `'N'` | The diagonal values of the matrix `X` will be read. | +| `'U'` | The diagonal of the matrix `X` is assumed to be all ones. | + +```@docs +LinearAlgebra.BLAS +LinearAlgebra.BLAS.dot +LinearAlgebra.BLAS.dotu +LinearAlgebra.BLAS.dotc +LinearAlgebra.BLAS.blascopy! +LinearAlgebra.BLAS.nrm2 +LinearAlgebra.BLAS.asum +LinearAlgebra.axpy! +LinearAlgebra.axpby! +LinearAlgebra.BLAS.scal! +LinearAlgebra.BLAS.scal +LinearAlgebra.BLAS.iamax +LinearAlgebra.BLAS.ger! +LinearAlgebra.BLAS.syr! +LinearAlgebra.BLAS.syrk! +LinearAlgebra.BLAS.syrk +LinearAlgebra.BLAS.syr2k! +LinearAlgebra.BLAS.syr2k +LinearAlgebra.BLAS.her! +LinearAlgebra.BLAS.herk! +LinearAlgebra.BLAS.herk +LinearAlgebra.BLAS.her2k! +LinearAlgebra.BLAS.her2k +LinearAlgebra.BLAS.gbmv! +LinearAlgebra.BLAS.gbmv +LinearAlgebra.BLAS.sbmv! +LinearAlgebra.BLAS.sbmv(::Any, ::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.sbmv(::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.gemm! +LinearAlgebra.BLAS.gemm(::Any, ::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.gemm(::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.gemv! +LinearAlgebra.BLAS.gemv(::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.gemv(::Any, ::Any, ::Any) +LinearAlgebra.BLAS.symm! +LinearAlgebra.BLAS.symm(::Any, ::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.symm(::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.symv! +LinearAlgebra.BLAS.symv(::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.symv(::Any, ::Any, ::Any) +LinearAlgebra.BLAS.hemm! +LinearAlgebra.BLAS.hemm(::Any, ::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.hemm(::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.hemv! +LinearAlgebra.BLAS.hemv(::Any, ::Any, ::Any, ::Any) +LinearAlgebra.BLAS.hemv(::Any, ::Any, ::Any) +LinearAlgebra.BLAS.trmm! +LinearAlgebra.BLAS.trmm +LinearAlgebra.BLAS.trsm! +LinearAlgebra.BLAS.trsm +LinearAlgebra.BLAS.trmv! +LinearAlgebra.BLAS.trmv +LinearAlgebra.BLAS.trsv! +LinearAlgebra.BLAS.trsv +LinearAlgebra.BLAS.set_num_threads +``` + +## LAPACK functions + +`LinearAlgebra.LAPACK` provides wrappers for some of the LAPACK functions for linear algebra. + Those functions that overwrite one of the input arrays have names ending in `'!'`. + +Usually a function has 4 methods defined, one each for [`Float64`](@ref), [`Float32`](@ref), +`ComplexF64` and `ComplexF32` arrays. + +Note that the LAPACK API provided by Julia can and will change in the future. Since this API is +not user-facing, there is no commitment to support/deprecate this specific set of functions in +future releases. + +```@docs +LinearAlgebra.LAPACK +LinearAlgebra.LAPACK.gbtrf! +LinearAlgebra.LAPACK.gbtrs! +LinearAlgebra.LAPACK.gebal! +LinearAlgebra.LAPACK.gebak! +LinearAlgebra.LAPACK.gebrd! +LinearAlgebra.LAPACK.gelqf! +LinearAlgebra.LAPACK.geqlf! +LinearAlgebra.LAPACK.geqrf! +LinearAlgebra.LAPACK.geqp3! +LinearAlgebra.LAPACK.gerqf! +LinearAlgebra.LAPACK.geqrt! +LinearAlgebra.LAPACK.geqrt3! +LinearAlgebra.LAPACK.getrf! +LinearAlgebra.LAPACK.tzrzf! +LinearAlgebra.LAPACK.ormrz! +LinearAlgebra.LAPACK.gels! +LinearAlgebra.LAPACK.gesv! +LinearAlgebra.LAPACK.getrs! +LinearAlgebra.LAPACK.getri! +LinearAlgebra.LAPACK.gesvx! +LinearAlgebra.LAPACK.gelsd! +LinearAlgebra.LAPACK.gelsy! +LinearAlgebra.LAPACK.gglse! +LinearAlgebra.LAPACK.geev! +LinearAlgebra.LAPACK.gesdd! +LinearAlgebra.LAPACK.gesvd! +LinearAlgebra.LAPACK.ggsvd! +LinearAlgebra.LAPACK.ggsvd3! +LinearAlgebra.LAPACK.geevx! +LinearAlgebra.LAPACK.ggev! +LinearAlgebra.LAPACK.gtsv! +LinearAlgebra.LAPACK.gttrf! +LinearAlgebra.LAPACK.gttrs! +LinearAlgebra.LAPACK.orglq! +LinearAlgebra.LAPACK.orgqr! +LinearAlgebra.LAPACK.orgql! +LinearAlgebra.LAPACK.orgrq! +LinearAlgebra.LAPACK.ormlq! +LinearAlgebra.LAPACK.ormqr! +LinearAlgebra.LAPACK.ormql! +LinearAlgebra.LAPACK.ormrq! +LinearAlgebra.LAPACK.gemqrt! +LinearAlgebra.LAPACK.posv! +LinearAlgebra.LAPACK.potrf! +LinearAlgebra.LAPACK.potri! +LinearAlgebra.LAPACK.potrs! +LinearAlgebra.LAPACK.pstrf! +LinearAlgebra.LAPACK.ptsv! +LinearAlgebra.LAPACK.pttrf! +LinearAlgebra.LAPACK.pttrs! +LinearAlgebra.LAPACK.trtri! +LinearAlgebra.LAPACK.trtrs! +LinearAlgebra.LAPACK.trcon! +LinearAlgebra.LAPACK.trevc! +LinearAlgebra.LAPACK.trrfs! +LinearAlgebra.LAPACK.stev! +LinearAlgebra.LAPACK.stebz! +LinearAlgebra.LAPACK.stegr! +LinearAlgebra.LAPACK.stein! +LinearAlgebra.LAPACK.syconv! +LinearAlgebra.LAPACK.sysv! +LinearAlgebra.LAPACK.sytrf! +LinearAlgebra.LAPACK.sytri! +LinearAlgebra.LAPACK.sytrs! +LinearAlgebra.LAPACK.hesv! +LinearAlgebra.LAPACK.hetrf! +LinearAlgebra.LAPACK.hetri! +LinearAlgebra.LAPACK.hetrs! +LinearAlgebra.LAPACK.syev! +LinearAlgebra.LAPACK.syevr! +LinearAlgebra.LAPACK.sygvd! +LinearAlgebra.LAPACK.bdsqr! +LinearAlgebra.LAPACK.bdsdc! +LinearAlgebra.LAPACK.gecon! +LinearAlgebra.LAPACK.gehrd! +LinearAlgebra.LAPACK.orghr! +LinearAlgebra.LAPACK.gees! +LinearAlgebra.LAPACK.gges! +LinearAlgebra.LAPACK.trexc! +LinearAlgebra.LAPACK.trsen! +LinearAlgebra.LAPACK.tgsen! +LinearAlgebra.LAPACK.trsyl! +``` + +```@meta +DocTestSetup = nothing +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Logging/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Logging/docs/src/index.md new file mode 100644 index 0000000..e1d6022 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Logging/docs/src/index.md @@ -0,0 +1,311 @@ +# Logging + +The [`Logging`](@ref Logging.Logging) module provides a way to record the history and progress of a +computation as a log of events. Events are created by inserting a logging +statement into the source code, for example: + +```julia +@warn "Abandon printf debugging, all ye who enter here!" +┌ Warning: Abandon printf debugging, all ye who enter here! +└ @ Main REPL[1]:1 +``` + +The system provides several advantages over peppering your source code with +calls to `println()`. First, it allows you to control the visibility and +presentation of messages without editing the source code. For example, in +contrast to the `@warn` above + +```julia +@debug "The sum of some values $(sum(rand(100)))" +``` + +will produce no output by default. Furthermore, it's very cheap to leave debug +statements like this in the source code because the system avoids evaluating +the message if it would later be ignored. In this case `sum(rand(100))` and +the associated string processing will never be executed unless debug logging is +enabled. + +Second, the logging tools allow you to attach arbitrary data to each event as a +set of key--value pairs. This allows you to capture local variables and other +program state for later analysis. For example, to attach the local array +variable `A` and the sum of a vector `v` as the key `s` you can use + +```jldoctest +A = ones(Int, 4, 4) +v = ones(100) +@info "Some variables" A s=sum(v) + +# output +┌ Info: Some variables +│ A = +│ 4×4 Matrix{Int64}: +│ 1 1 1 1 +│ 1 1 1 1 +│ 1 1 1 1 +│ 1 1 1 1 +└ s = 100.0 +``` + +All of the logging macros `@debug`, `@info`, `@warn` and `@error` share common +features that are described in detail in the documentation for the more +general macro [`@logmsg`](@ref). + +## Log event structure + +Each event generates several pieces of data, some provided by the user and some +automatically extracted. Let's examine the user-defined data first: + +* The *log level* is a broad category for the message that is used for early + filtering. There are several standard levels of type [`LogLevel`](@ref); + user-defined levels are also possible. + Each is distinct in purpose: + - `Debug` is information intended for the developer of the program. + These events are disabled by default. + - `Info` is for general information to the user. + Think of it as an alternative to using `println` directly. + - `Warn` means something is wrong and action is likely required + but that for now the program is still working. + - `Error` means something is wrong and it is unlikely to be recovered, + at least by this part of the code. + Often this log-level is unneeded as throwing an exception can convey + all the required information. + +* The *message* is an object describing the event. By convention + `AbstractString`s passed as messages are assumed to be in markdown format. + Other types will be displayed using `print(io, obj)` or `string(obj)` for + text-based output and possibly `show(io,mime,obj)` for other multimedia + displays used in the installed logger. +* Optional *key--value pairs* allow arbitrary data to be attached to each event. + Some keys have conventional meaning that can affect the way an event is + interpreted (see [`@logmsg`](@ref)). + +The system also generates some standard information for each event: + +* The `module` in which the logging macro was expanded. +* The `file` and `line` where the logging macro occurs in the source code. +* A message `id` that is a unique, fixed identifier for the *source code + statement* where the logging macro appears. This identifier is designed to be + fairly stable even if the source code of the file changes, as long as the + logging statement itself remains the same. +* A `group` for the event, which is set to the base name of the file by default, + without extension. This can be used to group messages into categories more + finely than the log level (for example, all deprecation warnings have group + `:depwarn`), or into logical groupings across or within modules. + +Notice that some useful information such as the event time is not included by +default. This is because such information can be expensive to extract and is +also *dynamically* available to the current logger. It's simple to define a +[custom logger](@ref AbstractLogger-interface) to augment event data with the +time, backtrace, values of global variables and other useful information as +required. + + +## Processing log events + +As you can see in the examples, logging statements make no mention of +where log events go or how they are processed. This is a key design feature +that makes the system composable and natural for concurrent use. It does this +by separating two different concerns: + +* *Creating* log events is the concern of the module author who needs to + decide where events are triggered and which information to include. +* *Processing* of log events — that is, display, filtering, aggregation and + recording — is the concern of the application author who needs to bring + multiple modules together into a cooperating application. + +### Loggers + +Processing of events is performed by a *logger*, which is the first piece of +user configurable code to see the event. All loggers must be subtypes of +[`AbstractLogger`](@ref). + +When an event is triggered, the appropriate logger is found by looking for a +task-local logger with the global logger as fallback. The idea here is that +the application code knows how log events should be processed and exists +somewhere at the top of the call stack. So we should look up through the call +stack to discover the logger — that is, the logger should be *dynamically +scoped*. (This is a point of contrast with logging frameworks where the +logger is *lexically scoped*; provided explicitly by the module author or as a +simple global variable. In such a system it's awkward to control logging while +composing functionality from multiple modules.) + +The global logger may be set with [`global_logger`](@ref), and task-local +loggers controlled using [`with_logger`](@ref). Newly spawned tasks inherit +the logger of the parent task. + +There are three logger types provided by the library. [`ConsoleLogger`](@ref) +is the default logger you see when starting the REPL. It displays events in a +readable text format and tries to give simple but user friendly control over +formatting and filtering. [`NullLogger`](@ref) is a convenient way to drop all +messages where necessary; it is the logging equivalent of the [`devnull`](@ref) +stream. [`SimpleLogger`](@ref) is a very simplistic text formatting logger, +mainly useful for debugging the logging system itself. + +Custom loggers should come with overloads for the functions described in the +[reference section](@ref AbstractLogger-interface). + +### Early filtering and message handling + +When an event occurs, a few steps of early filtering occur to avoid generating +messages that will be discarded: + +1. The message log level is checked against a global minimum level (set via + [`disable_logging`](@ref)). This is a crude but extremely cheap global + setting. +2. The current logger state is looked up and the message level checked against the + logger's cached minimum level, as found by calling [`Logging.min_enabled_level`](@ref). + This behavior can be overridden via environment variables (more on this later). +3. The [`Logging.shouldlog`](@ref) function is called with the current logger, taking + some minimal information (level, module, group, id) which can be computed + statically. Most usefully, `shouldlog` is passed an event `id` which can be + used to discard events early based on a cached predicate. + +If all these checks pass, the message and key--value pairs are evaluated in full +and passed to the current logger via the [`Logging.handle_message`](@ref) function. +`handle_message()` may perform additional filtering as required and display the +event to the screen, save it to a file, etc. + +Exceptions that occur while generating the log event are captured and logged +by default. This prevents individual broken events from crashing the +application, which is helpful when enabling little-used debug events in a +production system. This behavior can be customized per logger type by +extending [`Logging.catch_exceptions`](@ref). + +## Testing log events + +Log events are a side effect of running normal code, but you might find +yourself wanting to test particular informational messages and warnings. The +`Test` module provides a [`@test_logs`](@ref) macro that can be used to +pattern match against the log event stream. + +## Environment variables + +Message filtering can be influenced through the `JULIA_DEBUG` environment +variable, and serves as an easy way to enable debug logging for a file or +module. For example, loading julia with `JULIA_DEBUG=loading` will activate +`@debug` log messages in `loading.jl`: + +``` +$ JULIA_DEBUG=loading julia -e 'using OhMyREPL' +┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji due to it containing an invalid cache header +└ @ Base loading.jl:1328 +[ Info: Recompiling stale cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji for module OhMyREPL +┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/Tokenize.ji due to it containing an invalid cache header +└ @ Base loading.jl:1328 +... +``` + +Similarly, the environment variable can be used to enable debug logging of +modules, such as `Pkg`, or module roots (see [`Base.moduleroot`](@ref)). To +enable all debug logging, use the special value `all`. + +To turn debug logging on from the REPL, set `ENV["JULIA_DEBUG"]` to the +name of the module of interest. Functions defined in the REPL belong to +module `Main`; logging for them can be enabled like this: +```julia-repl +julia> foo() = @debug "foo" +foo (generic function with 1 method) + +julia> foo() + +julia> ENV["JULIA_DEBUG"] = Main +Main + +julia> foo() +┌ Debug: foo +└ @ Main REPL[1]:1 + +``` + +## Writing log events to a file + +Sometimes it can be useful to write log events to a file. Here is an example +of how to use a task-local and global logger to write information to a text +file: + +```julia-repl +# Load the logging module +julia> using Logging + +# Open a textfile for writing +julia> io = open("log.txt", "w+") +IOStream(<file log.txt>) + +# Create a simple logger +julia> logger = SimpleLogger(io) +SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}()) + +# Log a task-specific message +julia> with_logger(logger) do + @info("a context specific log message") + end + +# Write all buffered messages to the file +julia> flush(io) + +# Set the global logger to logger +julia> global_logger(logger) +SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}()) + +# This message will now also be written to the file +julia> @info("a global log message") + +# Close the file +julia> close(io) +``` + + +## Reference + +### Logging module +```@docs +Logging.Logging +``` + +### Creating events + +```@docs +Logging.@logmsg +Logging.LogLevel +``` + +### [Processing events with AbstractLogger](@id AbstractLogger-interface) + +Event processing is controlled by overriding functions associated with +`AbstractLogger`: + +| Methods to implement | | Brief description | +|:----------------------------------- |:---------------------- |:---------------------------------------- | +| [`Logging.handle_message`](@ref) | | Handle a log event | +| [`Logging.shouldlog`](@ref) | | Early filtering of events | +| [`Logging.min_enabled_level`](@ref) | | Lower bound for log level of accepted events | +| **Optional methods** | **Default definition** | **Brief description** | +| [`Logging.catch_exceptions`](@ref) | `true` | Catch exceptions during event evaluation | + + +```@docs +Logging.AbstractLogger +Logging.handle_message +Logging.shouldlog +Logging.min_enabled_level +Logging.catch_exceptions +Logging.disable_logging +``` + +### Using Loggers + +Logger installation and inspection: + +```@docs +Logging.global_logger +Logging.with_logger +Logging.current_logger +``` + +Loggers that are supplied with the system: + +```@docs +Logging.NullLogger +Logging.ConsoleLogger +Logging.SimpleLogger +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Markdown/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Markdown/docs/src/index.md new file mode 100644 index 0000000..a107929 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Markdown/docs/src/index.md @@ -0,0 +1,398 @@ +# [Markdown](@id markdown_stdlib) + +This section describes Julia's markdown syntax, which is enabled by the +Markdown standard library. The following Markdown elements are supported: + +## Inline elements + +Here "inline" refers to elements that can be found within blocks of text, i.e. paragraphs. These +include the following elements. + +### Bold + +Surround words with two asterisks, `**`, to display the enclosed text in boldface. + +``` +A paragraph containing a **bold** word. +``` + +### Italics + +Surround words with one asterisk, `*`, to display the enclosed text in italics. + +``` +A paragraph containing an *italicized* word. +``` + +### Literals + +Surround text that should be displayed exactly as written with single backticks, ``` ` ``` . + +``` +A paragraph containing a `literal` word. +``` + +Literals should be used when writing text that refers to names of variables, functions, or other +parts of a Julia program. + +!!! tip + To include a backtick character within literal text use three backticks rather than one to enclose + the text. + + ``` + A paragraph containing ``` `backtick` characters ```. + ``` + + By extension any odd number of backticks may be used to enclose a lesser number of backticks. + +### ``\LaTeX`` + +Surround text that should be displayed as mathematics using ``\LaTeX`` syntax with double backticks, +``` `` ``` . + +``` +A paragraph containing some ``\LaTeX`` markup. +``` + +!!! tip + As with literals in the previous section, if literal backticks need to be written within double + backticks use an even number greater than two. Note that if a single literal backtick needs to + be included within ``\LaTeX`` markup then two enclosing backticks is sufficient. + +!!! note + The `\` character should be escaped appropriately if the text is embedded in a Julia source code, + for example, ``` "``\\LaTeX`` syntax in a docstring." ```, since it is interpreted as a string + literal. Alternatively, in order to avoid escaping, it is possible to use the `raw` string macro + together with the `@doc` macro: + ``` + @doc raw"``\LaTeX`` syntax in a docstring." functionname + ``` + +### Links + +Links to either external or internal targets can be written using the following syntax, where +the text enclosed in square brackets, `[ ]`, is the name of the link and the text enclosed in +parentheses, `( )`, is the URL. + +``` +A paragraph containing a link to [Julia](http://www.julialang.org). +``` + +It's also possible to add cross-references to other documented functions/methods/variables within +the Julia documentation itself. For example: + +```julia +""" + tryparse(type, str; base) + +Like [`parse`](@ref), but returns either a value of the requested type, +or [`nothing`](@ref) if the string does not contain a valid number. +""" +``` + +This will create a link in the generated docs to the [`parse`](@ref) documentation +(which has more information about what this function actually does), and to the +[`nothing`](@ref) documentation. It's good to include cross references to mutating/non-mutating +versions of a function, or to highlight a difference between two similar-seeming functions. + +!!! note + The above cross referencing is *not* a Markdown feature, and relies on + [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl), which is + used to build base Julia's documentation. + +### Footnote references + +Named and numbered footnote references can be written using the following syntax. A footnote name +must be a single alphanumeric word containing no punctuation. + +``` +A paragraph containing a numbered footnote [^1] and a named one [^named]. +``` + +!!! note + The text associated with a footnote can be written anywhere within the same page as the footnote + reference. The syntax used to define the footnote text is discussed in the [Footnotes](@ref) section + below. + +## Toplevel elements + +The following elements can be written either at the "toplevel" of a document or within another +"toplevel" element. + +### Paragraphs + +A paragraph is a block of plain text, possibly containing any number of inline elements defined +in the [Inline elements](@ref) section above, with one or more blank lines above and below it. + +``` +This is a paragraph. + +And this is *another* paragraph containing some emphasized text. +A new line, but still part of the same paragraph. +``` + +### Headers + +A document can be split up into different sections using headers. Headers use the following syntax: + +```julia +# Level One +## Level Two +### Level Three +#### Level Four +##### Level Five +###### Level Six +``` + +A header line can contain any inline syntax in the same way as a paragraph can. + +!!! tip + Try to avoid using too many levels of header within a single document. A heavily nested document + may be indicative of a need to restructure it or split it into several pages covering separate + topics. + +### Code blocks + +Source code can be displayed as a literal block using an indent of four spaces as shown in the +following example. + +``` +This is a paragraph. + + function func(x) + # ... + end + +Another paragraph. +``` + +Additionally, code blocks can be enclosed using triple backticks with an optional "language" to +specify how a block of code should be highlighted. + +```` +A code block without a "language": + +``` +function func(x) + # ... +end +``` + +and another one with the "language" specified as `julia`: + +```julia +function func(x) + # ... +end +``` +```` + +!!! note + "Fenced" code blocks, as shown in the last example, should be preferred over indented code blocks + since there is no way to specify what language an indented code block is written in. + +### Block quotes + +Text from external sources, such as quotations from books or websites, can be quoted using `>` +characters prepended to each line of the quote as follows. + +``` +Here's a quote: + +> Julia is a high-level, high-performance dynamic programming language for +> technical computing, with syntax that is familiar to users of other +> technical computing environments. +``` + +Note that a single space must appear after the `>` character on each line. Quoted blocks may themselves +contain other toplevel or inline elements. + +### Images + +The syntax for images is similar to the link syntax mentioned above. Prepending a `!` character +to a link will display an image from the specified URL rather than a link to it. + +```julia + +``` + +### Lists + +Unordered lists can be written by prepending each item in a list with either `*`, `+`, or `-`. + +``` +A list of items: + + * item one + * item two + * item three +``` + +Note the two spaces before each `*` and the single space after each one. + +Lists can contain other nested toplevel elements such as lists, code blocks, or quoteblocks. A +blank line should be left between each list item when including any toplevel elements within a +list. + +``` +Another list: + + * item one + + * item two + + ``` + f(x) = x + ``` + + * And a sublist: + + + sub-item one + + sub-item two +``` + +!!! note + The contents of each item in the list must line up with the first line of the item. In the above + example the fenced code block must be indented by four spaces to align with the `i` in `item two`. + +Ordered lists are written by replacing the "bullet" character, either `*`, `+`, or `-`, with a +positive integer followed by either `.` or `)`. + +``` +Two ordered lists: + + 1. item one + 2. item two + 3. item three + + 5) item five + 6) item six + 7) item seven +``` + +An ordered list may start from a number other than one, as in the second list of the above example, +where it is numbered from five. As with unordered lists, ordered lists can contain nested toplevel +elements. + +### Display equations + +Large ``\LaTeX`` equations that do not fit inline within a paragraph may be written as display +equations using a fenced code block with the "language" `math` as in the example below. + +````julia +```math +f(a) = \frac{1}{2\pi}\int_{0}^{2\pi} (\alpha+R\cos(\theta))d\theta +``` +```` + +### Footnotes + +This syntax is paired with the inline syntax for [Footnote references](@ref). Make sure to read +that section as well. + +Footnote text is defined using the following syntax, which is similar to footnote reference syntax, +aside from the `:` character that is appended to the footnote label. + +``` +[^1]: Numbered footnote text. + +[^note]: + + Named footnote text containing several toplevel elements. + + * item one + * item two + * item three + + ```julia + function func(x) + # ... + end + ``` +``` + +!!! note + No checks are done during parsing to make sure that all footnote references have matching footnotes. + +### Horizontal rules + +The equivalent of an `<hr>` HTML tag can be achieved using three hyphens (`---`). +For example: + +``` +Text above the line. + +--- + +And text below the line. +``` + +### Tables + +Basic tables can be written using the syntax described below. Note that markdown tables have limited +features and cannot contain nested toplevel elements unlike other elements discussed above – +only inline elements are allowed. Tables must always contain a header row with column names. Cells +cannot span multiple rows or columns of the table. + +``` +| Column One | Column Two | Column Three | +|:---------- | ---------- |:------------:| +| Row `1` | Column `2` | | +| *Row* 2 | **Row** 2 | Column ``3`` | +``` + +!!! note + As illustrated in the above example each column of `|` characters must be aligned vertically. + + A `:` character on either end of a column's header separator (the row containing `-` characters) + specifies whether the row is left-aligned, right-aligned, or (when `:` appears on both ends) center-aligned. + Providing no `:` characters will default to right-aligning the column. + +### Admonitions + +Specially formatted blocks, known as admonitions, can be used to highlight particular remarks. +They can be defined using the following `!!!` syntax: + +``` +!!! note + + This is the content of the note. + +!!! warning "Beware!" + + And this is another one. + + This warning admonition has a custom title: `"Beware!"`. +``` + +The first word after `!!!` declares the type of the admonition. +There are standard admonition types that should produce special styling. +Namely (in order of decreasing severity): `danger`, `warning`, `info`/`note`, and `tip`. + +You can also use your own admonition types, as long as the type name only contains lowercase Latin characters (a-z). +For example, you could have a `terminology` block like this: + +``` +!!! terminology "julia vs Julia" + + Strictly speaking, "Julia" refers to the language, + and "julia" to the standard implementation. +``` + +However, unless the code rendering the Markdown special-cases that particular admonition type, it will get the default styling. + +A custom title for the box can be provided as a string (in double quotes) after the admonition type. +If no title text is specified after the admonition type, then the type name will be used as the title (e.g. `"Note"` for the `note` admonition). + +Admonitions, like most other toplevel elements, can contain other toplevel elements (e.g. lists, images). + +## Markdown Syntax Extensions + +Julia's markdown supports interpolation in a very similar way to basic string literals, with the +difference that it will store the object itself in the Markdown tree (as opposed to converting +it to a string). When the Markdown content is rendered the usual `show` methods will be called, +and these can be overridden as usual. This design allows the Markdown to be extended with arbitrarily +complex features (such as references) without cluttering the basic syntax. + +In principle, the Markdown parser itself can also be arbitrarily extended by packages, or an entirely +custom flavour of Markdown can be used, but this should generally be unnecessary. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Mmap/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Mmap/docs/src/index.md new file mode 100644 index 0000000..ada88b1 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Mmap/docs/src/index.md @@ -0,0 +1,7 @@ +# Memory-mapped I/O + +```@docs +Mmap.Anonymous +Mmap.mmap +Mmap.sync! +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/NetworkOptions/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/NetworkOptions/README.md new file mode 100644 index 0000000..f8df24d --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/NetworkOptions/README.md @@ -0,0 +1,270 @@ +# NetworkOptions + +[](https://travis-ci.org/JuliaLang/NetworkOptions.jl) +[](https://codecov.io/gh/JuliaLang/NetworkOptions.jl) + +The `NetworkOptions` package acts as a mediator between ways of configuring +network transport mechanisms (SSL/TLS, SSH, proxies, etc.) and Julia packages +that provide access to transport mechanisms. This allows the a common interface +to configuring things like TLS and SSH host verification and proxies via +environment variables (currently) and other configuration mechanisms (in the +future), while packages that need to configure these mechanisms can simply +ask `NetworkOptions` what to do in specific situations without worrying about +how that configuration is expressed. + +## API + +### ca_roots + +```jl +ca_roots() :: Union{Nothing, String} +``` +The `ca_roots()` function tells the caller where, if anywhere, to find a file or +directory of PEM-encoded certificate authority roots. By default, on systems +like Windows and macOS where the built-in TLS engines know how to verify hosts +using the system's built-in certificate verification mechanism, this function +will return `nothing`. On classic UNIX systems (excluding macOS), root +certificates are typically stored in a file in `/etc`: the common places for the +current UNIX system will be searched and if one of these paths exists, it will +be returned; if none of these typical root certificate paths exist, then the +path to the set of root certificates that are bundled with Julia is returned. + +The default value returned by `ca_roots()` may be overridden by setting the +`JULIA_SSL_CA_ROOTS_PATH`, `SSL_CERT_DIR`, or `SSL_CERT_FILE` environment +variables, in which case this function will always return the value of the first +of these variables that is set (whether the path exists or not). If +`JULIA_SSL_CA_ROOTS_PATH` is set to the empty string, then the other variables +are ignored (as if unset); if the other variables are set to the empty string, +they behave is if they are not set. + +### ca_roots_path + +```jl +ca_roots_path() :: String +``` +The `ca_roots_path()` function is similar to the `ca_roots()` function except +that it always returns a path to a file or directory of PEM-encoded certificate +authority roots. When called on a system like Windows or macOS, where system +root certificates are not stored in the file system, it will currently return +the path to the set of root certificates that are bundled with Julia. (In the +future, this function may instead extract the root certificates from the system +and save them to a file whose path would be returned.) + +If it is possible to configure a library that uses TLS to use the system +certificates that is generally preferrable: i.e. it is better to use +`ca_roots()` which returns `nothing` to indicate that the system certs should be +used. The `ca_roots_path()` function should only be used when configuring +libraries which _require_ a path to a file or directory for root certificates. + +The default value returned by `ca_roots_path()` may be overridden by setting the +`JULIA_SSL_CA_ROOTS_PATH`, `SSL_CERT_DIR`, or `SSL_CERT_FILE` environment +variables, in which case this function will always return the value of the first +of these variables that is set (whether the path exists or not). If +`JULIA_SSL_CA_ROOTS_PATH` is set to the empty string, then the other variables +are ignored (as if unset); if the other variables are set to the empty string, +they behave is if they are not set. + +### ssh_dir + +```jl +ssh_dir() :: String +``` +The `ssh_dir()` function returns the location of the directory where the `ssh` +program keeps/looks for configuration files. By default this is `~/.ssh` but +this can be overridden by setting the envirnoment variable `SSH_DIR`. + +### ssh_key_name + +```jl +ssh_key_name() :: String +``` +The `ssh_key_name()` function returns the base name of key files that SSH should +use for when estabilishing a connection. There is usually no reason that this +function should be called directly and libraries should generally use the +`ssh_key_path` and `ssh_pub_key_path` functions to get full paths. If the +environment variable `SSH_KEY_NAME` is set then this function returns that; +otherwise it returns `id_rsa` by default. + +### ssh_key_path + +```jl +ssh_key_path() :: String +``` +The `ssh_key_path()` function returns the path of the SSH private key file that +should be used for SSH connections. If the `SSH_KEY_PATH` environment variable +is set then it will return that value. Otherwise it defaults to returning +```jl +joinpath(ssh_dir(), ssh_key_name()) +``` +This default value in turn depends on the `SSH_DIR` and `SSH_KEY_NAME` +environment variables. + +### ssh_pub_key_path + +```jl +ssh_pub_key_path() :: String +``` +The `ssh_pub_key_path()` function returns the path of the SSH public key file +that should be used for SSH connections. If the `SSH_PUB_KEY_PATH` environment +variable is set then it will return that value. If that isn't set but +`SSH_KEY_PATH` is set, it will return that path with the `.pub` suffix appended. +If neither is set, it defaults to returning +```jl +joinpath(ssh_dir(), ssh_key_name() * ".pub") +``` +This default value in turn depends on the `SSH_DIR` and `SSH_KEY_NAME` +environment variables. + +### ssh_key_pass + +```jl +ssh_key_pass() :: String +``` +The `ssh_key_pass()` function returns the value of the environment variable +`SSH_KEY_PASS` if it is set or `nothing` if it is not set. In the future, this +may be able to find a password by other means, such as secure system storage, so +packages that need a pawword to decrypt an SSH private key should use this API +instead of directly checking the environment variable so that they gain such +capabilities automatically when they are added. + +### ssh_known_hosts_files + +```jl +ssh_known_hosts_files() :: Vector{String} +``` +The `ssh_known_hosts_files()` function returns a vector of paths of SSH known +hosts files that should be used when establishing the identities of remote +servers for SSH connections. By default this function returns +```jl +[joinpath(ssh_dir(), "known_hosts"), bundled_known_hosts] +``` +where `bundled_known_hosts` is the path of a copy of a known hosts file that is +bundled with this package (containing known hosts keys for `github.com` and +`gitlab.com`). If the environment variable `SSH_KNOWN_HOSTS_FILES` is set, +however, then its value is split into paths on the `:` character (or on `;` on +Windows) and this vector of paths is returned instead. If any component of this +vector is empty, it is expanded to the default known hosts paths. + +Packages that use `ssh_known_hosts_files()` should ideally look for matching +entries by comparing the host name and key types, considering the first entry in +any of the files which matches to be the definitive identity of the host. If the +caller cannot compare the key type (e.g. because it has been hashes) then it +must approximate the above algorithm by looking for all matching entries for a +host in each file: if a file has any entries for a host then one of them must +match; the caller should only continue to search further known hosts files if +there are no entries for the host in question in an earlier file. + +### ssh_known_hosts_file + +```jl +ssh_known_hosts_file() :: String +``` +The `ssh_known_hosts_file()` function returns a single path of an SSH known +hosts file that should be used when establishing the identities of remote +servers for SSH connections. It returns the first path returned by +`ssh_known_hosts_files` that actually exists. Callers who can look in more than +one known hosts file should use `ssh_known_hosts_files` instead and look for +host matches in all the files returned as described in that function's docs. + +### verify_host + +```jl +verify_host(url::AbstractString, [transport::AbstractString]) :: Bool +``` +The `verify_host` function tells the caller whether the identity of a host +should be verified when communicating over secure transports like TLS or SSH. +The `url` argument may be: + +1. a proper URL staring with `proto://` +2. an `ssh`-style bare host name or host name prefixed with `user@` +3. an `scp`-style host as above, followed by `:` and a path location + +In each case the host name part is parsed out and the decision about whether to +verify or not is made based solely on the host name, not anything else about the +input URL. In particular, the protocol of the URL does not matter (more below). + +The `transport` argument indicates the kind of transport that the query is +about. The currently known values are `SSL` (alias `TLS`) and `SSH`. If the +transport is ommitted, the query will return `true` only if the host name should +not be verified regardless of transport. + +The host name is matched against the host patterns in the relavent environment +variables depending on whether `transport` is supplied and what its value is: + +- `JULIA_NO_VERIFY_HOSTS` — hosts that should not be verified for any transport +- `JULIA_SSL_NO_VERIFY_HOSTS` — hosts that should not be verified for SSL/TLS +- `JULIA_SSH_NO_VERIFY_HOSTS` — hosts that should not be verified for SSH +- `JULIA_ALWAYS_VERIFY_HOSTS` — hosts that should always be verified + +The values of each of these variables is a comma-separated list of host name +patterns with the following syntax — each pattern is split on `.` into parts and +each part must one of: + +1. A literal domain name component consisting of one or more ASCII letter, + digit, hyphen or underscore (technically not part of a legal host name, but + sometimes used). A literal domain name component matches only itself. +2. A `**`, which matches zero or more domain name components. +3. A `*`, which match any one domain name component. + +When matching a host name against a pattern list in one of these variables, the +host name is split on `.` into components and that sequence of words is matched +against the pattern: a literal pattern matches exactly one host name component +with that value; a `*` pattern matches exactly one host name component with any +value; a `**` pattern matches any number of host name components. For example: + +- `**` matches any host name +- `**.org` matches any host name in the `.org` top-level domain +- `example.com` matches only the exact host name `example.com` +- `*.example.com` matches `api.example.com` but not `example.com` or + `v1.api.example.com` +- `**.example.com` matches any domain under `example.com`, including + `example.com` itself, `api.example.com` and `v1.api.example.com` + +#### Example scenarios + +Suppose you want to not verify any hosts under `safe.example.com` for all +protocols, skip SSL host verification for just `ssl.example.com`, and skip SSH +host verification for `ssh.example.com` and its immediate first level +subdomains. Then you could set the following environment variable values: +```sh +export JULIA_NO_VERIFY_HOSTS="**.safe.example.com" +export JULIA_SSL_NO_VERIFY_HOSTS="ssl.example.com" +export JULIA_SSH_NO_VERIFY_HOSTS="ssh.example.com,*.ssh.example.com" +``` +With this configuration: + +- `example.com` would be verified for all protocols +- `safe.example.com`, `api.safe.example.com`, `v1.api.safe.example.com` and so + on would be unverified for all transports +- `ssl.example.com` would be unverified for SSL/TLS transport +- `sub.ssl.example.com` would be verified for all transports, including SSL/TLS +- `ssh.example.com` and `sub.ssh.example.com` would be unverified for SSH only +- `sub.sub.ssh.example.com` would be verified for all transports + +Note that the protocol of `url` need not match the transport mechanism being +queried: the protocol of the URL is entirely discarded. The reason for this is +that the typical usage of this utility function is to configure a library to +enable or disable specific features like TLS host verification based on a URL. +If the URL does not actually use the TLS transport mechanism, then it doesn't +matter if verification for that transport is enabled or not. Moreover, different +protocols can use the same transport: for example, `https` and `ftps` protocols +both use TLS and `ssh`, `scp` and `sftp` protocols all use SSH. + +A common scenario that occur behind firewalls is for all connections to external +systems to go through a transparent man-in-the-middle proxy: any SSL/TLS +connection to a host under `example.com` would be internal and should have a +valid certificate but any connection outside of `example.com` would go through +the proxy, which uses a self-signed certificate. For such a scenario the best +solution would be to deploy a CA root certificate to all clients, but if that's +not possible, then configuring clients to verify hosts under `example.com` but +not verify other SSL/TLS connections would be a viable solution. In fact, as +long as the man-in-the-middle proxy verifies all upstream TLS connections, this +is still secure (although not private from the proxy, of course). Such a +configuration can be accomplished with the following exports: +```sh +export JULIA_ALWAYS_VERIFY_HOSTS="**.example.com" +export JULIA_SSL_NO_VERIFY_HOSTS="**" +``` +This configuration causes all domains under `example.com` to always be verified +for all protocols, including SSL/TLS, while skiping host verifiction for SSL/TLS +connections to all other hosts. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/LICENSE.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/LICENSE.md new file mode 100644 index 0000000..eb29596 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/LICENSE.md @@ -0,0 +1,47 @@ +The Pkg.jl package is licensed under the MIT "Expat" License: + +> Copyright (c) 2017: Stefan Karpinski. +> +> Permission is hereby granted, free of charge, to any person obtaining a copy +> of this software and associated documentation files (the "Software"), to deal +> in the Software without restriction, including without limitation the rights +> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +> copies of the Software, and to permit persons to whom the Software is +> furnished to do so, subject to the following conditions: +> +> The above copyright notice and this permission notice shall be included in all +> copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +> SOFTWARE. +> + +The file PlatformEngines.jl is under the following license: + +The BinaryProvider.jl package is licensed under the MIT "Expat" License: + +> Copyright (c) 2017: SimonDanisch. +> +> Permission is hereby granted, free of charge, to any person obtaining a copy +> of this software and associated documentation files (the "Software"), to deal +> in the Software without restriction, including without limitation the rights +> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +> copies of the Software, and to permit persons to whom the Software is +> furnished to do so, subject to the following conditions: +> +> The above copyright notice and this permission notice shall be included in all +> copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +> SOFTWARE. +> diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/README.md new file mode 100644 index 0000000..3389eeb --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/README.md @@ -0,0 +1,34 @@ +# Pkg + +| **Documentation** | **Build Status** | +|:-----------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------:| +| [![][docs-v1-img]][docs-v1-url] [![][docs-dev-img]][docs-dev-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] | + +Development repository for Julia's package manager, +shipped with Julia v1.0 and above. + +#### Using the development version of Pkg.jl + +If you want to develop this package do the following steps: +- Clone the repo anywhere. +- In line 2 of the `Project.toml` file (the line that begins with `uuid = ...`), modify the UUID, e.g. change the `44c` to `54c`. +- Change the current directory to the Pkg repo you just cloned and start julia with `julia --project`. +- `import Pkg` will now load the files in the cloned repo instead of the Pkg stdlib . +- To test your changes, simply do `include("test/runtests.jl")`. + +If you need to build Julia from source with a git checkout of Pkg, then instead use `make DEPS_GIT=Pkg` when building Julia. The `Pkg` repo is in `stdlib/Pkg`, and created initially with a detached `HEAD`. If you're doing this from a pre-existing Julia repository, you may need to `make clean` beforehand. + +[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg +[docs-dev-url]: https://julialang.github.io/Pkg.jl/dev/ + +[docs-v1-img]: https://img.shields.io/badge/docs-v1-blue.svg +[docs-v1-url]: https://julialang.github.io/Pkg.jl/v1/ + +[travis-img]: https://travis-ci.com/JuliaLang/Pkg.jl.svg?branch=master +[travis-url]: https://travis-ci.com/JuliaLang/Pkg.jl + +[appveyor-img]: https://ci.appveyor.com/api/projects/status/cgno2xgwapugpg4t/branch/master?svg=true +[appveyor-url]: https://ci.appveyor.com/project/JuliaLang/pkg-jl/branch/master + +[codecov-img]: https://codecov.io/gh/JuliaLang/Pkg.jl/branch/master/graph/badge.svg +[codecov-url]: https://codecov.io/gh/JuliaLang/Pkg.jl diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/api.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/api.md new file mode 100644 index 0000000..29a54c4 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/api.md @@ -0,0 +1,88 @@ +# [**12.** API Reference](@id API-Reference) + +This section describes the function interface, or "API mode", +for interacting with Pkg.jl. The function API is recommended +for non-interactive usage, for example in scripts. + +## General API Reference + +Certain options are generally useful and can be specified in any API call. +You can specify these options by setting keyword arguments. + +### Redirecting output + +Use the `io::IOBuffer` keyword argument to redirect Pkg output. +For example, `Pkg.add("Example"; io=devnull)` will discard any output produced by the `add` call. + +## Package API Reference + +In the REPL mode, packages (with associated version, UUID, URL etc) are parsed from strings, +for example `"Package#master"`,`"Package@v0.1"`, `"www.mypkg.com/MyPkg#my/feature"`. + +In the API mode, it is possible to use strings as arguments for simple commands (like `Pkg.add(["PackageA", "PackageB"])`, +but more complicated commands, which e.g. specify URLs or version range, require the use of a more structured format over strings. +This is done by creating an instance of [`PackageSpec`](@ref) which is passed in to functions. + +```@docs +PackageSpec +PackageMode +UpgradeLevel +Pkg.add +Pkg.develop +Pkg.activate +Pkg.rm +Pkg.update +Pkg.test +Pkg.build +Pkg.pin +Pkg.free +Pkg.instantiate +Pkg.resolve +Pkg.gc +Pkg.status +Pkg.precompile +Pkg.offline +Pkg.setprotocol! +Pkg.dependencies +Pkg.project +Pkg.undo +Pkg.redo +``` + + +## Registry API Reference + +!!! compat "Julia 1.1" + Pkg's registry handling requires at least Julia 1.1. + +The function API for registries uses [`RegistrySpec`](@ref)s, similar to +[`PackageSpec`](@ref). + +```@docs +RegistrySpec +Pkg.Registry.add +Pkg.Registry.rm +Pkg.Registry.update +Pkg.Registry.status +``` + +## [Artifacts API Reference](@id Artifacts-Reference) + +!!! compat "Julia 1.3" + Pkg's artifacts API requires at least Julia 1.3. + +```@docs +Pkg.Artifacts.create_artifact +Pkg.Artifacts.remove_artifact +Pkg.Artifacts.verify_artifact +Pkg.Artifacts.artifact_meta +Pkg.Artifacts.artifact_hash +Pkg.Artifacts.bind_artifact! +Pkg.Artifacts.unbind_artifact! +Pkg.Artifacts.download_artifact +Pkg.Artifacts.find_artifacts_toml +Pkg.Artifacts.ensure_artifact_installed +Pkg.Artifacts.ensure_all_artifacts_installed +Pkg.Artifacts.@artifact_str +Pkg.Artifacts.archive_artifact +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/artifacts.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/artifacts.md new file mode 100644 index 0000000..7b1ade6 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/artifacts.md @@ -0,0 +1,229 @@ +# [**8.** Artifacts](@id Artifacts) + +!!! compat "Julia 1.3" + Pkg's artifacts functionality requires at least Julia 1.3. + +`Pkg` can install and manage containers of data that are not Julia packages. These containers can contain platform-specific binaries, datasets, text, or any other kind of data that would be convenient to place within an immutable, life-cycled datastore. +These containers, (called "Artifacts") can be created locally, hosted anywhere, and automatically downloaded and unpacked upon installation of your Julia package. +This mechanism is also used to provide the binary dependencies for packages built with [`BinaryBuilder.jl`](https://github.com/JuliaPackaging/BinaryBuilder.jl). + +## Basic Usage + +`Pkg` artifacts are declared in an `Artifacts.toml` file, which can be placed in your current directory or in the root of your package. +Currently, `Pkg` supports downloading of tarfiles (which can be compressed) from a URL. +Following is a minimal `Artifacts.toml` file which will permit the downloading of a `socrates.tar.gz` file from `github.com`. +In this example, a single artifact, given the name `socrates`, is defined. + +```TOML +# a simple Artifacts.toml file +[socrates] +git-tree-sha1 = "43563e7631a7eafae1f9f8d9d332e3de44ad7239" + + [[socrates.download]] + url = "https://github.com/staticfloat/small_bin/raw/master/socrates.tar.gz" + sha256 = "e65d2f13f2085f2c279830e863292312a72930fee5ba3c792b14c33ce5c5cc58" +``` + +If this `Artifacts.toml` file is placed in your current directory, then `socrates.tar.gz` can be downloaded, unpacked and used with `artifact"socrates"`. +Since this tarball contains a folder `bin`, and a text file named `socrates` within that folder, we could access the content of that file as follows. + +```julia +using Pkg.Artifacts + +rootpath = artifact"socrates" +open(joinpath(rootpath, "bin", "socrates")) do file + println(read(file, String)) +end +``` + +If you have an existing tarball that is accessible via a `url`, it could also be be accessed in this manner. +To create the `Artifacts.toml` you must compute two hashes: the `sha256` hash of the download file, and the `git-tree-sha1` of the unpacked content. +These can be computed as follows. + +```julia +using Tar, Inflate, SHA + +filename = "socrates.tar.gz" +println("sha256: ", bytes2hex(open(sha256, filename))) +println("git-tree-sha1: ", Tar.tree_hash(IOBuffer(inflate_gzip(filename)))) +``` + +To access this artifact from within a package you create, place the `Artifacts.toml` at the root of your package, adjacent to `Project.toml`. Then, make sure to add `Pkg` in your `deps` and set `julia = "1.3"` or higher in your `compat` section. + +## `Artifacts.toml` files + +`Pkg` provides an API for working with artifacts, as well as a TOML file format for recording artifact usage in your packages, and to automate downloading of artifacts at package install time. +Artifacts can always be referred to by content hash, but are typically accessed by a name that is bound to a content hash in an `Artifacts.toml` file that lives in a project's source tree. + +!!! note + It is possible to use the alternate name `JuliaArtifacts.toml`, similar + to how it is possible to use `JuliaProject.toml` and `JuliaManifest.toml` + instead of `Project.toml` and `Manifest.toml`, respectively. + +An example `Artifacts.toml` file is shown here: + +```TOML +# Example Artifacts.toml file +[socrates] +git-tree-sha1 = "43563e7631a7eafae1f9f8d9d332e3de44ad7239" +lazy = true + + [[socrates.download]] + url = "https://github.com/staticfloat/small_bin/raw/master/socrates.tar.gz" + sha256 = "e65d2f13f2085f2c279830e863292312a72930fee5ba3c792b14c33ce5c5cc58" + + [[socrates.download]] + url = "https://github.com/staticfloat/small_bin/raw/master/socrates.tar.bz2" + sha256 = "13fc17b97be41763b02cbb80e9d048302cec3bd3d446c2ed6e8210bddcd3ac76" + +[[c_simple]] +arch = "x86_64" +git-tree-sha1 = "4bdf4556050cb55b67b211d4e78009aaec378cbc" +libc = "musl" +os = "linux" + + [[c_simple.download]] + sha256 = "411d6befd49942826ea1e59041bddf7dbb72fb871bb03165bf4e164b13ab5130" + url = "https://github.com/JuliaBinaryWrappers/c_simple_jll.jl/releases/download/c_simple+v1.2.3+0/c_simple.v1.2.3.x86_64-linux-musl.tar.gz" + +[[c_simple]] +arch = "x86_64" +git-tree-sha1 = "51264dbc770cd38aeb15f93536c29dc38c727e4c" +os = "macos" + + [[c_simple.download]] + sha256 = "6c17d9e1dc95ba86ec7462637824afe7a25b8509cc51453f0eb86eda03ed4dc3" + url = "https://github.com/JuliaBinaryWrappers/c_simple_jll.jl/releases/download/c_simple+v1.2.3+0/c_simple.v1.2.3.x86_64-apple-darwin14.tar.gz" + +[processed_output] +git-tree-sha1 = "1c223e66f1a8e0fae1f9fcb9d3f2e3ce48a82200" +``` + +This `Artifacts.toml` binds three artifacts; one named `socrates`, one named `c_simple` and one named `processed_output`. +The single required piece of information for an artifact is its `git-tree-sha1`. +Because artifacts are addressed only by their content hash, the purpose of an `Artifacts.toml` file is to provide metadata about these artifacts, such as binding a human-readable name to a content hash, providing information about where an artifact may be downloaded from, or even binding a single name to multiple hashes, keyed by platform-specific constraints such as operating system or libgfortran version. + +## Artifact types and properties + +In the above example, the `socrates` artifact showcases a platform-independent artifact with multiple download locations. +When downloading and installing the `socrates` artifact, URLs will be attempted in-order until one succeeds. +The `socrates` artifact is marked as `lazy`, which means that it will not be automatically downloaded when the containing package is installed, but rather will be downloaded on-demand when the package first attempts to use it. + +The `c_simple` artifact showcases a platform-dependent artifact, where each entry in the `c_simple` array contains keys that help the calling package choose the appropriate download based on the particulars of the host machine. +Note that each artifact contains both a `git-tree-sha1` and a `sha256` for each download entry. This is to ensure that the downloaded tarball is secure before attempting to unpack it, as well as enforcing that all tarballs must expand to the same overall tree hash. + +The `processed_output` artifact contains no `download` stanza, and so cannot be installed. +An artifact such as this would be the result of code that was previously run, generating a new artifact and binding the resultant hash to a name within this project. + +## Using Artifacts + +Artifacts can be manipulated using convenient APIs exposed from the `Pkg.Artifacts` namespace. +As a motivating example, let us imagine that we are writing a package that needs to load the [Iris machine learning dataset](https://archive.ics.uci.edu/ml/datasets/iris). +While we could just download the dataset during a build step into the package directory, and many packages currently do precisely this, that has some significant drawbacks: + +* First, it modifies the package directory, making package installation stateful, which we want to avoid. + In the future, we would like to reach the point where packages can be installed completely read-only, instead of being able to modify themselves after installation. + +* Second, the downloaded data is not shared across different versions of our package. + If we have three different versions of the package installed for use by various projects, then we need three different copies of the data, even if it hasn't changed between those versions. + Moreover, each time we upgrade or downgrade the package, unless we do something clever (and probably brittle), we have to download the data again. + +With artifacts, we will instead check to see if our `iris` artifact already exists on-disk and only if it doesn't will we download and install it, after which we can bind the result into our `Artifacts.toml` file: + +```julia +using Pkg.Artifacts + +# This is the path to the Artifacts.toml we will manipulate +artifact_toml = joinpath(@__DIR__, "Artifacts.toml") + +# Query the `Artifacts.toml` file for the hash bound to the name "iris" +# (returns `nothing` if no such binding exists) +iris_hash = artifact_hash("iris", artifact_toml) + +# If the name was not bound, or the hash it was bound to does not exist, create it! +if iris_hash == nothing || !artifact_exists(iris_hash) + # create_artifact() returns the content-hash of the artifact directory once we're finished creating it + iris_hash = create_artifact() do artifact_dir + # We create the artifact by simply downloading a few files into the new artifact directory + iris_url_base = "https://archive.ics.uci.edu/ml/machine-learning-databases/iris" + download("$(iris_url_base)/iris.data", joinpath(artifact_dir, "iris.csv")) + download("$(iris_url_base)/bezdekIris.data", joinpath(artifact_dir, "bezdekIris.csv")) + download("$(iris_url_base)/iris.names", joinpath(artifact_dir, "iris.names")) + end + + # Now bind that hash within our `Artifacts.toml`. `force = true` means that if it already exists, + # just overwrite with the new content-hash. Unless the source files change, we do not expect + # the content hash to change, so this should not cause unnecessary version control churn. + bind_artifact!(artifact_toml, "iris", iris_hash) +end + +# Get the path of the iris dataset, either newly created or previously generated. +# this should be something like `~/.julia/artifacts/dbd04e28be047a54fbe9bf67e934be5b5e0d357a` +iris_dataset_path = artifact_path(iris_hash) +``` + +For the specific use case of using artifacts that were previously bound, we have the shorthand notation `artifact"name"` which will automatically search for the `Artifacts.toml` file contained within the current package, look up the given artifact by name, install it if it is not yet installed, then return the path to that given artifact. +An example of this shorthand notation is given below: + +```julia +using Pkg.Artifacts + +# For this to work, an `Artifacts.toml` file must be in the current working directory +# (or in the root of the current package) and must define a mapping for the "iris" +# artifact. If it does not exist on-disk, it will be downloaded. +iris_dataset_path = artifact"iris" +``` + +## The `Pkg.Artifacts` API + +The `Artifacts` API is broken up into three levels: hash-aware functions, name-aware functions and utility functions. + +* **Hash-aware** functions deal with content-hashes and essentially nothing else. These methods allow you to query whether an artifact exists, what its path is, to verify that an artifact satisfies its content hash on-disk, etc. Hash-aware functions include: `artifact_exists()`, `artifact_path()`, `remove_artifact()`, `verify_artifact()` and `archive_artifact()`. Note that in general you should not use `remove_artifact()` and should instead use `Pkg.gc()` to cleanup artifact installations. + +* **Name-aware** functions deal with bound names within an `Artifacts.toml` file, and as such, typically require both a path to an `Artifacts.toml` file as well as the artifact name. Name-aware functions include: `artifact_meta()`, `artifact_hash()`, `bind_artifact!()`, `unbind_artifact!()`, `download_artifact()` and `ensure_artifact_installed()`. + +* **Utility** functions deal with miscellaneous aspects of artifact life, such as `create_artifact()`, `ensure_all_artifacts_installed()`, and even the `@artifact_str` string macro. + +For a full listing of docstrings and methods, see the [Artifacts Reference](@ref) section. + +## Overriding artifact locations + +It is occasionally necessary to be able to override the location and content of an artifact. +A common use case is a computing environment where certain versions of a binary dependency must be used, regardless of what version of this dependency a package was published with. +While a typical Julia configuration would download, unpack and link against a generic library, a system administrator may wish to disable this and instead use a library already installed on the local machine. +To enable this, `Pkg` supports a per-depot `Overrides.toml` file placed within the `artifacts` depot directory (e.g. `~/.julia/artifacts/Overrides.toml` for the default user depot) that can override the location of an artifact either by content-hash or by package UUID and bound artifact name. +Additionally, the destination location can be either an absolute path, or a replacement artifact content hash. +This allows sysadmins to create their own artifacts which they can then use by overriding other packages to use the new artifact. + +```TOML +# Override single hash to absolute path +78f35e74ff113f02274ce60dab6e92b4546ef806 = "/path/to/replacement" + +# Override single hash to new artifact content-hash +683942669b4639019be7631caa28c38f3e1924fe = "d826e316b6c0d29d9ad0875af6ca63bf67ed38c3" + +# Override package bindings by specifying the package UUID and bound artifact name +# For demonstration purposes we assume this package is called `Foo` +[d57dbccd-ca19-4d82-b9b8-9d660942965b] +libfoo = "/path/to/libfoo" +libbar = "683942669b4639019be7631caa28c38f3e1924fe" +``` + +Due to the layered nature of `Pkg` depots, multiple `Overrides.toml` files may be in effect at once. +This allows the "inner" `Overrides.toml` files to override the overrides placed within the "outer" `Overrides.toml` files. +To remove an override and re-enable default location logic for an artifact, insert an entry mapping to the empty string: + +```TOML +78f35e74ff113f02274ce60dab6e92b4546ef806 = "/path/to/new/replacement" +683942669b4639019be7631caa28c38f3e1924fe = "" + +[d57dbccd-ca19-4d82-b9b8-9d660942965b] +libfoo = "" +``` + +If the two `Overrides.toml` snippets as given above are layered on top of eachother, the end result will be mapping the content-hash `78f35e74ff113f02274ce60dab6e92b4546ef806` to `"/path/to/new/replacement"`, and mapping `Foo.libbar` to the artifact identified by the content-hash `683942669b4639019be7631caa28c38f3e1924fe`. +Note that while that hash was previously overridden, it is no longer, and therefore `Foo.libbar` will look directly at locations such as `~/.julia/artifacts/683942669b4639019be7631caa28c38f3e1924fe`. + +Most methods that are affected by overrides have the ability to ignore overrides by setting `honor_overrides=false` as a keyword argument within them. +For UUID/name based overrides to work, `Artifacts.toml` files must be loaded with the knowledge of the UUID of the loading package. +This is deduced automatically by the `artifacts""` string macro, however if you are for some reason manually using the `Pkg.Artifacts` API within your package and you wish to honor overrides, you must provide the package UUID to API calls like `artifact_meta()` and `ensure_artifact_installed()` via the `pkg_uuid` keyword argument. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/basedocs.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/basedocs.md new file mode 100644 index 0000000..21a12c5 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/basedocs.md @@ -0,0 +1,25 @@ +```@meta +EditURL = "https://github.com/JuliaLang/Pkg.jl/blob/master/docs/src/basedocs.md" +``` + +# Pkg + +Pkg is Julia's builtin package manager, and handles operations +such as installing, updating and removing packages. + +!!! note + What follows is a very brief introduction to Pkg. For more + information on `Project.toml` files, `Manifest.toml` files, package + version compatibility (`[compat]`), environments, registries, etc., + it is highly recommended to read the full manual, which is available here: + [https://julialang.github.io/Pkg.jl/v1/](https://julialang.github.io/Pkg.jl/v1/). + +```@eval +import Markdown +file = joinpath(Sys.STDLIB, "Pkg", "docs", "src", "getting-started.md") +str = read(file, String) +str = replace(str, r"^#.*$"m => "") +str = replace(str, "[API Reference](@ref)" => + "[API Reference](https://julialang.github.io/Pkg.jl/v1/api/)") +Markdown.parse(str) +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/compatibility.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/compatibility.md new file mode 100644 index 0000000..94f160e --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/compatibility.md @@ -0,0 +1,201 @@ +# [**6.** Compatibility](@id Compatibility) + +Compatibility refers to the ability to restrict the versions of the dependencies that your project is compatible with. +If the compatibility for a dependency is not given, the project is assumed to be compatible with all versions of that dependency. + +Compatibility for a dependency is entered in the `Project.toml` file as for example: + +```toml +[compat] +julia = "1.0" +Example = "0.4.3" +``` + +After a compatibility entry is put into the project file, `up` can be used to apply it. + +The format of the version specifier is described in detail below. + +!!! info + There is currently no way to give compatibility from the Pkg REPL mode so for now, one has to manually edit the project file. + +## Version specifier format + +Similar to other package managers, the Julia package manager respects [semantic versioning](https://semver.org/) (semver). +As an example, a version specifier given as e.g. `1.2.3` is therefore assumed to be compatible with the versions `[1.2.3 - 2.0.0)` where `)` is a non-inclusive upper bound. +More specifically, a version specifier is either given as a **caret specifier**, e.g. `^1.2.3` or as a **tilde specifier**, e.g. `~1.2.3`. +Caret specifiers are the default and hence `1.2.3 == ^1.2.3`. The difference between a caret and tilde is described in the next section. +The union of multiple version specifiers can be formed by comma separating individual version specifiers, e.g. +```toml +[compat] +Example = "1.2, 2" +``` +will result in `[1.2.0, 3.0.0)`. Note leading zeros are treated differently, e.g. `Example = "0.2, 1"` would only result in `[0.2.0-0.3.0, 1.0.0-2.0.0]`. See the next section for more information on versions with leading zeros. + +### [Behavior of versions with leading zeros (0.0.x and 0.x.y)](@id compat-pre-1.0) + +While the semver specification says that all versions with a major version of 0 (versions before 1.0.0) are incompatible +with each other, we have decided to only apply that for when both the major and minor versions are zero. In other words, +0.0.1 and 0.0.2 are considered incompatible. A pre-1.0 version with non-zero minor version (`0.a.b` with `a != 0`) is +considered compatible with versions with the same minor version and smaller or equal patch versions (`0.a.c` with `c <= b`); +i.e., the versions 0.2.2 and 0.2.3 are compatible with 0.2.1 and 0.2.0. Versions with a major version of 0 and different +minor versions are not considered compatible, so the version 0.3.0 might have breaking changes from 0.2.0. To that end, the +`[compat]` entry: + +```toml +[compat] +Example = "0.0.1" +``` + +results in a versionbound on `Example` as `[0.0.1, 0.0.2)` (which is equivalent to only the version 0.0.1), while the +`[compat]` entry: + +```toml +[compat] +Example = "0.2.1" +``` + +results in a versionbound on Example as `[0.2.1, 0.3.0)`. + +In particular, a package may set `version = "0.2.4"` when it has feature additions compared to 0.2.3 as long as it +remains backward compatible with 0.2.0. See also [The `version` field](@ref). + +### Caret specifiers + +A caret specifier allows upgrade that would be compatible according to semver. +An updated dependency is considered compatible if the new version does not modify the left-most non zero digit in the version specifier. + +Some examples are shown below. + +```toml +[compat] +PkgA = "^1.2.3" # [1.2.3, 2.0.0) +PkgB = "^1.2" # [1.2.0, 2.0.0) +PkgC = "^1" # [1.0.0, 2.0.0) +PkgD = "^0.2.3" # [0.2.3, 0.3.0) +PkgE = "^0.0.3" # [0.0.3, 0.0.4) +PkgF = "^0.0" # [0.0.0, 0.1.0) +PkgG = "^0" # [0.0.0, 1.0.0) +``` + +### Tilde specifiers + +A tilde specifier provides more limited upgrade possibilities. When specifying major, minor +and patch versions, or when specifying major and minor versions, only the patch version is +allowed to change. If you only specify a major version, then both minor and patch versions +are allowed to be upgraded (`~1` is thus equivalent to `^1`). +For example: + +```toml +[compat] +PkgA = "~1.2.3" # [1.2.3, 1.3.0) +PkgB = "~1.2" # [1.2.0, 1.3.0) +PkgC = "~1" # [1.0.0, 2.0.0) +PkgD = "~0.2.3" # [0.2.3, 0.3.0) +PkgE = "~0.0.3" # [0.0.3, 0.0.4) +PkgF = "~0.0" # [0.0.0, 0.1.0) +PkgG = "~0" # [0.0.0, 1.0.0) +``` + +For all versions with a major version of 0 the tilde and caret specifiers are equivalent. + +### Equality specifier + +Equality can be used to specify an exact version: + +```toml +[compat] +PkgA = "= 1.2.3" # [1.2.3, 1.2.3] +``` + +### Inequality specifiers + +Inequalities can also be used to specify version ranges: + +```toml +[compat] +PkgB = ">= 1.2.3" # [1.2.3, ∞) +PkgC = "≥ 1.2.3" # [1.2.3, ∞) +PkgD = "< 1.2.3" # [0.0.0, 1.2.3) = [0.0.0, 1.2.2] +``` + +### Hyphen specifiers + +Hyphen syntax can also be used to specify version ranges. Make sure that you have a space on both sides of the hyphen. + +```toml +[compat] +PkgA = "1.2.3 - 4.5.6" # [1.2.3, 4.5.6] +PkgA = "0.2.3 - 4.5.6" # [0.2.3, 4.5.6] +``` + +Any unspecified trailing numbers in the first end-point are considered to be zero: + +```toml +[compat] +PkgA = "1.2 - 4.5.6" # [1.2.0, 4.5.6] +PkgA = "1 - 4.5.6" # [1.0.0, 4.5.6] +PkgA = "0.2 - 4.5.6" # [0.2.0, 4.5.6] +PkgA = "0.2 - 0.5.6" # [0.2.0, 0.5.6] +``` + +Any unspecified trailing numbers in the second end-point will be considered to be wildcards: + +```toml +[compat] +PkgA = "1.2.3 - 4.5" # 1.2.3 - 4.5.* = [1.2.3, 4.6.0) +PkgA = "1.2.3 - 4" # 1.2.3 - 4.*.* = [1.2.3, 5.0.0) +PkgA = "1.2 - 4.5" # 1.2.0 - 4.5.* = [1.2.0, 4.6.0) +PkgA = "1.2 - 4" # 1.2.0 - 4.*.* = [1.2.0, 5.0.0) +PkgA = "1 - 4.5" # 1.0.0 - 4.5.* = [1.0.0, 4.6.0) +PkgA = "1 - 4" # 1.0.0 - 4.*.* = [1.0.0, 5.0.0) +PkgA = "0.2.3 - 4.5" # 0.2.3 - 4.5.* = [0.2.3, 4.6.0) +PkgA = "0.2.3 - 4" # 0.2.3 - 4.*.* = [0.2.3, 5.0.0) +PkgA = "0.2 - 4.5" # 0.2.0 - 4.5.* = [0.2.0, 4.6.0) +PkgA = "0.2 - 4" # 0.2.0 - 4.*.* = [0.2.0, 5.0.0) +PkgA = "0.2 - 0.5" # 0.2.0 - 0.5.* = [0.2.0, 0.6.0) +PkgA = "0.2 - 0" # 0.2.0 - 0.*.* = [0.2.0, 1.0.0) +``` + +!!! compat "Julia 1.4" + Hyphen specifiers requires at least Julia 1.4, so it is strongly recomended to also add + ```toml + [compat] + julia = "1.4" + ``` + to the project file when using them. + +## Fixing conflicts + +Version conflicts were introduced previously with an [example](@ref conflicts) +of a conflict arising in a package `D` used by two other packages, `B` and `C`. +Our analysis of the error message revealed that `B` is using an outdated +version of `D`. +To fix it, the first thing to try is to `pkg> dev B` so that +you can modify `B` and its compatibility requirements. +If you open its `Project.toml` file in an editor, you would probably notice something like + +```toml +[compat] +D = "0.1" +``` + +Usually the first step is to modify this to something like +```toml +[compat] +D = "0.1, 0.2" +``` + +This indicates that `B` is compatible with both versions 0.1 and version 0.2; if you `pkg> up` +this would fix the package error. +However, there is one major concern you need to address first: perhaps there was an incompatible change +in `v0.2` of `D` that breaks `B`. +Before proceeding further, you should update all packages and then run `B`'s tests, scanning the +output of `pkg> test B` to be sure that `v0.2` of `D` is in fact being used. +(It is possible that an additional dependency of `D` pins it to `v0.1`, and you wouldn't want to be misled into thinking that you had tested `B` on the newer version.) +If the new version was used and the tests still pass, +you can assume that `B` didn't need any further updating to accomodate `v0.2` of `D`; +you can safely submit this change as a pull request to `B` so that a new release is made. +If instead an error is thrown, it indicates that `B` requires more extensive updates to be +compatible with the latest version of `D`; those updates will need to be completed before +it becomes possible to use both `A` and `B` simultaneously. +You can, though, continue to use the independently of one another. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/creating-packages.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/creating-packages.md new file mode 100644 index 0000000..a21887c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/creating-packages.md @@ -0,0 +1,290 @@ +# **5.** Creating Packages + +A package is a project with a `name`, `uuid` and `version` entry in the `Project.toml` file, and a `src/PackageName.jl` file that defines the module `PackageName`. +This file is executed when the package is loaded. + +### Generating files for a package + +!!! note + The [PkgTemplates](https://github.com/invenia/PkgTemplates.jl) package offers a very easy, repeatable, and + customizable way to generate the files for a new package. We recommend that you use PkgTemplates for creating + new packages instead of using the minimal `pkg> generate` functionality described below. + +To generate files for a new package, use `pkg> generate`. + +```julia-repl +(v1.0) pkg> generate HelloWorld +``` + +This creates a new project `HelloWorld` with the following files (visualized with the external [`tree` command](https://linux.die.net/man/1/tree)): + +```julia-repl +julia> cd("HelloWorld") + +shell> tree . +. +├── Project.toml +└── src + └── HelloWorld.jl + +1 directory, 2 files +``` + +The `Project.toml` file contains the name of the package, its unique UUID, its version, the authors and potential dependencies: + +```toml +name = "HelloWorld" +uuid = "b4cd1eb8-1e24-11e8-3319-93036a3eb9f3" +version = "0.1.0" +authors = ["Some One <someone@email.com>"] + +[deps] +``` + +The content of `src/HelloWorld.jl` is: + +```julia +module HelloWorld + +greet() = print("Hello World!") + +end # module +``` + +We can now activate the project and load the package: + +```julia-repl +pkg> activate . + +julia> import HelloWorld + +julia> HelloWorld.greet() +Hello World! +``` + +### Adding dependencies to the project + +Let’s say we want to use the standard library package `Random` and the registered package `JSON` in our project. +We simply `add` these packages (note how the prompt now shows the name of the newly generated project, +since we `activate`d it): + +```julia-repl +(HelloWorld) pkg> add Random JSON + Resolving package versions... + Updating "~/Documents/HelloWorld/Project.toml" + [682c06a0] + JSON v0.17.1 + [9a3f8284] + Random + Updating "~/Documents/HelloWorld/Manifest.toml" + [34da2185] + Compat v0.57.0 + [682c06a0] + JSON v0.17.1 + [4d1e1d77] + Nullables v0.0.4 + ... +``` + +Both `Random` and `JSON` got added to the project’s `Project.toml` file, and the resulting dependencies got added to the `Manifest.toml` file. +The resolver has installed each package with the highest possible version, while still respecting the compatibility that each package enforces on its dependencies. + +We can now use both `Random` and `JSON` in our project. Changing `src/HelloWorld.jl` to + +```julia +module HelloWorld + +import Random +import JSON + +greet() = print("Hello World!") +greet_alien() = print("Hello ", Random.randstring(8)) + +end # module +``` + +and reloading the package, the new `greet_alien` function that uses `Random` can be called: + +```julia-repl +julia> HelloWorld.greet_alien() +Hello aT157rHV +``` + +### Adding a build step to the package + +The build step is executed the first time a package is installed or when explicitly invoked with `build`. +A package is built by executing the file `deps/build.jl`. + +```julia-repl +julia> print(read("deps/build.jl", String)) +println("I am being built...") + +(HelloWorld) pkg> build + Building HelloWorld → `deps/build.log` + Resolving package versions... + +julia> print(read("deps/build.log", String)) +I am being built... +``` + +If the build step fails, the output of the build step is printed to the console + +```julia-repl +julia> print(read("deps/build.jl", String)) +error("Ooops") + +(HelloWorld) pkg> build + Building HelloWorld → `deps/build.log` + Resolving package versions... +┌ Error: Error building `HelloWorld`: +│ ERROR: LoadError: Ooops +│ Stacktrace: +│ [1] error(::String) at ./error.jl:33 +│ [2] top-level scope at none:0 +│ [3] include at ./boot.jl:317 [inlined] +│ [4] include_relative(::Module, ::String) at ./loading.jl:1071 +│ [5] include(::Module, ::String) at ./sysimg.jl:29 +│ [6] include(::String) at ./client.jl:393 +│ [7] top-level scope at none:0 +│ in expression starting at /Users/kristoffer/.julia/dev/Pkg/HelloWorld/deps/build.jl:1 +└ @ Pkg.Operations Operations.jl:938 +``` + +### Adding tests to the package + +When a package is tested the file `test/runtests.jl` is executed: + +```julia-repl +julia> print(read("test/runtests.jl", String)) +println("Testing...") + +(HelloWorld) pkg> test + Testing HelloWorld + Resolving package versions... +Testing... + Testing HelloWorld tests passed +``` + +Tests are run in a new Julia process, where the package itself, and any +test-specific dependencies, are available, see below. + +#### Test-specific dependencies in Julia 1.2 and above + +!!! compat "Julia 1.2" + This section only applies to Julia 1.2 and above. For specifying test dependencies + on previous Julia versions, see [Test-specific dependencies in Julia 1.0 and 1.1](@ref). + +!!! note + The exact interaction between `Project.toml`, `test/Project.toml` and their corresponding + `Manifest.toml`s are not fully worked out, and may be subject to change in future versions. + The old method of adding test-specific dependencies, described in the next section, will + therefore be supported throughout all Julia 1.X releases. + +In Julia 1.2 and later the test environment is given by `test/Project.toml`. Thus, when running +tests, this will be the active project, and only dependencies to the `test/Project.toml` project +can be used. Note that Pkg will add the tested package itself implictly. + +!!! note + If no `test/Project.toml` exists Pkg will use the old style test-setup, as + described in [Test-specific dependencies in Julia 1.0 and 1.1](@ref). + +To add a test-specific dependency, i.e. a dependency that is available only when testing, +it is thus enough to add this dependency to the `test/Project.toml` project. This can be +done from the Pkg REPL by activating this environment, and then use `add` as one normally +does. Lets add the `Test` standard library as a test dependency: + +```julia-repl +(HelloWorld) pkg> activate ./test +[ Info: activating environment at `~/HelloWorld/test/Project.toml`. + +(test) pkg> add Test + Resolving package versions... + Updating `~/HelloWorld/test/Project.toml` + [8dfed614] + Test + Updating `~/HelloWorld/test/Manifest.toml` + [...] +``` + +We can now use `Test` in the test script and we can see that it gets installed when testing: + +```julia-repl +julia> print(read("test/runtests.jl", String)) +using Test +@test 1 == 1 + +(HelloWorld) pkg> test + Testing HelloWorld + Resolving package versions... + Updating `/var/folders/64/76tk_g152sg6c6t0b4nkn1vw0000gn/T/tmpPzUPPw/Project.toml` + [d8327f2a] + HelloWorld v0.1.0 [`~/.julia/dev/Pkg/HelloWorld`] + [8dfed614] + Test + Updating `/var/folders/64/76tk_g152sg6c6t0b4nkn1vw0000gn/T/tmpPzUPPw/Manifest.toml` + [d8327f2a] + HelloWorld v0.1.0 [`~/.julia/dev/Pkg/HelloWorld`] + Testing HelloWorld tests passed``` +``` + +#### Test-specific dependencies in Julia 1.0 and 1.1 + +!!! note + The method of adding test-specific dependencies described in this section will + be replaced by the method from the previous section in future Julia versions. + The method in this section will, however, be supported throughout all Julia 1.X + releases. + +In Julia 1.0 and Julia 1.1 test-specific dependencies are added to the main +`Project.toml`. To add `Markdown` and `Test` as test-dependencies, add the following: + +```toml +[extras] +Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a" +Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" + +[targets] +test = ["Markdown", "Test"] +``` + +### Package naming guidelines + +Package names should be sensible to most Julia users, *even to those who are not domain experts*. +The following guidelines applies to the `General` registry, but may be useful for other package +registries as well. + +Since the `General` registry belongs to the entire community, people may have opinions about +your package name when you publish it, especially if it's ambiguous or can be confused with +something other than what it is. Usually you will then get suggestions for a new name that +may fit your package better. + +1. Avoid jargon. In particular, avoid acronyms unless there is minimal possibility of confusion. + + * It's ok to say `USA` if you're talking about the USA. + * It's not ok to say `PMA`, even if you're talking about positive mental attitude. +2. Avoid using `Julia` in your package name or prefixing it with `Ju`. + + * It is usually clear from context and to your users that the package is a Julia package. + * Package names already have a `.jl` extension, which communicates to users that `Package.jl` is a Julia package. + * Having Julia in the name can imply that the package is connected to, or endorsed by, contributors + to the Julia language itself. +3. Packages that provide most of their functionality in association with a new type should have pluralized + names. + + * `DataFrames` provides the `DataFrame` type. + * `BloomFilters` provides the `BloomFilter` type. + * In contrast, `JuliaParser` provides no new type, but instead new functionality in the `JuliaParser.parse()` + function. +4. Err on the side of clarity, even if clarity seems long-winded to you. + + * `RandomMatrices` is a less ambiguous name than `RndMat` or `RMT`, even though the latter are shorter. +5. A less systematic name may suit a package that implements one of several possible approaches to + its domain. + + * Julia does not have a single comprehensive plotting package. Instead, `Gadfly`, `PyPlot`, `Winston` + and other packages each implement a unique approach based on a particular design philosophy. + * In contrast, `SortingAlgorithms` provides a consistent interface to use many well-established + sorting algorithms. +6. Packages that wrap external libraries or programs should be named after those libraries or programs. + + * `CPLEX.jl` wraps the `CPLEX` library, which can be identified easily in a web search. + * `MATLAB.jl` provides an interface to call the MATLAB engine from within Julia. +7. Avoid naming a package closely to an existing package + * `Websocket` is too close to `WebSockets` and can be confusing to users. Rather use a new name such as `SimpleWebsockets`. + +### Registering packages + +Once a package is ready it can be registered with the [General Registry](https://github.com/JuliaRegistries/General). +Currently packages are submitted via [`Registrator`](https://juliaregistrator.github.io/). +In addition to `Registrator`, [`TagBot`](https://github.com/apps/julia-tagbot) helps manage the process of tagging releases. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/environments.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/environments.md new file mode 100644 index 0000000..9d5bd46 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/environments.md @@ -0,0 +1,108 @@ +# **4.** Working with Environments + +The following discusses Pkg's interaction with environments. For more on the role environments play in code loading, including the "stack" of environments from which code can be loaded, see [this section in the Julia manual](https://docs.julialang.org/en/v1/manual/code-loading/#Environments-1). + +## Creating your own projects + +So far we have added packages to the default project at `~/.julia/environments/v1.0`. It is however easy to create other, independent, projects. +It should be pointed out that when two projects use the same package at the same version, the content of this package is not duplicated. +In order to create a new project, create a directory for it and then activate that directory to make it the "active project", which package operations manipulate: + +```julia-repl +julia> mkdir("MyProject") + +julia> cd("MyProject") +/Users/kristoffer/MyProject + +(v1.0) pkg> activate . + +(MyProject) pkg> st + Status `Project.toml` +``` + +Note that the REPL prompt changed when the new project is activated. Since this is a newly created project, the status command shows that it contains no packages, and in fact, it has no project or manifest file until we add a package to it: + +```julia-repl +julia> readdir() +0-element Array{String,1} + +(MyProject) pkg> add Example + Updating registry at `~/.julia/registries/General` + Updating git-repo `https://github.com/JuliaRegistries/General.git` + Resolving package versions... + Updating `Project.toml` + [7876af07] + Example v0.5.1 + Updating `Manifest.toml` + [7876af07] + Example v0.5.1 + [8dfed614] + Test +Precompiling project... + 1 dependency successfully precompiled in 2 seconds + +julia> readdir() +2-element Array{String,1}: + "Manifest.toml" + "Project.toml" + +julia> print(read("Project.toml", String)) +[deps] +Example = "7876af07-990d-54b4-ab0e-23690620f79a" + +julia> print(read("Manifest.toml", String)) +[[Example]] +deps = ["Test"] +git-tree-sha1 = "8eb7b4d4ca487caade9ba3e85932e28ce6d6e1f8" +uuid = "7876af07-990d-54b4-ab0e-23690620f79a" +version = "0.5.1" + +[[Test]] +uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40" +``` + +This new environment is completely separate from the one we used earlier. + + +## Project Precompilation + +By default any package that is added to a project or updated in a Pkg action will be automatically precompiled, along +with its dependencies. The exception is the `develop` command, which neither builds nor precompiles the package, when +that happens is left up to the user to decide. + +If a package that has been updated is already loaded in the session, the precompilation process will go ahead and precompile +the new version, and any packages that depend on it, but will note that the package cannot be used until session restart. + +To disable this auto-precompilation, set `ENV["JULIA_PKG_PRECOMPILE_AUTO"]=0`, after which precompilation can be triggered +manually either serially via code loading + +```julia-repl +julia> using Example +[ Info: Precompiling Example [7876af07-990d-54b4-ab0e-23690620f79a] +``` + + or the parallel precompilation, which can be significantly faster when many dependencies are involved, via + +```julia-repl +pkg> precompile +Precompiling project... + 23 dependencies successfully precompiled in 36 seconds +``` + +## Using someone else's project + +Simply clone their project using e.g. `git clone`, `cd` to the project directory and call + +```julia-repl +(v1.0) pkg> activate . + +(SomeProject) pkg> instantiate +``` + +If the project contains a manifest, this will install the packages in the same state that is given by that manifest. +Otherwise, it will resolve the latest versions of the dependencies compatible with the project. + +!!! note "Specifying project on startup" + Instead of using `activate` from within Julia you can specify the project on startup using + the `--project=<path>` flag. For example, to run a script from the command line using the + environment in the current directory you can run + ```bash + $ julia --project=. myscript.jl + ``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/faq.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/faq.md new file mode 100644 index 0000000..3809353 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/faq.md @@ -0,0 +1,3 @@ +# **8.** FAQ + +### Should `Manifest.toml` be checked in to the package? diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/getting-started.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/getting-started.md new file mode 100644 index 0000000..acfb0c5 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/getting-started.md @@ -0,0 +1,216 @@ +# **2.** Getting Started + +What follows is a quick overview of Pkg, Julia's package manager. +It should help new users become familiar with basic Pkg features. + +## Basic Usage + +Pkg comes with a REPL. +Enter the Pkg REPL by pressing `]` from the Julia REPL. +To get back to the Julia REPL, press backspace or ^C. + +!!! note + This guide relies on the Pkg REPL to execute Pkg commands. + For non-interactive use, we recommend the Pkg API. + The Pkg API is fully documented in the [API Reference](@ref) section of the Pkg documentation. + +Upon entering the Pkg REPL, you should see a similar prompt: + +```julia-repl +(v1.1) pkg> +``` + +To add a package, use `add`: + +```julia-repl +(v1.1) pkg> add Example +``` + +!!! note + Some Pkg output has been omitted in order to keep this guide focused. + This will help maintain a good pace and not get bogged down in details. + If you require more details, refer to subsequent sections of the Pkg manual. + +We can also specify multiple packages at once: + +```julia-repl +(v1.1) pkg> add JSON StaticArrays +``` + +To remove packages, use `rm`: + +```julia-repl +(v1.1) pkg> rm JSON StaticArrays +``` + +So far, we have referred only to registered packages. +Pkg also supports working with unregistered packages. +To add an unregistered package, specify a URL: + +```julia-repl +(v1.1) pkg> add https://github.com/JuliaLang/Example.jl +``` + +Use `rm` to remove this package by name: + +```julia-repl +(v1.1) pkg> rm Example +``` + +Use `update` to update an installed package: + +```julia-repl +(v1.1) pkg> update Example +``` + +To update all installed packages, use `update` without any arguments: + +```julia-repl +(v1.1) pkg> update +``` + +## Getting Started with Environments + +Up to this point, we have covered basic package management: adding, updating and removing packages. +This will be familiar if you have used other package managers. +Pkg offers significant advantages over traditional package managers +by organizing dependencies into **environments**. + +You may have noticed the `(v1.1)` in the REPL prompt. +This lets us know `v1.1` is the **active environment**. +The active environment is the environment that will be modified by Pkg commands such as `add`, `rm` and `update`. + +Let's set up a new environment so we may experiment. +To set the active environment, use `activate`: + +```julia-repl +(v1.1) pkg> activate tutorial +[ Info: activating new environment at `/tmp/tutorial/Project.toml`. +``` + +Pkg lets us know we are creating a new environment and that this environment +will be stored in the `/tmp/tutorial` directory. + +Pkg has also updated the REPL prompt in order to reflect the new +active environment: + +```julia-repl +(tutorial) pkg> +``` + +We can ask for information about the active environment by using `status`: + +```julia-repl +(tutorial) pkg> status + Status `/tmp/tutorial/Project.toml` + (empty environment) +``` + +`/tmp/tutorial/Project.toml` is the location of the active environment's **project file**. +A project file is where Pkg stores metadata for an environment. +Notice this new environment is empty. +Let us add a package and observe: + +```julia-repl +(tutorial) pkg> add Example +... + +(tutorial) pkg> status + Status `/tmp/tutorial/Project.toml` + [7876af07] Example v0.5.1 +``` + +We can see `tutorial` now contains `Example` as a dependency. + +## Modifying A Dependency + +Say we are working on `Example` and feel it needs new functionality. +How can we modify the source code? +We can use `develop` to set up a git clone of the `Example` package. + +```julia-repl +(tutorial) pkg> develop --local Example +... + +(tutorial) pkg> status + Status `/tmp/tutorial/Project.toml` + [7876af07] Example v0.5.1+ [`dev/Example`] +``` + +Notice the feedback has changed. +`dev/Example` refers to the location of the newly created clone. +If we look inside the `/tmp/tutorial` directory, we will notice the following files: + +``` +tutorial +├── dev +│ └── Example +├── Manifest.toml +└── Project.toml +``` + +Instead of loading a registered version of `Example`, +Julia will load the source code contained in `tutorial/dev/Example`. + +Let's try it out. +First we modify the file at `tutorial/dev/Example/src/Example.jl` and add a simple function: + +```julia +plusone(x::Int) = x + 1 +``` + +Now we can go back to the Julia REPL and load the package: + +```julia-repl +julia> import Example +``` + +!!! warn + A package can only be loaded once per Julia session. + If you have run `import Example` in the current Julia session, you will + have to restart Julia and rerun `activate tutorial` in the Pkg REPL. + [Revise.jl](https://github.com/timholy/Revise.jl/) can make this process + significantly more pleasant, but setting it up is beyond the scope of this guide. + +Julia should load our new code. Let's test it: + +```julia-repl +julia> Example.plusone(1) +2 +``` + +Say we have a change of heart and decide the world is not ready for such elegant code. +We can tell Pkg to stop using the local clone and use a registered version instead. +We do this with `free`: + +```julia-repl +(tutorial) pkg> free Example +``` + +When you are done experimenting with `tutorial`, you can return to the **default +environment** by running `activate` with no arguments: + +```julia-repl +(tutorial) pkg> activate + +(v1.1) pkg> +``` + +## Asking for Help + +If you are ever stuck, you can ask `Pkg` for help: + +```julia-repl +(v1.1) pkg> ? +``` + +You should see a list of available commands along with short descriptions. +You can ask for more detailed help by specifying a command: + +```julia-repl +(v1.1) pkg> ?develop +``` + +This guide should help you get started with `Pkg`. +`Pkg` has much more to offer in terms of powerful package management, +read the full manual to learn more! diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/glossary.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/glossary.md new file mode 100644 index 0000000..f632140 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/glossary.md @@ -0,0 +1,124 @@ +# [**9.** Glossary](@id Glossary) + +**Project:** a source tree with a standard layout, including a `src` directory +for the main body of Julia code, a `test` directory for testing the project, +a `docs` directory for documentation files, and optionally a `deps` directory for a build +script and its outputs. A project will typically also have a project file and +may optionally have a manifest file: + +- **Project file:** a file in the root directory of a project, named + `Project.toml` (or `JuliaProject.toml`), describing metadata about the project, + including its name, UUID (for packages), authors, license, and the names and + UUIDs of packages and libraries that it depends on. + +- **Manifest file:** a file in the root directory of a project, named + `Manifest.toml` (or `JuliaManifest.toml`), describing a complete dependency graph + and exact versions of each package and library used by a project. + +**Package:** a project which provides reusable functionality that can be used by +other Julia projects via `import X` or `using X`. A package should have a +project file with a `uuid` entry giving its package UUID. This UUID is used to +identify the package in projects that depend on it. + +!!! note + For legacy reasons it is possible to load a package without a project file or + UUID from the REPL or the top-level of a script. It is not possible, however, + to load a package without a project file or UUID from a project with them. Once + you've loaded from a project file, everything needs a project file and UUID. + +**Application:** a project which provides standalone functionality not intended +to be reused by other Julia projects. For example a web application or a +commmand-line utility, or simulation/analytics code accompanying a scientific paper. +An application may have a UUID but does not need one. +An application may also provide global configuration options for packages it +depends on. Packages, on the other hand, may not provide global configuration +since that could conflict with the configuration of the main application. + +!!! note + **Projects _vs._ Packages _vs._ Applications:** + + 1. **Project** is an umbrella term: packages and applications are kinds of projects. + 2. **Packages** should have UUIDs, applications can have a UUIDs but don't need them. + 3. **Applications** can provide global configuration, whereas packages cannot. + +**Library (future work):** a compiled binary dependency (not written in Julia) +packaged to be used by a Julia project. These are currently typically built in- +place by a `deps/build.jl` script in a project’s source tree, but in the future +we plan to make libraries first-class entities directly installed and upgraded +by the package manager. + +**Environment:** the combination of the top-level name map provided by a project +file combined with the dependency graph and map from packages to their entry points +provided by a manifest file. For more detail see the manual section on code loading. + +- **Explicit environment:** an environment in the form of an explicit project + file and an optional corresponding manifest file together in a directory. If the + manifest file is absent then the implied dependency graph and location maps are + empty. + +- **Implicit environment:** an environment provided as a directory (without a + project file or manifest file) containing packages with entry points of the form + `X.jl`, `X.jl/src/X.jl` or `X/src/X.jl`. The top-level name map is implied by + these entry points. The dependency graph is implied by the existence of project + files inside of these package directories, e.g. `X.jl/Project.toml` or + `X/Project.toml`. The dependencies of the `X` package are the dependencies in + the corresponding project file if there is one. The location map is implied by + the entry points themselves. + +**Registry:** a source tree with a standard layout recording metadata about a +registered set of packages, the tagged versions of them which are available, and +which versions of packages are compatible or incompatible with each other. A +registry is indexed by package name and UUID, and has a directory for each +registered package providing the following metadata about it: + +- name – e.g. `DataFrames` +- UUID – e.g. `a93c6f00-e57d-5684-b7b6-d8193f3e46c0` +- authors – e.g. `Jane Q. Developer <jane@example.com>` +- license – e.g. MIT, BSD3, or GPLv2 +- repository – e.g. `https://github.com/JuliaData/DataFrames.jl.git` +- description – a block of text summarizing the functionality of a package +- keywords – e.g. `data`, `tabular`, `analysis`, `statistics` +- versions – a list of all registered version tags + +For each registered version of a package, the following information is provided: + +- its semantic version number – e.g. `v1.2.3` +- its git tree SHA-1 hash – e.g. `7ffb18ea3245ef98e368b02b81e8a86543a11103` +- a map from names to UUIDs of dependencies +- which versions of other packages it is compatible/incompatible with + +Dependencies and compatibility are stored in a compressed but human-readable +format using ranges of package versions. + +**Depot:** a directory on a system where various package-related resources live, +including: + +- `environments`: shared named environments (e.g. `v1.0`, `devtools`) +- `clones`: bare clones of package repositories +- `compiled`: cached compiled package images (`.ji` files) +- `config`: global configuration files (e.g. `startup.jl`) +- `dev`: default directory for package development +- `logs`: log files (e.g. `manifest_usage.toml`, `repl_history.jl`) +- `packages`: installed package versions +- `registries`: clones of registries (e.g. `General`) + +**Load path:** a stack of environments where package identities, their +dependencies, and entry-points are searched for. The load path is controlled in +Julia by the `LOAD_PATH` global variable which is populated at startup based on +the value of the `JULIA_LOAD_PATH` environment variable. The first entry is your +primary environment, often the current project, while later entries provide +additional packages one may want to use from the REPL or top-level scripts. + +**Depot path:** a stack of depot locations where the package manager, as well as +Julia's code loading mechanisms, look for registries, installed packages, named +environments, repo clones, cached compiled package images, and configuration +files. The depot path is controlled by the Julia `DEPOT_PATH` global variable +which is populated at startup based on the value of the `JULIA_DEPOT_PATH` +environment variable. The first entry is the “user depot” and should be writable +by and owned by the current user. The user depot is where: registries are +cloned, new package versions are installed, named environments are created and +updated, package repos are cloned, newly compiled package image files are saved, +log files are written, development packages are checked out by default, and +global configuration data is saved. Later entries in the depot path are treated +as read-only and are appropriate for registries, packages, etc. installed and +managed by system administrators. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/index.md new file mode 100644 index 0000000..8cbab92 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/index.md @@ -0,0 +1,65 @@ +# **1.** Introduction + +Welcome to the documentation for Pkg, Julia's package manager. +The documentation covers many things, for example managing package +installations, developing packages, working with package registries and more. + +Throughout the manual the REPL interface to Pkg is used in the examples. +There is also a functional API interface, which is preferred when not working +interactively. This API is documented in the [API Reference](@ref) section. + +## Background and Design + +Pkg is a complete rewrite of Julia's old package manager[^1] and was released +together with Julia v1.0. Unlike traditional +package managers, which install and manage a single global set of packages, Pkg +is designed around “environments”: independent sets of packages that can be +local to an individual project or shared and selected by name. The exact set of +packages and versions in an environment is captured in a _manifest file_ which +can be checked into a project repository and tracked in version control, +significantly improving reproducibility of projects. If you’ve ever tried to run +code you haven’t used in a while only to find that you can’t get anything to +work because you’ve updated or uninstalled some of the packages your project was +using, you’ll understand the motivation for this approach. In Pkg, since each +project maintains its own independent set of package versions, you’ll never have +this problem again. Moreover, if you check out a project on a new system, you +can simply materialize the environment described by its manifest file and +immediately be up and running with a known-good set of dependencies. + +Since environments are managed and updated independently from each other, +“dependency hell” is significantly alleviated in Pkg. If you want to use the +latest and greatest version of some package in a new project but you’re stuck on +an older version in a different project, that’s no problem – since they have +separate environments they can just use different versions, which are both +installed at the same time in different locations on your system. The location +of each package version is canonical, so when environments use the same versions +of packages, they can share installations, avoiding unnecessary duplication of +the package. Old package versions that are no longer used by any environments +are periodically “garbage collected” by the package manager. + +Pkg’s approach to local environments may be familiar to people who have used +Python’s `virtualenv` or Ruby’s `bundler`. In Julia, instead of hacking the +language’s code loading mechanisms to support environments, we have the benefit +that Julia natively understands them. In addition, Julia environments are +“stackable”: you can overlay one environment with another and thereby have +access to additional packages outside of the primary environment. This makes it +easy to work on a project, which provides the primary environment, while still +having access from the REPL to all your usual dev tools like profilers, +debuggers, and so on, just by having an environment including these dev tools +later in the load path. + +Last but not least, Pkg is designed to support federated package registries. +This means that it allows multiple registries managed by different parties to +interact seamlessly. In particular, this includes private registries which can +live behind corporate firewalls. You can install and update your own packages +from a private registry with exactly the same tools and workflows that you use +to install and manage official Julia packages. If you urgently need to apply a +hotfix for a public package that’s critical to your company’s product, you can +tag a private version of it in your company’s internal registry and get a fix to +your developers and ops teams quickly and easily without having to wait for an +upstream patch to be accepted and published. Once an official fix is published, +however, you can just upgrade your dependencies and you'll be back on an +official release again. + +[^1]: Often denoted `Pkg2`, now archived as `OldPkg` at + [`github.com/JuliaAttic/OldPkg.jl`](https://github.com/JuliaAttic/OldPkg.jl). diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/managing-packages.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/managing-packages.md new file mode 100644 index 0000000..45df972 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/managing-packages.md @@ -0,0 +1,428 @@ +# **3.** Managing Packages + +## Adding packages + +There are two ways of adding packages, either using the `add` command or the `dev` command. +The most frequently used is `add` and its usage is described first. + +### Adding registered packages + +In the Pkg REPL, packages can be added with the `add` command followed by the name of the package, for example: + +```julia-repl +(v1.0) pkg> add Example + Cloning default registries into /Users/kristoffer/.julia/registries + Cloning registry General from "https://github.com/JuliaRegistries/General.git" + Updating registry at `~/.julia/registries/General` + Updating git-repo `https://github.com/JuliaRegistries/General.git` + Resolving package versions... + Updating `~/.julia/environments/v1.0/Project.toml` + [7876af07] + Example v0.5.1 + Updating `~/.julia/environments/v1.0/Manifest.toml` + [7876af07] + Example v0.5.1 + [8dfed614] + Test +``` + +Here we added the package Example to the current project. In this example, we are using a fresh Julia installation, +and this is our first time adding a package using Pkg. By default, Pkg clones Julia's General registry, +and uses this registry to look up packages requested for inclusion in the current environment. +The status update shows a short form of the package UUID to the left, then the package name, and the version. +Since standard libraries (e.g. `Test`) are shipped with Julia, they do not have a version. The project status contains the packages +you have added yourself, in this case, `Example`: + +```julia-repl +(v1.0) pkg> st + Status `Project.toml` + [7876af07] Example v0.5.1 +``` + +The manifest status shows all the packages in the environment, including recursive dependencies: + +```julia-repl +(v1.0) pkg> st --manifest + Status `Manifest.toml` + [7876af07] Example v0.5.1 + [8dfed614] Test +``` + +It is possible to add multiple packages in one command as `pkg> add A B C`. + +After a package is added to the project, it can be loaded in Julia: + +```julia-repl +julia> using Example + +julia> Example.hello("User") +"Hello, User" +``` + +A specific version can be installed by appending a version after a `@` symbol, e.g. `@v0.4`, to the package name: + +```julia-repl +(v1.0) pkg> add Example@0.4 + Resolving package versions... + Updating `~/.julia/environments/v1.0/Project.toml` + [7876af07] + Example v0.4.1 + Updating `~/.julia/environments/v1.0/Manifest.toml` + [7876af07] + Example v0.4.1 +``` + +If a branch (or a certain commit) of `Example` has a hotfix that is not yet included in a registered version, +we can explicitly track that branch (or commit) by appending `#branchname` (or `#commitSHA1`) to the package name: + +```julia-repl +(v1.0) pkg> add Example#master + Updating git-repo `https://github.com/JuliaLang/Example.jl.git` + Resolving package versions... + Updating `~/.julia/environments/v1.0/Project.toml` + [7876af07] ~ Example v0.5.1 ⇒ v0.5.1+ #master (https://github.com/JuliaLang/Example.jl.git) + Updating `~/.julia/environments/v1.0/Manifest.toml` + [7876af07] ~ Example v0.5.1 ⇒ v0.5.1+ #master (https://github.com/JuliaLang/Example.jl.git) +``` + +The status output now shows that we are tracking the `master` branch of `Example`. +When updating packages, we will pull updates from that branch. + +To go back to tracking the registry version of `Example`, the command `free` is used: + +```julia-repl +(v1.0) pkg> free Example + Resolving package versions... + Updating `~/.julia/environments/v1.0/Project.toml` + [7876af07] ~ Example v0.5.1+ #master (https://github.com/JuliaLang/Example.jl.git) ⇒ v0.5.1 + Updating `~/.julia/environments/v1.0/Manifest.toml` + [7876af07] ~ Example v0.5.1+ #master )https://github.com/JuliaLang/Example.jl.git) ⇒ v0.5.1 +``` + + +### Adding unregistered packages + +If a package is not in a registry, it can be added by specifying a URL to the repository: + +```julia-repl +(v1.0) pkg> add https://github.com/fredrikekre/ImportMacros.jl + Updating git-repo `https://github.com/fredrikekre/ImportMacros.jl` + Resolving package versions... +Downloaded MacroTools ─ v0.4.1 + Updating `~/.julia/environments/v1.0/Project.toml` + [e6797606] + ImportMacros v0.0.0 # (https://github.com/fredrikekre/ImportMacros.jl) + Updating `~/.julia/environments/v1.0/Manifest.toml` + [e6797606] + ImportMacros v0.0.0 # (https://github.com/fredrikekre/ImportMacros.jl) + [1914dd2f] + MacroTools v0.4.1 +``` + +The dependencies of the unregistered package (here `MacroTools`) got installed. +For unregistered packages we could have given a branch name (or commit SHA1) to track using `#`, just like for registered packages. + +If you want to add a package using the SSH-based `git` protocol, you have to use quotes because the URL contains a `@`. For example, +```julia-repl +(v1.0) pkg> add "git@github.com:fredrikekre/ImportMacros.jl.git" + Cloning git-repo `git@github.com:fredrikekre/ImportMacros.jl.git` + Updating git-repo `git@github.com:fredrikekre/ImportMacros.jl.git` + Updating registry at `~/.julia/registries/General` + Resolving package versions... +Updating `~/.julia/environments/v1/Project.toml` + [92a963f6] + ImportMacros v1.0.0 `git@github.com:fredrikekre/ImportMacros.jl.git#master` +Updating `~/.julia/environments/v1/Manifest.toml` + [92a963f6] + ImportMacros v1.0.0 `git@github.com:fredrikekre/ImportMacros.jl.git#master` +``` + +### Adding a local package + +Instead of giving a URL of a git repo to `add` we could instead have given a local path to a git repo. +This works similar to adding a URL. The local repository will be tracked (at some branch) and updates +from that local repo are pulled when packages are updated. +Note tracking a package through `add` is distinct from `develop`: +changes to files in the local package repository will not immediately be reflected when loading that package. +The changes would have to be committed and the packages updated in order to pull in the changes. + +In addition, it is possible to add packages relatively to the `Manifest.toml` file, see [Developing packages](@ref developing) for an example. + +### [Developing packages](@id developing) + +By only using `add` your Manifest will always have a "reproducible state", in other words, as long as the repositories and registries used are still accessible +it is possible to retrieve the exact state of all the dependencies in the project. This has the advantage that you can send your project (`Project.toml` +and `Manifest.toml`) to someone else and they can "instantiate" that project in the same state as you had it locally. +However, when you are developing a package, it is more convenient to load packages at their current state at some path. For this reason, the `dev` command exists. + +Let's try to `dev` a registered package: + +```julia-repl +(v1.0) pkg> dev Example + Updating git-repo `https://github.com/JuliaLang/Example.jl.git` + Resolving package versions... + Updating `~/.julia/environments/v1.0/Project.toml` + [7876af07] + Example v0.5.1+ [`~/.julia/dev/Example`] + Updating `~/.julia/environments/v1.0/Manifest.toml` + [7876af07] + Example v0.5.1+ [`~/.julia/dev/Example`] +``` + +The `dev` command fetches a full clone of the package to `~/.julia/dev/` (the path can be changed by setting the environment variable `JULIA_PKG_DEVDIR`). +When importing `Example` julia will now import it from `~/.julia/dev/Example` and whatever local changes have been made to the files in that path are consequently +reflected in the code loaded. When we used `add` we said that we tracked the package repository, we here say that we track the path itself. +Note the package manager will never touch any of the files at a tracked path. It is therefore up to you to pull updates, change branches etc. +If we try to `dev` a package at some branch that already exists at `~/.julia/dev/` the package manager we will simply use the existing path. +For example: + +```julia-repl +(v1.0) pkg> dev Example + Updating git-repo `https://github.com/JuliaLang/Example.jl.git` +[ Info: Path `/Users/kristoffer/.julia/dev/Example` exists and looks like the correct package, using existing path instead of cloning +``` + +Note the info message saying that it is using the existing path. +When tracking a path, the package manager will never modify the files at that path. + +If `dev` is used on a local path, that path to that package is recorded and used when loading that package. +The path will be recorded relative to the project file, unless it is given as an absolute path. + +To stop tracking a path and use the registered version again, use `free`: + +```julia-repl +(v1.0) pkg> free Example + Resolving package versions... + Updating `~/.julia/environments/v1.0/Project.toml` + [7876af07] ↓ Example v0.5.1+ [`~/.julia/dev/Example`] ⇒ v0.5.1 + Updating `~/.julia/environments/v1.0/Manifest.toml` + [7876af07] ↓ Example v0.5.1+ [`~/.julia/dev/Example`] ⇒ v0.5.1 +``` + +It should be pointed out that by using `dev` your project is now inherently stateful. +Its state depends on the current content of the files at the path and the manifest cannot be "instantiated" by someone else without +knowing the exact content of all the packages that are tracking a path. + +Note that if you add a dependency to a package that tracks a local path, the Manifest (which contains the whole dependency graph) will become +out of sync with the actual dependency graph. This means that the package will not be able to load that dependency since it is not recorded +in the Manifest. To synchronize the Manifest, use the REPL command `resolve`. + +In addition to absolute paths, `add` and `dev` can accept relative paths to packages. +In this case, the relative path from the active project to the package is stored. +This approach is useful when the relative location of tracked dependencies is more important than their absolute location. +For example, the tracked dependencies can be stored inside of the active project directory. +The whole directory can be moved and `Pkg` will still be able to find the dependencies +because their path relative to the active project is preserved even though their absolute path has changed. + +## Removing packages + +Packages can be removed from the current project by using `pkg> rm Package`. +This will only remove packages that exist in the project; to remove a package that only +exists as a dependency use `pkg> rm --manifest DepPackage`. +Note that this will remove all packages that depend on `DepPackage`. + +## [Updating packages](@id updating) + +When new versions of packages that the project is using are released, it is a good idea to update. Simply calling `up` will try to update *all* the dependencies of the project +to the latest compatible version. Sometimes this is not what you want. You can specify a subset of the dependencies to upgrade by giving them as arguments to `up`, e.g: + +```julia-repl +(v1.0) pkg> up Example +``` + +If `Example` has a dependency which is also a dependency for another explicitly added package, that dependency will not be updated. If you only want to update the minor version of packages, to reduce the risk that your project breaks, you can give the `--minor` flag, e.g: + +```julia-repl +(v1.0) pkg> up --minor Example +``` + +Packages that track a local repository are not updated when a minor upgrade is done. +Packages that track a path are never touched by the package manager. + +## Pinning a package + +A pinned package will never be updated. A package can be pinned using `pin`, for example: + +```julia-repl +(v1.0) pkg> pin Example + Resolving package versions... + Updating `~/.julia/environments/v1.0/Project.toml` + [7876af07] ~ Example v0.5.1 ⇒ v0.5.1 ⚲ + Updating `~/.julia/environments/v1.0/Manifest.toml` + [7876af07] ~ Example v0.5.1 ⇒ v0.5.1 ⚲ +``` + +Note the pin symbol `⚲` showing that the package is pinned. Removing the pin is done using `free` + +```julia-repl +(v1.0) pkg> free Example + Updating `~/.julia/environments/v1.0/Project.toml` + [7876af07] ~ Example v0.5.1 ⚲ ⇒ v0.5.1 + Updating `~/.julia/environments/v1.0/Manifest.toml` + [7876af07] ~ Example v0.5.1 ⚲ ⇒ v0.5.1 +``` + +## Testing packages + +The tests for a package can be run using `test`command: + +```julia-repl +(v1.0) pkg> test Example + Testing Example + Testing Example tests passed +``` + +## Building packages + +The build step of a package is automatically run when a package is first installed. +The output of the build process is directed to a file. +To explicitly run the build step for a package, the `build` command is used: + +```julia-repl +(v1.0) pkg> build MbedTLS + Building MbedTLS → `~/.julia/packages/MbedTLS/h1Vu/deps/build.log` + +julia> print(read("~/.julia/packages/MbedTLS/h1Vu/deps/build.log", String)) +┌ Warning: `wait(t::Task)` is deprecated, use `fetch(t)` instead. +│ caller = macro expansion at OutputCollector.jl:63 [inlined] +└ @ Core OutputCollector.jl:63 +... +[ Info: using prebuilt binaries +``` + +## [Interpreting and resolving version conflicts](@id conflicts) + +An environment consists of a set of mutually-compatible packages. +Sometimes, you can find yourself in a situation in which two packages you'd like to use simultaneously +have incompatible requirements. +In such cases you'll get an "Unsatisfiable requirements" error: + +```@setup conflict +using Pkg +include(joinpath(pkgdir(Pkg), "test", "resolve_utils.jl")) +using .ResolveUtils +deps_data = Any[["A", v"1.0.0", "C", v"0.2"], + ["B", v"1.0.0", "D", v"0.1"], + ["C", v"0.1.0", "D", v"0.1"], + ["C", v"0.1.1", "D", v"0.1"], + ["C", v"0.2.0", "D", v"0.2"], + ["D", v"0.1.0"], + ["D", v"0.2.0"], + ["D", v"0.2.1"]] +reqs_data = Any[["A", "*"], + ["B", "*"]] +``` + +```@example conflict +print("pkg> add A\n", try resolve_tst(deps_data, reqs_data) catch e sprint(showerror, e) end) # hide +``` + +This message means that a package named `D` has a version conflict. +Even if you have never `add`ed `D` directly, this kind of error can arise +if `D` is required by other packages that you are trying to use. + +The error message has a lot of crucial information. +It may be easiest to interpret piecewise: + +``` +Unsatisfiable requirements detected for package D [756980fe]: + D [756980fe] log: + ├─possible versions are: [0.1.0, 0.2.0-0.2.1] or uninstalled +``` +means that `D` has three released versions, `v0.1.0`, `v0.2.0`, and `v0.2.1`. +You also have the option of not having it installed at all. +Each of these options might have different implications for the set of other packages that can be installed. + +Crucially, notice the stroke characters (vertical and horizontal lines) and their indentation. +Together, these connect *messages* to specific *packages*. +For instance the right stroke of `├─` indicates that the message to its right (`possible versions...`) +is connected to the package pointed to by its vertical stroke (`D`). +This same principle applies to the next line: + +``` + ├─restricted by compatibility requirements with B [f4259836] to versions: 0.1.0 +``` +The vertical stroke here is also aligned under `D`, and thus this message +is in reference to `D`. +Specifically, there's some other package `B` that depends on version `v0.1.0` of `D`. +Notice that this is not the newest version of `D`. + +Next comes some information about `B`: + +``` + │ └─B [f4259836] log: + │ ├─possible versions are: 1.0.0 or uninstalled + │ └─restricted to versions * by an explicit requirement, leaving only versions 1.0.0 +``` +The two lines below the first have a vertical stroke that aligns with `B`, +and thus they provide information about `B`. +They tell you that `B` has just one release, `v1.0.0`. +You've not specified a particular version of `B` (`restricted to versions *` means that any version will do), +but the `explicit requirement` means that you've asked for `B` to be part of your environment, +for example by `pkg> add B`. +You might have asked for `B` previously, and the requirement is still active. + +The conflict becomes clear with the line +``` +└─restricted by compatibility requirements with C [c99a7cb2] to versions: 0.2.0 — no versions left +``` + +Here again the vertical stroke aligns with `D`: this means that `D` is *also* required by another package, `C`. +`C` requires `v0.2.0` of `D`, and this conflicts with `B`'s need for `v0.1.0` of `D`. +This explains the conflict. + +But wait, you might ask, what is `C` and why do I need it at all? +The next few lines introduce the problem: + +``` + └─C [c99a7cb2] log: + ├─possible versions are: [0.1.0-0.1.1, 0.2.0] or uninstalled + └─restricted by compatibility requirements with A [29c70717] to versions: 0.2.0 +``` +These provide more information about `C`, revealing that it has 3 released versions: `v0.1.0`, `v0.1.1`, and `v0.2.0`. +Moreover, `C` is required by another package `A`. +Indeed, `A`'s requirements are such that we need `v0.2.0` of `C`. +`A`'s origin is revealed on the next lines: + +``` + └─A [29c70717] log: + ├─possible versions are: 1.0.0 or uninstalled + └─restricted to versions * by an explicit requirement, leaving only versions 1.0.0 +``` + +So we can see that `A` was `explicitly required`, and in this case it's because we were trying to +`add` it to our environment. + +In summary, we explicitly asked to use `A` and `B`, but this gave a conflict for `D`. +The reason was that `B` and `C` require conflicting versions of `D`. +Even though `C` isn't something we asked for explicitly, it was needed by `A`. + +To fix such errors, you have a number of options: + +- try [updating your packages](@ref updating). It's possible the developers of these packages have recently released new versions that are mutually compatible. +- remove either `A` or `B` from your environment. Perhaps `B` is left over from something you were previously working on, and you don't need it anymore. If you don't need `A` and `B` at the same time, this is the easiest way to fix the problem. +- try reporting your conflict. In this case, we were able to deduce that `B` requires an outdated version of `D`. You could thus report an issue in the development repository of `B.jl` asking for an updated version. +- try fixing the problem yourself. + This becomes easier once you understand `Project.toml` files and how they declare their compatiblity requirements. We'll return to this example in [Fixing conflicts](@ref). + +## Garbage collecting old, unused packages + +As packages are updated and projects are deleted, installed package versions and artifacts that were +once used will inevitably become old and not used from any existing project. +`Pkg` keeps a log of all projects used so it can go through the log and see exactly which projects still exist +and what packages/artifacts those projects used. +If a package or artifact is not marked as used by any project, it is added to a list of orphaned packages. +Packages and artifacts that are in the orphan list for 30 days without being used again are deleted from the system on the next garbage collection. +This timing is configurable via the `collect_delay` keyword argument to `Pkg.gc()`. +A value of `0` will cause anything currently not in use immediately, skipping the orphans list entirely; +If you are short on disk space and want to clean out as many unused packages and artifacts as possible, you may want to try this, but if you need these versions again, you will have to download them again. +To run a typical garbage collection with default arguments, simply use the `gc` command at the `pkg>` REPL: + +```julia-repl +(v1.0) pkg> gc + Active manifests at: + `~/BinaryProvider/Manifest.toml` + ... + `~/Compat.jl/Manifest.toml` + Active artifacts: + `~/src/MyProject/Artifacts.toml` + + Deleted ~/.julia/packages/BenchmarkTools/1cAj: 146.302 KiB + Deleted ~/.julia/packages/Cassette/BXVB: 795.557 KiB + ... + Deleted `~/.julia/artifacts/e44cdf2579a92ad5cbacd1cddb7414c8b9d2e24e` (152.253 KiB) + Deleted `~/.julia/artifacts/f2df5266567842bbb8a06acca56bcabf813cd73f` (21.536 MiB) + + Deleted 36 package installations (113.205 MiB) + Deleted 15 artifact installations (20.759 GiB) +``` + +Note that only packages in `~/.julia/packages` are deleted. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/registries.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/registries.md new file mode 100644 index 0000000..be6f8e2 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/registries.md @@ -0,0 +1,81 @@ +# **7.** Registries + +Registries contain information about packages, such as +available releases and dependencies, and where they can be downloaded. +The `General` registry (https://github.com/JuliaRegistries/General) +is the default one, and is installed automatically. + +## Managing registries + +!!! compat "Julia 1.1" + Pkg's registry handling requires at least Julia 1.1. + +Registries can be added, removed and updated from either the Pkg REPL +or by using the function based API. In this section we will describe the +REPL interface. The registry API is documented in +the [Registry API Reference](@ref) section. + +### Adding registries + +A custom registry can be added with the `registry add` command +from the Pkg REPL. Usually this will be done with a URL to the +registry. Here we add the `General` registry: + +```julia-repl +pkg> registry add https://github.com/JuliaRegistries/General + Cloning registry from "https://github.com/JuliaRegistries/General" + Added registry `General` to `~/.julia/registries/General` +``` + +and now all the packages registered in `General` are available for e.g. adding. +To see which registries are currently installed you can use the `registry status` +(or `registry st`) command + +```julia-repl +pkg> registry st +Registry Status + [23338594] General (https://github.com/JuliaRegistries/General.git) +``` + +Registries are always added to the user depot, which is the first entry in `DEPOT_PATH` (cf. the [Glossary](@ref) section). + +### Removing registries + +Registries can be removed with the `registry remove` (or `registry rm`) command. +Here we remove the `General` registry + +```julia-repl +pkg> registry rm General + Removing registry `General` from ~/.julia/registries/General + +pkg> registry st +Registry Status + (no registries found) +``` + +In case there are multiple registries named `General` installed you have to +disambiguate with the `uuid`, just as when manipulating packages, e.g. + +```julia-repl +pkg> registry rm General=23338594-aafe-5451-b93e-139f81909106 + Removing registry `General` from ~/.julia/registries/General +``` + +### Updating registries + +The `registry update` (or `registry up`) command is available to update registries. +Here we update the `General` registry: + +```julia-repl +pkg> registry up General + Updating registry at `~/.julia/registries/General` + Updating git-repo `https://github.com/JuliaRegistries/General` +``` + +and to update all installed registries just do: + +```julia-repl +pkg> registry up + Updating registry at `~/.julia/registries/General` + Updating git-repo `https://github.com/JuliaRegistries/General` +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/toml-files.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/toml-files.md new file mode 100644 index 0000000..d79f9ef --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/toml-files.md @@ -0,0 +1,270 @@ +# [**10.** `Project.toml` and `Manifest.toml`](@id Project-and-Manifest) + +Two files that are central to Pkg are `Project.toml` and `Manifest.toml`. `Project.toml` +and `Manifest.toml` are written in [TOML](https://github.com/toml-lang/toml) (hence the +`.toml` extension) and include information about dependencies, versions, package names, +UUIDs etc. + +!!! note + The `Project.toml` and `Manifest.toml` files are not only used by the package manager; + they are also used by Julia's code loading, and determine e.g. what `using Example` + should do. For more details see the section about + [Code Loading](https://docs.julialang.org/en/v1/manual/code-loading/) + in the Julia manual. + + +## `Project.toml` + +The project file describes the project on a high level, for example the package/project +dependencies and compatibility constraints are listed in the project file. The file entries +are described below. + + +### The `authors` field + +For a package, the optional `authors` field is a list of strings describing the +package authors, in the form `NAME <EMAIL>`. For example: +```toml +authors = ["Some One <someone@email.com>", + "Foo Bar <foo@bar.com>"] +``` + + +### The `name` field + +The name of the package/project is determined by the `name` field, for example: +```toml +name = "Example" +``` +The name can contain word characters `[a-zA-Z0-9_]`, but can not start with a number. For +packages it is recommended to follow the +[package naming guidelines](@ref Package-naming-guidelines). The `name` field is mandatory +for packages. + + +### The `uuid` field + +`uuid` is a string with a [universally unique identifier] +(https://en.wikipedia.org/wiki/Universally_unique_identifier) for the package/project, for example: +```toml +uuid = "7876af07-990d-54b4-ab0e-23690620f79a" +``` +The `uuid` field is mandatory for packages. + +!!! note + It is recommended that `UUIDs.uuid4()` is used to generate random UUIDs. + + +### The `version` field + +`version` is a string with the version number for the package/project. It should consist of +three numbers, major version, minor version and patch number, separated with a `.`, for example: +```toml +version = "1.2.5" +``` +Julia uses [Semantic Versioning](https://semver.org/) (SemVer) and the `version` field +should follow SemVer. The basic rules are: +* Before 1.0.0, anything goes, but when you make breaking changes the minor version should + be incremented. +* After 1.0.0 only make breaking changes when incrementing the major version. +* After 1.0.0 no new public API should be added without incrementing the minor version. + This includes, in particular, new types, functions, methods and method overloads, from + `Base` or other packages. +See also the section on [Compatibility](@ref). + +Note that Pkg.jl deviates from the SemVer specification when it comes to versions pre-1.0.0. See +the section on [pre-1.0 behavior](@ref compat-pre-1.0) for more details. + + +### The `[deps]` section + +All dependencies of the package/project are listed in the `[deps]` section. Each dependency +is listed as a name-uuid pair, for example: + +```toml +[deps] +Example = "7876af07-990d-54b4-ab0e-23690620f79a" +Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" +``` + +Typically it is not needed to manually add entries to the `[deps]` section; this is instead +handled by Pkg operations such as `add`. + + +### The `[compat]` section + +Compatibility constraints for the dependencies listed under `[deps]` can be listed in the +`[compat]` section. +Example: + +```toml +[deps] +Example = "7876af07-990d-54b4-ab0e-23690620f79a" + +[compat] +Example = "1.2" +``` + +The [Compatibility](@ref) section describes the different possible compatibility +constraints in detail. It is also possible to list constraints on `julia` itself, although +`julia` is not listed as a dependency in the `[deps]` section: + +```toml +[compat] +julia = "1.1" +``` + + +## `Manifest.toml` + +The manifest file is an absolute record of the state of the packages in the environment. +It includes exact information about (direct and indirect) dependencies of the project. +Given a `Project.toml` + `Manifest.toml` pair, it is possible to instantiate the exact same +package environment, which is very useful for reproducibility. +For the details, see [`Pkg.instantiate`](@ref). + +!!! note + The `Manifest.toml` file is generated and maintained by Pkg and, in general, this file + should *never* be modified manually. + + +### `Manifest.toml` entries + +Each dependency has its own section in the manifest file, and its content varies depending +on how the dependency was added to the environment. Every +dependency section includes a combination of the following entries: + +* `uuid`: the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) + for the dependency, for example `uuid = "7876af07-990d-54b4-ab0e-23690620f79a"`. +* `deps`: a vector listing the dependencies of the dependency, for example + `deps = ["Example", "JSON"]`. +* `version`: a version number, for example `version = "1.2.6"`. +* `path`: a file path to the source code, for example `path = /home/user/Example`. +* `repo-url`: a URL to the repository where the source code was found, + for example `repo-url = "https://github.com/JuliaLang/Example.jl.git"`. +* `repo-rev`: a git revision, for example a branch `repo-rev = "master"` + or a commit `repo-rev = "66607a62a83cb07ab18c0b35c038fcd62987c9b1"`. +* `git-tree-sha1`: a content hash of the source tree, for example + `git-tree-sha1 = "ca3820cc4e66f473467d912c4b2b3ae5dc968444"`. + + +#### Added package + +When a package is added from a package registry, for example by invoking `pkg> add Example` +or with a specific version `pkg> add Example@1.2`, the resulting `Manifest.toml` entry looks +like: + +```toml +[[Example]] +deps = ["DependencyA", "DependencyB"] +git-tree-sha1 = "8eb7b4d4ca487caade9ba3e85932e28ce6d6e1f8" +uuid = "7876af07-990d-54b4-ab0e-23690620f79a" +version = "1.2.3" +``` + +Note, in particular, that no `repo-url` is present, since that information is included in +the registry where this package were found. + +#### Added package by branch + +The resulting dependency section when adding a package specified by a branch, e.g. +`pkg> add Example#master` or `pkg> add https://github.com/JuliaLang/Example.jl.git`, +looks like: + +```toml +[[Example]] +deps = ["DependencyA", "DependencyB"] +git-tree-sha1 = "54c7a512469a38312a058ec9f429e1db1f074474" +repo-rev = "master" +repo-url = "https://github.com/JuliaLang/Example.jl.git" +uuid = "7876af07-990d-54b4-ab0e-23690620f79a" +version = "1.2.4" +``` + +Note that both the branch we are tracking (`master`) and the remote repository url +(`"https://github.com/JuliaLang/Example.jl.git"`) are stored in the manifest. + +#### Added package by commit + +The resulting dependency section when adding a package specified by a commit, e.g. +`pkg> add Example#cf6ba6cc0be0bb5f56840188563579d67048be34`, looks like: + +```toml +[[Example]] +deps = ["DependencyA", "DependencyB"] +git-tree-sha1 = "54c7a512469a38312a058ec9f429e1db1f074474" +repo-rev = "cf6ba6cc0be0bb5f56840188563579d67048be34" +repo-url = "https://github.com/JuliaLang/Example.jl.git" +uuid = "7876af07-990d-54b4-ab0e-23690620f79a" +version = "1.2.4" +``` + +The only difference from tracking a branch is the content of `repo-rev`. + +#### Developed package + +The resulting dependency section when adding a package with `develop`, +e.g. `pkg> develop Example` or `pkg> develop /path/to/local/folder/Example`, +looks like: + +```toml +[[Example]] +deps = ["DependencyA", "DependencyB"] +path = "/home/user/.julia/dev/Example/" +uuid = "7876af07-990d-54b4-ab0e-23690620f79a" +version = "1.2.4" +``` + +Note that the path to the source code is included, and changes made to that +source tree is directly reflected. + +#### Pinned package + +Pinned packages are also recorded in the manifest file; the resulting +dependency section for e.g. `pkg> add Example; pin Example` looks like: + +```toml +[[Example]] +deps = ["DependencyA", "DependencyB"] +git-tree-sha1 = "54c7a512469a38312a058ec9f429e1db1f074474" +pinned = true +uuid = "7876af07-990d-54b4-ab0e-23690620f79a" +version = "1.2.4" +``` + +The only difference is the addition of the `pinned = true` entry. + +#### Multiple package with the same name + +Julia differentiates packages based on UUID, which means that the name alone is not enough +to identify a package. It is possible to have multiple packages in the same environment +with the same name, but with different UUID. In such a situation the `Manifest.toml` file +looks a bit different. Consider for example the situation where you have added `A` and `B` +to your environment, and the `Project.toml` file looks as follows: + +```toml +[deps] +A = "ead4f63c-334e-11e9-00e6-e7f0a5f21b60" +B = "edca9bc6-334e-11e9-3554-9595dbb4349c" +``` + +If `A` now depends on `B = "f41f7b98-334e-11e9-1257-49272045fb24"`, i.e. *another* package +named `B` there will be two different `B` packages in the `Manifest.toml` file. In this +case the full `Manifest.toml` file, with `git-tree-sha1` and `version` fields removed for +clarity, looks like: + +```toml +[[A]] +uuid = "ead4f63c-334e-11e9-00e6-e7f0a5f21b60" + + [A.deps] + B = "f41f7b98-334e-11e9-1257-49272045fb24" + +[[B]] +uuid = "f41f7b98-334e-11e9-1257-49272045fb24" +[[B]] +uuid = "edca9bc6-334e-11e9-3554-9595dbb4349c" +``` + +There is now an array of the two `B` packages, and the `[deps]` section for `A` has been +expanded in order to be explicit about which `B` package `A` depends on. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/SameNameDifferentUUID/dev/Unregistered/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/SameNameDifferentUUID/dev/Unregistered/README.md new file mode 100644 index 0000000..26b9f8d --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/SameNameDifferentUUID/dev/Unregistered/README.md @@ -0,0 +1,2 @@ +# Unregistered.jl +Test repo diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/SandboxFallback2/dev/Unregistered/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/SandboxFallback2/dev/Unregistered/README.md new file mode 100644 index 0000000..26b9f8d --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/SandboxFallback2/dev/Unregistered/README.md @@ -0,0 +1,2 @@ +# Unregistered.jl +Test repo diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/TestDepTrackingPath/test/dev/Unregistered/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/TestDepTrackingPath/test/dev/Unregistered/README.md new file mode 100644 index 0000000..26b9f8d --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/TestDepTrackingPath/test/dev/Unregistered/README.md @@ -0,0 +1,2 @@ +# Unregistered.jl +Test repo diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/TransferSubgraph/dev/Unregistered/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/TransferSubgraph/dev/Unregistered/README.md new file mode 100644 index 0000000..26b9f8d --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/test/test_packages/TransferSubgraph/dev/Unregistered/README.md @@ -0,0 +1,2 @@ +# Unregistered.jl +Test repo diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Printf/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Printf/docs/src/index.md new file mode 100644 index 0000000..828e527 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Printf/docs/src/index.md @@ -0,0 +1,6 @@ +# Printf + +```@docs +Printf.@printf +Printf.@sprintf +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Profile/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Profile/docs/src/index.md new file mode 100644 index 0000000..ac60bb9 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Profile/docs/src/index.md @@ -0,0 +1,17 @@ +# [Profiling](@id lib-profiling) + +```@docs +Profile.@profile +``` + +The methods in `Profile` are not exported and need to be called e.g. as `Profile.print()`. + +```@docs +Profile.clear +Profile.print +Profile.init +Profile.fetch +Profile.retrieve +Profile.callers +Profile.clear_malloc_data +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/REPL/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/REPL/docs/src/index.md new file mode 100644 index 0000000..168d3e9 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/REPL/docs/src/index.md @@ -0,0 +1,692 @@ +# The Julia REPL + +Julia comes with a full-featured interactive command-line REPL (read-eval-print loop) built into +the `julia` executable. In addition to allowing quick and easy evaluation of Julia statements, +it has a searchable history, tab-completion, many helpful keybindings, and dedicated help and +shell modes. The REPL can be started by simply calling `julia` with no arguments or double-clicking +on the executable: + +```@eval +io = IOBuffer() +Base.banner(io) +banner = String(take!(io)) +import Markdown +Markdown.parse("```\n\$ julia\n\n$(banner)\njulia>\n```") +``` + +To exit the interactive session, type `^D` -- the control key together with the `d` key on a blank +line -- or type `exit()` followed by the return or enter key. The REPL greets you with a banner +and a `julia>` prompt. + +## The different prompt modes + +### The Julian mode + +The REPL has five main modes of operation. The first and most common is the Julian prompt. It +is the default mode of operation; each new line initially starts with `julia>`. It is here that +you can enter Julia expressions. Hitting return or enter after a complete expression has been +entered will evaluate the entry and show the result of the last expression. + +```jldoctest +julia> string(1 + 2) +"3" +``` + +There are a number useful features unique to interactive work. In addition to showing the result, +the REPL also binds the result to the variable `ans`. A trailing semicolon on the line can be +used as a flag to suppress showing the result. + +```jldoctest +julia> string(3 * 4); + +julia> ans +"12" +``` + +In Julia mode, the REPL supports something called *prompt pasting*. This activates when pasting +text that starts with `julia> ` into the REPL. In that case, only expressions starting with +`julia> ` are parsed, others are removed. This makes it possible to paste a chunk of code +that has been copied from a REPL session without having to scrub away prompts and outputs. This +feature is enabled by default but can be disabled or enabled at will with `REPL.enable_promptpaste(::Bool)`. +If it is enabled, you can try it out by pasting the code block above this paragraph straight into +the REPL. This feature does not work on the standard Windows command prompt due to its limitation +at detecting when a paste occurs. + +Objects are printed at the REPL using the [`show`](@ref) function with a specific [`IOContext`](@ref). +In particular, the `:limit` attribute is set to `true`. +Other attributes can receive in certain `show` methods a default value if it's not already set, +like `:compact`. +It's possible, as an experimental feature, to specify the attributes used by the REPL via the +`Base.active_repl.options.iocontext` dictionary (associating values to attributes). For example: + +```julia-repl +julia> rand(2, 2) +2×2 Array{Float64,2}: + 0.8833 0.329197 + 0.719708 0.59114 + +julia> show(IOContext(stdout, :compact => false), "text/plain", rand(2, 2)) + 0.43540323669187075 0.15759787870609387 + 0.2540832269192739 0.4597637838786053 +julia> Base.active_repl.options.iocontext[:compact] = false; + +julia> rand(2, 2) +2×2 Array{Float64,2}: + 0.2083967319174056 0.13330606013126012 + 0.6244375177790158 0.9777957560761545 +``` + +In order to define automatically the values of this dictionary at startup time, one can use the +[`atreplinit`](@ref) function in the `~/.julia/config/startup.jl` file, for example: +```julia +atreplinit() do repl + repl.options.iocontext[:compact] = false +end +``` + +### Help mode + +When the cursor is at the beginning of the line, the prompt can be changed to a help mode by typing +`?`. Julia will attempt to print help or documentation for anything entered in help mode: + +```julia-repl +julia> ? # upon typing ?, the prompt changes (in place) to: help?> + +help?> string +search: string String Cstring Cwstring RevString randstring bytestring SubString + + string(xs...) + + Create a string from any values using the print function. +``` + +Macros, types and variables can also be queried: + +``` +help?> @time + @time + + A macro to execute an expression, printing the time it took to execute, the number of allocations, + and the total number of bytes its execution caused to be allocated, before returning the value of the + expression. + + See also @timev, @timed, @elapsed, and @allocated. + +help?> Int32 +search: Int32 UInt32 + + Int32 <: Signed + + 32-bit signed integer type. +``` + +A string or regex literal searches all docstrings using [`apropos`](@ref): + +``` +help?> "aprop" +REPL.stripmd +Base.Docs.apropos + +help?> r"ap..p" +Base.:∘ +Base.shell_escape_posixly +Distributed.CachingPool +REPL.stripmd +Base.Docs.apropos +``` + +Help mode can be exited by pressing backspace at the beginning of the line. + +### [Shell mode](@id man-shell-mode) + +Just as help mode is useful for quick access to documentation, another common task is to use the +system shell to execute system commands. Just as `?` entered help mode when at the beginning +of the line, a semicolon (`;`) will enter the shell mode. And it can be exited by pressing backspace +at the beginning of the line. + +```julia-repl +julia> ; # upon typing ;, the prompt changes (in place) to: shell> + +shell> echo hello +hello +``` +!!! note + For Windows users, Julia's shell mode does not expose windows shell commands. + Hence, this will fail: + +```julia-repl +julia> ; # upon typing ;, the prompt changes (in place) to: shell> + +shell> dir +ERROR: IOError: could not spawn `dir`: no such file or directory (ENOENT) +Stacktrace! +....... +``` +However, you can get access to `PowerShell` like this: +```julia-repl +julia> ; # upon typing ;, the prompt changes (in place) to: shell> + +shell> powershell +Windows PowerShell +Copyright (C) Microsoft Corporation. All rights reserved. +PS C:\Users\elm> +``` +... and to `cmd.exe` like that (see the `dir` command): +```julia-repl +julia> ; # upon typing ;, the prompt changes (in place) to: shell> + +shell> cmd +Microsoft Windows [version 10.0.17763.973] +(c) 2018 Microsoft Corporation. All rights reserved. +C:\Users\elm>dir + Volume in drive C has no label + Volume Serial Number is 1643-0CD7 + Directory of C:\Users\elm + +29/01/2020 22:15 <DIR> . +29/01/2020 22:15 <DIR> .. +02/02/2020 08:06 <DIR> .atom +``` + +### Pkg mode + +The Package manager mode accepts specialized commands for loading and updating packages. It is entered +by pressing the `]` key at the Julian REPL prompt and exited by pressing CTRL-C or pressing the backspace key +at the beginning of the line. The prompt for this mode is `pkg>`. It supports its own help-mode, which is +entered by pressing `?` at the beginning of the line of the `pkg>` prompt. The Package manager mode is +documented in the Pkg manual, available at [https://julialang.github.io/Pkg.jl/v1/](https://julialang.github.io/Pkg.jl/v1/). + +### Search modes + +In all of the above modes, the executed lines get saved to a history file, which can be searched. + To initiate an incremental search through the previous history, type `^R` -- the control key +together with the `r` key. The prompt will change to ```(reverse-i-search)`':```, and as you +type the search query will appear in the quotes. The most recent result that matches the query +will dynamically update to the right of the colon as more is typed. To find an older result using +the same query, simply type `^R` again. + +Just as `^R` is a reverse search, `^S` is a forward search, with the prompt ```(i-search)`':```. + The two may be used in conjunction with each other to move through the previous or next matching +results, respectively. + +## Key bindings + +The Julia REPL makes great use of key bindings. Several control-key bindings were already introduced +above (`^D` to exit, `^R` and `^S` for searching), but there are many more. In addition to the +control-key, there are also meta-key bindings. These vary more by platform, but most terminals +default to using alt- or option- held down with a key to send the meta-key (or can be configured +to do so), or pressing Esc and then the key. + +| Keybinding | Description | +|:------------------- |:---------------------------------------------------------------------------------------------------------- | +| **Program control** | | +| `^D` | Exit (when buffer is empty) | +| `^C` | Interrupt or cancel | +| `^L` | Clear console screen | +| Return/Enter, `^J` | New line, executing if it is complete | +| meta-Return/Enter | Insert new line without executing it | +| `?` or `;` | Enter help or shell mode (when at start of a line) | +| `^R`, `^S` | Incremental history search, described above | +| **Cursor movement** | | +| Right arrow, `^F` | Move right one character | +| Left arrow, `^B` | Move left one character | +| ctrl-Right, `meta-F`| Move right one word | +| ctrl-Left, `meta-B` | Move left one word | +| Home, `^A` | Move to beginning of line | +| End, `^E` | Move to end of line | +| Up arrow, `^P` | Move up one line (or change to the previous history entry that matches the text before the cursor) | +| Down arrow, `^N` | Move down one line (or change to the next history entry that matches the text before the cursor) | +| Shift-Arrow Key | Move cursor according to the direction of the Arrow key, while activating the region ("shift selection") | +| Page-up, `meta-P` | Change to the previous history entry | +| Page-down, `meta-N` | Change to the next history entry | +| `meta-<` | Change to the first history entry (of the current session if it is before the current position in history) | +| `meta->` | Change to the last history entry | +| `^-Space` | Set the "mark" in the editing region (and de-activate the region if it's active) | +| `^-Space ^-Space` | Set the "mark" in the editing region and make the region "active", i.e. highlighted | +| `^G` | De-activate the region (i.e. make it not highlighted) | +| `^X^X` | Exchange the current position with the mark | +| **Editing** | | +| Backspace, `^H` | Delete the previous character, or the whole region when it's active | +| Delete, `^D` | Forward delete one character (when buffer has text) | +| meta-Backspace | Delete the previous word | +| `meta-d` | Forward delete the next word | +| `^W` | Delete previous text up to the nearest whitespace | +| `meta-w` | Copy the current region in the kill ring | +| `meta-W` | "Kill" the current region, placing the text in the kill ring | +| `^K` | "Kill" to end of line, placing the text in the kill ring | +| `^Y` | "Yank" insert the text from the kill ring | +| `meta-y` | Replace a previously yanked text with an older entry from the kill ring | +| `^T` | Transpose the characters about the cursor | +| `meta-Up arrow` | Transpose current line with line above | +| `meta-Down arrow` | Transpose current line with line below | +| `meta-u` | Change the next word to uppercase | +| `meta-c` | Change the next word to titlecase | +| `meta-l` | Change the next word to lowercase | +| `^/`, `^_` | Undo previous editing action | +| `^Q` | Write a number in REPL and press `^Q` to open editor at corresponding stackframe or method | +| `meta-Left Arrow` | indent the current line on the left | +| `meta-Right Arrow` | indent the current line on the right | +| `meta-.` | insert last word from previous history entry | + +### Customizing keybindings + +Julia's REPL keybindings may be fully customized to a user's preferences by passing a dictionary +to `REPL.setup_interface`. The keys of this dictionary may be characters or strings. The key +`'*'` refers to the default action. Control plus character `x` bindings are indicated with `"^x"`. +Meta plus `x` can be written `"\\M-x"` or `"\ex"`, and Control plus `x` can be written +`"\\C-x"` or `"^x"`. +The values of the custom keymap must be `nothing` (indicating +that the input should be ignored) or functions that accept the signature +`(PromptState, AbstractREPL, Char)`. +The `REPL.setup_interface` function must be called before the REPL is initialized, by registering +the operation with [`atreplinit`](@ref) . For example, to bind the up and down arrow keys to move through +history without prefix search, one could put the following code in `~/.julia/config/startup.jl`: + +```julia +import REPL +import REPL.LineEdit + +const mykeys = Dict{Any,Any}( + # Up Arrow + "\e[A" => (s,o...)->(LineEdit.edit_move_up(s) || LineEdit.history_prev(s, LineEdit.mode(s).hist)), + # Down Arrow + "\e[B" => (s,o...)->(LineEdit.edit_move_down(s) || LineEdit.history_next(s, LineEdit.mode(s).hist)) +) + +function customize_keys(repl) + repl.interface = REPL.setup_interface(repl; extra_repl_keymap = mykeys) +end + +atreplinit(customize_keys) +``` + +Users should refer to `LineEdit.jl` to discover the available actions on key input. + +## Tab completion + +In both the Julian and help modes of the REPL, one can enter the first few characters of a function +or type and then press the tab key to get a list all matches: + +```julia-repl +julia> stri[TAB] +stride strides string strip + +julia> Stri[TAB] +StridedArray StridedMatrix StridedVecOrMat StridedVector String +``` + +The tab key can also be used to substitute LaTeX math symbols with their Unicode equivalents, +and get a list of LaTeX matches as well: + +```julia-repl +julia> \pi[TAB] +julia> π +π = 3.1415926535897... + +julia> e\_1[TAB] = [1,0] +julia> e₁ = [1,0] +2-element Array{Int64,1}: + 1 + 0 + +julia> e\^1[TAB] = [1 0] +julia> e¹ = [1 0] +1×2 Array{Int64,2}: + 1 0 + +julia> \sqrt[TAB]2 # √ is equivalent to the sqrt function +julia> √2 +1.4142135623730951 + +julia> \hbar[TAB](h) = h / 2\pi[TAB] +julia> ħ(h) = h / 2π +ħ (generic function with 1 method) + +julia> \h[TAB] +\hat \hermitconjmatrix \hkswarow \hrectangle +\hatapprox \hexagon \hookleftarrow \hrectangleblack +\hbar \hexagonblack \hookrightarrow \hslash +\heartsuit \hksearow \house \hspace + +julia> α="\alpha[TAB]" # LaTeX completion also works in strings +julia> α="α" +``` + +A full list of tab-completions can be found in the [Unicode Input](@ref) section of the manual. + +Completion of paths works for strings and julia's shell mode: + +```julia-repl +julia> path="/[TAB]" +.dockerenv .juliabox/ boot/ etc/ lib/ media/ opt/ root/ sbin/ sys/ usr/ +.dockerinit bin/ dev/ home/ lib64/ mnt/ proc/ run/ srv/ tmp/ var/ +shell> /[TAB] +.dockerenv .juliabox/ boot/ etc/ lib/ media/ opt/ root/ sbin/ sys/ usr/ +.dockerinit bin/ dev/ home/ lib64/ mnt/ proc/ run/ srv/ tmp/ var/ +``` + +Tab completion can help with investigation of the available methods matching the input arguments: + +```julia-repl +julia> max([TAB] # All methods are displayed, not shown here due to size of the list + +julia> max([1, 2], [TAB] # All methods where `Vector{Int}` matches as first argument +max(x, y) in Base at operators.jl:215 +max(a, b, c, xs...) in Base at operators.jl:281 + +julia> max([1, 2], max(1, 2), [TAB] # All methods matching the arguments. +max(x, y) in Base at operators.jl:215 +max(a, b, c, xs...) in Base at operators.jl:281 +``` + +Keywords are also displayed in the suggested methods after `;`, see below line where `limit` +and `keepempty` are keyword arguments: + +```julia-repl +julia> split("1 1 1", [TAB] +split(str::AbstractString; limit, keepempty) in Base at strings/util.jl:302 +split(str::T, splitter; limit, keepempty) where T<:AbstractString in Base at strings/util.jl:277 +``` + +The completion of the methods uses type inference and can therefore see if the arguments match +even if the arguments are output from functions. The function needs to be type stable for the +completion to be able to remove non-matching methods. + +Tab completion can also help completing fields: + +```julia-repl +julia> import UUIDs + +julia> UUIDs.uuid[TAB] +uuid1 uuid4 uuid_version +``` + +Fields for output from functions can also be completed: + +```julia-repl +julia> split("","")[1].[TAB] +lastindex offset string +``` + +The completion of fields for output from functions uses type inference, and it can only suggest +fields if the function is type stable. + +Dictionary keys can also be tab completed: + +```julia-repl +julia> foo = Dict("qwer1"=>1, "qwer2"=>2, "asdf"=>3) +Dict{String,Int64} with 3 entries: + "qwer2" => 2 + "asdf" => 3 + "qwer1" => 1 + +julia> foo["q[TAB] + +"qwer1" "qwer2" +julia> foo["qwer +``` + +## Customizing Colors + +The colors used by Julia and the REPL can be customized, as well. To change the +color of the Julia prompt you can add something like the following to your +`~/.julia/config/startup.jl` file, which is to be placed inside your home directory: + +```julia +function customize_colors(repl) + repl.prompt_color = Base.text_colors[:cyan] +end + +atreplinit(customize_colors) +``` + +The available color keys can be seen by typing `Base.text_colors` in the help mode of the REPL. +In addition, the integers 0 to 255 can be used as color keys for terminals +with 256 color support. + +You can also change the colors for the help and shell prompts and +input and answer text by setting the appropriate field of `repl` in the `customize_colors` function +above (respectively, `help_color`, `shell_color`, `input_color`, and `answer_color`). For the +latter two, be sure that the `envcolors` field is also set to false. + +It is also possible to apply boldface formatting by using +`Base.text_colors[:bold]` as a color. For instance, to print answers in +boldface font, one can use the following as a `~/.julia/config/startup.jl`: + +```julia +function customize_colors(repl) + repl.envcolors = false + repl.answer_color = Base.text_colors[:bold] +end + +atreplinit(customize_colors) +``` + +You can also customize the color used to render warning and informational messages by +setting the appropriate environment variables. For instance, to render error, warning, and informational +messages respectively in magenta, yellow, and cyan you can add the following to your +`~/.julia/config/startup.jl` file: + +```julia +ENV["JULIA_ERROR_COLOR"] = :magenta +ENV["JULIA_WARN_COLOR"] = :yellow +ENV["JULIA_INFO_COLOR"] = :cyan +``` + +## TerminalMenus + +TerminalMenus is a submodule of the Julia REPL and enables small, low-profile interactive menus in the terminal. + +### Examples + +```julia +import REPL +using REPL.TerminalMenus + +options = ["apple", "orange", "grape", "strawberry", + "blueberry", "peach", "lemon", "lime"] + +``` + +#### RadioMenu + +The RadioMenu allows the user to select one option from the list. The `request` +function displays the interactive menu and returns the index of the selected +choice. If a user presses 'q' or `ctrl-c`, `request` will return a `-1`. + + +```julia +# `pagesize` is the number of items to be displayed at a time. +# The UI will scroll if the number of options is greater +# than the `pagesize` +menu = RadioMenu(options, pagesize=4) + +# `request` displays the menu and returns the index after the +# user has selected a choice +choice = request("Choose your favorite fruit:", menu) + +if choice != -1 + println("Your favorite fruit is ", options[choice], "!") +else + println("Menu canceled.") +end + +``` + +Output: + +``` +Choose your favorite fruit: +^ grape + strawberry + > blueberry +v peach +Your favorite fruit is blueberry! +``` + +#### MultiSelectMenu + +The MultiSelectMenu allows users to select many choices from a list. + +```julia +# here we use the default `pagesize` 10 +menu = MultiSelectMenu(options) + +# `request` returns a `Set` of selected indices +# if the menu us canceled (ctrl-c or q), return an empty set +choices = request("Select the fruits you like:", menu) + +if length(choices) > 0 + println("You like the following fruits:") + for i in choices + println(" - ", options[i]) + end +else + println("Menu canceled.") +end +``` + +Output: + +``` +Select the fruits you like: +[press: d=done, a=all, n=none] + [ ] apple + > [X] orange + [X] grape + [ ] strawberry + [ ] blueberry + [X] peach + [ ] lemon + [ ] lime +You like the following fruits: + - orange + - grape + - peach +``` + +### Customization / Configuration + +#### ConfiguredMenu subtypes + +Starting with Julia 1.6, the recommended way to configure menus is via the constructor. +For instance, the default multiple-selection menu + +``` +julia> menu = MultiSelectMenu(options, pagesize=5); + +julia> request(menu) # ASCII is used by default +[press: d=done, a=all, n=none] + [ ] apple + [X] orange + [ ] grape + > [X] strawberry +v [ ] blueberry +``` + +can instead be rendered with Unicode selection and navigation characters with + +```julia +julia> menu = MultiSelectMenu(options, pagesize=5, charset=:unicode); + +julia> request(menu) +[press: d=done, a=all, n=none] + ⬚ apple + ✓ orange + ⬚ grape + → ✓ strawberry +↓ ⬚ blueberry +``` + +More fine-grained configuration is also possible: + +```julia +julia> menu = MultiSelectMenu(options, pagesize=5, charset=:unicode, checked="YEP!", unchecked="NOPE", cursor='⧐'); + +julia> request(menu) +julia> request(menu) +[press: d=done, a=all, n=none] + NOPE apple + YEP! orange + NOPE grape + ⧐ YEP! strawberry +↓ NOPE blueberry +``` + +Aside from the overall `charset` option, for `RadioMenu` the configurable options are: + + - `cursor::Char='>'|'→'`: character to use for cursor + - `up_arrow::Char='^'|'↑'`: character to use for up arrow + - `down_arrow::Char='v'|'↓'`: character to use for down arrow + - `updown_arrow::Char='I'|'↕'`: character to use for up/down arrow in one-line page + - `scroll_wrap::Bool=false`: optionally wrap-around at the beginning/end of a menu + - `ctrl_c_interrupt::Bool=true`: If `false`, return empty on ^C, if `true` throw InterruptException() on ^C + +`MultiSelectMenu` adds: + + - `checked::String="[X]"|"✓"`: string to use for checked + - `unchecked::String="[ ]"|"⬚")`: string to use for unchecked + +You can create new menu types of your own. +Types that are derived from `TerminalMenus.ConfiguredMenu` configure the menu options at construction time. + +#### Legacy interface + +Prior to Julia 1.6, and still supported throughout Julia 1.x, one can also configure menus by calling +`TerminalMenus.config()`. + +## References + +### REPL + +```@docs +Base.atreplinit +``` + +### TerminalMenus + +#### Configuration + +```@docs +REPL.TerminalMenus.Config +REPL.TerminalMenus.MultiSelectConfig +REPL.TerminalMenus.config +``` + +#### User interaction + +```@docs +REPL.TerminalMenus.request +``` + +#### AbstractMenu extension interface + +Any subtype of `AbstractMenu` must be mutable, and must contain the fields `pagesize::Int` and +`pageoffset::Int`. +Any subtype must also implement the following functions: + +```@docs +REPL.TerminalMenus.pick +REPL.TerminalMenus.cancel +REPL.TerminalMenus.writeline +``` + +It must also implement either `options` or `numoptions`: + +```@docs +REPL.TerminalMenus.options +REPL.TerminalMenus.numoptions +``` + +If the subtype does not have a field named `selected`, it must also implement + +```@docs +REPL.TerminalMenus.selected +``` + +The following are optional but can allow additional customization: + +```@docs +REPL.TerminalMenus.header +REPL.TerminalMenus.keypress +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/REPL/src/TerminalMenus/LICENSE.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/REPL/src/TerminalMenus/LICENSE.md new file mode 100644 index 0000000..9ca98a4 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/REPL/src/TerminalMenus/LICENSE.md @@ -0,0 +1,22 @@ +The TerminalMenus.jl package is licensed under the MIT "Expat" License: + +> Copyright (c) 2017: Nick Paul. +> +> Permission is hereby granted, free of charge, to any person obtaining a copy +> of this software and associated documentation files (the "Software"), to deal +> in the Software without restriction, including without limitation the rights +> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +> copies of the Software, and to permit persons to whom the Software is +> furnished to do so, subject to the following conditions: +> +> The above copyright notice and this permission notice shall be included in all +> copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +> SOFTWARE. +> diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Random/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Random/docs/src/index.md new file mode 100644 index 0000000..ca86de4 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Random/docs/src/index.md @@ -0,0 +1,358 @@ +# Random Numbers + +```@meta +DocTestSetup = :(using Random) +``` + +Random number generation in Julia uses the [Mersenne Twister library](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/#dSFMT) +via `MersenneTwister` objects. Julia has a global RNG, which is used by default. Other RNG types +can be plugged in by inheriting the `AbstractRNG` type; they can then be used to have multiple +streams of random numbers. Besides `MersenneTwister`, Julia also provides the `RandomDevice` RNG +type, which is a wrapper over the OS provided entropy. + +Most functions related to random generation accept an optional `AbstractRNG` object as first argument, +which defaults to the global one if not provided. Moreover, some of them accept optionally +dimension specifications `dims...` (which can be given as a tuple) to generate arrays of random +values. In a multi-threaded program, you should generally use different RNG objects from different threads +in order to be thread-safe. However, the default global RNG is thread-safe as of Julia 1.3 (because +it internally corresponds to a per-thread RNG). + +A `MersenneTwister` or `RandomDevice` RNG can generate uniformly random numbers of the following types: +[`Float16`](@ref), [`Float32`](@ref), [`Float64`](@ref), [`BigFloat`](@ref), [`Bool`](@ref), +[`Int8`](@ref), [`UInt8`](@ref), [`Int16`](@ref), [`UInt16`](@ref), [`Int32`](@ref), +[`UInt32`](@ref), [`Int64`](@ref), [`UInt64`](@ref), [`Int128`](@ref), [`UInt128`](@ref), +[`BigInt`](@ref) (or complex numbers of those types). +Random floating point numbers are generated uniformly in ``[0, 1)``. As `BigInt` represents +unbounded integers, the interval must be specified (e.g. `rand(big.(1:6))`). + +Additionally, normal and exponential distributions are implemented for some `AbstractFloat` and +`Complex` types, see [`randn`](@ref) and [`randexp`](@ref) for details. + +!!! warning + Because the precise way in which random numbers are generated is considered an implementation detail, bug fixes and speed improvements may change the stream of numbers that are generated after a version change. Relying on a specific seed or generated stream of numbers during unit testing is thus discouraged - consider testing properties of the methods in question instead. + +## Random numbers module +```@docs +Random.Random +``` + +## Random generation functions + +```@docs +Random.rand +Random.rand! +Random.bitrand +Random.randn +Random.randn! +Random.randexp +Random.randexp! +Random.randstring +``` + +## Subsequences, permutations and shuffling + +```@docs +Random.randsubseq +Random.randsubseq! +Random.randperm +Random.randperm! +Random.randcycle +Random.randcycle! +Random.shuffle +Random.shuffle! +``` + +## Generators (creation and seeding) + +```@docs +Random.seed! +Random.AbstractRNG +Random.MersenneTwister +Random.RandomDevice +``` + +## Hooking into the `Random` API + +There are two mostly orthogonal ways to extend `Random` functionalities: +1) generating random values of custom types +2) creating new generators + +The API for 1) is quite functional, but is relatively recent so it may still have to evolve in subsequent releases of the `Random` module. +For example, it's typically sufficient to implement one `rand` method in order to have all other usual methods work automatically. + +The API for 2) is still rudimentary, and may require more work than strictly necessary from the implementor, +in order to support usual types of generated values. + +### Generating random values of custom types + +Generating random values for some distributions may involve various trade-offs. *Pre-computed* values, such as an [alias table](https://en.wikipedia.org/wiki/Alias_method) for discrete distributions, or [“squeezing” functions](https://en.wikipedia.org/wiki/Rejection_sampling) for univariate distributions, can speed up sampling considerably. How much information should be pre-computed can depend on the number of values we plan to draw from a distribution. Also, some random number generators can have certain properties that various algorithms may want to exploit. + +The `Random` module defines a customizable framework for obtaining random values that can address these issues. Each invocation of `rand` generates a *sampler* which can be customized with the above trade-offs in mind, by adding methods to `Sampler`, which in turn can dispatch on the random number generator, the object that characterizes the distribution, and a suggestion for the number of repetitions. Currently, for the latter, `Val{1}` (for a single sample) and `Val{Inf}` (for an arbitrary number) are used, with `Random.Repetition` an alias for both. + +The object returned by `Sampler` is then used to generate the random values. When implementing the random generation interface for a value `X` that can be sampled from, the implementor should define the method + +```julia +rand(rng, sampler) +``` +for the particular `sampler` returned by `Sampler(rng, X, repetition)`. + +Samplers can be arbitrary values that implement `rand(rng, sampler)`, but for most applications the following predefined samplers may be sufficient: + +1. `SamplerType{T}()` can be used for implementing samplers that draw from type `T` (e.g. `rand(Int)`). This is the default returned by `Sampler` for *types*. + +2. `SamplerTrivial(self)` is a simple wrapper for `self`, which can be accessed with `[]`. This is the recommended sampler when no pre-computed information is needed (e.g. `rand(1:3)`), and is the default returned by `Sampler` for *values*. + +3. `SamplerSimple(self, data)` also contains the additional `data` field, which can be used to store arbitrary pre-computed values, which should be computed in a *custom method* of `Sampler`. + +We provide examples for each of these. We assume here that the choice of algorithm is independent of the RNG, so we use `AbstractRNG` in our signatures. + +```@docs +Random.Sampler +Random.SamplerType +Random.SamplerTrivial +Random.SamplerSimple +``` + +Decoupling pre-computation from actually generating the values is part of the API, and is also available to the user. As an example, assume that `rand(rng, 1:20)` has to be called repeatedly in a loop: the way to take advantage of this decoupling is as follows: + +```julia +rng = MersenneTwister() +sp = Random.Sampler(rng, 1:20) # or Random.Sampler(MersenneTwister, 1:20) +for x in X + n = rand(rng, sp) # similar to n = rand(rng, 1:20) + # use n +end +``` + +This is the mechanism that is also used in the standard library, e.g. by the default implementation of random array generation (like in `rand(1:20, 10)`). + +#### Generating values from a type + +Given a type `T`, it's currently assumed that if `rand(T)` is defined, an object of type `T` will be produced. `SamplerType` is the *default sampler for types*. In order to define random generation of values of type `T`, the `rand(rng::AbstractRNG, ::Random.SamplerType{T})` method should be defined, and should return values what `rand(rng, T)` is expected to return. + +Let's take the following example: we implement a `Die` type, with a variable number `n` of sides, numbered from `1` to `n`. We want `rand(Die)` to produce a `Die` with a random number of up to 20 sides (and at least 4): + +```jldoctest Die +struct Die + nsides::Int # number of sides +end + +Random.rand(rng::AbstractRNG, ::Random.SamplerType{Die}) = Die(rand(rng, 4:20)) + +# output + +``` + +Scalar and array methods for `Die` now work as expected: + +```jldoctest Die; setup = :(Random.seed!(1)) +julia> rand(Die) +Die(15) + +julia> rand(MersenneTwister(0), Die) +Die(11) + +julia> rand(Die, 3) +3-element Vector{Die}: + Die(18) + Die(5) + Die(4) + +julia> a = Vector{Die}(undef, 3); rand!(a) +3-element Vector{Die}: + Die(5) + Die(20) + Die(15) +``` + +#### A simple sampler without pre-computed data + +Here we define a sampler for a collection. If no pre-computed data is required, it can be implemented with a `SamplerTrivial` sampler, which is in fact the *default fallback for values*. + +In order to define random generation out of objects of type `S`, the following method should be defined: `rand(rng::AbstractRNG, sp::Random.SamplerTrivial{S})`. Here, `sp` simply wraps an object of type `S`, which can be accessed via `sp[]`. Continuing the `Die` example, we want now to define `rand(d::Die)` to produce an `Int` corresponding to one of `d`'s sides: + +```jldoctest Die; setup = :(Random.seed!(1)) +julia> Random.rand(rng::AbstractRNG, d::Random.SamplerTrivial{Die}) = rand(rng, 1:d[].nsides); + +julia> rand(Die(4)) +3 + +julia> rand(Die(4), 3) +3-element Vector{Any}: + 4 + 1 + 1 +``` + +Given a collection type `S`, it's currently assumed that if `rand(::S)` is defined, an object of type `eltype(S)` will be produced. In the last example, a `Vector{Any}` is produced; the reason is that `eltype(Die) == Any`. The remedy is to define `Base.eltype(::Type{Die}) = Int`. + +#### Generating values for an `AbstractFloat` type + +`AbstractFloat` types are special-cased, because by default random values are not produced in the whole type domain, but rather in `[0,1)`. The following method should be implemented for `T <: AbstractFloat`: `Random.rand(::AbstractRNG, ::Random.SamplerTrivial{Random.CloseOpen01{T}})` + +#### An optimized sampler with pre-computed data + +Consider a discrete distribution, where numbers `1:n` are drawn with given probabilities that sum to one. When many values are needed from this distribution, the fastest method is using an [alias table](https://en.wikipedia.org/wiki/Alias_method). We don't provide the algorithm for building such a table here, but suppose it is available in `make_alias_table(probabilities)` instead, and `draw_number(rng, alias_table)` can be used to draw a random number from it. + +Suppose that the distribution is described by +```julia +struct DiscreteDistribution{V <: AbstractVector} + probabilities::V +end +``` +and that we *always* want to build an alias table, regardless of the number of values needed (we learn how to customize this below). The methods +```julia +Random.eltype(::Type{<:DiscreteDistribution}) = Int + +function Random.Sampler(::Type{<:AbstractRNG}, distribution::DiscreteDistribution, ::Repetition) + SamplerSimple(disribution, make_alias_table(distribution.probabilities)) +end +``` +should be defined to return a sampler with pre-computed data, then +```julia +function rand(rng::AbstractRNG, sp::SamplerSimple{<:DiscreteDistribution}) + draw_number(rng, sp.data) +end +``` +will be used to draw the values. + +#### Custom sampler types + +The `SamplerSimple` type is sufficient for most use cases with precomputed data. However, in order to demonstrate how to use custom sampler types, here we implement something similar to `SamplerSimple`. + +Going back to our `Die` example: `rand(::Die)` uses random generation from a range, so there is an opportunity for this optimization. We call our custom sampler `SamplerDie`. + +```julia +import Random: Sampler, rand + +struct SamplerDie <: Sampler{Int} # generates values of type Int + die::Die + sp::Sampler{Int} # this is an abstract type, so this could be improved +end + +Sampler(RNG::Type{<:AbstractRNG}, die::Die, r::Random.Repetition) = + SamplerDie(die, Sampler(RNG, 1:die.nsides, r)) +# the `r` parameter will be explained later on + +rand(rng::AbstractRNG, sp::SamplerDie) = rand(rng, sp.sp) +``` + +It's now possible to get a sampler with `sp = Sampler(rng, die)`, and use `sp` instead of `die` in any `rand` call involving `rng`. In the simplistic example above, `die` doesn't need to be stored in `SamplerDie` but this is often the case in practice. + +Of course, this pattern is so frequent that the helper type used above, namely `Random.SamplerSimple`, is available, +saving us the definition of `SamplerDie`: we could have implemented our decoupling with: + +```julia +Sampler(RNG::Type{<:AbstractRNG}, die::Die, r::Random.Repetition) = + SamplerSimple(die, Sampler(RNG, 1:die.nsides, r)) + +rand(rng::AbstractRNG, sp::SamplerSimple{Die}) = rand(rng, sp.data) +``` + +Here, `sp.data` refers to the second parameter in the call to the `SamplerSimple` constructor +(in this case equal to `Sampler(rng, 1:die.nsides, r)`), while the `Die` object can be accessed +via `sp[]`. + +Like `SamplerDie`, any custom sampler must be a subtype of `Sampler{T}` where `T` is the type +of the generated values. Note that `SamplerSimple(x, data) isa Sampler{eltype(x)}`, +so this constrains what the first argument to `SamplerSimple` can be +(it's recommended to use `SamplerSimple` like in the `Die` example, where +`x` is simply forwarded while defining a `Sampler` method). +Similarly, `SamplerTrivial(x) isa Sampler{eltype(x)}`. + +Another helper type is currently available for other cases, `Random.SamplerTag`, but is +considered as internal API, and can break at any time without proper deprecations. + + +#### Using distinct algorithms for scalar or array generation + +In some cases, whether one wants to generate only a handful of values or a large number of values +will have an impact on the choice of algorithm. This is handled with the third parameter of the +`Sampler` constructor. Let's assume we defined two helper types for `Die`, say `SamplerDie1` +which should be used to generate only few random values, and `SamplerDieMany` for many values. +We can use those types as follows: + +```julia +Sampler(RNG::Type{<:AbstractRNG}, die::Die, ::Val{1}) = SamplerDie1(...) +Sampler(RNG::Type{<:AbstractRNG}, die::Die, ::Val{Inf}) = SamplerDieMany(...) +``` + +Of course, `rand` must also be defined on those types (i.e. `rand(::AbstractRNG, ::SamplerDie1)` and `rand(::AbstractRNG, ::SamplerDieMany)`). Note that, as usual, `SamplerTrivial` and `SamplerSimple` can be used if custom types are not necessary. + +Note: `Sampler(rng, x)` is simply a shorthand for `Sampler(rng, x, Val(Inf))`, and +`Random.Repetition` is an alias for `Union{Val{1}, Val{Inf}}`. + + +### Creating new generators + +The API is not clearly defined yet, but as a rule of thumb: +1) any `rand` method producing "basic" types (`isbitstype` integer and floating types in `Base`) + should be defined for this specific RNG, if they are needed; +2) other documented `rand` methods accepting an `AbstractRNG` should work out of the box, + (provided the methods from 1) what are relied on are implemented), + but can of course be specialized for this RNG if there is room for optimization; +3) `copy` for pseudo-RNGs should return an independent copy that generates the exact same random sequence as the + original from that point when called in the same way. When this is not feasible (e.g. hardware-based RNGs), + `copy` must not be implemented. + +Concerning 1), a `rand` method may happen to work automatically, but it's not officially +supported and may break without warnings in a subsequent release. + +To define a new `rand` method for an hypothetical `MyRNG` generator, and a value specification `s` +(e.g. `s == Int`, or `s == 1:10`) of type `S==typeof(s)` or `S==Type{s}` if `s` is a type, +the same two methods as we saw before must be defined: + +1) `Sampler(::Type{MyRNG}, ::S, ::Repetition)`, which returns an object of type say `SamplerS` +2) `rand(rng::MyRNG, sp::SamplerS)` + +It can happen that `Sampler(rng::AbstractRNG, ::S, ::Repetition)` is +already defined in the `Random` module. It would then be possible to +skip step 1) in practice (if one wants to specialize generation for +this particular RNG type), but the corresponding `SamplerS` type is +considered as internal detail, and may be changed without warning. + + +#### Specializing array generation + +In some cases, for a given RNG type, generating an array of random +values can be more efficient with a specialized method than by merely +using the decoupling technique explained before. This is for example +the case for `MersenneTwister`, which natively writes random values in +an array. + +To implement this specialization for `MyRNG` +and for a specification `s`, producing elements of type `S`, +the following method can be defined: +`rand!(rng::MyRNG, a::AbstractArray{S}, ::SamplerS)`, +where `SamplerS` is the type of the sampler returned by `Sampler(MyRNG, s, Val(Inf))`. +Instead of `AbstractArray`, it's possible to implement the functionality only for a subtype, e.g. `Array{S}`. +The non-mutating array method of `rand` will automatically call this specialization internally. + +```@meta +DocTestSetup = nothing +``` + +# Reproducibility + +By using an RNG parameter initialized with a given seed, you can reproduce the same pseudorandom +number sequence when running your program multiple times. However, a minor release of Julia (e.g. +1.3 to 1.4) *may change* the sequence of pseudorandom numbers generated from a specific seed, in +particular if `MersenneTwister` is used. (Even if the sequence produced by a low-level function like +[`rand`](@ref) does not change, the output of higher-level functions like [`randsubseq`](@ref) may +change due to algorithm updates.) Rationale: guaranteeing that pseudorandom streams never change +prohibits many algorithmic improvements. + +If you need to guarantee exact reproducibility of random data, it is advisable to simply *save the +data* (e.g. as a supplementary attachment in a scientific publication). (You can also, of course, +specify a particular Julia version and package manifest, especially if you require bit +reproducibility.) + +Software tests that rely on *specific* "random" data should also generally either save the data, +embed it into the test code, or use third-party packages like +[StableRNGs.jl](https://github.com/JuliaRandom/StableRNGs.jl). On the other hand, tests that should +pass for *most* random data (e.g. testing `A \ (A*x) ≈ x` for a random matrix `A = randn(n,n)`) can +use an RNG with a fixed seed to ensure that simply running the test many times does not encounter a +failure due to very improbable data (e.g. an extremely ill-conditioned matrix). + +The statistical *distribution* from which random samples are drawn *is* guaranteed to be the same +across any minor Julia releases. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SHA/LICENSE.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SHA/LICENSE.md new file mode 100644 index 0000000..eec075c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SHA/LICENSE.md @@ -0,0 +1,58 @@ +The SHA.jl package is licensed under the MIT "Expat" License: + +> Copyright (c) 2014: Elliot Saba. +> +> Permission is hereby granted, free of charge, to any person obtaining +> a copy of this software and associated documentation files (the +> "Software"), to deal in the Software without restriction, including +> without limitation the rights to use, copy, modify, merge, publish, +> distribute, sublicense, and/or sell copies of the Software, and to +> permit persons to whom the Software is furnished to do so, subject to +> the following conditions: +> +> The above copyright notice and this permission notice shall be +> included in all copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +> CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +> TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +This package was inspired by the SHA2 [source code from Minix](https://github.com/minix3/minix/blob/b6cbf7203b080219de306404f8022a65b7884f33/common/lib/libc/hash/sha2/sha2.c), itself released under the BSD license: + +> sha2.c +> +> Version 1.0.0beta1 +> +> Written by Aaron D. Gifford <me@aarongifford.com> +> +> Copyright 2000 Aaron D. Gifford. All rights reserved. +> +> Redistribution and use in source and binary forms, with or without +> modification, are permitted provided that the following conditions +> are met: +> +> 1. Redistributions of source code must retain the above copyright +> notice, this list of conditions and the following disclaimer. +> +> 2. Redistributions in binary form must reproduce the above copyright +> notice, this list of conditions and the following disclaimer in the +> documentation and/or other materials provided with the distribution. +> +> 3. Neither the name of the copyright holder nor the names of contributors +> may be used to endorse or promote products derived from this software +> without specific prior written permission. +> +> THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) AND CONTRIBUTOR(S) ``AS IS'' AND +> ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +> IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +> ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE LIABLE +> FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +> DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +> OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +> HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +> LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +> OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SHA/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SHA/docs/src/index.md new file mode 100644 index 0000000..30c88e5 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SHA/docs/src/index.md @@ -0,0 +1,75 @@ +# SHA + + +Usage is very straightforward: +```julia +julia> using SHA + +julia> bytes2hex(sha256("test")) +"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" +``` + +Each exported function (at the time of this writing, SHA-1, SHA-2 224, 256, 384 and 512, and SHA-3 224, 256, 384 and 512 functions are implemented) takes in either an `AbstractVector{UInt8}`, an `AbstractString` or an `IO` object. This makes it trivial to checksum a file: + +```julia +shell> cat /tmp/test.txt +test +julia> using SHA + +julia> open("/tmp/test.txt") do f + sha2_256(f) + end +32-element Array{UInt8,1}: + 0x9f + 0x86 + 0xd0 + 0x81 + 0x88 + 0x4c + 0x7d + 0x65 + ⋮ + 0x5d + 0x6c + 0x15 + 0xb0 + 0xf0 + 0x0a + 0x08 +``` + +Due to the colloquial usage of `sha256` to refer to `sha2_256`, convenience functions are provided, mapping `shaxxx()` function calls to `sha2_xxx()`. For SHA-3, no such colloquialisms exist and the user must use the full `sha3_xxx()` names. + +`shaxxx()` takes `AbstractString` and array-like objects (`NTuple` and `Array`) with elements of type `UInt8`. + +To create a hash from multiple items the `SHAX_XXX_CTX()` types can be used to create a stateful hash object that +is updated with `update!` and finalized with `digest!` + +```julia +julia> ctx = SHA2_256_CTX() +SHA2 256-bit hash state + +julia> update!(ctx, b"some data") +0x0000000000000009 + +julia> update!(ctx, b"some more data") +0x0000000000000017 + +julia> digest!(ctx) +32-element Vector{UInt8}: + 0xbe + 0xcf + 0x23 + 0xda + 0xaf + 0x02 + ⋮ + 0x25 + 0x52 + 0x19 + 0xa0 + 0x8b + 0xc5 +``` + +Note that, at the time of this writing, the SHA3 code is not optimized, and as such is roughly an order of magnitude slower than SHA2. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Serialization/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Serialization/docs/src/index.md new file mode 100644 index 0000000..c01ead7 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Serialization/docs/src/index.md @@ -0,0 +1,7 @@ +# Serialization + +```@docs +Serialization.serialize +Serialization.deserialize +Serialization.writeheader +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SharedArrays/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SharedArrays/docs/src/index.md new file mode 100644 index 0000000..7b23ec1 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SharedArrays/docs/src/index.md @@ -0,0 +1,11 @@ +# Shared Arrays + +```@docs +SharedArrays.SharedArray +SharedArrays.SharedVector +SharedArrays.SharedMatrix +SharedArrays.procs(::SharedArray) +SharedArrays.sdata +SharedArrays.indexpids +SharedArrays.localindices +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Sockets/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Sockets/docs/src/index.md new file mode 100644 index 0000000..c294461 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Sockets/docs/src/index.md @@ -0,0 +1,33 @@ +# Sockets + +```@docs +Sockets.Sockets +Sockets.connect(::TCPSocket, ::Integer) +Sockets.connect(::AbstractString) +Sockets.listen(::Any) +Sockets.listen(::AbstractString) +Sockets.getaddrinfo +Sockets.getipaddr +Sockets.getipaddrs +Sockets.islinklocaladdr +Sockets.getalladdrinfo +Sockets.DNSError +Sockets.getnameinfo +Sockets.getsockname +Sockets.getpeername +Sockets.IPAddr +Sockets.IPv4 +Sockets.IPv6 +Sockets.@ip_str +Sockets.TCPSocket +Sockets.UDPSocket +Sockets.accept +Sockets.listenany +Sockets.bind +Sockets.send +Sockets.recv +Sockets.recvfrom +Sockets.setopt +Sockets.nagle +Sockets.quickack +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SparseArrays/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SparseArrays/docs/src/index.md new file mode 100644 index 0000000..286c46c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SparseArrays/docs/src/index.md @@ -0,0 +1,232 @@ +# Sparse Arrays + +```@meta +DocTestSetup = :(using SparseArrays, LinearAlgebra) +``` + +Julia has support for sparse vectors and [sparse matrices](https://en.wikipedia.org/wiki/Sparse_matrix) +in the `SparseArrays` stdlib module. Sparse arrays are arrays that contain enough zeros +that storing them in a special data structure leads to savings in space and execution time, +compared to dense arrays. + +## [Compressed Sparse Column (CSC) Sparse Matrix Storage](@id man-csc) + +In Julia, sparse matrices are stored in the [Compressed Sparse Column (CSC) format](https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_column_.28CSC_or_CCS.29). +Julia sparse matrices have the type [`SparseMatrixCSC{Tv,Ti}`](@ref), where `Tv` is the +type of the stored values, and `Ti` is the integer type for storing column pointers and +row indices. The internal representation of `SparseMatrixCSC` is as follows: + +```julia +struct SparseMatrixCSC{Tv,Ti<:Integer} <: AbstractSparseMatrixCSC{Tv,Ti} + m::Int # Number of rows + n::Int # Number of columns + colptr::Vector{Ti} # Column j is in colptr[j]:(colptr[j+1]-1) + rowval::Vector{Ti} # Row indices of stored values + nzval::Vector{Tv} # Stored values, typically nonzeros +end +``` + +The compressed sparse column storage makes it easy and quick to access the elements in the column +of a sparse matrix, whereas accessing the sparse matrix by rows is considerably slower. Operations +such as insertion of previously unstored entries one at a time in the CSC structure tend to be slow. This is +because all elements of the sparse matrix that are beyond the point of insertion have to be moved +one place over. + +All operations on sparse matrices are carefully implemented to exploit the CSC data structure +for performance, and to avoid expensive operations. + +If you have data in CSC format from a different application or library, and wish to import it +in Julia, make sure that you use 1-based indexing. The row indices in every column need to be +sorted. If your `SparseMatrixCSC` object contains unsorted row indices, one quick way to sort +them is by doing a double transpose. + +In some applications, it is convenient to store explicit zero values in a `SparseMatrixCSC`. These +*are* accepted by functions in `Base` (but there is no guarantee that they will be preserved in +mutating operations). Such explicitly stored zeros are treated as structural nonzeros by many +routines. The [`nnz`](@ref) function returns the number of elements explicitly stored in the +sparse data structure, including non-structural zeros. In order to count the exact number of +numerical nonzeros, use [`count(!iszero, x)`](@ref), which inspects every stored element of a sparse +matrix. [`dropzeros`](@ref), and the in-place [`dropzeros!`](@ref), can be used to +remove stored zeros from the sparse matrix. + +```jldoctest +julia> A = sparse([1, 1, 2, 3], [1, 3, 2, 3], [0, 1, 2, 0]) +3×3 SparseMatrixCSC{Int64, Int64} with 4 stored entries: + 0 ⋅ 1 + ⋅ 2 ⋅ + ⋅ ⋅ 0 + +julia> dropzeros(A) +3×3 SparseMatrixCSC{Int64, Int64} with 2 stored entries: + ⋅ ⋅ 1 + ⋅ 2 ⋅ + ⋅ ⋅ ⋅ +``` + +## Sparse Vector Storage + +Sparse vectors are stored in a close analog to compressed sparse column format for sparse +matrices. In Julia, sparse vectors have the type [`SparseVector{Tv,Ti}`](@ref) where `Tv` +is the type of the stored values and `Ti` the integer type for the indices. The internal +representation is as follows: + +```julia +struct SparseVector{Tv,Ti<:Integer} <: AbstractSparseVector{Tv,Ti} + n::Int # Length of the sparse vector + nzind::Vector{Ti} # Indices of stored values + nzval::Vector{Tv} # Stored values, typically nonzeros +end +``` + +As for [`SparseMatrixCSC`](@ref), the `SparseVector` type can also contain explicitly +stored zeros. (See [Sparse Matrix Storage](@ref man-csc).). + +## Sparse Vector and Matrix Constructors + +The simplest way to create a sparse array is to use a function equivalent to the [`zeros`](@ref) +function that Julia provides for working with dense arrays. To produce a +sparse array instead, you can use the same name with an `sp` prefix: + +```jldoctest +julia> spzeros(3) +3-element SparseVector{Float64, Int64} with 0 stored entries +``` + +The [`sparse`](@ref) function is often a handy way to construct sparse arrays. For +example, to construct a sparse matrix we can input a vector `I` of row indices, a vector +`J` of column indices, and a vector `V` of stored values (this is also known as the +[COO (coordinate) format](https://en.wikipedia.org/wiki/Sparse_matrix#Coordinate_list_.28COO.29)). +`sparse(I,J,V)` then constructs a sparse matrix such that `S[I[k], J[k]] = V[k]`. The +equivalent sparse vector constructor is [`sparsevec`](@ref), which takes the (row) index +vector `I` and the vector `V` with the stored values and constructs a sparse vector `R` +such that `R[I[k]] = V[k]`. + +```jldoctest sparse_function +julia> I = [1, 4, 3, 5]; J = [4, 7, 18, 9]; V = [1, 2, -5, 3]; + +julia> S = sparse(I,J,V) +5×18 SparseMatrixCSC{Int64, Int64} with 4 stored entries: +⠀⠈⠀⡀⠀⠀⠀⠀⠠ +⠀⠀⠀⠀⠁⠀⠀⠀⠀ + +julia> R = sparsevec(I,V) +5-element SparseVector{Int64, Int64} with 4 stored entries: + [1] = 1 + [3] = -5 + [4] = 2 + [5] = 3 +``` + +The inverse of the [`sparse`](@ref) and [`sparsevec`](@ref) functions is +[`findnz`](@ref), which retrieves the inputs used to create the sparse array. +[`findall(!iszero, x)`](@ref) returns the cartesian indices of non-zero entries in `x` +(including stored entries equal to zero). + +```jldoctest sparse_function +julia> findnz(S) +([1, 4, 5, 3], [4, 7, 9, 18], [1, 2, 3, -5]) + +julia> findall(!iszero, S) +4-element Vector{CartesianIndex{2}}: + CartesianIndex(1, 4) + CartesianIndex(4, 7) + CartesianIndex(5, 9) + CartesianIndex(3, 18) + +julia> findnz(R) +([1, 3, 4, 5], [1, -5, 2, 3]) + +julia> findall(!iszero, R) +4-element Vector{Int64}: + 1 + 3 + 4 + 5 +``` + +Another way to create a sparse array is to convert a dense array into a sparse array using +the [`sparse`](@ref) function: + +```jldoctest +julia> sparse(Matrix(1.0I, 5, 5)) +5×5 SparseMatrixCSC{Float64, Int64} with 5 stored entries: + 1.0 ⋅ ⋅ ⋅ ⋅ + ⋅ 1.0 ⋅ ⋅ ⋅ + ⋅ ⋅ 1.0 ⋅ ⋅ + ⋅ ⋅ ⋅ 1.0 ⋅ + ⋅ ⋅ ⋅ ⋅ 1.0 + +julia> sparse([1.0, 0.0, 1.0]) +3-element SparseVector{Float64, Int64} with 2 stored entries: + [1] = 1.0 + [3] = 1.0 +``` + +You can go in the other direction using the [`Array`](@ref) constructor. The [`issparse`](@ref) +function can be used to query if a matrix is sparse. + +```jldoctest +julia> issparse(spzeros(5)) +true +``` + +## Sparse matrix operations + +Arithmetic operations on sparse matrices also work as they do on dense matrices. Indexing of, +assignment into, and concatenation of sparse matrices work in the same way as dense matrices. +Indexing operations, especially assignment, are expensive, when carried out one element at a time. +In many cases it may be better to convert the sparse matrix into `(I,J,V)` format using [`findnz`](@ref), +manipulate the values or the structure in the dense vectors `(I,J,V)`, and then reconstruct +the sparse matrix. + +## Correspondence of dense and sparse methods + +The following table gives a correspondence between built-in methods on sparse matrices and their +corresponding methods on dense matrix types. In general, methods that generate sparse matrices +differ from their dense counterparts in that the resulting matrix follows the same sparsity pattern +as a given sparse matrix `S`, or that the resulting sparse matrix has density `d`, i.e. each matrix +element has a probability `d` of being non-zero. + +Details can be found in the [Sparse Vectors and Matrices](@ref stdlib-sparse-arrays) +section of the standard library reference. + +| Sparse | Dense | Description | +|:-------------------------- |:---------------------- |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`spzeros(m,n)`](@ref) | [`zeros(m,n)`](@ref) | Creates a *m*-by-*n* matrix of zeros. ([`spzeros(m,n)`](@ref) is empty.) | +| [`sparse(I,n,n)`](@ref) | [`Matrix(I,n,n)`](@ref)| Creates a *n*-by-*n* identity matrix. | +| [`sparse(A)`](@ref) | [`Array(S)`](@ref) | Interconverts between dense and sparse formats. | +| [`sprand(m,n,d)`](@ref) | [`rand(m,n)`](@ref) | Creates a *m*-by-*n* random matrix (of density *d*) with iid non-zero elements distributed uniformly on the half-open interval ``[0, 1)``. | +| [`sprandn(m,n,d)`](@ref) | [`randn(m,n)`](@ref) | Creates a *m*-by-*n* random matrix (of density *d*) with iid non-zero elements distributed according to the standard normal (Gaussian) distribution. | +| [`sprandn(rng,m,n,d)`](@ref) | [`randn(rng,m,n)`](@ref) | Creates a *m*-by-*n* random matrix (of density *d*) with iid non-zero elements generated with the `rng` random number generator | + +# [Sparse Arrays](@id stdlib-sparse-arrays) + +```@docs +SparseArrays.AbstractSparseArray +SparseArrays.AbstractSparseVector +SparseArrays.AbstractSparseMatrix +SparseArrays.SparseVector +SparseArrays.SparseMatrixCSC +SparseArrays.sparse +SparseArrays.sparsevec +SparseArrays.issparse +SparseArrays.nnz +SparseArrays.findnz +SparseArrays.spzeros +SparseArrays.spdiagm +SparseArrays.blockdiag +SparseArrays.sprand +SparseArrays.sprandn +SparseArrays.nonzeros +SparseArrays.rowvals +SparseArrays.nzrange +SparseArrays.droptol! +SparseArrays.dropzeros! +SparseArrays.dropzeros +SparseArrays.permute +permute!{Tv, Ti, Tp <: Integer, Tq <: Integer}(::SparseMatrixCSC{Tv,Ti}, ::SparseMatrixCSC{Tv,Ti}, ::AbstractArray{Tp,1}, ::AbstractArray{Tq,1}) +``` + +```@meta +DocTestSetup = nothing +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Statistics/LICENSE.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Statistics/LICENSE.md new file mode 100644 index 0000000..7528792 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Statistics/LICENSE.md @@ -0,0 +1,24 @@ +Statistics.jl is licensed under the MIT License: + +> Copyright (c) 2012-2016: Jeff Bezanson, Stefan Karpinski, Viral B. Shah, +> Dahua Lin, Simon Byrne, Andreas Noack, Douglas Bates, John Myles White, +> Simon Kornblith, and other contributors. + +> Permission is hereby granted, free of charge, to any person obtaining +> a copy of this software and associated documentation files (the +> "Software"), to deal in the Software without restriction, including +> without limitation the rights to use, copy, modify, merge, publish, +> distribute, sublicense, and/or sell copies of the Software, and to +> permit persons to whom the Software is furnished to do so, subject to +> the following conditions: +> +> The above copyright notice and this permission notice shall be +> included in all copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +> LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +> OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +> WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Statistics/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Statistics/README.md new file mode 100644 index 0000000..db50bb9 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Statistics/README.md @@ -0,0 +1,19 @@ +# Statistics.jl + +[![Travis CI Build Status][travis-img]][travis-url] + +Development repository for the Statistics standard library (stdlib) that ships with Julia. + +#### Using the development version of Statistics.jl + +If you want to develop this package, do the following steps: +- Clone the repo anywhere. +- In line 2 of the `Project.toml` file (the line that begins with `uuid = ...`), modify the UUID, e.g. change the `107` to `207`. +- Change the current directory to the Statistics repo you just cloned and start julia with `julia --project`. +- `import Statistics` will now load the files in the cloned repo instead of the Statistics stdlib. +- To test your changes, simply do `include("test/runtests.jl")`. + +If you need to build Julia from source with a git checkout of Statistics, then instead use `make DEPS_GIT=Statistics` when building Julia. The `Statistics` repo is in `stdlib/Statistics`, and created initially with a detached `HEAD`. If you're doing this from a pre-existing Julia repository, you may need to `make clean` beforehand. + +[travis-img]: https://travis-ci.com/JuliaLang/Statistics.jl.svg?branch=master +[travis-url]: https://travis-ci.com/JuliaLang/Statistics.jl diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Statistics/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Statistics/docs/src/index.md new file mode 100644 index 0000000..93f3db5 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Statistics/docs/src/index.md @@ -0,0 +1,19 @@ +# Statistics + +The Statistics standard library module contains basic statistics functionality. + +```@docs +std +stdm +var +varm +cor +cov +mean! +mean +median! +median +middle +quantile! +quantile +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SuiteSparse/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SuiteSparse/docs/src/index.md new file mode 100644 index 0000000..e8654ca --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/SuiteSparse/docs/src/index.md @@ -0,0 +1,34 @@ +# Sparse Linear Algebra + +```@meta +DocTestSetup = :(using LinearAlgebra, SparseArrays, SuiteSparse) +``` + +Sparse matrix solvers call functions from [SuiteSparse](http://suitesparse.com). The following factorizations are available: + +| Type | Description | +|:--------------------------------- |:--------------------------------------------- | +| `SuiteSparse.CHOLMOD.Factor` | Cholesky factorization | +| `SuiteSparse.UMFPACK.UmfpackLU` | LU factorization | +| `SuiteSparse.SPQR.QRSparse` | QR factorization | + +Other solvers such as [Pardiso.jl](https://github.com/JuliaSparse/Pardiso.jl/) are as external packages. [Arpack.jl](https://julialinearalgebra.github.io/Arpack.jl/stable/) provides `eigs` and `svds` for iterative solution of eigensystems and singular value decompositions. + +These factorizations are described in the [`Linear Algebra`](@ref man-linalg) section of the manual: +1. [`cholesky`](@ref) +2. [`ldlt`](@ref) +3. [`lu`](@ref) +4. [`qr`](@ref) + +```@docs +SuiteSparse.CHOLMOD.lowrankupdate +SuiteSparse.CHOLMOD.lowrankupdate! +SuiteSparse.CHOLMOD.lowrankdowndate +SuiteSparse.CHOLMOD.lowrankdowndate! +SuiteSparse.CHOLMOD.lowrankupdowndate! +``` + + +```@meta +DocTestSetup = nothing +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/benchmark/tune.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/benchmark/tune.json new file mode 100644 index 0000000..d8d7ca2 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/benchmark/tune.json @@ -0,0 +1 @@ +[{"Julia":"1.5.0","BenchmarkTools":"0.4.3"},[["BenchmarkGroup",{"data":{"strings":["BenchmarkGroup",{"data":{"long":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":1,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}],"short":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":1,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}]},"tags":[]}],"numbers":["BenchmarkGroup",{"data":{"integers":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":1,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}],"floats":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":1,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}]},"tags":[]}],"registry":["BenchmarkGroup",{"data":{"Registry.toml":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":1,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}],"Compat.toml":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":1,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}]},"tags":[]}],"arrays":["BenchmarkGroup",{"data":{"heterogeneous":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":1,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}],"homogeneous":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":1,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}]},"tags":[]}],"array of tables":["BenchmarkGroup",{"data":{"empty":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":1,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}]},"tags":[]}],"parse empty":["BenchmarkTools.Parameters",{"gctrial":true,"time_tolerance":0.05,"samples":10000,"evals":340,"gcsample":false,"seconds":5.0,"overhead":0.0,"memory_tolerance":0.01}]},"tags":[]}]]]
\ No newline at end of file diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/docs/src/index.md new file mode 100644 index 0000000..36e8ec6 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/docs/src/index.md @@ -0,0 +1,132 @@ +# TOML + +TOML.jl is a Julia standard library for parsing and writing [TOML +v1.0](https://toml.io/en/) files. + +## Parsing TOML data + +```jldoctest +julia> using TOML + +julia> data = """ + [database] + server = "192.168.1.1" + ports = [ 8001, 8001, 8002 ] + """; + +julia> TOML.parse(data) +Dict{String, Any} with 1 entry: + "database" => Dict{String, Any}("server"=>"192.168.1.1", "ports"=>[8001, 8001… +``` + +To parse a file, use [`TOML.parsefile`](@ref). If the file has a syntax error, +an exception is thrown: + +```jldoctest +julia> using TOML + +julia> TOML.parse(""" + value = 0.0.0 + """) +ERROR: TOML Parser error: +none:1:16 error: failed to parse value + value = 0.0.0 + ^ +[...] +``` + +There are other versions of the parse functions ([`TOML.tryparse`](@ref) +and [`TOML.tryparsefile`]) that instead of throwing exceptions on parser error +returns a [`TOML.ParserError`](@ref) with information: + +```jldoctest +julia> using TOML + +julia> err = TOML.tryparse(""" + value = 0.0.0 + """); + +julia> err.type +ErrGenericValueError::ErrorType = 14 + +julia> err.line +1 + +julia> err.column +16 +``` + + +## Exporting data to TOML file + +The [`TOML.print`](@ref) function is used to print (or serialize) data into TOML +format. + +```jldoctest +julia> using TOML + +julia> data = Dict( + "names" => ["Julia", "Julio"], + "age" => [10, 20], + ); + +julia> TOML.print(data) +names = ["Julia", "Julio"] +age = [10, 20] + +julia> fname = tempname(); + +julia> open(fname, "w") do io + TOML.print(io, data) + end + +julia> TOML.parsefile(fname) +Dict{String, Any} with 2 entries: + "names" => ["Julia", "Julio"] + "age" => [10, 20] +``` + +Keys can be sorted according to some value + +```jldoctest +julia> using TOML + +julia> TOML.print(Dict( + "abc" => 1, + "ab" => 2, + "abcd" => 3, + ); sorted=true, by=length) +ab = 2 +abc = 1 +abcd = 3 +``` + +For custom structs, pass a function that converts the struct to a supported +type + +```jldoctest +julia> using TOML + +julia> struct MyStruct + a::Int + b::String + end + +julia> TOML.print(Dict("foo" => MyStruct(5, "bar"))) do x + x isa MyStruct && return [x.a, x.b] + error("unhandled type $(typeof(x))") + end +foo = [5, "bar"] +``` + + +## References +```@docs +TOML.parse +TOML.parsefile +TOML.tryparse +TOML.tryparsefile +TOML.print +TOML.Parser +TOML.ParserError +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-empty.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-empty.json new file mode 100644 index 0000000..2fbf256 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-empty.json @@ -0,0 +1,11 @@ +{ + "thevoid": { "type": "array", "value": [ + {"type": "array", "value": [ + {"type": "array", "value": [ + {"type": "array", "value": [ + {"type": "array", "value": []} + ]} + ]} + ]} + ]} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-nospaces.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-nospaces.json new file mode 100644 index 0000000..1833d61 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-nospaces.json @@ -0,0 +1,10 @@ +{ + "ints": { + "type": "array", + "value": [ + {"type": "integer", "value": "1"}, + {"type": "integer", "value": "2"}, + {"type": "integer", "value": "3"} + ] + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-string-quote-comma-2.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-string-quote-comma-2.json new file mode 100644 index 0000000..a88eb26 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-string-quote-comma-2.json @@ -0,0 +1 @@ +{"title": {"type": "array", "value": [{"type": "string", "value": " \", "}]}} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-string-quote-comma.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-string-quote-comma.json new file mode 100644 index 0000000..c6f031f --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-string-quote-comma.json @@ -0,0 +1,9 @@ +{ + "title": { + "type": "array", + "value": [ + {"type": "string", "value": "Client: \"XXXX\", Job: XXXX"}, + {"type": "string", "value": "Code: XXXX"} + ] + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-string-with-comma.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-string-with-comma.json new file mode 100644 index 0000000..d879c4c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-string-with-comma.json @@ -0,0 +1,9 @@ +{ + "title": { + "type": "array", + "value": [ + {"type": "string", "value": "Client: XXXX, Job: XXXX"}, + {"type": "string", "value": "Code: XXXX"} + ] + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-table-array-string-backslash.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-table-array-string-backslash.json new file mode 100644 index 0000000..4797be9 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/array-table-array-string-backslash.json @@ -0,0 +1,7 @@ +{ + "foo": [ + { + "bar": {"type": "string", "value": "\"{{baz}}\"" } + } + ] +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/arrays-hetergeneous.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/arrays-hetergeneous.json new file mode 100644 index 0000000..478fa5c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/arrays-hetergeneous.json @@ -0,0 +1,19 @@ +{ + "mixed": { + "type": "array", + "value": [ + {"type": "array", "value": [ + {"type": "integer", "value": "1"}, + {"type": "integer", "value": "2"} + ]}, + {"type": "array", "value": [ + {"type": "string", "value": "a"}, + {"type": "string", "value": "b"} + ]}, + {"type": "array", "value": [ + {"type": "float", "value": "1.1"}, + {"type": "float", "value": "2.1"} + ]} + ] + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/arrays-nested.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/arrays-nested.json new file mode 100644 index 0000000..d21920c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/arrays-nested.json @@ -0,0 +1,13 @@ +{ + "nest": { + "type": "array", + "value": [ + {"type": "array", "value": [ + {"type": "string", "value": "a"} + ]}, + {"type": "array", "value": [ + {"type": "string", "value": "b"} + ]} + ] + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/arrays.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/arrays.json new file mode 100644 index 0000000..2445116 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/arrays.json @@ -0,0 +1,41 @@ +{ + "ints": { + "type": "array", + "value": [ + {"type": "integer", "value": "1"}, + {"type": "integer", "value": "2"}, + {"type": "integer", "value": "3"} + ] + }, + "floats": { + "type": "array", + "value": [ + {"type": "float", "value": "1.1"}, + {"type": "float", "value": "2.1"}, + {"type": "float", "value": "3.1"} + ] + }, + "strings": { + "type": "array", + "value": [ + {"type": "string", "value": "a"}, + {"type": "string", "value": "b"}, + {"type": "string", "value": "c"} + ] + }, + "dates": { + "type": "array", + "value": [ + {"type": "datetime", "value": "1987-07-05T17:45:00Z"}, + {"type": "datetime", "value": "1979-05-27T07:32:00Z"}, + {"type": "datetime", "value": "2006-06-01T11:00:00Z"} + ] + }, + "comments": { + "type": "array", + "value": [ + {"type": "integer", "value": "1"}, + {"type": "integer", "value": "2"} + ] + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/bool.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/bool.json new file mode 100644 index 0000000..ae368e9 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/bool.json @@ -0,0 +1,4 @@ +{ + "f": {"type": "bool", "value": "false"}, + "t": {"type": "bool", "value": "true"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/comments-at-eof.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/comments-at-eof.json new file mode 100644 index 0000000..458c38a --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/comments-at-eof.json @@ -0,0 +1,3 @@ +{ + "key": {"type": "string", "value": "value"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/comments-at-eof2.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/comments-at-eof2.json new file mode 100644 index 0000000..458c38a --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/comments-at-eof2.json @@ -0,0 +1,3 @@ +{ + "key": {"type": "string", "value": "value"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/comments-everywhere.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/comments-everywhere.json new file mode 100644 index 0000000..e69a2e9 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/comments-everywhere.json @@ -0,0 +1,12 @@ +{ + "group": { + "answer": {"type": "integer", "value": "42"}, + "more": { + "type": "array", + "value": [ + {"type": "integer", "value": "42"}, + {"type": "integer", "value": "42"} + ] + } + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/datetime-timezone.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/datetime-timezone.json new file mode 100644 index 0000000..0b70f14 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/datetime-timezone.json @@ -0,0 +1,3 @@ +{ + "bestdayever": {"type": "datetime", "value": "2017-06-06T12:34:56-05:00"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/datetime.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/datetime.json new file mode 100644 index 0000000..4cdc000 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/datetime.json @@ -0,0 +1,5 @@ +{ + "bestdayever": {"type": "datetime", "value": "1987-07-05T17:45:00Z"}, + "numoffset": {"type": "datetime", "value": "1977-06-28T12:32:00Z"}, + "milliseconds": {"type": "datetime", "value": "1977-12-21T03:32:00.555+00:00"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/double-quote-escape.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/double-quote-escape.json new file mode 100644 index 0000000..0c4ac37 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/double-quote-escape.json @@ -0,0 +1,6 @@ +{ + "test": { + "type": "string", + "value": "\"one\"" + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/empty.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/empty.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/empty.json @@ -0,0 +1 @@ +{} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/escaped-escape.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/escaped-escape.json new file mode 100644 index 0000000..9db7f8a --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/escaped-escape.json @@ -0,0 +1,3 @@ +{ + "answer": {"type": "string", "value": "\\x64"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/example.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/example.json new file mode 100644 index 0000000..48aa907 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/example.json @@ -0,0 +1,14 @@ +{ + "best-day-ever": {"type": "datetime", "value": "1987-07-05T17:45:00Z"}, + "numtheory": { + "boring": {"type": "bool", "value": "false"}, + "perfection": { + "type": "array", + "value": [ + {"type": "integer", "value": "6"}, + {"type": "integer", "value": "28"}, + {"type": "integer", "value": "496"} + ] + } + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/exponent-part-float.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/exponent-part-float.json new file mode 100644 index 0000000..4dbfbee --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/exponent-part-float.json @@ -0,0 +1,5 @@ +{ + "million": {"type": "float", "value": "1000000"}, + "minustenth": {"type": "float", "value": "-0.1"}, + "beast": {"type": "float", "value": "666"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/float-exponent.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/float-exponent.json new file mode 100644 index 0000000..b0d40bd --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/float-exponent.json @@ -0,0 +1,9 @@ +{ + "lower": {"type": "float", "value": "300.0"}, + "upper": {"type": "float", "value": "300.0"}, + "neg": {"type": "float", "value": "0.03"}, + "pos": {"type": "float", "value": "300.0"}, + "zero": {"type": "float", "value": "3.0"}, + "pointlower": {"type": "float", "value": "310.0"}, + "pointupper": {"type": "float", "value": "310.0"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/float-underscore.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/float-underscore.json new file mode 100644 index 0000000..f86cdd7 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/float-underscore.json @@ -0,0 +1,5 @@ +{ + "before": {"type": "float", "value": "3141.5927"}, + "after": {"type": "float", "value": "3141.5927"}, + "exponent": {"type": "float", "value": "3e14"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/float.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/float.json new file mode 100644 index 0000000..3f69b17 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/float.json @@ -0,0 +1,6 @@ +{ + "pi": {"type": "float", "value": "3.14"}, + "pospi": {"type": "float", "value": "3.14"}, + "negpi": {"type": "float", "value": "-3.14"}, + "zero-intpart": {"type": "float", "value": "0.123"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/implicit-and-explicit-after.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/implicit-and-explicit-after.json new file mode 100644 index 0000000..374bd09 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/implicit-and-explicit-after.json @@ -0,0 +1,10 @@ +{ + "a": { + "better": {"type": "integer", "value": "43"}, + "b": { + "c": { + "answer": {"type": "integer", "value": "42"} + } + } + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/implicit-and-explicit-before.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/implicit-and-explicit-before.json new file mode 100644 index 0000000..374bd09 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/implicit-and-explicit-before.json @@ -0,0 +1,10 @@ +{ + "a": { + "better": {"type": "integer", "value": "43"}, + "b": { + "c": { + "answer": {"type": "integer", "value": "42"} + } + } + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/implicit-groups.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/implicit-groups.json new file mode 100644 index 0000000..fbae7fc --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/implicit-groups.json @@ -0,0 +1,9 @@ +{ + "a": { + "b": { + "c": { + "answer": {"type": "integer", "value": "42"} + } + } + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/inline-table-array.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/inline-table-array.json new file mode 100644 index 0000000..84df2da --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/inline-table-array.json @@ -0,0 +1,16 @@ +{ + "people": [ + { + "first_name": {"type": "string", "value": "Bruce"}, + "last_name": {"type": "string", "value": "Springsteen"} + }, + { + "first_name": {"type": "string", "value": "Eric"}, + "last_name": {"type": "string", "value": "Clapton"} + }, + { + "first_name": {"type": "string", "value": "Bob"}, + "last_name": {"type": "string", "value": "Seger"} + } + ] +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/inline-table.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/inline-table.json new file mode 100644 index 0000000..71cc119 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/inline-table.json @@ -0,0 +1,16 @@ +{ + "name": { + "first": {"type": "string", "value": "Tom"}, + "last": {"type": "string", "value": "Preston-Werner"} + }, + "point": { + "x": {"type": "integer", "value": "1"}, + "y": {"type": "integer", "value": "2"} + }, + "simple": { "a": {"type": "integer", "value": "1"} }, + "str-key": { "a": {"type": "integer", "value": "1"} }, + "table-array": [ + { "a": {"type": "integer", "value": "1"} }, + { "b": {"type": "integer", "value": "2"} } + ] +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/integer-underscore.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/integer-underscore.json new file mode 100644 index 0000000..bb6c3e7 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/integer-underscore.json @@ -0,0 +1,3 @@ +{ + "kilo": {"type": "integer", "value": "1000"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/integer.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/integer.json new file mode 100644 index 0000000..543738b --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/integer.json @@ -0,0 +1,6 @@ +{ + "answer": {"type": "integer", "value": "42"}, + "neganswer": {"type": "integer", "value": "-42"}, + "posanswer": {"type": "integer", "value": "42"}, + "zero": {"type": "integer", "value": "0"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-equals-nospace.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-equals-nospace.json new file mode 100644 index 0000000..1f8709a --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-equals-nospace.json @@ -0,0 +1,3 @@ +{ + "answer": {"type": "integer", "value": "42"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-numeric.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-numeric.json new file mode 100644 index 0000000..862f8cb --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-numeric.json @@ -0,0 +1,3 @@ +{ + "1": {"type": "integer", "value": "1"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-space.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-space.json new file mode 100644 index 0000000..9d1f769 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-space.json @@ -0,0 +1,3 @@ +{ + "a b": {"type": "integer", "value": "1"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-special-chars.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-special-chars.json new file mode 100644 index 0000000..3585b2c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/key-special-chars.json @@ -0,0 +1,5 @@ +{ + "~!@$^&*()_+-`1234567890[]|/?><.,;:'": { + "type": "integer", "value": "1" + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/keys-with-dots.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/keys-with-dots.json new file mode 100644 index 0000000..d2ee002 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/keys-with-dots.json @@ -0,0 +1,14 @@ +{ + "plain": {"type": "integer", "value": "1"}, + "with.dot": {"type": "integer", "value": "2"}, + "plain_table": { + "plain": {"type": "integer", "value": "3"}, + "with.dot": {"type": "integer", "value": "4"} + }, + "table": { + "withdot": { + "plain": {"type": "integer", "value": "5"}, + "key.with.dots": {"type": "integer", "value": "6"} + } + } +}
\ No newline at end of file diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/long-float.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/long-float.json new file mode 100644 index 0000000..8ceed47 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/long-float.json @@ -0,0 +1,4 @@ +{ + "longpi": {"type": "float", "value": "3.141592653589793"}, + "neglongpi": {"type": "float", "value": "-3.141592653589793"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/long-integer.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/long-integer.json new file mode 100644 index 0000000..16c331e --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/long-integer.json @@ -0,0 +1,4 @@ +{ + "answer": {"type": "integer", "value": "9223372036854775807"}, + "neganswer": {"type": "integer", "value": "-9223372036854775808"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/multiline-string.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/multiline-string.json new file mode 100644 index 0000000..075bf50 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/multiline-string.json @@ -0,0 +1,30 @@ +{ + "multiline_empty_one": { + "type": "string", + "value": "" + }, + "multiline_empty_two": { + "type": "string", + "value": "" + }, + "multiline_empty_three": { + "type": "string", + "value": "" + }, + "multiline_empty_four": { + "type": "string", + "value": "" + }, + "equivalent_one": { + "type": "string", + "value": "The quick brown fox jumps over the lazy dog." + }, + "equivalent_two": { + "type": "string", + "value": "The quick brown fox jumps over the lazy dog." + }, + "equivalent_three": { + "type": "string", + "value": "The quick brown fox jumps over the lazy dog." + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/nested-inline-table-array.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/nested-inline-table-array.json new file mode 100644 index 0000000..89cd83e --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/nested-inline-table-array.json @@ -0,0 +1,7 @@ +{ + "a": [ + { + "b": {} + } + ] +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/newline-crlf.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/newline-crlf.json new file mode 100644 index 0000000..d32f230 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/newline-crlf.json @@ -0,0 +1,4 @@ +{ + "os": {"type": "string", "value": "DOS"}, + "newline": {"type": "string", "value": "crlf"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/newline-lf.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/newline-lf.json new file mode 100644 index 0000000..8114848 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/newline-lf.json @@ -0,0 +1,4 @@ +{ + "os": {"type": "string", "value": "unix"}, + "newline": {"type": "string", "value": "lf"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/raw-multiline-string-win.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/raw-multiline-string-win.json new file mode 100644 index 0000000..90e27df --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/raw-multiline-string-win.json @@ -0,0 +1,14 @@ +{ + "oneline": { + "type": "string", + "value": "This string has a ' quote character." + }, + "firstnl": { + "type": "string", + "value": "This string has a ' quote character." + }, + "multiline": { + "type": "string", + "value": "This string\r\nhas ' a quote character\r\nand more than\r\none newline\r\nin it." + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/raw-multiline-string.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/raw-multiline-string.json new file mode 100644 index 0000000..b43cce5 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/raw-multiline-string.json @@ -0,0 +1,14 @@ +{ + "oneline": { + "type": "string", + "value": "This string has a ' quote character." + }, + "firstnl": { + "type": "string", + "value": "This string has a ' quote character." + }, + "multiline": { + "type": "string", + "value": "This string\nhas ' a quote character\nand more than\none newline\nin it." + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/raw-string.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/raw-string.json new file mode 100644 index 0000000..693ab9b --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/raw-string.json @@ -0,0 +1,30 @@ +{ + "backspace": { + "type": "string", + "value": "This string has a \\b backspace character." + }, + "tab": { + "type": "string", + "value": "This string has a \\t tab character." + }, + "newline": { + "type": "string", + "value": "This string has a \\n new line character." + }, + "formfeed": { + "type": "string", + "value": "This string has a \\f form feed character." + }, + "carriage": { + "type": "string", + "value": "This string has a \\r carriage return character." + }, + "slash": { + "type": "string", + "value": "This string has a \\/ slash character." + }, + "backslash": { + "type": "string", + "value": "This string has a \\\\ backslash character." + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/right-curly-brace-after-boolean.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/right-curly-brace-after-boolean.json new file mode 100644 index 0000000..a6c11ea --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/right-curly-brace-after-boolean.json @@ -0,0 +1,16 @@ +{ + "black":{ + "allow_prereleases":{ + "type":"bool", + "value":"true" + }, + "python":{ + "type":"string", + "value":">3.6" + }, + "version":{ + "type":"string", + "value":">=18.9b0" + } + } + }
\ No newline at end of file diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-empty.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-empty.json new file mode 100644 index 0000000..6c26d69 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-empty.json @@ -0,0 +1,6 @@ +{ + "answer": { + "type": "string", + "value": "" + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-escapes.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-escapes.json new file mode 100644 index 0000000..98e2c82 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-escapes.json @@ -0,0 +1,46 @@ +{ + "backspace": { + "type": "string", + "value": "This string has a \u0008 backspace character." + }, + "tab": { + "type": "string", + "value": "This string has a \u0009 tab character." + }, + "newline": { + "type": "string", + "value": "This string has a \u000A new line character." + }, + "formfeed": { + "type": "string", + "value": "This string has a \u000C form feed character." + }, + "carriage": { + "type": "string", + "value": "This string has a \u000D carriage return character." + }, + "quote": { + "type": "string", + "value": "This string has a \u0022 quote character." + }, + "backslash": { + "type": "string", + "value": "This string has a \u005C backslash character." + }, + "notunicode1": { + "type": "string", + "value": "This string does not have a unicode \\u escape." + }, + "notunicode2": { + "type": "string", + "value": "This string does not have a unicode \u005Cu escape." + }, + "notunicode3": { + "type": "string", + "value": "This string does not have a unicode \\u0075 escape." + }, + "notunicode4": { + "type": "string", + "value": "This string does not have a unicode \\\u0075 escape." + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-nl.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-nl.json new file mode 100644 index 0000000..54a4a98 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-nl.json @@ -0,0 +1,22 @@ +{ + "nl_mid": { + "type": "string", + "value": "val\nue" + }, + "nl_end": { + "type": "string", + "value": "value\n" + }, + "lit_nl_end": { + "type": "string", + "value": "value\\n" + }, + "lit_nl_mid": { + "type": "string", + "value": "val\\nue" + }, + "lit_nl_uni": { + "type": "string", + "value": "val\\ue" + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-simple.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-simple.json new file mode 100644 index 0000000..2e05f99 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-simple.json @@ -0,0 +1,6 @@ +{ + "answer": { + "type": "string", + "value": "You are not drinking enough whisky." + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-with-pound.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-with-pound.json new file mode 100644 index 0000000..33cdc9c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/string-with-pound.json @@ -0,0 +1,7 @@ +{ + "pound": {"type": "string", "value": "We see no # comments here."}, + "poundcomment": { + "type": "string", + "value": "But there are # some comments here." + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-implicit.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-implicit.json new file mode 100644 index 0000000..32e4640 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-implicit.json @@ -0,0 +1,7 @@ +{ + "albums": { + "songs": [ + {"name": {"type": "string", "value": "Glory Days"}} + ] + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-many.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-many.json new file mode 100644 index 0000000..84df2da --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-many.json @@ -0,0 +1,16 @@ +{ + "people": [ + { + "first_name": {"type": "string", "value": "Bruce"}, + "last_name": {"type": "string", "value": "Springsteen"} + }, + { + "first_name": {"type": "string", "value": "Eric"}, + "last_name": {"type": "string", "value": "Clapton"} + }, + { + "first_name": {"type": "string", "value": "Bob"}, + "last_name": {"type": "string", "value": "Seger"} + } + ] +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-nest.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-nest.json new file mode 100644 index 0000000..c117afa --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-nest.json @@ -0,0 +1,18 @@ +{ + "albums": [ + { + "name": {"type": "string", "value": "Born to Run"}, + "songs": [ + {"name": {"type": "string", "value": "Jungleland"}}, + {"name": {"type": "string", "value": "Meeting Across the River"}} + ] + }, + { + "name": {"type": "string", "value": "Born in the USA"}, + "songs": [ + {"name": {"type": "string", "value": "Glory Days"}}, + {"name": {"type": "string", "value": "Dancing in the Dark"}} + ] + } + ] +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-one.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-one.json new file mode 100644 index 0000000..d75faae --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-one.json @@ -0,0 +1,8 @@ +{ + "people": [ + { + "first_name": {"type": "string", "value": "Bruce"}, + "last_name": {"type": "string", "value": "Springsteen"} + } + ] +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-table-array.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-table-array.json new file mode 100644 index 0000000..e5b7e0a --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-array-table-array.json @@ -0,0 +1,10 @@ +{ + "a": [ + { + "b": [ + { "c" : { "d": {"type": "string", "value": "val0" } } }, + { "c" : { "d": {"type": "string", "value": "val1" } } } + ] + } + ] +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-empty.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-empty.json new file mode 100644 index 0000000..6f3873a --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-empty.json @@ -0,0 +1,3 @@ +{ + "a": {} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-no-eol.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-no-eol.json new file mode 100644 index 0000000..11fa444 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-no-eol.json @@ -0,0 +1 @@ +{ "table": {} } diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-sub-empty.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-sub-empty.json new file mode 100644 index 0000000..9787770 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-sub-empty.json @@ -0,0 +1,3 @@ +{ + "a": { "b": {} } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-whitespace.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-whitespace.json new file mode 100644 index 0000000..3a73ec8 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-whitespace.json @@ -0,0 +1,3 @@ +{ + "valid key": {} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-with-literal-string.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-with-literal-string.json new file mode 100644 index 0000000..8f006b0 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-with-literal-string.json @@ -0,0 +1,9 @@ +{ + "a": { + "\"b\"": { + "c": { + "answer": {"type": "integer", "value": "42"} + } + } + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-with-pound.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-with-pound.json new file mode 100644 index 0000000..5e594e4 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-with-pound.json @@ -0,0 +1,5 @@ +{ + "key#group": { + "answer": {"type": "integer", "value": "42"} + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-with-single-quotes.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-with-single-quotes.json new file mode 100644 index 0000000..fbae7fc --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/table-with-single-quotes.json @@ -0,0 +1,9 @@ +{ + "a": { + "b": { + "c": { + "answer": {"type": "integer", "value": "42"} + } + } + } +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/underscored-float.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/underscored-float.json new file mode 100644 index 0000000..480109c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/underscored-float.json @@ -0,0 +1,3 @@ +{ + "electron_mass": {"type": "float", "value": "9.109109383e-31"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/underscored-integer.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/underscored-integer.json new file mode 100644 index 0000000..0804919 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/underscored-integer.json @@ -0,0 +1,3 @@ +{ + "million": {"type": "integer", "value": "1000000"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/unicode-escape.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/unicode-escape.json new file mode 100644 index 0000000..216f8f7 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/unicode-escape.json @@ -0,0 +1,4 @@ +{ + "answer4": {"type": "string", "value": "\u03B4"}, + "answer8": {"type": "string", "value": "\u03B4"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/unicode-literal.json b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/unicode-literal.json new file mode 100644 index 0000000..00aa2f8 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/TOML/test/testfiles/valid/unicode-literal.json @@ -0,0 +1,3 @@ +{ + "answer": {"type": "string", "value": "δ"} +} diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Tar/README.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Tar/README.md new file mode 100644 index 0000000..d9c2e08 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Tar/README.md @@ -0,0 +1,467 @@ +# Tar.jl + +[](https://travis-ci.org/JuliaIO/Tar.jl) +[](https://codecov.io/gh/JuliaIO/Tar.jl) + +The `Tar` package can list, extract and create POSIX TAR archives ("tarballs") +as specified in [POSIX +1003.1-2001](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html). +It is designed to support using the TAR format as a mechanism for sending trees +of files from one system to another, rather than for the historical use case of +backing up files for restoration to the same system. Because of this design +goal, `Tar` intentionally ignores much of the metadata included in the TAR +format, which does not make sense for the data transfer use case. The package +also does not aim to read or create legacy non-POSIX variants of the TAR format, +although it does support reading GNU long name and long link extensions. + +## API & Usage + +The public API of `Tar` includes five functions and one type: + +* `create` — creates a tarball from an on-disk file tree +* `extract` — extracts a tarball to an on-disk file tree +* `list` — lists the contents of a tarball as a vector of `Header` objects +* `rewrite` — rewrite a tarball to the standard format `create` produces +* `tree_hash` — compute a tree hash of the content of a tarball (default: git + SHA1) +* `Header` — struct representing metadata that `Tar` considers important in a + TAR entry + +None of these are exported, however: the recommended usage is to do `import Tar` +and then access all of these names fully qualified as `Tar.create`, +`Tar.extract` and so on. + +<!-- BEGIN: copied from inline doc strings --> + +### Tar.create + +```jl +create([ predicate, ] dir, [ tarball ]; [ skeleton ]) -> tarball +``` +* `predicate :: String --> Bool` +* `dir :: AbstractString` +* `tarball :: Union{AbstractString, AbstractCmd, IO}` +* `skeleton :: Union{AbstractString, AbstractCmd, IO}` + +Create a tar archive ("tarball") of the directory `dir`. The resulting archive +is written to the path `tarball` or if no path is specified, a temporary path is +created and returned by the function call. If `tarball` is an IO object then the +tarball content is written to that handle instead (the handle is left open). + +If a `predicate` function is passed, it is called on each system path that is +encountered while recursively searching `dir` and `path` is only included in the +tarball if `predicate(path)` is true. If `predicate(path)` returns false for a +directory, then the directory is excluded entirely: nothing under that directory +will be included in the archive. + +If the `skeleton` keyword is passed then the file or IO handle given is used as +a "skeleton" to generate the tarball. You create a skeleton file by passing the +`skeleton` keyword to the `extract` command. If `create` is called with that +skeleton file and the extracted files haven't changed, an identical tarball is +recreated. The `skeleton` and `predicate` arguments cannot be used together. + +### Tar.extract + +```jl +extract([ predicate, ] tarball, [ dir ]; + [ skeleton, ] [ copy_symlinks ]) -> dir +``` +* `predicate :: Header --> Bool` +* `tarball :: Union{AbstractString, AbstractCmd, IO}` +* `dir :: AbstractString` +* `skeleton :: Union{AbstractString, AbstractCmd, IO}` +* `copy_symlinks :: Bool` + +Extract a tar archive ("tarball") located at the path `tarball` into the +directory `dir`. If `tarball` is an IO object instead of a path, then the +archive contents will be read from that IO stream. The archive is extracted to +`dir` which must either be an existing empty directory or a non-existent path +which can be created as a new directory. If `dir` is not specified, the archive +is extracted into a temporary directory which is returned by `extract`. + +If a `predicate` function is passed, it is called on each `Header` object that +is encountered while extracting `tarball` and the entry is only extracted if the +`predicate(hdr)` is true. This can be used to selectively extract only parts of +an archive, to skip entries that cause `extract` to throw an error, or to record +what is extracted during the extraction process. + +If the `skeleton` keyword is passed then a "skeleton" of the extracted tarball +is written to the file or IO handle given. This skeleton file can be used to +recreate an identical tarball by passing the `skeleton` keyword to the `create` +function. The `skeleton` and `predicate` arguments cannot be used together. + +If `copy_symlinks` is `true` then instead of extracting symbolic links as such, +they will be extracted as copies of what they link to if they are internal to +the tarball and if it is possible to do so. Non-internal symlinks, such as a +link to `/etc/passwd` will not be copied. Symlinks which are in any way cyclic +will also not be copied and will instead be skipped. By default, `extract` will +detect whether symlinks can be created in `dir` or not and will automatically +copy symlinks if they cannot be created. + +### Tar.list + +```jl +list(tarball; [ strict = true ]) -> Vector{Header} +list(callback, tarball; [ strict = true ]) +``` +* `callback :: Header --> Bool` +* `tarball :: Union{AbstractString, AbstractCmd, IO}` +* `strict :: Bool` + +List the contents of a tar archive ("tarball") located at the path `tarball`. If +`tarball` is an IO handle, read the tar contents from that stream. Returns a +vector of `Header` structs. See [`Header`](@ref) for details. If a `callback` is +provided then instead of returning a vector of headers, the callback is called +on each `Header`. This can be useful if the number of items in the tarball is +large or if you want examine items prior to an error in the tarball. + +By default `list` will error if it encounters any tarball contents which the +`extract` function would refuse to extract. With `strict=false` it will skip +these checks and list all the the contents of the tar file whether `extract` +would extract them or not. Beware that malicious tarballs can do all sorts of +crafty and unexpected things to try to trick you into doing something bad. + +If the `tarball` argument is a skeleton file (see `extract` and `create`) then +`list` will detect that from the file header and appropriately list or iterate +the headers of the skeleton file. + +### Tar.rewrite + +```jl +rewrite([ predicate, ], old_tarball, [ new_tarball ]) -> new_tarball +``` +* `predicate :: Header --> Bool` +* `old_tarball :: Union{AbstractString, AbstractCmd, IO}` +* `new_tarball :: Union{AbstractString, AbstractCmd, IO}` + +Rewrite `old_tarball` to the standard format that `create` generates, while also +checking that it doesn't contain anything that would cause `extract` to raise an +error. This is functionally equivalent to doing +```jl +Tar.create(Tar.extract(predicate, old_tarball), new_tarball) +``` +However, it never extracts anything to disk and instead uses the `seek` function +to navigate the old tarball's data. If no `new_tarball` argument is passed, the +new tarball is written to a temporary file whose path is returned. + +If a `predicate` function is passed, it is called on each `Header` object that +is encountered while extracting `old_tarball` and the entry is skipped unless +`predicate(hdr)` is true. This can be used to selectively rewrite only parts of +an archive, to skip entries that would cause `extract` to throw an error, or to +record what content is encountered during the rewrite process. + +### Tar.tree_hash + +```jl +tree_hash([ predicate, ] tarball; + [ algorithm = "git-sha1", ] + [ skip_empty = false ]) -> hash::String +``` +* `predicate :: Header --> Bool` +* `tarball :: Union{AbstractString, AbstractCmd, IO}` +* `algorithm :: AbstractString` +* `skip_empty :: Bool` + +Compute a tree hash value for the file tree that the tarball contains. By +default, this uses git's tree hashing algorithm with the SHA1 secure hash +function (like current versions of git). This means that for any tarball whose +file tree git can represent—i.e. one with only files, symlinks and non-empty +directories—the hash value computed by this function will be the same as the +hash value git would compute for that file tree. Note that tarballs can +represent file trees with empty directories, which git cannot store, and this +function can generate hashes for those, which will, by default (see `skip_empty` +below for how to change this behavior), differ from the hash of a tarball which +omits those empty directories. In short, the hash function agrees with git on +all trees which git can represent, but extends (in a consistent way) the domain +of hashable trees to other trees which git cannot represent. + +If a `predicate` function is passed, it is called on each `Header` object that +is encountered while processing `tarball` and an entry is only hashed if +`predicate(hdr)` is true. This can be used to selectively hash only parts of an +archive, to skip entries that cause `extract` to throw an error, or to record +what is extracted during the hashing process. + +Currently supported values for `algorithm` are `git-sha1` (the default) and +`git-sha256`, which uses the same basic algorithm as `git-sha1` but replaces the +SHA1 hash function with SHA2-256, the hash function that git will transition to +using in the future (due to known attacks on SHA1). Support for other file tree +hashing algorithms may be added in the future. + +The `skip_empty` option controls whether directories in the tarball which +recursively contain no files or symlinks are included in the hash or ignored. +In general, if you are hashing the content of a tarball or a file tree, you care +about all directories, not just non-empty ones, so including these in the +computed hash is the default. So why does this function even provide the option +to skip empty directories? Because git refuses to store empty directories and +will ignore them if you try to add them to a repo. So if you compute a reference +tree hash by by adding files to a git repo and then asking git for the tree +hash, the hash value that you get will match the hash value computed by +`tree_hash` with `skip_empty=true`. In other words, this option allows +`tree_hash` to emulate how git would hash a tree with empty directories. If you +are hashing trees that may contain empty directories (i.e. do not come from a +git repo), however, it is recommended that you hash them using a tool (such as +this one) that does not ignore empty directories. + +### Tar.Header + +The `Header` type is a struct representing the essential metadata for a single +record in a tar file with this definition: +```jl +struct Header + path :: String # path relative to the root + type :: Symbol # type indicator (see below) + mode :: UInt16 # mode/permissions (best viewed in octal) + size :: Int64 # size of record data in bytes + link :: String # target path of a symlink +end +``` +Types are represented with the following symbols: `file`, `hardlink`, `symlink`, +`chardev`, `blockdev`, `directory`, `fifo`, or for unknown types, the typeflag +character as a symbol. Note that [`extract`](#Tarextract) refuses to extract +records types other than `file`, `symlink` and `directory`; [`list`](#Tarlist) +will only list other kinds of records if called with `strict=false`. + +<!-- END: copied from inline doc strings --> + +### Compression + +It is typical to compress tarballs when saving of transferring them. In the UNIX +tradition of doing one thing and doing it well, the `Tar` package does not do +any kind of compression and instead makes it easy to compose it's API with +external compression tools. The simplest way to read a compressed archive is to +use a command-line tool to decompress it. For example: +```jl +Tar.list(`gzcat $tarball`) +Tar.extract(`gzcat $tarball`) +``` +This will spawn the `gzcat $tarball` command, read the uncompressed tarball data +from the output of that process, and then close the process. Creating a tarball +with the `gzip` command is nearly as easy: +```jl +Tar.create(dir, pipeline(`gzip -9`, tarball)) +``` +This assumes that `dir` is the directory you want to archive and `tarball` is +the path you want to create as a compressed archive. + +If you want to compress or decompress a tarball in the same process, you can +using various +[[TranscodingStreams](https://github.com/JuliaIO/TranscodingStreams.jl) +packages: +```jl +using CodecZlib + +tar_gz = open(tarball, write=true) +tar = GzipCompressorStream(tar_gz) +Tar.create(dir, tar) +close(tar) +``` +This assumes that `dir` is the directory you want to archive and `tarball` is +the path you want to create as a compressed archive. You can decompress +in-process in a similar manner: +```jl +using CodecZlib + +tar_gz = open(tarball) +tar = GzipDecompressorStream(tar_gz) +dir = Tar.extract(tar) +close(tar) +``` +This assumes that `tarball` is the path of the compressed archive you want to +extract. + +### API comparison with command-line tar + +It might be helpful to compare the `Tar` API with command-line `tar`. Unlike +`tar -c` the `Tar.create` function does not include any of the path you tell it +to bundle in the resulting TAR file: the location of the data is not part of the +data. Doing `Tar.create(dir, tarball)` is roughly equivalent to running the +following `tar` command: +```sh +tar -f $tarball -C $dir -c $(cd $dir; ls -A) +``` +In other words, `tar` is told to change into the directory `dir` before +constructing the tarball and then include all the top-level items in that +directory without any path prefix. Note that the above command does not fully +emulate the behavior of `Tar.create`: it does not sort entries in the same order +and it still records user and group information, modification times and exact +permissions. Coaxing command-line `tar` programs to omit this non-portable +information and use a portable (and `git`-compatible sort order) is non-trivial. + +Another difference from command-line `tar`: non-empty directories are also +omitted from the tarballs that `Tar` creates since no metadata is recorded about +directories aside from the fact that they exist and the existence of non-empty +directories is already implied by the fact that they contain something else. If, +in the future, the ability to record metadata about directories is added, +tarballs will record entries for non-empty directories with non-default +metadata. + +On the extraction side of things, doing `Tar.extract(tarball, dir)` is roughly +equivalent to the following commands: +```sh +test -d $dir || mkdir $dir +tar -f $tarball -C $dir -mx +``` +Again, `tar` is told to change into the directory `dir` before extracting the +tarball and to extract each path relative to that directory. The `-m` option +tells `tar` to ignore the modification times recorded in the tarball and just +let files and directories have their natural modification times. + +If the current user has elevated privileges, the `tar` command will attempt to +change the owner and group of files to what is recorded in the tarball, whereas +`Tar.extract` will never do that. The `tar` command may also try to restore +permissions without respecting the current `umask` if the user is an +administrator. Again, `Tar.extract` will never do that—it behaves the same way +for any users: by ignoring any user/group/permission information, aside from +whether plain files are executable by their owner or not. To suppress these +behaviors with GNU tar, you can use the `--no-same-owner` and +`--no-same-permissions` options; these options are not broadly supported by +other `tar` commands, which may not have options to support these behaviors. + +## Design & Features + +Unlike the `tar` command line tool, which was originally designed to archive +data in order to restore it back to the same system or to a replica thereof, the +`Tar` package is designed for using the TAR format to transfer trees of files +and directories from one system to another. This design goal means that some +metadata fields supported by the TAR format and used by default by historical +`tar` tools are not used or supported by `Tar`. In short, the choice of features +and defaults for `Tar` are designed to support transfer of data, rather than +backup and restoration. + +The TAR format can, for example, record the name and ID of the user that owns +each file. Recording this information makes perfect sense when using tarballs +for backup: the `tar` program should run as root when restoring data, so it can +restore the original owner of each file and directory. On the other hand, this +ownership information is of no use when using the TAR format to transfer data +from one system to another: the user names and IDs will not generally be the +same on different systems, and the tool should _not_ be run as `root`, so it +cannot change the owner of anything it extracts. For data transfer, ownership +metadata should be disregarded and need not be recorded in the first place. + +Similarly, it makes little sense, when using tarballs for data transfer, to copy +the modification time of each file from the source system. Those time stamps are +unlikely to be relevant on the destination system, and in some cases, clock skew +between the systems could mean that time stamps from the source appear to be in +the future at the destination. This can confuse some programs and may even be +perceived as an attempted security breach; most `tar` command line tools print +warnings when extracting files with time stamps from the future. When using the +TAR format for data transfer, it is better to ignore time stamps and just let +the extracted contents have natural modification times. + +The features and defaults of the `Tar` package are guided by the principle that +it uses the TAR format for transmitting data, not as a tool for backup and +restoration. If you want to use the TAR format for archival purposes, you are +likely better off using a traditional command line tool like [GNU +tar](https://www.gnu.org/software/tar/). If, on the other hand, you want to use +the TAR format to transmit data from one system to another, then you've come to +the right place. + +### File Types + +Since `Tar` is designed for transmission of file and directory trees, it +supports only the following file types: + +* plain files +* directories +* symlinks + +The `Tar` package does not support other file types that the TAR format can +represent, including: hard links, character devices, block devices, and FIFOs. +If you attempt to create or extract an archive that contains any of these kinds +of entries, `Tar` will raise an error. You can, however, list the contents of a +tarball containing other kinds of entries by passing the `strict=false` flag to +the `list` function; without this option, `list` raises the same error as +`extract` would. + +In the future, optional support may be added for using hard links within +archives to avoid duplicating identical files. + +### Time Stamps + +Also in accordance with its design goal as a data transfer tool, the `Tar` +package does not record or set modification times upon tarball creation and +extraction. When creating a tarball, it sets the time stamp of each entry to +`0`, representing the UNIX epoch (Jan 1st, 1970). When extracting a tarball, it +ignores the time stamps of entries and lets all extracted content have "natural" +modification times based on when each file or directory is extracted. + +In the future, optional support may be added for recording and restoring time +stamps. + +### Users & Groups + +`Tar` ignores user and group names and IDs when creating and extracting +tarballs. This is due to two facts: + +* names and IDs on source and destination systems will generally not match; +* names and IDs can only be changed if `Tar` is run with elevated privileges. + +The first fact means that it probably doesn't make sense to try to restore +ownership when transferring data, while the second fact means that it's probably +not possible. Accordingly, `Tar` disregards user and group names and IDs when +creating and extracting tarballs. During creation, the ID fields are recorded as +`0` and names fields are recorded as the empty string. When extracting a +tarball, the user and group fields are ignored entirely and all extracted +content is owned by the current user. + +It is unlikely that support will be added for recording or restoring ownership +of files or directories since that functionality only makes sense when using the +TAR format for backup, a purpose better served by using a command line `tar` +tool. + +### Permissions + +Upon tarball extraction, `Tar` respects the permissions recorded for each file. +When creating tarball, however, it ignores most permission information and +normalizes permissions as follows: + +* files that are not executable by the owner are archived with mode `0o644`; +* files that are executable by the owner are archived with mode `0o755`; +* directories and symlinks are always archived with mode `0o755`. + +In other words, `Tar` records only one significant bit of information: whether +plain files are executable by their owner or not. No permission information for +directories or symlinks is considered significant. This one bit of information +is the only one which makes sense across all platforms, so this choice makes +`Tar`'s behavior as portable as possible. On systems (like Windows) that do not +use POSIX modes, whatever permission mechanism exists (_e.g._ ACLs) should be +queried/modified to determine whether each file is executable by its owner or +not. Unfortunately, this is currently broken on Windows since `libuv` does not +correctly support querying or changing the user executable "bit"; this is +actively being worked on, however, and should be fixed in future versions of +Julia. + +In the future, optional support may be added for recording exact permission +modes on POSIX systems, and possibly for normalizing permissions on extraction +in the same way that they are normalized upon archive creation. + +### Reproducibility + +The information that `Tar` records about permissions is the same information +that `git` considers to be significant when recording and hashing tree contents +(admittedly not by coincidence). As a result, an important and useful +consequence of `Tar`'s design is that it has the following properties: + +* if you create a tarball from a file tree and extract it, the new tree will + have the same `git` tree hash as the original; +* if you `git checkout` a file tree and archive it using `Tar`, the resulting + TAR archive file is always the same. + +One important caveat to keep in mind is that `git` ignores directories that +recursively contain only directories—_i.e._ unless there's a file or a symlink +somewhere, `git` will not acknowledge the existence of a subdirectory. This +means that two trees with the same `git` tree hash can produce different +tarballs if they differ by subdirectories containing no files or symlinks: `git` +will ignore those subdirectories, while `Tar` will not. Therefore, they will +have the same `git` tree hash, but produce different tarballs. Two _identical_ +file trees will always produce identical tarballs, however, and that tarball +should remain stable in future versions of the `Tar` package. + +The `tree_hash` function can be used to compute a git-style tree hash of the +contents of a tarball (without needing to extract it). Moreover, two tarballs +created by the `Tar` package will have the same hash if and only if they contain +the same file tree, which is true if and only if they are identical tarballs. +You can, however, hash tarballs not created by `Tar` this way to see if they +represent the same file tree, and you can use the `skip_empty=true` option to +`tree_hash` to compute the hash that `git` would assign the tree, ignoring empty +directories. diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Test/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Test/docs/src/index.md new file mode 100644 index 0000000..8e3ba43 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Test/docs/src/index.md @@ -0,0 +1,293 @@ +# Unit Testing + +```@meta +DocTestSetup = :(using Test) +``` + +## Testing Base Julia + +Julia is under rapid development and has an extensive test suite to verify functionality across +multiple platforms. If you build Julia from source, you can run this test suite with `make test`. +In a binary install, you can run the test suite using `Base.runtests()`. + +```@docs +Base.runtests +``` + +## Basic Unit Tests + +The `Test` module provides simple *unit testing* functionality. Unit testing is a way to +see if your code is correct by checking that the results are what you expect. It can be helpful +to ensure your code still works after you make changes, and can be used when developing as a way +of specifying the behaviors your code should have when complete. + +Simple unit testing can be performed with the `@test` and `@test_throws` macros: + +```@docs +Test.@test +Test.@test_throws +``` + +For example, suppose we want to check our new function `foo(x)` works as expected: + +```jldoctest testfoo +julia> using Test + +julia> foo(x) = length(x)^2 +foo (generic function with 1 method) +``` + +If the condition is true, a `Pass` is returned: + +```jldoctest testfoo +julia> @test foo("bar") == 9 +Test Passed + +julia> @test foo("fizz") >= 10 +Test Passed +``` + +If the condition is false, then a `Fail` is returned and an exception is thrown: + +```jldoctest testfoo +julia> @test foo("f") == 20 +Test Failed at none:1 + Expression: foo("f") == 20 + Evaluated: 1 == 20 +ERROR: There was an error during testing +``` + +If the condition could not be evaluated because an exception was thrown, which occurs in this +case because `length` is not defined for symbols, an `Error` object is returned and an exception +is thrown: + +```julia-repl +julia> @test foo(:cat) == 1 +Error During Test + Test threw an exception of type MethodError + Expression: foo(:cat) == 1 + MethodError: no method matching length(::Symbol) + Closest candidates are: + length(::SimpleVector) at essentials.jl:256 + length(::Base.MethodList) at reflection.jl:521 + length(::MethodTable) at reflection.jl:597 + ... + Stacktrace: + [...] +ERROR: There was an error during testing +``` + +If we expect that evaluating an expression *should* throw an exception, then we can use `@test_throws` +to check that this occurs: + +```jldoctest testfoo +julia> @test_throws MethodError foo(:cat) +Test Passed + Thrown: MethodError +``` + +## Working with Test Sets + +Typically a large number of tests are used to make sure functions work correctly over a range +of inputs. In the event a test fails, the default behavior is to throw an exception immediately. +However, it is normally preferable to run the rest of the tests first to get a better picture +of how many errors there are in the code being tested. + +!!! note + The `@testset` will create a local scope of its own when running the tests in it. + +The `@testset` macro can be used to group tests into *sets*. All the tests in a test set will +be run, and at the end of the test set a summary will be printed. If any of the tests failed, +or could not be evaluated due to an error, the test set will then throw a `TestSetException`. + +```@docs +Test.@testset +``` + +We can put our tests for the `foo(x)` function in a test set: + +```jldoctest testfoo +julia> @testset "Foo Tests" begin + @test foo("a") == 1 + @test foo("ab") == 4 + @test foo("abc") == 9 + end; +Test Summary: | Pass Total +Foo Tests | 3 3 +``` + +Test sets can also be nested: + +```jldoctest testfoo +julia> @testset "Foo Tests" begin + @testset "Animals" begin + @test foo("cat") == 9 + @test foo("dog") == foo("cat") + end + @testset "Arrays $i" for i in 1:3 + @test foo(zeros(i)) == i^2 + @test foo(fill(1.0, i)) == i^2 + end + end; +Test Summary: | Pass Total +Foo Tests | 8 8 +``` + +In the event that a nested test set has no failures, as happened here, it will be hidden in the +summary, unless the `verbose=true` option is passed: + +```jldoctest testfoo +julia> @testset verbose = true "Foo Tests" begin + @testset "Animals" begin + @test foo("cat") == 9 + @test foo("dog") == foo("cat") + end + @testset "Arrays $i" for i in 1:3 + @test foo(zeros(i)) == i^2 + @test foo(fill(1.0, i)) == i^2 + end + end; +Test Summary: | Pass Total +Foo Tests | 8 8 + Animals | 2 2 + Arrays 1 | 2 2 + Arrays 2 | 2 2 + Arrays 3 | 2 2 +``` + +If we do have a test failure, only the details for the failed test sets will be shown: + +```julia-repl +julia> @testset "Foo Tests" begin + @testset "Animals" begin + @testset "Felines" begin + @test foo("cat") == 9 + end + @testset "Canines" begin + @test foo("dog") == 9 + end + end + @testset "Arrays" begin + @test foo(zeros(2)) == 4 + @test foo(fill(1.0, 4)) == 15 + end + end + +Arrays: Test Failed + Expression: foo(fill(1.0, 4)) == 15 + Evaluated: 16 == 15 +[...] +Test Summary: | Pass Fail Total +Foo Tests | 3 1 4 + Animals | 2 2 + Arrays | 1 1 2 +ERROR: Some tests did not pass: 3 passed, 1 failed, 0 errored, 0 broken. +``` + +## Other Test Macros + +As calculations on floating-point values can be imprecise, you can perform approximate equality +checks using either `@test a ≈ b` (where `≈`, typed via tab completion of `\approx`, is the +[`isapprox`](@ref) function) or use [`isapprox`](@ref) directly. + +```jldoctest +julia> @test 1 ≈ 0.999999999 +Test Passed + +julia> @test 1 ≈ 0.999999 +Test Failed at none:1 + Expression: 1 ≈ 0.999999 + Evaluated: 1 ≈ 0.999999 +ERROR: There was an error during testing +``` + +```@docs +Test.@inferred +Test.@test_logs +Test.@test_deprecated +Test.@test_warn +Test.@test_nowarn +``` + +## Broken Tests + +If a test fails consistently it can be changed to use the `@test_broken` macro. This will denote +the test as `Broken` if the test continues to fail and alerts the user via an `Error` if the test +succeeds. + +```@docs +Test.@test_broken +``` + +`@test_skip` is also available to skip a test without evaluation, but counting the skipped test +in the test set reporting. The test will not run but gives a `Broken` `Result`. + +```@docs +Test.@test_skip +``` + +## Creating Custom `AbstractTestSet` Types + +Packages can create their own `AbstractTestSet` subtypes by implementing the `record` and `finish` +methods. The subtype should have a one-argument constructor taking a description string, with +any options passed in as keyword arguments. + +```@docs +Test.record +Test.finish +``` + +`Test` takes responsibility for maintaining a stack of nested testsets as they are executed, +but any result accumulation is the responsibility of the `AbstractTestSet` subtype. You can access +this stack with the `get_testset` and `get_testset_depth` methods. Note that these functions are +not exported. + +```@docs +Test.get_testset +Test.get_testset_depth +``` + +`Test` also makes sure that nested `@testset` invocations use the same `AbstractTestSet` +subtype as their parent unless it is set explicitly. It does not propagate any properties of the +testset. Option inheritance behavior can be implemented by packages using the stack infrastructure +that `Test` provides. + +Defining a basic `AbstractTestSet` subtype might look like: + +```julia +import Test: Test, record, finish +using Test: AbstractTestSet, Result, Pass, Fail, Error +using Test: get_testset_depth, get_testset +struct CustomTestSet <: Test.AbstractTestSet + description::AbstractString + foo::Int + results::Vector + # constructor takes a description string and options keyword arguments + CustomTestSet(desc; foo=1) = new(desc, foo, []) +end + +record(ts::CustomTestSet, child::AbstractTestSet) = push!(ts.results, child) +record(ts::CustomTestSet, res::Result) = push!(ts.results, res) +function finish(ts::CustomTestSet) + # just record if we're not the top-level parent + if get_testset_depth() > 0 + record(get_testset(), ts) + end + ts +end +``` + +And using that testset looks like: + +```julia +@testset CustomTestSet foo=4 "custom testset inner 2" begin + # this testset should inherit the type, but not the argument. + @testset "custom testset inner" begin + @test true + end +end +``` + +```@meta +DocTestSetup = nothing +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/UUIDs/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/UUIDs/docs/src/index.md new file mode 100644 index 0000000..1e6c950 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/UUIDs/docs/src/index.md @@ -0,0 +1,8 @@ +# UUIDs + +```@docs +UUIDs.uuid1 +UUIDs.uuid4 +UUIDs.uuid5 +UUIDs.uuid_version +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Unicode/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Unicode/docs/src/index.md new file mode 100644 index 0000000..aba9d80 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Unicode/docs/src/index.md @@ -0,0 +1,7 @@ +# Unicode + +```@docs +Unicode.isassigned +Unicode.normalize +Unicode.graphemes +``` diff --git a/research/flossing/external/julia-1.6.7/share/julia/test/clangsa/lit.cfg.py b/research/flossing/external/julia-1.6.7/share/julia/test/clangsa/lit.cfg.py new file mode 100644 index 0000000..5790eab --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/test/clangsa/lit.cfg.py @@ -0,0 +1,27 @@ +import os +import sys +import re +import platform + +import lit.util +import lit.formats + +config.name = 'Julia-GCChecker' +config.suffixes = ['.c','.cpp'] +config.test_source_root = os.path.dirname(__file__) +config.test_format = lit.formats.ShTest(True) +config.substitutions.append(('%shlibext', '.dylib' if platform.system() == 'Darwin' else '.dll' if + platform.system() == 'Windows' else '.so')) +config.substitutions.append(("%julia_home", os.path.join(os.path.dirname(__file__), "../.."))) + +path = os.path.pathsep.join((os.path.join(os.path.dirname(__file__),"../../usr/tools"), os.path.join(os.path.dirname(__file__),"../../usr/bin"), config.environment['PATH'])) +config.environment['PATH'] = path +config.environment['HOME'] = "/tmp" +config.environment['CLANGSA_FLAGS'] = os.environ.get('CLANGSA_FLAGS', "") +config.environment['CLANGSA_CXXFLAGS'] = os.environ.get('CLANGSA_CXXFLAGS', "") +config.environment['CPPFLAGS'] = os.environ.get('CPPFLAGS', "") +config.environment['CFLAGS'] = os.environ.get('CFLAGS', "") +config.environment['CXXFLAGS'] = os.environ.get('CXXFLAGS', "") + +if platform.machine() == "x86_64": + config.available_features.add('x86_64') diff --git a/research/flossing/external/julia-1.6.7/share/julia/test/llvmpasses/lit.cfg.py b/research/flossing/external/julia-1.6.7/share/julia/test/llvmpasses/lit.cfg.py new file mode 100644 index 0000000..2054876 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/test/llvmpasses/lit.cfg.py @@ -0,0 +1,21 @@ +import os +import sys +import re +import platform + +import lit.util +import lit.formats + +config.name = 'Julia' +config.suffixes = ['.ll','.jl'] +config.test_source_root = os.path.dirname(__file__) +config.test_format = lit.formats.ShTest(True) +config.substitutions.append(('%shlibext', '.dylib' if platform.system() == 'Darwin' else '.dll' if + platform.system() == 'Windows' else '.so')) + +path = os.path.pathsep.join((os.path.join(os.path.dirname(__file__),"../../usr/tools"), os.path.join(os.path.dirname(__file__),"../../usr/bin"), config.environment['PATH'])) +config.environment['PATH'] = path +config.environment['HOME'] = "/tmp" + +if platform.machine() == "x86_64": + config.available_features.add('x86_64') diff --git a/research/flossing/external/julia_depot/registries/General/.ci/instantiate.sh b/research/flossing/external/julia_depot/registries/General/.ci/instantiate.sh new file mode 100755 index 0000000..ce636ec --- /dev/null +++ b/research/flossing/external/julia_depot/registries/General/.ci/instantiate.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash + +# This script runs `Pkg.instantiate()` inside a bounded retry loop. + +dir="${1:-}" + +if [ -z "$dir" ]; then + echo "Usage: $0 <julia-project-dir>" >&2 + exit 2 +fi +if [ ! -d "$dir" ]; then + echo "Error: '$dir' is not a directory." >&2 + exit 2 +fi + +try_count=0 +while [ "$try_count" -lt 9 ]; do + julia --color=yes --project="$dir" -e 'import Pkg; Pkg.instantiate()' + if [ $? -eq 0 ]; then exit 0; fi + try_count=$((try_count + 1)) + sleep 20 +done + +exit 1 diff --git a/research/flossing/external/julia_depot/registries/General/CONTRIBUTING.md b/research/flossing/external/julia_depot/registries/General/CONTRIBUTING.md new file mode 100644 index 0000000..62e00fe --- /dev/null +++ b/research/flossing/external/julia_depot/registries/General/CONTRIBUTING.md @@ -0,0 +1,185 @@ +# Contribution guidelines + +Anyone can help improve the General registry! Here are a few ways. + +## As a package author + +You can register your package! +See [Registering a package in General](https://github.com/JuliaRegistries/General#registering-a-package-in-general) in the README for how to do that. +The "FAQ" section in the README helps answer many more questions, like [do I need to register a package to install it?](https://github.com/JuliaRegistries/General#do-i-need-to-register-a-package-to-install-it), [should I register my package?](https://github.com/JuliaRegistries/General#should-i-register-my-package), and more. + +* Please be aware of the [package naming guidelines][naming-guidelines] +* We strongly encourage authors to follow best practices like having documentation (or a descriptive README), tests, and continuous integration. + +## As a Julia community member + +You (yes, you!) can help General be the best registry it can be. + +### New package registrations + +The first step to getting involved with General is to check out new package registrations. +They are filed under the ["new package" label](https://github.com/JuliaRegistries/General/pulls?q=is%3Apr+is%3Aopen+label%3A%22new+package%22), and a automatic feed posts them in the `#new-packages-feed` channel in the [community Slack](https://julialang.org/slack/) or [Zulip](https://julialang.zulipchat.com/register/). + +When registration is triggered for a new package (or new version of a package), [RegistryCI.jl](RegistryCI)-powered AutoMerge automatically runs and performs [some basic checks](https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/). +These are merely guidelines, and not all checks must pass --- if a check fails, the registration can still be manually merged. +There are a few ways to help here: + +1. First, whenever you are engaging with a package author, remember to always be polite and kind-- if you are feeling frustrated, it may be better to not comment at all and let someone else respond instead. +Not everyone understands things from the same explanations, and some folks may need to translate or overcome other barriers to understanding, or may simply disagree with you. +When we are helping maintain the General registry, we are acting as representatives of the Julia community, and need to be mindful of that. +2. If an AutoMerge guideline fails and the package author does not seem to know how to address it, you can help guide them through the process. +Pointing them to the [FAQ](FAQ) can help, as can updating the FAQ and other guidance to make the process more clear. +Sometimes folks also just need a bit of help to understand the process, and writing a note can help. +3. If an AutoMerge fails but you think the package should be manually merged, comment in the PR to explain why. + * One common issue here is the name similarity check. + This exists to prevent malicious [typosquatting](https://en.wikipedia.org/wiki/Typosquatting). + For example, [Flux](https://github.com/FluxML/Flux.jl) is a popular machine learning package. + A malicious actor could try to register FIux (with an uppercase-eye instead of a lowercase-ell), and encourage users to install it by writing a tutorial or such. + They could then add malicious code to the package to try to steal secrets. + Such an event would be an extreme security violation and the package would be yanked or removed from the registry as soon as possible-- but we try to be a bit safer by proactively screening names to require manual merging if they are "too similar" to an existing package name. + + If a package fails the name similarity check, you can help out by taking a look at the two names as well as the package code itself, and try to make a determination if it looks "too close" (e.g. Websockets vs WebSocket), and if the package code contains anything that would indicate malicious activity. + You can make a comment in the PR indicating whether or not you think the name similarity is okay. Include `[noblock]` in the comment if you don't want to block AutoMerge. + If you have [triage](permissions)-level access or higher to General, you can additionally override automerge by adding the label _Override AutoMerge: name similarity is okay_. + +4. Regardless of AutoMerge's status, if you think perhaps something more should be done before registration, feel free to leave a comment in the PR explaining what you think should be done first. +Any comment without `[noblock]` included in it will block AutoMerge from automatically merging the pull request (editing `[noblock]` into old comments **will** allow it to resume). + * For example, occasionally someone will register a package without any content in order to reserve the package name, with the intent to add content later. + We don't allow that in General, and ask authors to add content first before registering. + * Sometimes authors register packages without any description of what the package is for in the README or without documentation. + Since registration is a mechanism to share code with the whole Julia community, such a description is important for the package to be useful. + While we don't strictly require such documentation, it can help to give a polite and gentle nudge in the PR comments, or show folks how to write documentation and/or what is helpful to include in a README. + We want to encourage best practices (in an inclusive and friendly way!) even when they are not strict requirements. + * Sometimes package names are possibly confusing or don't conform to our [naming guidelines][naming-guidelines], but AutoMerge does not detect this. + Feel free to comment, describing what you think is confusing or non-compliant about the current name, and any suggestions you have for a more clear name. + +### Other PRs to General + +Sometimes, the registry needs to be updated in other ways that involve manual pull requests (PRs) rather than auto-generated ones. +The most common reason is to update the URL for a repository. + +#### Updating the URL for a repository + +If someone transfers a GitHub repository, [we ask](https://github.com/JuliaRegistries/General#how-do-i-transfer-a-package-to-an-organization-or-another-user) that they update the URL stored in General. +This is done by manually making a PR to General to update the URL. +You can review such a PR by checking that the old URL redirects to the new one. +* If it does, that's a clear sign that the change is legitimate and the new URL is correct. + If you have write permissions to General, you can merge the PR; otherwise you can approve it or comment. +* If it does not, you can ask the author why. This should be handled on a case-by-case basis. Be sure to check that: + 1. The package is not being hijacked; check for example that the person making the PR has registered a version of the package before, indicating they are authorized to do so. + 2. All the registered revisions of the package are accessible in the new repository. + Specifically, this means checking that all the git-tree-shas can be found in the new repository. + See [the appendix](#appendix-checking-if-a-repository-contains-all-registered-versions-of-a-package) below for a script to automate this checking. + +### Other ways to help + +Besides helping out with PRs to General, you can... + +* ...improve [General's README](https://github.com/JuliaRegistries/General#general), the [RegistryCI documentation](https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/), or these guidelines! +* ...add new checks to AutoMerge (in [RegistryCI](RegistryCI)) or improve existing ones. +* ...address open issues in [General](https://github.com/JuliaRegistries/General/issues), [RegistryCI.jl](https://github.com/JuliaRegistries/RegistryCI.jl/issues), or [Registrator.jl](https://github.com/JuliaRegistries/Registrator.jl/issues). +* ...write blog posts and documentation to help folks get started with writing documentation, tests, and setting up CI for their own packages, and find appropriate places to link to it and help out new package authors. + +Additionally, if you have elevated [permissions](permissions) to General, there's a few more things you can do: + +* [triage] You can add or remove labels to PRs to help communicate the status and to automatically override AutoMerge for name similairty failures + * Specifically, adding the label `Override AutoMerge: name similarity is okay` will retrigger AutoMerge and cause it to ignore the distance check between the package name and existing package names. This will not override any other guidelines (e.g. name too short). +* [triage] You can close PRs if the package author requests it or the registration is superseded by another registration request. +* [write] You can merge PRs that have the _needs to be manually merged in 3 days_ label once the requisite waiting period has passed, assuming there are no outstanding objections in the PR comments. +* [write] You can choose to facilitate expedited merge requests, after manually reviewing the package. +You generally should not merge your own registrations or those you are involved with (though you can make requests to another maintainer). See also [this FAQ entry](https://github.com/JuliaRegistries/General/#who-can-approve-an-early-merge). +* [write] You can merge improvements to the README, these guidelines, or our workflows. +* [admin] You can give other contributors triage-level access so they can apply labels to PRs, or write-level permissions to merge PRs. + +## Expectations and tips for registry maintainers + +We ask registry maintainers to refrain from merging their own PRs or PRs that they are closely involved in. + +### Is there a checklist for reviewing PRs that change the URL of a repo? + +Here's a checklist. + +```md +1. [ ] I have confirmed that the old URL automatically redirects to the new URL in the web browser. +2. [ ] The PR preserves the trailing `.git` at the end of the URL. +3. [ ] The Treecheck CI job ran on this PR and is green. +``` + +## Appendix: Checking if a repository contains all registered versions of a package + +When someone wishes to move a package from one repo to another, it is important that the new repo contains all of the tree hashes corresponding to registered versions of a package. That way these old versions of the package can continue to be installed from the new repository. In order to check if a given repository contains all of the registered versions of a package, the following script can be used: + +```julia +using RegistryInstances, UUIDs, Git + +const GENERAL_UUID = UUID("23338594-aafe-5451-b93e-139f81909106") + +pretty_print_row(row) = println(row.pkg_name, ": v", row.version, " ", row.found ? "found" : "is missing") +pretty_print_table(table) = foreach(pretty_print_row, table) + +function check_all_found(table) + idx = findfirst(row -> !row.found, table) + idx === nothing && return nothing + row = table[idx] + error(string("Repository missing v", row.version, " of package $(row.pkg_name)")) +end + +function check_packages_versions(pkg_names, repo_url; registry_uuid=GENERAL_UUID, verbose=true, throw=true) + if isdir(repo_url) + dir = repo_url + else + dir = mktempdir() + run(`$(git()) clone $(repo_url) $dir`) + end + + registry = only(filter!(r -> r.uuid == registry_uuid, reachable_registries())) + + table = @NamedTuple{pkg_name::String, version::VersionNumber, found::Bool, tree_sha::Base.SHA1}[] + + for pkg_name in pkg_names + pkg = registry.pkgs[only(uuids_from_name(registry, pkg_name))] + versions = registry_info(pkg).version_info + for version in sort(collect(keys(versions))) + tree_sha = versions[version].git_tree_sha1 + found = success(`$(git()) -C $dir rev-parse -q --verify "$(tree_sha)^{tree}"`) + + push!(table, (; pkg_name, version, found, tree_sha)) + end + end + verbose && pretty_print_table(table) + throw && check_all_found(table) + return table +end + +check_package_versions(pkg_name, repo_url; kw...) = check_packages_versions([pkg_name], repo_url; kw...) +``` + +For example, in [General#75319](https://github.com/JuliaRegistries/General/pull/75319), a package author wanted to update the URL associated +to their package "FastParzenWindows". At the time, the package had 1 registered version. We can check that it is present in the new repository via: + +```julia +julia> check_package_versions("FastParzenWindows", "https://github.com/ngiann/FastParzenWindows.jl.git"); +Cloning into '/var/folders/jb/plyyfc_d2bz195_0rc0n_zcw0000gp/T/jl_ke9E8C'... +...text omitted... +FastParzenWindows: v0.1.2 found +``` + +We see that this version was found in the new repository. This script was based on [this comment from General#35965](https://github.com/JuliaRegistries/General/pull/35965#issuecomment-832721704), +which involved checking if 4 packages in the same repository all had their versions present in the new repository. That example can be handled as follows: + +```julia +pkg_names = ["ReinforcementLearningBase", "ReinforcementLearningCore", + "ReinforcementLearningEnvironments", "ReinforcementLearningZoo"] +check_packages_versions(pkg_names, "https://github.com/JuliaReinforcementLearning/ReinforcementLearning.jl.git") +``` + +You can also use this script against local repositories when modifying Git commit history: + +```julia +check_package_versions("FastParzenWindows", ".") +``` + +[FAQ]: https://github.com/JuliaRegistries/General#faq] +[naming-guidelines]: ./NAMING_GUIDELINES.md +[permissions]: https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization +[RegistryCI]: https://github.com/JuliaRegistries/RegistryCI.jl/ |