docgen HTML escapes characters inside of `syntax_block`s. This commit replaces the escaped
greater than with the `>` character. No other occurrences were found.
Fixes#9840
There were two things to resolve here:
* Snektron's branch edited Zir printing, but in master branch
I moved the printing code from Zir.zig to print_zir.zig. So that
just had to be moved over.
* In master branch I fleshed out coerceInMemory a bit more, which
caused one of Snektron's test cases to fail, so I had to add
addrspace awareness to that. Once I did that the tests passed again.
In a previous commit (f4d3d29), syntax checking for code blocks with the
`syntax` type was disabled due to a change in astgen now checking the existence of
identifiers. The change in astgen caused some code samples in the language
reference to cause compilation errors.
This commit updates the code samples in the language reference and
re-enables syntax checking. Some code samples have been changed to unchecked
syntax blocks using `{#syntax_block#}` when suitable.
This edit allows the reader to understand the syntax this section is talking about more quickly – they don’t have to read the whole code block and understand which part of it demonstrates the feature being described.
Affects https://ziglang.org/documentation/master/#Inferred-Error-Sets
* langref: add some more "see also" links for atomics
* Add the following AIR instructions
- atomic_load
- atomic_store_unordered
- atomic_store_monotonic
- atomic_store_release
- atomic_store_seq_cst
- atomic_rmw
* Implement those AIR instructions in LLVM and C backends.
* AstGen: make the `ty` result locations for `@atomicRmw`, `@atomicLoad`,
and `@atomicStore` be `coerced_ty` to avoid unnecessary ZIR
instructions when Sema will be doing the coercions redundantly.
* Sema for `@atomicLoad` and `@atomicRmw` is done, however Sema for
`@atomicStore` is not yet implemented.
- comptime eval for `@atomicRmw` is not yet implemented.
* Sema: flesh out `coerceInMemoryAllowed` a little bit more. It can now
handle pointers.
The language reference's HTML has been updated to be more semantically correct.
This also helps to improve the document's accessibility concerns.
* Document structure has single h1, other header sections start at h2, nav sections w/ aria labels, main section
* Zig's homepage is linked, Zig Standard Library section link to it
* Tables have caption and scoping rows and columns
* Code blocks are figures with figure captions citing source files
* Change line height 1.5 to include table of contents as well
* Luminosity contrast ratios have been adjusted to 7:1
* Dark mode colors adjusted to reduce eye strain
* Links have default browser underline with hover and focus effects
* Asides, definition lists, keyboard inputs, program outputs are represented semantically
Tools used to check:
WAVE plugin https://wave.webaim.org/
Firefox Accessibility Developer Tool
Lighthouse Accessibility Tool
- adds 1 simple behavior tests for each
which does integer and vector ops at
runtime and comptime
- adds bigint_*_sat() methods for each
- use CreateIntrinsic() which accepts a
variable number of arguments to pass
the scale parameter
* update langref
- added case to test/compile_errors.zig given floats
- explain upstream bug in llvm.smul.fix.sat and link to #9643 in langref and commented out test cases
* sat-arithmetic: skip mul tests if arch == .wasm32 because ci is erroring with 'LLVM ERROR: Unable to expand fixed point multiplication' when compiling for wasm32
This is a backwards-compatible language change.
Previously, `@intToEnum` coerced its integer operand to the integer tag
type of the destination enum type, often requiring the callsite to
additionally wrap the operand in an `@intCast`. Now, the `@intCast` is
implicit, and any integer operand can be passed to `@intToEnum`.
The same as before, it is illegal behavior to pass any integer which does
not have a corresponding enum tag.
The async/await documentation was somewhat hard for me to follow when first learning. Two particular sticking points were
1. The alphabet example constructing the string "abcdefghi" breaks the stated rule that every async has a matching await.
2. It was somewhat unclear to me what the rules for control flow were around async/await constructs.
I've tried to improve this documentation with some minimal explanatory edits, which are correct to the best of my beginner's understanding & experimentation.
* Make clearer inline code blocks in language reference paragraphs
This commit makes the inline code blocks within paragraphs standout against the
descriptive text. The code blocks within tables are left un-styled.
The line-height of the paragraphs has been set to 1.7 based on recommendations
from MDN Web Docs and W3C. The value is unitless based on the recommendation.
Closes#9316, #6313
* Make clearer inline code blocks in language reference paragraphs
Goal: To improve legibility of inline code blocks in the language reference.
This commit alters the styles of code HTML elements in paragraphs, unordered
lists, ordered lists, tables, and preformatted text elements.
Most of the changes here are taken from suggestions from @dbandstra on GitHub
in response to a code review.
* p, ul, ol, but not #toc are set to the same line-height
* p, ul, ol, and table have the same inline code styles
* The inline code background color set to match the preformatted code blocks in
the light theme and dark theme. The border colors are adjusted as well.
* The preformatted code block font size is set to default. The 12pt setting was removed.
The line-height of paragraphs is set to 1.5. This value is chosen based on
recommendations from W3C [1] via MDN Web Docs [2] and the contents of the
language reference.
The MDN Web Docs offers two recommendations:
1. Use a unitless number for line-height.
2. Use a minimum value of 1.5 for main paragraph content.
[1] https://www.w3.org/TR/WCAG21/#visual-presentation
[2] https://developer.mozilla.org/en-US/docs/Web/CSS/line-heightCloses#6313, #9316
* Set language reference line-height and pre code border color
This commit is an update to a group of commits with the goal of improving the
legibility of the language reference. In this commit, the line-height is now set
in the `#contents` ID and reset to normal for preformatted code blocks. This
change better separates lines of all main content text for legibility.
Closes: #9316, #6313
* Style the language reference code elements
This commit sets the style of the HTML code element. Since preformatted code
blocks have an overriding style, this is safe to set for all inline code elements.
@select(
comptime T: type,
pred: std.meta.Vector(len, bool),
a: std.meta.Vector(len, T),
b: std.meta.Vector(len, T)
) std.meta.Vector(len, T)
Constructs a vector from a & b, based on the values in the predicate vector. For indices where the predicate value is true, the corresponding
element from the a vector is selected, and otherwise from b.
* Added doc comments for `std.Target.ObjectFormat` enum
* `std.Target.oFileExt` is removed because it is incorrect for Plan-9
targets. Instead, use `std.Target.ObjectFormat.fileExt` and pass a
CPU architecture.
* Added `Compilation.Directory.joinZ` for when a null byte is desired.
* Improvements to `Compilation.create` logic for computing `use_llvm`
and reporting errors in contradictory flags. `-femit-llvm-ir` and
`-femit-llvm-bc` will now imply `-fLLVM`.
* Fix compilation when passing `.bc` files on the command line.
* Improvements to the stage2 LLVM backend:
- cleaned up error messages and error reporting. Properly bubble up
some errors rather than dumping to stderr; others turn into panics.
- properly call ZigLLVMCreateTargetMachine and
ZigLLVMTargetMachineEmitToFile and implement calculation of the
respective parameters (cpu features, code model, abi name, lto,
tsan, etc).
- LLVM module verification only runs in debug builds of the compiler
- use LLVMDumpModule rather than printToString because in the case
that we incorrectly pass a null pointer to LLVM it may crash during
dumping the module and having it partially printed is helpful in
this case.
- support -femit-asm, -fno-emit-bin, -femit-llvm-ir, -femit-llvm-bc
- Support LLVM backend when used with Mach-O and WASM linkers.
c_void is *not* simply `const c_void = opaque{};`. It has unique
semantics as any pointer type may coerce to `*c_void` which is not true
for an arbitrary `*opaque{}`.
The "Zig Test" section of the language reference has been moved between the
current "Hello World" section and the "Comments" section. This was done to
introduce the Zig test syntax before it is used in later sections.
The description of the Zig test feature has NOT been updated in this commit.
Closes#5837
* Remove parser error on double ampersand
* Add failing test for double ampersand case
* Add error when encountering double ampersand in AstGen
"Bit and" operator should not make sense when one of its operands
is an address.
* Check that 2 ampersands are adjacent to each other in source string
* Remove cases of unused variables in tests
This is for consistency with the documentation on sentinel-terminated
{arrays,slices,pointers} which already use `N` for a comptime-inferred
size rather than `X`.
Also adds a behavioral test to assert that a string literal is returned.
This was already the case, but the documentation failed to point out
that the returned value is of type `*const [N:0]u8`, i.e. that of a
string literal.
Also adds a behavioral test to assert that this is the case.
The Zig language specification will support identifiers and field access
in order to refer to which declaration to export with `@export`.
This commit implements the change in AstGen and updates the language
reference.
I want the language reference to be divorced from any particular
community. Also remove the call to action since the docs are
known to be incomplete and are not the current focus of the project.
Closes#9055
- hash/eql functions moved into a Context object
- *Context functions pass an explicit context
- *Adapted functions pass specialized keys and contexts
- new getPtr() function returns a pointer to value
- remove functions renamed to fetchRemove
- new remove functions return bool
- removeAssertDiscard deleted, use assert(remove(...)) instead
- Keys and values are stored in separate arrays
- Entry is now {*K, *V}, the new KV is {K, V}
- BufSet/BufMap functions renamed to match other set/map types
- fixed iterating-while-modifying bug in src/link/C.zig
This matches the behaviour for other targets in that
```
zig build-lib math.zig -target wasm32-freestanding
```
produces now `libmath.a` while
```
zig build-lib math.zig -dynamic -target wasm32-freestanding
```
is required to create a loadable Wasm module.
This matches the behaviour of other languages and leaves us
the ability to create actual static Wasm archives with
```
zig build-lib -static some.zig
```
which can then be combined with other Wasm object files and linked
into either a Wasm lib or executable using `wasm-ld`.
Update langref to reflect the fact we now ship WASI libc.
Conflicts:
* doc/langref.html.in
* lib/std/enums.zig
* lib/std/fmt.zig
* lib/std/hash/auto_hash.zig
* lib/std/math.zig
* lib/std/mem.zig
* lib/std/meta.zig
* test/behavior/alignof.zig
* test/behavior/bitcast.zig
* test/behavior/bugs/1421.zig
* test/behavior/cast.zig
* test/behavior/ptrcast.zig
* test/behavior/type_info.zig
* test/behavior/vector.zig
Master branch added `try` to a bunch of testing function calls, and some
lines also had changed how to refer to the native architecture and other
`@import("builtin")` stuff.
Conflicts:
lib/std/crypto/25519/field.zig
lib/std/crypto/poly1305.zig
I had resolved those by removing `comptime` but master branch decided to
make the parameters `comptime`.
This also pulls in the updated default `zig build` install directory.
* docs: document the nosuspend keyword
* Specify that resuming from suspend is allowed in nosuspend
* Fix the description of the requirements of nosuspend
* Make use of nosuspend in some example code.
This is mainly motivated by the incorrect claim that "there would be
no way to collect the return value of amain, if it were something
other than void".
This makes a few changes to the base64 codecs.
* The padding character is optional. The common "URL-safe" variant, in
particular, is generally not used with padding. This is also the case for
password hashes, so having this will avoid code duplication with bcrypt,
scrypt and other functions.
* The URL-safe variant is added. Instead of having individual constants
for each parameter of each variant, we are now grouping these in a
struct. So, `standard_pad_char` just becomes `standard.pad_char`.
* Types are not `snake_case`'d any more. So, `standard_encoder` becomes
`standard.Encoder`, as it is a type.
* Creating a decoder with ignored characters required the alphabet and
padding. Now, `standard.decoderWithIgnore(<ignored chars>)` returns a
decoder with the standard parameters and the set of ignored chars.
* Whatever applies to `standard.*` obviously also works with `url_safe.*`
* the `calcSize()` interface was inconsistent, taking a length in the
encoder, and a slice in the encoder. Rename the variant that takes a
slice to `calcSizeForSlice()`.
* In the decoder with ignored characters, add `calcSizeUpperBound()`,
which is more useful than the one that takes a slice in order to size
a fixed buffer before we have the data.
* Return `error.InvalidCharacter` when the input actually contains
characters that are neither padding nor part of the alphabet. If we
hit a padding issue (which includes extra bits at the end),
consistently return `error.InvalidPadding`.
* Don't keep the `char_in_alphabet` array permanently in a decoder;
it is only required for sanity checks during initialization.
* Tests are unchanged, but now cover both the standard (padded) and
the url-safe (non-padded) variants.
* Add an error set, rename `OutputTooSmallError` to `NoSpaceLeft`
to match the `hex2bin` equivalent.
Previous wording made it seem like any signed or floating-point value would be allowed at comptime, whereas negative values do not work with `%`, and negative integers do not work with `/`.
In this commit, the code samples in the language reference have been changed to
use `std.testing.expect` rather than `std.debug.assert` when they are
written in `test` code. This will teach Zig learners best practices when
they write their own test code.
Not all uses of `std.debug.assert` have been replaced. There are examples where
using `assert` fits the context of the sample.
Using `std.debug.assert` in test code can lead to errors if running tests in
ReleaseFast mode. In ReleaseFast mode, the `unreachable` in `assert` is
undefined behavior. It is possible that `assert` always causes `zig test` to
pass thus possibly leading to incorrect test code outcomes. The goal is to
prevent incorrect code from passing test cases.
Closes#5836
* move the opaque section to after struct, enum, union, and add
hyperlinks
* improve the introduction of the zig build system. don't link to the
wiki.
* update to the latest zig init-exe example code
* rename headers to avoid redundant words such as "zig"
* simplify example code
* std.log: still print error messages in ReleaseSmall builds.
- when start code gets an error code from main, it uses std.log.err
to report the error. this resulted in a test failure because
ReleaseSmall wasn't printing `error: TheErrorCode` when an error
was returned from main. But that seems like it should keep working.
So I changed the std.log defaults. I plan to follow this up with a
proposal to change the names of and reduce the quantity of the
log levels.
* warning emitted when using -femit-h when using stage1 backend; fatal
log message when using -femit-h with self-hosted backend (because the
feature is not yet available)
* fix double `test-cli` build steps in zig's build.zig
* update docgen to use new CLI
* translate-c uses `-x c` and generates a temporary basename with a
`.h` extension. Otherwise clang reports an error.
* --show-builtin implies -fno-emit-bin
* restore the compile error for using an extern "c" function without
putting -lc on the build line. we have to know about the libc
dependency up front.
* Fix ReleaseFast and ReleaseSmall getting swapped when passing the
value to the stage1 backend.
* correct the zig0 CLI usage text.
* update test harness code to the new CLI.
This commit edits the "Hello, World!" introduction. It introduces Error Union
Types. Also, it changes `outStream` to `writer` in the code example and description.
To introduce the Zig programming language, the "Hello, world!" code sample now has
documentation to explain some of the features shown in the code sample
and contains links to those features in the rest of the documentation.
Writing style goals:
* Balance writing style to keep beginner and experience programmers interested.
* Be concise: allow the rest of the documentation to clarify language features.
This is an edge case that isn't too uncommon but is rather confusing to try to deduce without documentation, since it feels like `else` is being overloaded in this scenario and there's no obvious 'correct' behavior here. This just adds a test demonstrating how Zig currently behaves in this scenario.
The language reference's Index is a list of the documentation's contents in
order of appearance. This commit renames "Index" to "Contents" as in table of
contents. It also renames the HTML/CSS identifiers from "index" to "toc".
This commit generalizes `std.fs.wasi.PreopenList.find(...)` allowing
search by `std.fs.wasi.PreopenType` union type rather than by dir
name. In the future releases of WASI, it is expected to have more
preopen types (or capabilities) than just directories. This commit
aligns itself with that vision.
This is a potentially breaking change. However, since `std.fs.wasi.PreopenList`
wasn't made part of any Zig release yet, I think we should be OK
to introduce those changes without pointing to any deprecations.
Remove `std.fs.deleteTree`. Callers instead should use
`std.fs.cwd().deleteTree`.
Add `std.fs.deleteTreeAbsolute` for when the caller has an absolute
path.
* Underscores `_` may be placed between two digits in a int/float literal
* Consecutive underscores are not allowed
* Fixed parsing bug in exponents of hexadecimal float literals.
Exponents should always be base 10, but hex characters would be parsed
inside the exponent and everything after them would be ignored. eg:
`0x1.0p1ab1` would be parsed as `0x1.0p1`.
Zig now supports a more fine-grained sense of what is native and what is
not. Some examples:
This is now allowed:
-target native
Different OS but native CPU, default Windows C ABI:
-target native-windows
This could be useful for example when running in Wine.
Different CPU but native OS, native C ABI.
-target x86_64-native -mcpu=skylake
Different C ABI but otherwise native target:
-target native-native-musl
-target native-native-gnu
Lots of breaking changes to related std lib APIs.
Calls to getOs() will need to be changed to getOsTag().
Calls to getArch() will need to be changed to getCpuArch().
Usage of Target.Cross and Target.Native need to be updated to use
CrossTarget API.
`std.build.Builder.standardTargetOptions` is changed to accept its
parameters as a struct with default values. It now has the ability to
specify a whitelist of targets allowed, as well as the default target.
Rather than two different ways of collecting the target, it's now always
a string that is validated, and prints helpful diagnostics for invalid
targets. This feature should now be actually useful, and contributions
welcome to further improve the user experience.
`std.build.LibExeObjStep.setTheTarget` is removed.
`std.build.LibExeObjStep.setTarget` is updated to take a CrossTarget
parameter.
`std.build.LibExeObjStep.setTargetGLibC` is removed. glibc versions are
handled in the CrossTarget API and can be specified with the `-target`
triple.
`std.builtin.Version` gains a `format` method.
this was causing unrelated behavior tests to fail.
if this commit is reverted, the docs are good, but `@newStackCall` is
already deprecated in favor of `@call`, supplying the `stack` property.
