Initial commit of Arabic translation of dlang-tour

.editorconfig

@@ -0,0 +1,12 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.md]
+charset = utf-8
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4

.gitignore

@@ -0,0 +1 @@
+.vscode/*

.travis.yml

@@ -0,0 +1,25 @@
+dist: trusty
+language: d
+d:
+  - dmd
+  - ldc
+branches:
+  only:
+    - master
+addons:
+  apt:
+    packages:
+    - libevent-dev
+
+script:
+  - echo "Check for trailing whitespace"
+  - grep -nr --include \*.md '\s$' . ; test $? -eq 1
+  - echo "Check for tabs"
+  - grep -nrP --include \*.md '\t' . ; test $? -eq 1
+  - git clone https://github.com/dlang-tour/core ../tour
+  - mkdir -p ../tour/public/content/lang
+  - mv * ../tour/public/content/lang
+  - wget https://raw.githubusercontent.com/dlang/tools/master/rdmd.d
+  - ${DC} rdmd.d
+  - export PATH=$PATH:$PWD
+  - (cd ../tour && dub --compiler=${DC} -- --sanitycheck .)

README.md

@@ -0,0 +1,27 @@
+Arabic translation of DLang Tour
+==============================================
+
+[![Build Status](https://travis-ci.com/dlang-tour/arabic.svg?branch=master)](https://travis-ci.com/dlang-tour/arabic)
+
+Found a typo or want to improve the content?
+Just click on "edit" and send us a pull request.
+If you want to discuss an idea for a change first,
+don't hesitate to open an [issue](https://github.com/dlang-tour/arabic/issues).
+
+You might also be looking for the [base repository](https://github.com/dlang-tour/core)
+that hosts the content.
+
+Run locally
+-----------
+
+You will need to fetch the [base repository](https://github.com/dlang-tour/core) via DUB once:
+
+```sh
+dub fetch dlang-tour
+```
+
+Now you can execute `dlang-tour` in the root directory of this repository:
+
+```sh
+dub run dlang-tour -- --lang-dir .
+```

basics/alias-strings.md

@@ -0,0 +1,144 @@
+# Alias & Strings
+
+Now that we know what arrays are, have gotten in touch with `immutable`,
+and had a quick look at the basic types, it's time to introduce two
+new constructs in one line:
+
+    alias string = immutable(char)[];
+
+The term `string` is defined by an `alias` statement which defines it
+as a slice of `immutable(char)`s. This means, once a `string` has been constructed
+its content will never change again. And actually this is the second
+introduction: welcome UTF-8 `string`!
+
+Due to their immutablility, `string`s can be shared perfectly among
+different threads. As `string` is a slice, parts can be taken out of it without
+allocating memory. The standard function
+[`std.algorithm.splitter`](https://dlang.org/phobos/std_algorithm_iteration.html#.splitter)
+for example, splits a string by newline without any memory allocations.
+
+Besides the UTF-8 `string`, there are two more types:
+
+    alias wstring = immutable(wchar)[]; // UTF-16
+    alias dstring = immutable(dchar)[]; // UTF-32
+
+The variants are most easily converted between each other using
+the `to` method from `std.conv`:
+
+    dstring myDstring = to!dstring(myString);
+    string myString   = to!string(myDstring);
+
+### Unicode strings
+
+This means that a plain `string` is defined as an array of 8-bit Unicode [code
+units](http://unicode.org/glossary/#code_unit). All array operations can be
+used on strings, but they will work on a code unit level, and not a character level. At
+the same time, standard library algorithms will interpret `string`s as sequences
+of [code points](http://unicode.org/glossary/#code_point), and there is also an
+option to treat them as sequences of
+[graphemes](http://unicode.org/glossary/#grapheme) by explicit usage of
+[`std.uni.byGrapheme`](https://dlang.org/library/std/uni/by_grapheme.html).
+
+This small example illustrates the difference in interpretation:
+
+    string s = "\u0041\u0308"; // Ä
+
+    writeln(s.length); // 3
+
+    import std.range : walkLength;
+    writeln(s.walkLength); // 2
+
+    import std.uni : byGrapheme;
+    writeln(s.byGrapheme.walkLength); // 1
+
+Here the actual array length of `s` is 3, because it contains 3 code units:
+`0x41`, `0x03` and `0x08`. Those latter two define a single code point
+(combining diacritics character) and
+[`walkLength`](https://dlang.org/library/std/range/primitives/walk_length.html)
+(standard library function to calculate arbitrary range length) counts two code
+points total. Finally, `byGrapheme` performs rather expensive calculations
+to recognize that these two code points combine into a single displayed
+character.
+
+Correct processing of Unicode can be very complicated, but most of the time, D
+developers can simply consider `string` variables as magical byte arrays and
+rely on standard library algorithms to do the right job.
+If by element (code unit) iteration is desired, one can use
+[`byCodeUnit`](http://dlang.org/phobos/std_utf.html#.byCodeUnit).
+
+Auto-decoding in D is explained in more detail
+in the [Unicode gems chapter](gems/unicode).
+
+### Multi-line strings
+
+Strings in D can always span over multiple lines:
+
+    string multiline = "
+    This
+    may be a
+    long document
+    ";
+
+When quotes appear in the document, Wysiwyg strings (see below) or
+[heredoc strings](http://dlang.org/spec/lex.html#delimited_strings) can be used.
+
+### Wysiwyg strings
+
+It is also possible to use raw strings to minimize laborious escaping
+of reserved symbols. Raw strings can be declared using either backticks (`` `
+... ` ``) or the r(aw)-prefix (`r" ... "`).
+
+    string raw  =  `raw "string"`; // raw "string"
+    string raw2 = r"raw `string`"; // raw `string`
+
+D provides even more ways to represent strings - don't hesitate
+to [explore](https://dlang.org/spec/lex.html#string_literals) them.
+
+### In-depth
+
+- [Unicode gem](gems/unicode)
+- [Characters in _Programming in D_](http://ddili.org/ders/d.en/characters.html)
+- [Strings in _Programming in D_](http://ddili.org/ders/d.en/strings.html)
+- [std.utf](http://dlang.org/phobos/std_utf.html) - UTF en-/decoding algorithms
+- [std.uni](http://dlang.org/phobos/std_uni.html) - Unicode algorithms
+- [String Literals in the D spec](http://dlang.org/spec/lex.html#string_literals)
+
+## {SourceCode}
+
+```d
+import std.stdio : writeln, writefln;
+import std.range : walkLength;
+import std.uni : byGrapheme;
+import std.string : format;
+
+void main() {
+    // format generates a string using a printf
+    // like syntax. D allows native UTF string
+    // handling!
+    string str = format("%s %s", "Hellö",
+        "Wörld");
+    writeln("My string: ", str);
+    writeln("Array length (code unit count)"
+        ~ " of string: ", str.length);
+    writeln("Range length (code point count)"
+        ~ " of string: ", str.walkLength);
+    writeln("Character length (grapheme count)"
+        ~ " of string: ",
+        str.byGrapheme.walkLength);
+
+    // Strings are just normal arrays, so any
+    // operation that works on arrays works here
+    // too!
+    import std.array : replace;
+    writeln(replace(str, "lö", "lo"));
+    import std.algorithm : endsWith;
+    writefln("Does %s end with 'rld'? %s",
+        str, endsWith(str, "rld"));
+
+    import std.conv : to;
+    // Convert to UTF-32
+    dstring dstr = to!dstring(str);
+    // .. which of course looks the same!
+    writeln("My dstring: ", dstr);
+}
+```

basics/arrays.md

@@ -0,0 +1,125 @@
+# Arrays
+
+There are two types of Arrays in D: **static** and **dynamic**.
+Access to arrays of any kind is bounds-checked (except when the compiler can prove
+that bounds checks aren't necessary).
+A failed bounds check yields a `RangeError` which aborts the application.
+The brave can disable this safety feature with the
+compiler flag `-boundscheck=off`
+in order to gain speed improvements at the cost of safety.
+
+#### Static arrays
+
+Static arrays are stored on the stack if defined inside a function,
+or in static memory otherwise. They have a fixed,
+compile-time known length. A static array's type includes
+the fixed size:
+
+    int[8] arr;
+
+`arr`'s type is `int[8]`. Note that the size of the array is denoted
+next to the type, and not after the variable name like in C/C++.
+
+#### Dynamic arrays
+
+Dynamic arrays are stored on the heap and can be expanded
+or shrunk at runtime. A dynamic array is created using a `new` expression
+and its length:
+
+    int size = 8; // run-time variable
+    int[] arr = new int[size];
+
+The type of `arr` is `int[]`, which is also called a **slice**. Slices
+are views on a contiguous block of memory and will be explained
+in more detail in the [next section](basics/slices).
+Multi-dimensional arrays can be created easily
+using the `auto arr = new int[3][3]` syntax.
+
+#### Array operations and properties
+
+Arrays can be concatenated using the `~` operator, which
+will create a new dynamic array.
+
+Mathematical operations can
+be applied to whole arrays using a syntax like `c[] = a[] + b[]`, for example.
+This adds all elements of `a` and `b` so that
+`c[0] = a[0] + b[0]`, `c[1] = a[1] + b[1]`, etc. It is also possible
+to perform operations on a whole array with a single
+value:
+
+    a[] *= 2; // multiply all elements by 2
+    a[] %= 26; // calculate the modulo by 26 for all a's
+
+These operations might be optimized
+by the compiler to use special processor instructions that
+do the operations in one go.
+
+Both static and dynamic arrays provide the property `.length`,
+which is read-only for static arrays, but can be used in the case of
+dynamic arrays to change its size dynamically. The
+property `.dup` creates a copy of the array.
+
+When indexing an array through the `arr[idx]` syntax, a special
+`$` symbol denotes an array's length. For example, `arr[$ - 1]` references
+the last element and is a short form for `arr[arr.length - 1]`.
+
+### Exercise
+
+Complete the function `encrypt` to encrypt the secret message.
+The text should be encrypted using *Caesar encryption*,
+which shifts the characters in the alphabet using a certain index.
+The to-be-encrypted text only contains characters in the range `a-z`,
+which should make things easier.
+
+You can browse the solution [here](https://github.com/dlang-tour/core/issues/227).
+
+### In-depth
+
+- [Arrays in _Programming in D_](http://ddili.org/ders/d.en/arrays.html)
+- [D Slices](https://dlang.org/d-array-article.html)
+- [Array specification](https://dlang.org/spec/arrays.html)
+
+## {SourceCode:incomplete}
+
+```d
+import std.stdio : writeln;
+
+/**
+Shifts every character in the
+array `input` for `shift` characters.
+The character range is limited to `a-z`
+and the next character after z is a.
+
+Params:
+    input = array to shift
+    shift = shift length for each char
+Returns:
+    Shifted char array
+*/
+char[] encrypt(char[] input, char shift)
+{
+    auto result = input.dup;
+    // TODO: shift each character
+    return result;
+}
+
+void main()
+{
+    // We will now encrypt the message with
+    // Caesar encryption and a
+    // shift factor of 16!
+    char[] toBeEncrypted = [ 'w','e','l','c',
+      'o','m','e','t','o','d',
+      // The last , is okay and will just
+      // be ignored!
+    ];
+    writeln("Before: ", toBeEncrypted);
+    auto encrypted = encrypt(toBeEncrypted, 16);
+    writeln("After: ", encrypted);
+
+    // Make sure the algorithm works
+    // as expected
+    assert(encrypted == [ 'm','u','b','s','e',
+            'c','u','j','e','t' ]);
+}
+```