diff options
50 files changed, 5776 insertions, 2309 deletions
diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index 79d6838a..18a5a5d7 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -103,11 +103,3 @@ You can buid the site locally to test your changes. Follow the steps below. these commands at `learnxinyminutes-site/`). * Build - `bundle exec middleman build` * Dev server - `bundle exec middleman --force-polling --verbose` - -## Building the site locally, for Nix users - -You can buid the site locally to test your changes too: - -* Clone or zip download the [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site) repo. -* Get the source in place following the instructions above -* Install all site dependencies and start a dev server by running `nix-shell` at the `learnxinyminutes-site/` root directory. diff --git a/clojure.html.markdown b/clojure.html.markdown index c94625d6..16771e25 100644 --- a/clojure.html.markdown +++ b/clojure.html.markdown @@ -416,3 +416,6 @@ Clojuredocs.org has documentation with examples for most core functions: Clojure-doc.org (yes, really) has a number of getting started articles: [http://clojure-doc.org/](http://clojure-doc.org/) + +Clojure for the Brave and True has a great introduction to Clojure and a free online version: +[https://www.braveclojure.com/clojure-for-the-brave-and-true/](https://www.braveclojure.com/clojure-for-the-brave-and-true/) diff --git a/coq.html.markdown b/coq.html.markdown new file mode 100644 index 00000000..115d9ff8 --- /dev/null +++ b/coq.html.markdown @@ -0,0 +1,478 @@ +--- +language: Coq +filename: learncoq.v +contributors: + - ["Philip Zucker", "http://www.philipzucker.com/"] +--- + +The Coq system is a proof assistant. It is designed to build and verify mathematical proofs. The Coq system contains the functional programming language Gallina and is capable of proving properties about programs written in this language. + +Coq is a dependently typed language. This means that the types of the language may depend on the values of variables. In this respect, it is similar to other related languages such as Agda, Idris, F*, Lean, and others. Via the Curry-Howard correspondence, programs, properties and proofs are formalized in the same language. + +Coq is developed in OCaml and shares some syntactic and conceptual similarity with it. Coq is a language containing many fascinating but difficult topics. This tutorial will focus on the programming aspects of Coq, rather than the proving. It may be helpful, but not necessary to learn some OCaml first, especially if you are unfamiliar with functional programming. This tutorial is based upon its OCaml equivalent + +The standard usage model of Coq is to write it with interactive tool assistance, which operates like a high powered REPL. Two common such editors are the CoqIDE and Proof General Emacs mode. + +Inside Proof General `Ctrl+C Ctrl+<Enter>` will evaluate up to your cursor. + + +```coq +(*** Comments ***) + +(* Comments are enclosed in (* and *). It's fine to nest comments. *) + +(* There are no single-line comments. *) + +(*** Variables and functions ***) + +(* The Coq proof assistant can be controlled and queried by a command language called + the vernacular. Vernacular keywords are capitalized and the commands end with a period. + Variable and function declarations are formed with the Definition vernacular. *) + +Definition x := 10. + +(* Coq can sometimes infer the types of arguments, but it is common practice to annotate + with types. *) + +Definition inc_nat (x : nat) : nat := x + 1. + +(* There exists a large number of vernacular commands for querying information. + These can be very useful. *) + +Compute (1 + 1). (* 2 : nat *) (* Compute a result. *) + +Check tt. (* tt : unit *) (* Check the type of an expressions *) + +About plus. (* Prints information about an object *) + +(* Print information including the definition *) +Print true. (* Inductive bool : Set := true : Bool | false : Bool *) + +Search nat. (* Returns a large list of nat related values *) +Search "_ + _". (* You can also search on patterns *) +Search (?a -> ?a -> bool). (* Patterns can have named parameters *) +Search (?a * ?a). + +(* Locate tells you where notation is coming from. Very helpful when you encounter + new notation. *) +Locate "+". + +(* Calling a function with insufficient number of arguments + does not cause an error, it produces a new function. *) +Definition make_inc x y := x + y. (* make_inc is int -> int -> int *) +Definition inc_2 := make_inc 2. (* inc_2 is int -> int *) +Compute inc_2 3. (* Evaluates to 5 *) + +(* Definitions can be chained with "let ... in" construct. + This is roughly the same to assigning values to multiple + variables before using them in expressions in imperative + languages. *) +Definition add_xy : nat := let x := 10 in + let y := 20 in + x + y. + + +(* Pattern matching is somewhat similar to switch statement in imperative + languages, but offers a lot more expressive power. *) +Definition is_zero (x : nat) := + match x with + | 0 => true + | _ => false (* The "_" pattern means "anything else". *) + end. + + +(* You can define recursive function definition using the Fixpoint vernacular.*) +Fixpoint factorial n := match n with + | 0 => 1 + | (S n') => n * factorial n' + end. + + +(* Function application usually doesn't need parentheses around arguments *) +Compute factorial 5. (* 120 : nat *) + +(* ...unless the argument is an expression. *) +Compute factorial (5-1). (* 24 : nat *) + +(* You can define mutually recursive functions using "with" *) +Fixpoint is_even (n : nat) : bool := match n with + | 0 => true + | (S n) => is_odd n +end with + is_odd n := match n with + | 0 => false + | (S n) => is_even n + end. + +(* As Coq is a total programming language, it will only accept programs when it can + understand they terminate. It can be most easily seen when the recursive call is + on a pattern matched out subpiece of the input, as then the input is always decreasing + in size. Getting Coq to understand that functions terminate is not always easy. See the + references at the end of the article for more on this topic. *) + +(* Anonymous functions use the following syntax: *) + +Definition my_square : nat -> nat := fun x => x * x. + +Definition my_id (A : Type) (x : A) : A := x. +Definition my_id2 : forall A : Type, A -> A := fun A x => x. +Compute my_id nat 3. (* 3 : nat *) + +(* You can ask Coq to infer terms with an underscore *) +Compute my_id _ 3. + +(* An implicit argument of a function is an argument which can be inferred from contextual + knowledge. Parameters enclosed in {} are implicit by default *) + +Definition my_id3 {A : Type} (x : A) : A := x. +Compute my_id3 3. (* 3 : nat *) + +(* Sometimes it may be necessary to turn this off. You can make all arguments explicit + again with @ *) +Compute @my_id3 nat 3. + +(* Or give arguments by name *) +Compute my_id3 (A:=nat) 3. + +(* Coq has the ability to extract code to OCaml, Haskell, and Scheme *) +Require Extraction. +Extraction Language OCaml. +Extraction "factorial.ml" factorial. +(* The above produces a file factorial.ml and factorial.mli that holds: + +type nat = +| O +| S of nat + +(** val add : nat -> nat -> nat **) + +let rec add n m = + match n with + | O -> m + | S p -> S (add p m) + +(** val mul : nat -> nat -> nat **) + +let rec mul n m = + match n with + | O -> O + | S p -> add m (mul p m) + +(** val factorial : nat -> nat **) + +let rec factorial n = match n with +| O -> S O +| S n' -> mul n (factorial n') +*) + + +(*** Notation ***) + +(* Coq has a very powerful Notation system that can be used to write expressions in more + natural forms. *) +Compute Nat.add 3 4. (* 7 : nat *) +Compute 3 + 4. (* 7 : nat *) + +(* Notation is a syntactic transformation applied to the text of the program before being + evaluated. Notation is organized into notation scopes. Using different notation scopes + allows for a weak notion of overloading. *) + +(* Imports the Zarith module containing definitions related to the integers Z *) +Require Import ZArith. + +(* Notation scopes can be opened *) +Open Scope Z_scope. + +(* Now numerals and addition are defined on the integers. *) +Compute 1 + 7. (* 8 : Z *) + +(* Integer equality checking *) +Compute 1 =? 2. (* false : bool *) + +(* Locate is useful for finding the origin and definition of notations *) +Locate "_ =? _". (* Z.eqb x y : Z_scope *) +Close Scope Z_scope. + +(* We're back to nat being the default interpretation of "+" *) +Compute 1 + 7. (* 8 : nat *) + +(* Scopes can also be opened inline with the shorthand % *) +Compute (3 * -7)%Z. (* -21%Z : Z *) + +(* Coq declares by default the following interpretation scopes: core_scope, type_scope, + function_scope, nat_scope, bool_scope, list_scope, int_scope, uint_scope. You may also + want the numerical scopes Z_scope (integers) and Q_scope (fractions) held in the ZArith + and QArith module respectively. *) + +(* You can print the contents of scopes *) +Print Scope nat_scope. +(* +Scope nat_scope +Delimiting key is nat +Bound to classes nat Nat.t +"x 'mod' y" := Nat.modulo x y +"x ^ y" := Nat.pow x y +"x ?= y" := Nat.compare x y +"x >= y" := ge x y +"x > y" := gt x y +"x =? y" := Nat.eqb x y +"x <? y" := Nat.ltb x y +"x <=? y" := Nat.leb x y +"x <= y <= z" := and (le x y) (le y z) +"x <= y < z" := and (le x y) (lt y z) +"n <= m" := le n m +"x < y <= z" := and (lt x y) (le y z) +"x < y < z" := and (lt x y) (lt y z) +"x < y" := lt x y +"x / y" := Nat.div x y +"x - y" := Init.Nat.sub x y +"x + y" := Init.Nat.add x y +"x * y" := Init.Nat.mul x y +*) + +(* Coq has exact fractions available as the type Q in the QArith module. + Floating point numbers and real numbers are also available but are a more advanced + topic, as proving properties about them is rather tricky. *) + +Require Import QArith. + +Open Scope Q_scope. +Compute 1. (* 1 : Q *) +Compute 2. (* 2 : nat *) (* only 1 and 0 are interpreted as fractions by Q_scope *) +Compute (2 # 3). (* The fraction 2/3 *) +Compute (1 # 3) ?= (2 # 6). (* Eq : comparison *) +Close Scope Q_scope. + +Compute ( (2 # 3) / (1 # 5) )%Q. (* 10 # 3 : Q *) + + +(*** Common data structures ***) + +(* Many common data types are included in the standard library *) + +(* The unit type has exactly one value, tt *) +Check tt. (* tt : unit *) + +(* The option type is useful for expressing computations that might fail *) +Compute None. (* None : option ?A *) +Check Some 3. (* Some 3 : option nat *) + +(* The type sum A B allows for values of either type A or type B *) +Print sum. +Check inl 3. (* inl 3 : nat + ?B *) +Check inr true. (* inr true : ?A + bool *) +Check sum bool nat. (* (bool + nat)%type : Set *) +Check (bool + nat)%type. (* Notation for sum *) + +(* Tuples are (optionally) enclosed in parentheses, items are separated + by commas. *) +Check (1, true). (* (1, true) : nat * bool *) +Compute prod nat bool. (* (nat * bool)%type : Set *) + +Definition my_fst {A B : Type} (x : A * B) : A := match x with + | (a,b) => a + end. + +(* A destructuring let is available if a pattern match is irrefutable *) +Definition my_fst2 {A B : Type} (x : A * B) : A := let (a,b) := x in + a. + +(*** Lists ***) + +(* Lists are built by using cons and nil or by using notation available in list_scope. *) +Compute cons 1 (cons 2 (cons 3 nil)). (* (1 :: 2 :: 3 :: nil)%list : list nat *) +Compute (1 :: 2 :: 3 :: nil)%list. + +(* There is also list notation available in the ListNotations modules *) +Require Import List. +Import ListNotations. +Compute [1 ; 2 ; 3]. (* [1; 2; 3] : list nat *) + + +(* +There are a large number of list manipulation functions available, including: + +• length +• head : first element (with default) +• tail : all but first element +• app : appending +• rev : reverse +• nth : accessing n-th element (with default) +• map : applying a function +• flat_map : applying a function returning lists +• fold_left : iterator (from head to tail) +• fold_right : iterator (from tail to head) + + *) + +Definition my_list : list nat := [47; 18; 34]. + +Compute List.length my_list. (* 3 : nat *) +(* All functions in coq must be total, so indexing requires a default value *) +Compute List.nth 1 my_list 0. (* 18 : nat *) +Compute List.map (fun x => x * 2) my_list. (* [94; 36; 68] : list nat *) +Compute List.filter (fun x => Nat.eqb (Nat.modulo x 2) 0) my_list. (* [18; 34] : list nat *) +Compute (my_list ++ my_list)%list. (* [47; 18; 34; 47; 18; 34] : list nat *) + +(*** Strings ***) + +Require Import Strings.String. + +(* Use double quotes for string literals. *) +Compute "hi"%string. + +Open Scope string_scope. + +(* Strings can be concatenated with the "++" operator. *) +Compute String.append "Hello " "World". (* "Hello World" : string *) +Compute "Hello " ++ "World". (* "Hello World" : string *) + +(* Strings can be compared for equality *) +Compute String.eqb "Coq is fun!" "Coq is fun!". (* true : bool *) +Compute "no" =? "way". (* false : bool *) + +Close Scope string_scope. + +(*** Other Modules ***) + +(* Other Modules in the standard library that may be of interest: + +• Logic : Classical logic and dependent equality +• Arith : Basic Peano arithmetic +• PArith : Basic positive integer arithmetic +• NArith : Basic binary natural number arithmetic +• ZArith : Basic relative integer arithmetic +• Numbers : Various approaches to natural, integer and cyclic numbers (currently + axiomatically and on top of 2^31 binary words) +• Bool : Booleans (basic functions and results) +• Lists : Monomorphic and polymorphic lists (basic functions and results), + Streams (infinite sequences defined with co-inductive types) +• Sets : Sets (classical, constructive, finite, infinite, power set, etc.) +• FSets : Specification and implementations of finite sets and finite maps + (by lists and by AVL trees) +• Reals : Axiomatization of real numbers (classical, basic functions, integer part, + fractional part, limit, derivative, Cauchy series, power series and results,...) +• Relations : Relations (definitions and basic results) +• Sorting : Sorted list (basic definitions and heapsort correctness) +• Strings : 8-bits characters and strings +• Wellfounded : Well-founded relations (basic results) + *) + +(*** User-defined data types ***) + +(* Because Coq is dependently typed, defining type aliases is no different than defining + an alias for a value. *) + +Definition my_three : nat := 3. +Definition my_nat : Type := nat. + +(* More interesting types can be defined using the Inductive vernacular. Simple enumeration + can be defined like so *) +Inductive ml := OCaml | StandardML | Coq. +Definition lang := Coq. (* Has type "ml". *) + +(* For more complicated types, you will need to specify the types of the constructors. *) + +(* Type constructors don't need to be empty. *) +Inductive my_number := plus_infinity + | nat_value : nat -> my_number. +Compute nat_value 3. (* nat_value 3 : my_number *) + + +(* Record syntax is sugar for tuple-like types. It defines named accessor functions for + the components. Record types are defined with the notation {...} *) +Record Point2d (A : Set) := mkPoint2d { x2 : A ; y2 : A }. +(* Record values are constructed with the notation {|...|} *) +Definition mypoint : Point2d nat := {| x2 := 2 ; y2 := 3 |}. +Compute x2 nat mypoint. (* 2 : nat *) +Compute mypoint.(x2 nat). (* 2 : nat *) + +(* Types can be parameterized, like in this type for "list of lists + of anything". 'a can be substituted with any type. *) +Definition list_of_lists a := list (list a). +Definition list_list_nat := list_of_lists nat. + +(* Types can also be recursive. Like in this type analogous to + built-in list of naturals. *) + +Inductive my_nat_list := EmptyList | NatList : nat -> my_nat_list -> my_nat_list. +Compute NatList 1 EmptyList. (* NatList 1 EmptyList : my_nat_list *) + +(** Matching type constructors **) + +Inductive animal := Dog : string -> animal | Cat : string -> animal. + +Definition say x := + match x with + | Dog x => (x ++ " says woof")%string + | Cat x => (x ++ " says meow")%string + end. + +Compute say (Cat "Fluffy"). (* "Fluffy says meow". *) + +(** Traversing data structures with pattern matching **) + +(* Recursive types can be traversed with pattern matching easily. + Let's see how we can traverse a data structure of the built-in list type. + Even though the built-in cons ("::") looks like an infix operator, + it's actually a type constructor and can be matched like any other. *) +Fixpoint sum_list l := + match l with + | [] => 0 + | head :: tail => head + (sum_list tail) + end. + +Compute sum_list [1; 2; 3]. (* Evaluates to 6 *) + + +(*** A Taste of Proving ***) + +(* Explaining the proof language is out of scope for this tutorial, but here is a taste to + whet your appetite. Check the resources below for more. *) + +(* A fascinating feature of dependently type based theorem provers is that the same + primitive constructs underly the proof language as the programming features. + For example, we can write and prove the proposition A and B implies A in raw Gallina *) + +Definition my_theorem : forall A B, A /\ B -> A := fun A B ab => match ab with + | (conj a b) => a + end. + +(* Or we can prove it using tactics. Tactics are a macro language to help build proof terms + in a more natural style and automate away some drudgery. *) +Theorem my_theorem2 : forall A B, A /\ B -> A. +Proof. + intros A B ab. destruct ab as [ a b ]. apply a. +Qed. + +(* We can prove easily prove simple polynomial equalities using the automated tactic ring. *) +Require Import Ring. +Require Import Arith. +Theorem simple_poly : forall (x : nat), (x + 1) * (x + 2) = x * x + 3 * x + 2. + Proof. intros. ring. Qed. + +(* Here we prove the closed form for the sum of all numbers 1 to n using induction *) + +Fixpoint sumn (n : nat) : nat := + match n with + | 0 => 0 + | (S n') => n + (sumn n') + end. + +Theorem sum_formula : forall n, 2 * (sumn n) = (n + 1) * n. +Proof. intros n. induction n. + - reflexivity. (* 0 = 0 base case *) + - simpl. ring [IHn]. (* induction step *) +Qed. +``` + +With this we have only scratched the surface of Coq. It is a massive ecosystem with many interesting and peculiar topics leading all the way up to modern research. + +## Further reading + +* [The Coq reference manual](https://coq.inria.fr/refman/) +* [Software Foundations](https://softwarefoundations.cis.upenn.edu/) +* [Certified Programming with Dependent Types](http://adam.chlipala.net/cpdt/) +* [Mathematical Components](https://math-comp.github.io/mcb/) +* [Coq'Art: The Calculus of Inductive Constructions](http://www.cse.chalmers.se/research/group/logic/TypesSS05/resources/coq/CoqArt/) +* [FRAP](http://adam.chlipala.net/frap/) diff --git a/csharp.html.markdown b/csharp.html.markdown index df6544d3..37573e01 100644 --- a/csharp.html.markdown +++ b/csharp.html.markdown @@ -14,20 +14,22 @@ filename: LearnCSharp.cs C# is an elegant and type-safe object-oriented language that enables developers to build a variety of secure and robust applications that run on the .NET Framework. -[Read more here.](http://msdn.microsoft.com/en-us/library/vstudio/z1zx9t92.aspx) +[Read more here.](https://docs.microsoft.com/dotnet/csharp/getting-started/introduction-to-the-csharp-language-and-the-net-framework) ```c# // Single-line comments start with // + /* Multi-line comments look like this */ + /// <summary> /// This is an XML documentation comment which can be used to generate external /// documentation or provide context help within an IDE /// </summary> /// <param name="firstParam">This is some parameter documentation for firstParam</param> /// <returns>Information on the returned value of a function</returns> -//public void MethodOrClassOrOtherWithParsableHelp(string firstParam) {} +public void MethodOrClassOrOtherWithParsableHelp(string firstParam) {} // Specify the namespaces this source code will be using // The namespaces below are all part of the standard .NET Framework Class Library @@ -254,7 +256,7 @@ on a new line! ""Wow!"", the masses cried"; int fooWhile = 0; while (fooWhile < 100) { - //Iterated 100 times, fooWhile 0->99 + // Iterated 100 times, fooWhile 0->99 fooWhile++; } @@ -273,10 +275,10 @@ on a new line! ""Wow!"", the masses cried"; } while (fooDoWhile < 100); - //for loop structure => for(<start_statement>; <conditional>; <step>) + // for loop structure => for(<start_statement>; <conditional>; <step>) for (int fooFor = 0; fooFor < 10; fooFor++) { - //Iterated 10 times, fooFor 0->9 + // Iterated 10 times, fooFor 0->9 } // For Each Loop @@ -287,7 +289,7 @@ on a new line! ""Wow!"", the masses cried"; // (The ToCharArray() could be removed, because a string also implements IEnumerable) foreach (char character in "Hello World".ToCharArray()) { - //Iterated over all the characters in the string + // Iterated over all the characters in the string } // Switch Case @@ -329,7 +331,7 @@ on a new line! ""Wow!"", the masses cried"; // Convert String To Integer // this will throw a FormatException on failure - int.Parse("123");//returns an integer version of "123" + int.Parse("123"); // returns an integer version of "123" // try parse will default to type default on failure // in this case: 0 @@ -373,7 +375,7 @@ on a new line! ""Wow!"", the masses cried"; Console.Read(); } // End main method - // CONSOLE ENTRY A console application must have a main method as an entry point + // CONSOLE ENTRY - A console application must have a main method as an entry point public static void Main(string[] args) { OtherInterestingFeatures(); @@ -404,7 +406,7 @@ on a new line! ""Wow!"", the masses cried"; ref int maxCount, // Pass by reference out int count) { - //the argument passed in as 'count' will hold the value of 15 outside of this function + // the argument passed in as 'count' will hold the value of 15 outside of this function count = 15; // out param must be assigned before control leaves the method } @@ -552,7 +554,7 @@ on a new line! ""Wow!"", the masses cried"; } // PARALLEL FRAMEWORK - // http://blogs.msdn.com/b/csharpfaq/archive/2010/06/01/parallel-programming-in-net-framework-4-getting-started.aspx + // https://devblogs.microsoft.com/csharpfaq/parallel-programming-in-net-framework-4-getting-started/ var words = new List<string> {"dog", "cat", "horse", "pony"}; @@ -564,11 +566,11 @@ on a new line! ""Wow!"", the masses cried"; } ); - //Running this will produce different outputs - //since each thread finishes at different times. - //Some example outputs are: - //cat dog horse pony - //dog horse pony cat + // Running this will produce different outputs + // since each thread finishes at different times. + // Some example outputs are: + // cat dog horse pony + // dog horse pony cat // DYNAMIC OBJECTS (great for working with other languages) dynamic student = new ExpandoObject(); @@ -865,7 +867,7 @@ on a new line! ""Wow!"", the masses cried"; } } - //Method to display the attribute values of this Object. + // Method to display the attribute values of this Object. public virtual string Info() { return "Gear: " + Gear + @@ -960,7 +962,7 @@ on a new line! ""Wow!"", the masses cried"; /// <summary> /// Used to connect to DB for LinqToSql example. /// EntityFramework Code First is awesome (similar to Ruby's ActiveRecord, but bidirectional) - /// http://msdn.microsoft.com/en-us/data/jj193542.aspx + /// https://docs.microsoft.com/ef/ef6/modeling/code-first/workflows/new-database /// </summary> public class BikeRepository : DbContext { @@ -1069,7 +1071,7 @@ on a new line! ""Wow!"", the masses cried"; { private static bool LogException(Exception ex) { - /* log exception somewhere */ + // log exception somewhere return false; } @@ -1117,12 +1119,12 @@ on a new line! ""Wow!"", the masses cried"; [Obsolete("Use NewMethod instead", false)] public static void ObsoleteMethod() { - /* obsolete code */ + // obsolete code } public static void NewMethod() { - /* new code */ + // new code } public static void Main() @@ -1154,9 +1156,9 @@ namespace Learning.More.CSharp } } -//New C# 7 Feature -//Install Microsoft.Net.Compilers Latest from Nuget -//Install System.ValueTuple Latest from Nuget +// New C# 7 Feature +// Install Microsoft.Net.Compilers Latest from Nuget +// Install System.ValueTuple Latest from Nuget using System; namespace Csharp7 { @@ -1310,13 +1312,11 @@ namespace Csharp7 ## Further Reading - * [DotNetPerls](http://www.dotnetperls.com) - * [C# in Depth](http://manning.com/skeet2) - * [Programming C#](http://shop.oreilly.com/product/0636920024064.do) - * [LINQ](http://shop.oreilly.com/product/9780596519254.do) - * [MSDN Library](http://msdn.microsoft.com/en-us/library/618ayhy6.aspx) - * [ASP.NET MVC Tutorials](http://www.asp.net/mvc/tutorials) - * [ASP.NET Web Matrix Tutorials](http://www.asp.net/web-pages/tutorials) - * [ASP.NET Web Forms Tutorials](http://www.asp.net/web-forms/tutorials) - * [Windows Forms Programming in C#](http://www.amazon.com/Windows-Forms-Programming-Chris-Sells/dp/0321116208) - * [C# Coding Conventions](http://msdn.microsoft.com/en-us/library/vstudio/ff926074.aspx) + * [C# language reference](https://docs.microsoft.com/dotnet/csharp/language-reference/) + * [Learn .NET](https://dotnet.microsoft.com/learn) + * [C# Coding Conventions](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions) + * [DotNetPerls](https://www.dotnetperls.com/) + * [C# in Depth](https://manning.com/skeet3) + * [Programming C# 5.0](http://shop.oreilly.com/product/0636920024064) + * [LINQ Pocket Reference](http://shop.oreilly.com/product/9780596519254) + * [Windows Forms Programming in C#](https://www.amazon.com/Windows-Forms-Programming-Chris-Sells/dp/0321116208) diff --git a/de-de/bash-de.html.markdown b/de-de/bash-de.html.markdown index 7a0db157..3fb3e71f 100644 --- a/de-de/bash-de.html.markdown +++ b/de-de/bash-de.html.markdown @@ -217,7 +217,7 @@ done function foo () { echo "Argumente funktionieren wie bei skripts: $@" - echo Und: $1 $2..." + echo "Und: $1 $2..." echo "Dies ist eine Funktion" return 0 } diff --git a/de-de/c++-de.html.markdown b/de-de/c++-de.html.markdown index cef7514b..87e75ad6 100644 --- a/de-de/c++-de.html.markdown +++ b/de-de/c++-de.html.markdown @@ -9,6 +9,7 @@ contributors: - ["Ankush Goyal", "http://github.com/ankushg07"] - ["Jatin Dhankhar", "https://github.com/jatindhankhar"] - ["Maximilian Sonnenburg", "https://github.com/LamdaLamdaLamda"] + - ["caminsha", "https://github.com/caminsha"] lang: de-de --- @@ -22,9 +23,9 @@ entworfen wurde um, - Objektorientierung zu unterstützen - generische Programmierung zu unterstützen -Durch seinen Syntax kann sie durchaus schwieriger und komplexer als neuere Sprachen sein. +Durch seine Syntax kann sie durchaus schwieriger und komplexer als neuere Sprachen sein. -Sie ist weit verbreitet, weil sie in Maschinen-Code kompiliert, welches direkt vom Prozessor ausgeführt +Sie ist weit verbreitet, weil sie in Maschinen-Code kompiliert, welcher direkt vom Prozessor ausgeführt werden kann und somit eine strikte Kontrolle über die Hardware bietet und gleichzeitig High-Level-Features wie generics, exceptions und Klassen enthält. @@ -36,7 +37,7 @@ weitverbreitesten Programmiersprachen. // Vergleich zu C ////////////////// -// C ist fast eine Untermenge von C++ und teilt sich grundsätzlich den +// C ist fast eine Untermenge von C++ und teilt sich grundsätzlich die // Syntax für Variablen Deklarationen, primitiven Typen und Funktionen. // Wie in C ist der Programmeinsprungpunkt eine Funktion, welche "main" genannt wird und @@ -137,7 +138,7 @@ void invalidDeclaration(int a = 1, int b) // Fehler! ///////////// -// Namespaces (Namesräume) +// Namespaces (Namensräume) ///////////// // Namespaces stellen einen getrennten Gültigkeitsbereich für Variablen, @@ -169,7 +170,7 @@ void foo() int main() { - // Fügt all Symbole aus dem namespace Second in den aktuellen Gültigkeitsbereich (scope). + // Fügt alle Symbole aus dem namespace Second in den aktuellen Gültigkeitsbereich (scope). // "foo()" wird nun nicht länger funktionieren, da es nun doppeldeutig ist, ob foo aus // dem namespace foo oder darüberliegenden aufgerufen wird. using namespace Second; @@ -283,7 +284,7 @@ string retVal = tempObjectFun(); // für Details). Wie in diesem Code: foo(bar(tempObjectFun())) -// Nehmen wir an foo und bar existieren. Das Objekt wird von "tempObjectFun" zurückgegeben, +// Nehmen wir an, foo und bar existieren. Das Objekt wird von "tempObjectFun" zurückgegeben, // wird an bar übergeben und ist zerstört bevor foo aufgerufen wird. // Zurück zu Referenzen. Die Annahme, dass die "am Ende des Ausdrucks" Regel gültig ist, @@ -335,7 +336,7 @@ ECarTypes GetPreferredCarType() return ECarTypes::Hatchback; } -// Mit C++11 existiert eine einfache Möglichkeit einem Typ dem Enum zu zuweisen. Dies +// Mit C++11 existiert eine einfache Möglichkeit einem Typ dem Enum zuzuweisen. Dies // kann durchaus sinnvoll bei der Serialisierung von Daten sein, oder bei der Konvertierung // zwischen Typen bzw. Konstanten. enum ECarTypes : uint8_t @@ -574,7 +575,7 @@ int main () // Templates in C++ werden in erster Linie dafür verwendet generisch zu programmieren. // Sie unterstützen explizite und partielle Spezialisierung und darüber hinaus können // sie für funktionale Klassen verwendet werden. -// Tatsächlich bilden templates die Turing-Vollständigkeit +// Tatsächlich bilden Templates die Turing-Vollständigkeit // (universelle Programmierbarkeit) ab. @@ -588,12 +589,12 @@ public: void insert(const T&) { ... } }; -// Während der Kompilierung generiert der Compiler Kopien für jedes template, wobei +// Während der Kompilierung generiert der Compiler Kopien für jedes Template, wobei // hierbei die Parameter substituiert werden. Somit muss bei jedem Aufruf die gesamte // Definition der Klasse zur Verfügung stehen. Aus diesem Grund wird ein Template // komplett im header definiert. -// Erzeugung einer Template-Klasse auf dem stack: +// Erzeugung einer Template-Klasse auf dem Stack: Box<int> intBox; // eine der zu erwartenden Verwendungen: @@ -612,7 +613,7 @@ boxOfBox.insert(intBox); // sind fast identisch hinsichtlich der Funktionalität. Weitere // Informationen auf: http://en.wikipedia.org/wiki/Typename -// Eine template-Funktion: +// Eine Template-Funktion: template<class T> void barkThreeTimes(const T& input) { @@ -622,7 +623,7 @@ void barkThreeTimes(const T& input) } // Hierbei ist zu beachten, dass an dieser Stelle nichts über den Typen des Parameters -// definiert wurde. Der Kompiler wird bei jedem Aufruf bzw. jeder Erzeugung den Typen +// definiert wurde. Der Compiler wird bei jedem Aufruf bzw. jeder Erzeugung den Typen // prüfen. Somit funktioniert die zuvor definierte Funktion für jeden Typ 'T', die die // const Methode 'bark' implementiert hat. @@ -637,10 +638,10 @@ void printMessage() cout << "Learn C++ in " << Y << " minutes!" << endl; } -// Des Weiteren können templates aus Effizienzgründen genauer spezifiziert werden. -// Selbstverständlich sind reale-Problemen, welche genauer spezifiziert werden nicht +// Des Weiteren können Templates aus Effizienzgründen genauer spezifiziert werden. +// Selbstverständlich sind reale Probleme, welche genauer spezifiziert werden, nicht // derart trivial. Auch wenn alle Parameter explizit definiert wurden, muss die -// Funktion oder Klasse als template deklariert werden. +// Funktion oder Klasse als Template deklariert werden. template<> void printMessage<10>() { @@ -818,9 +819,9 @@ void doSomethingWithAFile(const std::string& filename) // Container ///////////////////// -// Die Container der Standard template Bibliothek beinhaltet einige vordefinierter templates. +// Die Container der Standard template Bibliothek beinhaltet einige vordefinierte Templates. // Diese verwalten die Speicherbereiche für die eigenen Elemente und stellen Member-Funktionen -// für den Zugriff und die Maniplulation bereit. +// für den Zugriff und die Manipulation bereit. // Beispielhafte Container: @@ -876,7 +877,7 @@ for(it=ST.begin();it<ST.end();it++) // 10 // 30 -// Zum leeren des gesamten Container wird die Methode +// Zum leeren des gesamten Containers wird die Methode // Container._name.clear() verwendet. ST.clear(); cout << ST.size(); // Ausgabe der Set-Größe @@ -948,11 +949,11 @@ fooMap.find(Foo(1)); // Wahr // Lambda Ausdrücke (C++11 und höher) /////////////////////////////////////// -// Lambdas sind eine gängige Methodik um anonyme Funktionen an dem +// Lambdas sind eine gängige Methodik, um anonyme Funktionen an dem // Ort der Verwendung zu definieren. Darüber hinaus auch bei der // Verwendung von Funktionen als Argument einer Funktion. -// Nehmen wir an es soll ein Vektor von "pairs" (Paaren) mithilfe +// Nehmen wir an, es soll ein Vektor von "pairs" (Paaren) mithilfe // des zweiten Werts des "pairs" sortiert werden. vector<pair<int, int> > tester; @@ -966,7 +967,7 @@ sort(tester.begin(), tester.end(), [](const pair<int, int>& lhs, const pair<int, return lhs.second < rhs.second; }); -// Beachte den Syntax von Lambda-Ausdrücken. +// Beachte die Syntax von Lambda-Ausdrücken. // Die [] im Lambda Ausdruck werden für die Variablen verwendet. // Diese so genannte "capture list" definiert, was außerhalb des Lambdas, // innerhalb der Funktion verfügbar sein soll und in welcher Form. @@ -1025,7 +1026,7 @@ for(auto elem: arr) // Einige Aspekte von C++ sind für Neueinsteiger häufig überraschend (aber auch für // C++ Veteranen). // Der nachfolgende Abschnitt ist leider nicht vollständig: -// C++ ist eine der Sprachen, bei der es ein leichtes ist sich selbst ins Bein zu schießen. +// C++ ist eine der Sprachen, bei der es ein Leichtes ist, sich selbst ins Bein zu schießen. // Private-Methoden können überschrieben werden class Foo @@ -1074,10 +1075,10 @@ f1 = f2; #include<tuple> -// Konzeptionell sind Tuple´s alten Datenstrukturen sehr ähnlich, allerdings haben diese keine +// Konzeptionell sind Tupel alten Datenstrukturen sehr ähnlich, allerdings haben diese keine // bezeichneten Daten-Member, sondern werden durch die Reihenfolge angesprochen. -// Erstellen des Tuples und das Einfügen eines Werts. +// Erstellen des Tupels und das Einfügen eines Werts. auto first = make_tuple(10, 'A'); const int maxN = 1e9; const int maxL = 15; @@ -1102,7 +1103,7 @@ tuple<int, char, double> third(11, 'A', 3.14141); cout << tuple_size<decltype(third)>::value << "\n"; // prints: 3 -// tuple_cat fügt die Elemente eines Tuples aneinander (in der selben Reihenfolge). +// tuple_cat fügt die Elemente eines Tupels aneinander (in der selben Reihenfolge). auto concatenated_tuple = tuple_cat(first, second, third); // concatenated_tuple wird zu = (10, 'A', 1e9, 15, 11, 'A', 3.14141) diff --git a/de-de/nix-de.html.markdown b/de-de/nix-de.html.markdown index 79b60d20..ea02e81d 100644 --- a/de-de/nix-de.html.markdown +++ b/de-de/nix-de.html.markdown @@ -8,11 +8,11 @@ translators: lang: de-de --- -Nix ist eine simple funktionale Programmiersprache, die für den +Nix ist eine simple funktionale Programmiersprache, die für den [Nix package manager](https://nixos.org/nix/) und [NixOS](https://nixos.org/) entwickelt wurde. -Du kannst Nix Ausdrücke evaluieren mithilfe von +Du kannst Nix Ausdrücke evaluieren mithilfe von [nix-instantiate](https://nixos.org/nix/manual/#sec-nix-instantiate) oder [`nix-repl`](https://github.com/edolstra/nix-repl). @@ -24,7 +24,7 @@ with builtins; [ # Inline Kommentare sehen so aus. - /* Multizeilen Kommentare + /* Multizeilen Kommentare sehen so aus. */ @@ -61,7 +61,7 @@ with builtins; [ "String Literale sind in Anführungszeichen." " - String Literale können mehrere + String Literale können mehrere Zeilen umspannen. " @@ -95,7 +95,7 @@ with builtins; [ tutorials/learn.nix #=> /the-base-path/tutorials/learn.nix - # Ein Pfad muss mindestens einen Schrägstrich enthalten. Ein Pfad für eine + # Ein Pfad muss mindestens einen Schrägstrich enthalten. Ein Pfad für eine # Datei im selben Verzeichnis benötigt ein ./ Präfix. ./learn.nix #=> /the-base-path/learn.nix @@ -238,7 +238,7 @@ with builtins; [ #=> { d = 2; e = 3; } # Die Nachkommen eines Attributs können in diesem Feld nicht zugeordnet werden, wenn - # das Attribut selbst nicht zugewiesen wurde. + # das Attribut selbst nicht zugewiesen wurde. { a = { b = 1; }; a.c = 2; @@ -261,9 +261,9 @@ with builtins; [ #=> 7 # Die erste Linie diese Tutorials startet mit "with builtins;", - # weil builtins ein Set mit allen eingebauten + # weil builtins ein Set mit allen eingebauten # Funktionen (length, head, tail, filter, etc.) umfasst. - # Das erspart uns beispielsweise "builtins.length" zu schreiben, + # Das erspart uns beispielsweise "builtins.length" zu schreiben, # anstatt nur "length". @@ -305,7 +305,7 @@ with builtins; [ (tryEval (abort "foo")) #=> error: evaluation aborted with the following error message: ‘foo’ - # `assert` evaluiert zu dem gegebenen Wert, wenn die Bedingung wahr ist, sonst + # `assert` evaluiert zu dem gegebenen Wert, wenn die Bedingung wahr ist, sonst # löst es eine abfangbare Exception aus. (assert 1 < 2; 42) #=> 42 @@ -319,7 +319,7 @@ with builtins; [ #========================================= # Da die Wiederholbarkeit von Builds für den Nix Packetmanager entscheidend ist, - # werden in der Nix Sprache reine funktionale Elemente betont. Es gibt aber ein paar + # werden in der Nix Sprache reine funktionale Elemente betont. Es gibt aber ein paar # unreine Elemente. # Du kannst auf Umgebungsvariablen verweisen. (getEnv "HOME") @@ -355,4 +355,4 @@ with builtins; [ (https://medium.com/@MrJamesFisher/nix-by-example-a0063a1a4c55) * [Susan Potter - Nix Cookbook - Nix By Example] - (http://funops.co/nix-cookbook/nix-by-example/) + (https://ops.functionalalgebra.com/nix-by-example/) diff --git a/fr-fr/elixir-fr.html.markdown b/fr-fr/elixir-fr.html.markdown new file mode 100644 index 00000000..90cdad7c --- /dev/null +++ b/fr-fr/elixir-fr.html.markdown @@ -0,0 +1,479 @@ +--- +language: elixir +contributors: + - ["Joao Marques", "http://github.com/mrshankly"] + - ["Dzianis Dashkevich", "https://github.com/dskecse"] + - ["Ryan Plant", "https://github.com/ryanplant-au"] + - ["Ev Bogdanov", "https://github.com/evbogdanov"] +translator: + - ["Timothé Pardieu", "https://github.com/timprd"] +filename: learnelixir-fr.ex +lang: fr-fr +--- +Elixir est un langage de programmation fonctionnel moderne reposant sur la machine virtuelle BEAM, qui héberge aussi Erlang. +Il est totalement compatible avec Erlang mais dispose d'une syntaxe plus agréable et apporte de nouvelles fonctionnalités. + + +```elixir + +# Un commentaire simple sur une seule ligne commence par un dièse. + +# Il n'y a pas de commentaire multi-ligne, +# Mais il est possible de les empiler comme ici. + +# La commande `iex` permet de lancer le shell Elixir. +# La commande `elixirc` permet de compiler vos modules. + +# Les deux devraient être dans votre path si vous avez installé Elixir correctement. + +## --------------------------- +## -- Types basiques +## --------------------------- + +# Il y a les nombres +3 # Integer +0x1F # Integer +3.0 # Float + +# Les atomes, des littéraux, qui sont des constantes avec comme valeur leur nom. +# Ils commencent par `:`. + +:hello # atom + +# Il existe également des n-uplets dont les valeurs sont stockés de manière contiguë +# en mémoire. + +{1,2,3} # tuple + +# Il est possible d'accéder à un element d'un tuple avec la fonction +# `elem`: +elem({1, 2, 3}, 0) #=> 1 + +# Les listes sont implémentées sous forme de listes chainées. +[1,2,3] # list + +# La tête et le reste d'une liste peuvent être récupérés comme cela : +[head | tail] = [1,2,3] +head #=> 1 +tail #=> [2,3] + +# En Elixir, comme en Erlang, le `=` dénote un 'pattern matching' +# (Filtrage par motif) et non une affectation. +# Cela signifie que la partie de gauche (pattern) est comparé (match) à +# la partie de droite. + + +# Une erreur sera lancée si aucun model (match) est trouvé. +# Dans cet exemple les tuples ont des tailles différentes +# {a, b, c} = {1, 2} #=> ** (MatchError) no match of right hand side value: {1,2} + +# Il y a aussi les binaires +<<1,2,3>> # binary + +# Chaine de caractères et liste de caractères +"hello" # string +'hello' # char list + +# Chaine de caractères sur plusieurs lignes +""" +Je suis une chaine de caractères +sur plusieurs lignes. +""" +#=> "Je suis une chaine de caractères\nsur plusieurs lignes.\n" + +# Les chaines de caractères sont encodées en UTF-8 : +"héllò" #=> "héllò" + +# Les chaines de caractères sont des binaires tandis que +# les listes de caractères sont des listes. +<<?a, ?b, ?c>> #=> "abc" +[?a, ?b, ?c] #=> 'abc' + +# `?a` en Elixir retourne le code ASCII (Integer) de la lettre `a` +?a #=> 97 + +# Pour concaténer des listes il faut utiliser `++`, et `<>` pour les +# binaires +[1,2,3] ++ [4,5] #=> [1,2,3,4,5] +'hello ' ++ 'world' #=> 'hello world' + +<<1,2,3>> <> <<4,5>> #=> <<1,2,3,4,5>> +"hello " <> "world" #=> "hello world" + +# Les intervalles sont représentés de cette sorte `début..fin` +# (tout deux inclusifs) +1..10 #=> 1..10 +bas..haut = 1..10 # Possibilité d'utiliser le pattern matching sur les intervalles aussi. +[bas, haut] #=> [1, 10] + +# Les Maps (Tableau associatif) sont des paires clée - valeur +genders = %{"david" => "male", "gillian" => "female"} +genders["david"] #=> "male" + +# Les maps avec des atomes peuvent être utilisés comme cela +genders = %{david: "male", gillian: "female"} +genders.gillian #=> "female" + +## --------------------------- +## -- Operateurs +## --------------------------- + +# Mathématiques +1 + 1 #=> 2 +10 - 5 #=> 5 +5 * 2 #=> 10 +10 / 2 #=> 5.0 + +# En Elixir l'opérateur `/` retourne toujours un Float (virgule flottante). + +# Pour faire une division avec entier il faut utiliser `div` +div(10, 2) #=> 5 + +# Pour obtenir le reste de la division il faut utiliser `rem` +rem(10, 3) #=> 1 + +# Il y a aussi les opérateurs booléen: `or`, `and` et `not`. +# Ces opérateurs attendent un booléen en premier argument. +true and true #=> true +false or true #=> true +# 1 and true +#=> ** (BadBooleanError) expected a booléens on left-side of "and", got: 1 + +# Elixir fournit aussi `||`, `&&` et `!` qui acceptent des arguments de +# tout type. +# Chaque valeur sauf `false` et `nil` seront évalués à vrai (true). +1 || true #=> 1 +false && 1 #=> false +nil && 20 #=> nil +!true #=> false + +# Pour les comparaisons il y a : `==`, `!=`, `===`, `!==`, `<=`, `>=`, `<` et `>` +1 == 1 #=> true +1 != 1 #=> false +1 < 2 #=> true + +# `===` et `!==` sont plus stricts en comparant les Integers (entiers) +# et les Floats (nombres à virgules) : +1 == 1.0 #=> true +1 === 1.0 #=> false + +# On peut aussi comparer deux types de données différents : +1 < :hello #=> true + +# L'ordre est défini de la sorte : +# number < atom < reference < functions < port < pid < tuple < list < bit string + +# Pour citer Joe Armstrong : "The actual order is not important, +# but that a total ordering is well defined is important." + +## --------------------------- +## -- Structure de contrôle +## --------------------------- + +# Condition avec `if` (si) +if false do + "Cela ne sera pas vu" +else + "Cela le sera" +end + +# Condition avec `unless` (sauf). +# Il correspond à la négation d'un `if` (si) +unless true do + "Cela ne sera pas vu" +else + "Cela le sera" +end + +# Beaucoup de structures en Elixir se basent sur le pattern matching. +# `case` permet de comparer une valeur à plusieurs modèles: +case {:one, :two} do + {:four, :five} -> + "Ne match pas" + {:one, x} -> + "Match et lie `x` à `:two` dans ce cas" + _ -> + "Match toutes les valeurs" +end + +# Il est commun de lier la valeur à `_` si on ne l'utilise pas. +# Par exemple, si seulement la tête d'une liste nous intéresse: +[head | _] = [1,2,3] +head #=> 1 + +# Pour plus de lisibilité, ce procédé est utilisé: +[head | _tail] = [:a, :b, :c] +head #=> :a + +# `cond` permet de vérifier plusieurs conditions à la fois. +# Il est conseillé d'utiliser `cond` plutôt que des `if` imbriqués. +cond do + 1 + 1 == 3 -> + "Je ne serai pas vu" + 2 * 5 == 12 -> + "Moi non plus" + 1 + 2 == 3 -> + "Mais moi oui" +end + +# Il est commun d'attribuer la dernière condition à true (vrai), qui +# matchera toujours. +cond do + 1 + 1 == 3 -> + "Je ne serai pas vu" + 2 * 5 == 12 -> + "Moi non plus" + true -> + "Mais moi oui (représente un else)" +end + +# `try/catch` est utilisé pour attraper les valeurs rejetées. +# Il supporte aussi un +# `after` qui est appelé autant si une valeur est jetée ou non. +try do + throw(:hello) +catch + message -> "Message : #{message}." +after + IO.puts("Je suis la clause after (après).") +end +#=> Je suis la clause after (après). +# "Message : :hello" + +## --------------------------- +## -- Modules et Fonctions +## --------------------------- + +# Fonctions anonymes (notez le point). +square = fn(x) -> x * x end +square.(5) #=> 25 + +# Les fonctions anonymes acceptent aussi de nombreuses clauses et guards (gardes). +# Les guards permettent d'affiner le pattern matching, +# ils sont indiqués par le mot-clef `when` : +f = fn + x, y when x > 0 -> x + y + x, y -> x * y +end + +f.(1, 3) #=> 4 +f.(-1, 3) #=> -3 + +# Elixir propose aussi de nombreuses fonctions internes. +is_number(10) #=> true +is_list("hello") #=> false +elem({1,2,3}, 0) #=> 1 + +# Il est possible de grouper plusieurs fonctions dans un module. +# Dans un module, les fonctions sont définies par `def` +defmodule Math do + def sum(a, b) do + a + b + end + + def square(x) do + x * x + end +end + +Math.sum(1, 2) #=> 3 +Math.square(3) #=> 9 + +# Pour compiler notre module `Math`, +# il faut le sauvegarder en tant que `math.ex` et utiliser `elixirc`. +# Executez ainsi `elixirc math.ex` dans le terminal. + +# Au sein d'un module, nous pouvons définir les fonctions avec `def` +# et `defp` pour les fonctions privées. +# Une fonction définie par `def` est disponible dans les autres +# modules. Une fonction privée est disponible localement seulement. +defmodule PrivateMath do + def sum(a, b) do + do_sum(a, b) + end + + defp do_sum(a, b) do + a + b + end +end + +PrivateMath.sum(1, 2) #=> 3 +# PrivateMath.do_sum(1, 2) #=> ** (UndefinedFunctionError) + +# La déclaration de fonction supporte également les guards (gardes) +# et les clauses. +# Quand une fonction avec plusieurs clauses est appelée, +# la première fonction dont la clause est satisfaite par les arguments sera appelée. +# Exemple: le code `area({:circle, 3})` appelle la deuxième fonction definie plus bas, +# et non la première car ses arguments correspondent à la signature de cette dernière: +defmodule Geometry do + def area({:rectangle, w, h}) do + w * h + end + + def area({:circle, r}) when is_number(r) do + 3.14 * r * r + end +end + +Geometry.area({:rectangle, 2, 3}) #=> 6 +Geometry.area({:circle, 3}) #=> 28.25999999999999801048 +# Geometry.area({:circle, "not_a_number"}) +#=> ** (FunctionClauseError) no function clause matching in Geometry.area/1 + +# En raison de l'immutabilité, la récursivité est une grande partie +# d'Elixir +defmodule Recursion do + def sum_list([head | tail], acc) do + sum_list(tail, acc + head) + end + + def sum_list([], acc) do + acc + end +end + +Recursion.sum_list([1,2,3], 0) #=> 6 + +# Les modules Elixir supportent des attributs internes, +# ceux-ci peuvent aussi être personnalisés. +defmodule MyMod do + @moduledoc """ + This is a built-in attribute on a example module. + """ + + @my_data 100 # Attribut personnel. + IO.inspect(@my_data) #=> 100 +end + +# L'opérateur pipe (|>) permet de passer la sortie d'une expression +# en premier paramètre d'une fonction. + +Range.new(1,10) +|> Enum.map(fn x -> x * x end) +|> Enum.filter(fn x -> rem(x, 2) == 0 end) +#=> [4, 16, 36, 64, 100] + +## --------------------------- +## -- Structs et Exceptions +## --------------------------- + +# Les Structs sont des extensions des Maps. +# Apportant en plus les valeurs par defaut, le polymorphisme et +# la vérification à la compilation dans Elixir. +defmodule Person do + defstruct name: nil, age: 0, height: 0 +end + +jean_info = %Person{ name: "Jean", age: 30, height: 180 } +#=> %Person{age: 30, height: 180, name: "Jean"} + +# Access the value of name +jean_info.name #=> "Jean" + +# Update the value of age +older_jean_info = %{ jean_info | age: 31 } +#=> %Person{age: 31, height: 180, name: "Jean"} + +# Le bloc `try` avec le mot-clef `rescue` est utilisé pour gérer les exceptions +try do + raise "some error" +rescue + RuntimeError -> "rescued a runtime error" + _error -> "this will rescue any error" +end +#=> "rescued a runtime error" + +# Chaque exception possède un message +try do + raise "some error" +rescue + x in [RuntimeError] -> + x.message +end +#=> "some error" + +## --------------------------- +## -- Concurrence +## --------------------------- + +# Elixir se repose sur le modèle d'acteur pour gérer la concurrence. +# Pour écrire un programme concurrent en Elixir il faut trois +# primitives: spawning processes (création), sending messages (envoi) +# et receiving messages (réception). + +# Pour débuter un nouveau processus, il faut utiliser +# la fonction `spawn` qui prend en argument une fonction. +f = fn -> 2 * 2 end #=> #Function<erl_eval.20.80484245> +spawn(f) #=> #PID<0.40.0> + +# `spawn` retourn un pid (identifiant de processus), il est possible +# d'utiliser ce pid pour envoyer un message au processus. +# Pour faire parvenir le message il faut utiliser l'opérateur `send`. +# Pour que cela soit utile il faut être capable de recevoir les +# messages. +# Cela est possible grâce au mechanisme de `receive`: + +# Le bloc `receive do` est utilisé pour écouter les messages et les traiter +# au moment de la réception. Un bloc `receive do` pourra traiter un seul +# message reçu. +# Pour traiter plusieurs messages, une fonction avec un bloc `receive do` +# doit s'appeler elle-même récursivement. + +defmodule Geometry do + def area_loop do + receive do + {:rectangle, w, h} -> + IO.puts("Area = #{w * h}") + area_loop() + {:circle, r} -> + IO.puts("Area = #{3.14 * r * r}") + area_loop() + end + end +end + +# Ceci compile le module et créer un processus qui évalue dans le terminal `area_loop` +pid = spawn(fn -> Geometry.area_loop() end) #=> #PID<0.40.0> +# Alternativement +pid = spawn(Geometry, :area_loop, []) + +# On envoi un message au `pid` qui correspond à la régle de réception. +send pid, {:rectangle, 2, 3} +#=> Area = 6 +# {:rectangle,2,3} + +send pid, {:circle, 2} +#=> Area = 12.56000000000000049738 +# {:circle,2} + +# Le shell est aussi un processus, il est possible d'utiliser `self` +# pour obtenir le pid du processus courant. +self() #=> #PID<0.27.0> + +## --------------------------- +## -- Agents +## --------------------------- + +# Un agent est un processus qui garde les traces des valeurs modifiées. + +# Pour créer un agent on utilise `Agent.start_link` avec une fonction. +# L'état initial de l'agent sera ce que la fonction retourne +{ok, my_agent} = Agent.start_link(fn -> ["red", "green"] end) + +# `Agent.get` prend un nom d'agent et une fonction (`fn`). +# Qu'importe ce que cette `fn` retourne, l'état sera ce qui est retourné. +Agent.get(my_agent, fn colors -> colors end) #=> ["red", "green"] + +# Modification de l'état de l'agent +Agent.update(my_agent, fn colors -> ["blue" | colors] end) +``` + +## Références + +* [Guide de debut](http://elixir-lang.org/getting-started/introduction.html) depuis le site [Elixir](http://elixir-lang.org) +* [Documentation Elixir ](https://elixir-lang.org/docs.html) +* ["Programming Elixir"](https://pragprog.com/book/elixir/programming-elixir) de Dave Thomas +* [Elixir Cheat Sheet](http://media.pragprog.com/titles/elixir/ElixirCheat.pdf) +* ["Learn You Some Erlang for Great Good!"](http://learnyousomeerlang.com/) de Fred Hebert +* ["Programming Erlang: Software for a Concurrent World"](https://pragprog.com/book/jaerlang2/programming-erlang) de Joe Armstrong diff --git a/haxe.html.markdown b/haxe.html.markdown index a31728e1..e086dd7a 100644 --- a/haxe.html.markdown +++ b/haxe.html.markdown @@ -6,8 +6,8 @@ contributors: - ["Dan Korostelev", "https://github.com/nadako/"] --- -Haxe is a web-oriented language that provides platform support for C++, C#, -Swf/ActionScript, Javascript, Java, PHP, Python, Lua, HashLink, and Neko byte code +[Haxe](https://haxe.org/) is a general-purpose language that provides platform support for C++, C#, +Swf/ActionScript, JavaScript, Java, PHP, Python, Lua, HashLink, and Neko bytecode (the latter two being also written by the Haxe author). Note that this guide is for Haxe version 3. Some of the guide may be applicable to older versions, but it is recommended to use other references. @@ -189,7 +189,7 @@ class LearnHaxe3 { trace(m.get('bar') + " is the value for m.get('bar')"); trace(m['bar'] + " is the value for m['bar']"); - var m2 = ['foo' => 4, 'baz' => 6]; // Alternative map syntax + var m2 = ['foo' => 4, 'baz' => 6]; // Alternative map syntax trace(m2 + " is the value for m2"); // Remember, you can use type inference. The Haxe compiler will @@ -234,10 +234,9 @@ class LearnHaxe3 { ^ Bitwise exclusive OR | Bitwise inclusive OR */ - - // increments + var i = 0; - trace("Increments and decrements"); + trace("Pre-/Post- Increments and Decrements"); trace(i++); // i = 1. Post-Increment trace(++i); // i = 2. Pre-Increment trace(i--); // i = 1. Post-Decrement @@ -287,7 +286,7 @@ class LearnHaxe3 { } // do-while loop - var l = 0; + var l = 0; do { trace("do statement always runs at least once"); } while (l > 0); @@ -338,7 +337,7 @@ class LearnHaxe3 { */ var my_dog_name = "fido"; var favorite_thing = ""; - switch(my_dog_name) { + switch (my_dog_name) { case "fido" : favorite_thing = "bone"; case "rex" : favorite_thing = "shoe"; case "spot" : favorite_thing = "tennis ball"; @@ -366,7 +365,7 @@ class LearnHaxe3 { trace("k equals ", k); // outputs 10 - var other_favorite_thing = switch(my_dog_name) { + var other_favorite_thing = switch (my_dog_name) { case "fido" : "teddy"; case "rex" : "stick"; case "spot" : "football"; @@ -559,7 +558,7 @@ class SimpleEnumTest { // You can specify the "full" name, var e_explicit:SimpleEnum = SimpleEnum.Foo; var e = Foo; // but inference will work as well. - switch(e) { + switch (e) { case Foo: trace("e was Foo"); case Bar: trace("e was Bar"); case Baz: trace("e was Baz"); // comment this line to throw an error. @@ -572,7 +571,7 @@ class SimpleEnumTest { You can also specify a default for enum switches as well: */ - switch(e) { + switch (e) { case Foo: trace("e was Foo again"); default : trace("default works here too"); } @@ -595,21 +594,21 @@ class ComplexEnumTest { var e1:ComplexEnum = IntEnum(4); // specifying the enum parameter // Now we can switch on the enum, as well as extract any parameters // it might have had. - switch(e1) { + switch (e1) { case IntEnum(x) : trace('$x was the parameter passed to e1'); default: trace("Shouldn't be printed"); } // another parameter here that is itself an enum... an enum enum? var e2 = SimpleEnumEnum(Foo); - switch(e2){ + switch (e2){ case SimpleEnumEnum(s): trace('$s was the parameter passed to e2'); default: trace("Shouldn't be printed"); } // enums all the way down var e3 = ComplexEnumEnum(ComplexEnumEnum(MultiEnum(4, 'hi', 4.3))); - switch(e3) { + switch (e3) { // You can look for certain nested enums by specifying them // explicitly: case ComplexEnumEnum(ComplexEnumEnum(MultiEnum(i,j,k))) : { @@ -668,7 +667,7 @@ class TypedefsAndStructuralTypes { That would give us a single "Surface" type to work with across all of those platforms. - */ + */ } } @@ -700,8 +699,7 @@ class UsingExample { instance, and the compiler still generates code equivalent to a static method. */ - } - + } } ``` diff --git a/javascript.html.markdown b/javascript.html.markdown index c466c09b..ce9772ca 100644 --- a/javascript.html.markdown +++ b/javascript.html.markdown @@ -586,6 +586,48 @@ if (Object.create === undefined){ // don't overwrite it if it exists return new Constructor(); }; } + +// ES6 Additions + +// The "let" keyword allows you to define variables in a lexical scope, +// as opposed to a block scope like the var keyword does. +let name = "Billy"; + +// Variables defined with let can be reassigned new values. +name = "William"; + +// The "const" keyword allows you to define a variable in a lexical scope +// like with let, but you cannot reassign the value once one has been assigned. + +const pi = 3.14; + +pi = 4.13; // You cannot do this. + +// There is a new syntax for functions in ES6 known as "lambda syntax". +// This allows functions to be defined in a lexical scope like with variables +// defined by const and let. + +const isEven = (number) => { + return number % 2 === 0; +}; + +isEven(7); // false + +// The "equivalent" of this function in the traditional syntax would look like this: + +function isEven(number) { + return number % 2 === 0; +}; + +// I put the word "equivalent" in double quotes because a function defined +// using the lambda syntax cannnot be called before the definition. +// The following is an example of invalid usage: + +add(1, 8); + +const add = (firstNumber, secondNumber) => { + return firstNumber + secondNumber; +}; ``` ## Further Reading diff --git a/lsf/lambda-calculus-lsf.html.markdown b/lsf/lambda-calculus-lsf.html.markdown new file mode 100644 index 00000000..88bb638f --- /dev/null +++ b/lsf/lambda-calculus-lsf.html.markdown @@ -0,0 +1,91 @@ +--- +category: Algorithms & Data Structures +name: Lambda Calculus +contributors: + - ["Max Sun", "http://github.com/maxsun"] +translators: + - ["Victore Leve", "https://github.com/AcProIL"] +lang: lsf +--- + +# Calculo λ + +Calculo lambda, creato principto per Alonzo Church, es lingua de programmatura +computatro maximo parvo. Quamquam non habe numero, serie de charactere vel ullo +typo de data non functionale, id pote repraesenta omne machina de Turing. + +Tres elemento compone calculo lambda: **quantitate variabile** (q.v.), +**functione** et **applicatione**. + +| Elemento | Syntaxe | Exemplo | +|----------------------|-----------------------------------|-----------| +| Quantitate variabile | `<nomine>` | `x` | +| Functione | `λ<parametro>.<corpore>` | `λx.x` | +| Applicatione | `<functione><q.v. aut functione>` | `(λx.x)a` | + +Functione fundamentale es identitate: `λx.x` cum argumento primo `x` et cum +corpore secundo `x`. In mathematica, nos scribe `id: x↦x`. + +## Quantitate variabile libero et ligato + +* In functione praecedente, `x` es q.v. ligato nam id es et in copore et + argumento. +* In `λx.y`, `y` es q.v. libero nam non es declarato ante. + +## Valutatione + +Valutatione es facto per reductione beta (reductione β) que es essentialiter +substitutione lexicale. + +Dum valutatione de formula `(λx.x)a`, nos substitue omne evento de `x` in +corpore de functione pro `a`. + +* `(λx.x)a` vale `a` +* `(λx.y)a` vale `y` + +Pote etiam crea functione de ordine supero: `(λx.(λy.x))a` vale `λy.a`. + +Etsi calculo lambda solo tracta functione de uno parametro, nos pote crea +functione cum plure argumento utente methodo de Curry: `λx.(λy.(λz.xyz))` +es scriptura informatica de formula mathematico `f: x, y, z ↦ x(y(z)))`. + +Ergo, interdum, nos ute `λxy.<corpore>` pro `λx.λy.<corpore>`. + +## Arithmetica + +### Logica de Boole + +Es nec numero nec booleano in calculo lambda. + +* «vero» es `v = λx.λy.x` +* «falso» es `f = λx.λy.y` + +Primo, nos pote defini functione «si t tunc a alio b» per `si = λtab.tab`. +Si `t` es vero, valutatione da `(λxy.x) a b` id es `a`. Similiter si `t` es +falso, nos obtine `b`. + +Secundo, nos pote defini operatore de logica: + +* «a et b» es `et = λa.λb.si a b f` +* «a vel b» es `vel = λa.λb.si a t b` +* «non a» es `non = λa.si a f t` + +### Numeros + +Nos pone: + +* `0 = λf.λx.x` (`0: f↦id`) +* `1 = λf.λx.f x` (`1: f↦f`) +* `2 = λf.λx.f(f x)` (`2: f↦f⚬f`) + +Cum mente generale, successore de numero `n` es `S n = λf.λx.f((n f) x)` +(`n+1: f↦f⚬fⁿ`). Id es **`n` est functione que da `fⁿ` ex functione `f`**. + +Postremo additione es `λab.(a S)b` + +## Ut progrede + +### In lingua anglo + +1. [A Tutorial Introduction to the Lambda Calculus](http://www.inf.fu-berlin.de/lehre/WS03/alpi/lambda.pdf) per Raúl Roja +2. [The Lambda Calculus](http://www.cs.cornell.edu/courses/cs3110/2008fa/recitations/rec26.html), CS 312 Recitation 26 diff --git a/lsf/latex-lsf.html.markdown b/lsf/latex-lsf.html.markdown new file mode 100644 index 00000000..18c2e62b --- /dev/null +++ b/lsf/latex-lsf.html.markdown @@ -0,0 +1,146 @@ +--- +language: latex +lang: lsf +contributors: + - ["Chaitanya Krishna Ande", "http://icymist.github.io"] + - ["Colton Kohnke", "http://github.com/voltnor"] + - ["Sricharan Chiruvolu", "http://sricharan.xyz"] +translators: + - ["Victore Leve", "https://github.com/AcProIL"] +filename: learn-latex-lsf.tex +--- + +```tex +% Solo existe commentario monolinea, illo incipe cum charactere % + +% LaTeX non es sicut MS Word aut OpenOffice: que scribe non es que obtine. +% Primo, scribe imperio (que semper incipe cum \) et secundo programma crea +% lima. + +% Nos defini typo de document (id es articulo aut libro aut libello etc.). +% Optione muta quomodo programma age, per exemplo altore de littera. +\documentclass[12pt]{article} + +% Deinde nos lista paccettos que nos vol ute. Es classe de imperio que alio +% utatore e scribe. Pote muta funda, geometria de pagina, etc. vel adde +% functionnalitate. +\usepackage{euler} +\usepackage{graphicx} + +% Ultimo statione ante scribe documento es metadata id es titulo, auctore et +% tempore. Charactere ~ es spatio que non pote es secato. +\title{Disce LaTeX in~Y Minutos!} +\author{Chaitanya Krishna Ande, Colton Kohnke \& Sricharan Chiruvolu} +\date{\today} + +% Principio de documento +\begin{document} + \maketitle % Nos vol adfige metadata. + + % Saepe nos adde breviario us describe texto. + \begin{abstract} + Hic es exmplo de documento sibre cum lingua de LaTeX. + \end{abstract} + + % \section crea sectione cum titulo dato sicut sperato + \section{Introductione} + + Traductione de hic cursu es importante. + + \subsection{Methodo} + Iste parte non es utile. + + \subsubsection{Methodo peculiare} + % \label da nomine ad parte ut post ute imperio de referentia \ref. + \label{subsec:metpec} + + % Cum asteritco nos indice que nos non vol numero ante titulo de sectione. + \section*{Me non aestima numero…} + + …sed de Peano aut de Church. + + \section{Listas} + + Que me debe scribe: + + \begin{enumerate} % `enumerate` designa lista cum numeros contra `itemize`. + \item articulo, + \item libro, + \item cursu. + \end{enumerate} + + \section{Mathematica} + + Methematicas ute multo programma LaTeX ut communica suo decooperito. + Illo necessita symbolo multo instar de logica vel sagitta vel littera cum + accento. + + % Fornula es in linea si nos scribe inter \( et \) (aut duo $) sed magno si + % nos ute \[ et \]. + \(\forall n\in N_0\) % pro omne n in classe N₀ + \[^{3}/_{4} = \frac{3}{4} < 1\] % ¾ < 1 + + Alphabeta graeco contine littera $\alpha$. + + % Ut scribe equatione cum numero et nomine, existe circumiecto `equation`. + \begin{equation} + c^2 = a^2 + b^2 + \label{eq:pythagoras} + \end{equation} + + \begin{equation} + % Summa ab 1 ad n de numeros dimidio de n(n+1) + \sum_{i=1}^n i = \frac{n(n+1)}{2} + \end{equation} + + \section{Figura} + + % Nos adde imagine `right-triangle.png` cum latitudo de quinque centimetro, + % horizontaliter in centro et cum capite «Triangulo recto». + \begin{figure} + \centering + \includegraphics[width=5cm]{right-triangle.png} + \caption{Triangulo recto} + \label{fig:right-triangle} + \end{figure} + + \subsection{Tabula} + + \begin{table} + \caption{Título para la tabla.} + % Argumento de `tabular` es lineamente de columna. + % c: centro, l: sinistra, r: destra, | linea verticale + \begin{tabular}{c|cc} + Numero & B & C \\ + \hline % linea horizontale + 1 & et & aut \\ + 2 & atque & vel + \end{tabular} + \end{table} + + \section{Stylo} + + Texto pote es \textbf{crasso} et \textit{italico}! + + \section{Texto puro} + + % Circumiecto `verbatim` ignora imperio, nos saepe ute id pro monstra + % programma. + \begin{verbatim} +from math import tau, e +print(e ** tau) + \end{verbatim} + + \section{Et plus!} + LaTeX habe facultate crea bibliographia, paritura, scaccarip… cum paccetto + dedicato. +\end{document} +``` + +Imperio ut conge documento es `pdflatex documento` in terminale. + +## Ut progrede + +### In lingua anglo + +* [LaTeX tutorial](http://www.latex-tutorial.com/) per Claudio Vellage diff --git a/perl6.html.markdown b/perl6.html.markdown deleted file mode 100644 index c7fde218..00000000 --- a/perl6.html.markdown +++ /dev/null @@ -1,1976 +0,0 @@ ---- -category: language -language: perl6 -filename: learnperl6.p6 -contributors: - - ["vendethiel", "http://github.com/vendethiel"] - - ["Samantha McVey", "https://cry.nu"] ---- - -Perl 6 is a highly capable, feature-rich programming language made for at -least the next hundred years. - -The primary Perl 6 compiler is called [Rakudo](http://rakudo.org), which runs on -the JVM and [the MoarVM](http://moarvm.com). - -Meta-note: double pound signs (`##`) are used to indicate paragraphs, -while single pound signs (`#`) indicate notes. - -`#=>` represents the output of a command. - -```perl6 -# Single line comments start with a pound sign. - -#`( Multiline comments use #` and a quoting construct. - (), [], {}, 「」, etc, will work. -) - -# Use the same syntax for multiline comments to embed comments. -for #`(each element in) @array { - put #`(or print element) $_ #`(with newline); -} -``` - -## Variables - -```perl6 -## In Perl 6, you declare a lexical variable using the `my` keyword: -my $variable; -## Perl 6 has 3 basic types of variables: scalars, arrays, and hashes. -``` - -### Scalars - -```perl6 -# Scalars represent a single value. They start with the `$` sigil: -my $str = 'String'; - -# Double quotes allow for interpolation (which we'll see later): -my $str2 = "String"; - -## Variable names can contain but not end with simple quotes and dashes, -## and can contain (and end with) underscores: -my $person's-belongings = 'towel'; # this works! - -my $bool = True; # `True` and `False` are Perl 6's boolean values. -my $inverse = !$bool; # Invert a bool with the prefix `!` operator. -my $forced-bool = so $str; # And you can use the prefix `so` operator -$forced-bool = ?$str; # to turn its operand into a Bool. Or use `?`. -``` - -### Arrays and Lists - -```perl6 -## Arrays represent multiple values. An array variable starts with the `@` -## sigil. Unlike lists, from which arrays inherit, arrays are mutable. - -my @array = 'a', 'b', 'c'; -# equivalent to: -my @letters = <a b c>; # array of words, delimited by space. - # Similar to perl5's qw, or Ruby's %w. -@array = 1, 2, 3; - -say @array[2]; # Array indices start at 0. Here the third element - # is being accessed. - -say "Interpolate an array using []: @array[]"; -#=> Interpolate an array using []: 1 2 3 - -@array[0] = -1; # Assigning a new value to an array index -@array[0, 1] = 5, 6; # Assigning multiple values - -my @keys = 0, 2; -@array[@keys] = @letters; # Assignment using an array containing index values -say @array; #=> a 6 b -``` - -### Hashes, or key-value Pairs. - -```perl6 -## Hashes are pairs of keys and values. You can construct a `Pair` object -## using the syntax `Key => Value`. Hash tables are very fast for lookup, -## and are stored unordered. Keep in mind that keys get "flattened" in hash -## context, and any duplicated keys are deduplicated. -my %hash = 'a' => 1, 'b' => 2; - -%hash = a => 1, # keys get auto-quoted when => (fat comma) is used. - b => 2, # Trailing commas are okay. -; - -## Even though hashes are internally stored differently than arrays, -## Perl 6 allows you to easily create a hash from an even numbered array: -%hash = <key1 value1 key2 value2>; # Or: -%hash = "key1", "value1", "key2", "value2"; - -%hash = key1 => 'value1', key2 => 'value2'; # same result as above - -## You can also use the "colon pair" syntax. This syntax is especially -## handy for named parameters that you'll see later. -%hash = :w(1), # equivalent to `w => 1` - :truey, # equivalent to `:truey(True)` or `truey => True` - :!falsey, # equivalent to `:falsey(False)` or `falsey => False` -; -## The :truey and :!falsey constructs are known as the -## `True` and `False` shortcuts respectively. - -say %hash{'key1'}; # You can use {} to get the value from a key. -say %hash<key2>; # If it's a string without spaces, you can actually use - # <> (quote-words operator). `{key1}` doesn't work, - # as Perl6 doesn't have barewords. -``` - -## Subs - -```perl6 -## Subroutines, or functions as most other languages call them, are -## created with the `sub` keyword. -sub say-hello { say "Hello, world" } - -## You can provide (typed) arguments. If specified, the type will be checked -## at compile-time if possible, otherwise at runtime. -sub say-hello-to( Str $name ) { - say "Hello, $name !"; -} - -## A sub returns the last value of the block. Similarly, the semicolon in -## the last can be omitted. -sub return-value { 5 } -say return-value; # prints 5 - -sub return-empty { } -say return-empty; # prints Nil - -## Some control flow structures produce a value, like `if`: -sub return-if { - if True { "Truthy" } -} -say return-if; # prints Truthy - -## Some don't, like `for`: -sub return-for { - for 1, 2, 3 { 'Hi' } -} -say return-for; # prints Nil - -## Positional arguments are required by default. To make them optional, use -## the `?` after the parameters' names. -sub with-optional( $arg? ) { - # This sub returns `(Any)` (Perl's null-like value) if - # no argument is passed. Otherwise, it returns its argument. - $arg; -} -with-optional; # returns Any -with-optional(); # returns Any -with-optional(1); # returns 1 - -## You can also give them a default value when they're not passed. -## Required parameters must come before optional ones. -sub greeting( $name, $type = "Hello" ) { - say "$type, $name!"; -} - -greeting("Althea"); #=> Hello, Althea! -greeting("Arthur", "Good morning"); #=> Good morning, Arthur! - -## You can also, by using a syntax akin to the one of hashes -## (yay unified syntax !), pass *named* arguments to a `sub`. They're -## optional, and will default to "Any". -sub with-named( $normal-arg, :$named ) { - say $normal-arg + $named; -} -with-named(1, named => 6); #=> 7 - -## There's one gotcha to be aware of, here: If you quote your key, Perl 6 -## won't be able to see it at compile time, and you'll have a single `Pair` -## object as a positional parameter, which means -## `with-named(1, 'named' => 6);` fails. - -with-named(2, :named(5)); #=> 7 - -## To make a named argument mandatory, you can append `!` to the parameter, -## which is the inverse of `?`: -sub with-mandatory-named( :$str! ) { - say "$str!"; -} -with-mandatory-named(str => "My String"); #=> My String! -with-mandatory-named; # runtime error:"Required named parameter not passed" -with-mandatory-named(3);# runtime error:"Too many positional parameters passed" - -## If a sub takes a named boolean argument... -sub takes-a-bool( $name, :$bool ) { - say "$name takes $bool"; -} -## ... you can use the same "short boolean" hash syntax: -takes-a-bool('config', :bool); #=> config takes True -takes-a-bool('config', :!bool); #=> config takes False - -## You can also provide your named arguments with default values: -sub named-def( :$def = 5 ) { - say $def; -} -named-def; #=> 5 -named-def(def => 15); #=> 15 - -## Since you can omit parenthesis to call a function with no arguments, -## you need `&` in the name to store `say-hello` in a variable. This means -## `&say-hello` is a code object and not a subroutine call. -my &s = &say-hello; -my &other-s = sub { say "Anonymous function!" } - -## A sub can have a "slurpy" parameter, or "doesn't-matter-how-many". For -## this, you must use `*@` (slurpy) which will "take everything else". You can -## have as many parameters *before* a slurpy one, but not *after*. -sub as-many($head, *@rest) { - say @rest.join(' / ') ~ " !"; -} -say as-many('Happy', 'Happy', 'Birthday');#=> Happy / Birthday ! - # Note that the splat (the *) did not - # consume the parameter before it. - -## You can call a function with an array using the "argument list flattening" -## operator `|` (it's not actually the only role of this operator, -## but it's one of them). -sub concat3($a, $b, $c) { - say "$a, $b, $c"; -} -concat3(|@array); #=> a, b, c - # `@array` got "flattened" as a part of the argument list -``` - -## Containers - -```perl6 -## In Perl 6, values are actually stored in "containers". The assignment -## operator asks the container on the left to store the value on its right. -## When passed around, containers are marked as immutable which means that, -## in a function, you'll get an error if you try to mutate one of your -## arguments. If you really need to, you can ask for a mutable container by -## using the `is rw` trait: -sub mutate( $n is rw ) { - $n++; # postfix ++ operator increments its argument but returns its old value -} - -my $m = 42; -mutate $m; # the value is incremented but the old value is returned - #=> 42 -say $m; #=> 43 - -## This works because we are passing the container $m to the `mutate` sub. -## If we try to just pass a number instead of passing a variable it won't work -## because there is no container being passed and integers are immutable by -## themselves: - -mutate 42; # Parameter '$n' expected a writable container, but got Int value - -## Similar error would be obtained, if a bound variable is passed to -## to the subroutine: - -my $v := 50; # binding 50 to the variable $v -mutate $v; # Parameter '$n' expected a writable container, but got Int value - -## If what you want is a copy instead, use the `is copy` trait which will -## cause the argument to be copied and allow you to modify the argument -## inside the routine. - -## A sub itself returns a container, which means it can be marked as rw: -my $x = 42; -sub x-store() is rw { $x } -x-store() = 52; # in this case, the parentheses are mandatory - # (else Perl 6 thinks `x-store` is an identifier) -say $x; #=> 52 -``` - -## Control Flow Structures - -### Conditionals - -```perl6 -## - `if` -## Before talking about `if`, we need to know which values are "Truthy" -## (represent True), and which are "Falsey" (represent False). Only these -## values are Falsey: 0, (), {}, "", Nil, A type (like `Str` or `Int`) and -## of course False itself. Any other value is Truthy. -if True { - say "It's true!"; -} - -unless False { - say "It's not false!"; -} - -## As you can see, you don't need parentheses around conditions. However, you -## do need the curly braces around the "body" block. For example, -## `if (true) say;` doesn't work. - -## You can also use their statement modifier (postfix) versions: -say "Quite truthy" if True; #=> Quite truthy -say "Quite falsey" unless False; #=> Quite falsey - -## - Ternary operator, "x ?? y !! z" -## This returns $value-if-true if the condition is true and $value-if-false -## if it is false. -## my $result = condition ?? $value-if-true !! $value-if-false; - -my $age = 30; -say $age > 18 ?? "You are an adult" !! "You are under 18"; -#=> You are an adult -``` - -### given/when, or Perl 6's switch construct - -```perl6 -## `given...when` looks like other languages' `switch`, but is much more -## powerful thanks to smart matching and Perl 6's "topic variable", $_. -## -## The topic variable $_ contains the default argument of a block, a loop's -## current iteration (unless explicitly named), etc. -## -## `given` simply puts its argument into `$_` (like a block would do), -## and `when` compares it using the "smart matching" (`~~`) operator. -## -## Since other Perl 6 constructs use this variable (as said before, like `for`, -## blocks, etc), this means the powerful `when` is not only applicable along -## with a `given`, but instead anywhere a `$_` exists. - -given "foo bar" { - say $_; #=> foo bar - when /foo/ { # Don't worry about smart matching yet. Just know - say "Yay !"; # `when` uses it. This is equivalent to `if $_ ~~ /foo/`. - - } - when $_.chars > 50 { # smart matching anything with True is True, - # i.e. (`$a ~~ True`) - # so you can also put "normal" conditionals. - # This `when` is equivalent to this `if`: - # `if $_ ~~ ($_.chars > 50) {...}` - # which means: `if $_.chars > 50 {...}` - say "Quite a long string !"; - } - default { # same as `when *` (using the Whatever Star) - say "Something else" - } -} -``` - -### Looping constructs - -```perl6 -## - `loop` is an infinite loop if you don't pass it arguments, but can also -## be a C-style `for` loop: -loop { - say "This is an infinite loop !"; - last; # last breaks out of the loop, like - # the `break` keyword in other languages -} - -loop (my $i = 0; $i < 5; $i++) { - next if $i == 3; # `next` skips to the next iteration, like `continue` - # in other languages. Note that you can also use postfix - # conditionals, loops, etc. - say "This is a C-style for loop!"; -} - -## - `for` - Iterating through an array - -my @array = 1, 2, 6, 7, 3; - -## Accessing the array's elements with the topic variable $_. -for @array { - say "I've got $_ !"; -} - -## Accessing the array's elements with a "pointy block", `->`. -## Here each element is read-only. -for @array -> $variable { - say "I've got $variable !"; -} - -## Accessing the array's elements with a "doubly pointy block", `<->`. -## Here each element is read-write so mutating `$variable` mutates -## that element in the array. -for @array <-> $variable { - say "I've got $variable !"; -} - -## As we saw with given, a for loop's default "current iteration" variable -## is `$_`. That means you can use `when` in a `for`loop just like you were -## able to in a `given`. -for @array { - say "I've got $_"; - - .say; # This is also allowed. A dot call with no "topic" (receiver) - # is sent to `$_` by default - $_.say; # This is equivalent to the above statement. -} - -for @array { - # You can... - next if $_ == 3; # Skip to the next iteration (`continue` in C-like lang.) - redo if $_ == 4; # Re-do iteration, keeping the same topic variable (`$_`) - last if $_ == 5; # Or break out of loop (like `break` in C-like lang.) -} - -## The "pointy block" syntax isn't specific to the `for` loop. It's just a way -## to express a block in Perl 6. -sub long-computation { "Finding factors of large primes" } -if long-computation() -> $result { - say "The result is $result."; -} -``` - -## Operators - -```perl6 -## Since Perl languages are very much operator-based languages, Perl 6 -## operators are actually just funny-looking subroutines, in syntactic -## categories, like infix:<+> (addition) or prefix:<!> (bool not). - -## The categories are: -## - "prefix": before (like `!` in `!True`). -## - "postfix": after (like `++` in `$a++`). -## - "infix": in between (like `*` in `4 * 3`). -## - "circumfix": around (like `[`-`]` in `[1, 2]`). -## - "post-circumfix": around, after another term (like `{`-`}` in -## `%hash{'key'}`) - -## The associativity and precedence list are explained below. - -## Alright, you're set to go! - -## Equality Checking -##------------------ - -## - `==` is numeric comparison -3 == 4; #=> False -3 != 4; #=> True - -## - `eq` is string comparison -'a' eq 'b'; #=> False -'a' ne 'b'; #=> True, not equal -'a' !eq 'b'; #=> True, same as above - -## - `eqv` is canonical equivalence (or "deep equality") -(1, 2) eqv (1, 3); #=> False -(1, 2) eqv (1, 2); #=> True -Int === Int #=> True - -## - `~~` is the smart match operator -## Aliases the left hand side to $_ and then evaluates the right hand side. -## Here are some common comparison semantics: - -## String or numeric equality -'Foo' ~~ 'Foo'; # True if strings are equal. -12.5 ~~ 12.50; # True if numbers are equal. - -## Regex - For matching a regular expression against the left side. -## Returns a `Match` object, which evaluates as True if regexp matches. - -my $obj = 'abc' ~~ /a/; -say $obj; #=> ｢a｣ -say $obj.WHAT; #=> (Match) - -## Hashes -'key' ~~ %hash; # True if key exists in hash. - -## Type - Checks if left side "is of type" (can check superclasses and -## roles). -say 1 ~~ Int; #=> True - -## Smart-matching against a boolean always returns that boolean -## (and will warn). -say 1 ~~ True; #=> True -say False ~~ True; #=> True - -## General syntax is `$arg ~~ &bool-returning-function;`. For a complete list -## of combinations, use this table: -## http://perlcabal.org/syn/S03.html#Smart_matching - -## Of course, you also use `<`, `<=`, `>`, `>=` for numeric comparison. -## Their string equivalent are also available: `lt`, `le`, `gt`, `ge`. -3 > 4; # False -3 >= 4; # False -3 < 4; # True -3 <= 4; # True -'a' gt 'b'; # False -'a' ge 'b'; # False -'a' lt 'b'; # True -'a' le 'b'; # True - - -## Range constructor -##------------------ -3 .. 7; # 3 to 7, both included. -3 ..^ 7; # 3 to 7, exclude right endpoint. -3 ^.. 7; # 3 to 7, exclude left endpoint. -3 ^..^ 7; # 3 to 7, exclude both endpoints. - # 3 ^.. 7 almost like 4 .. 7 when we only consider integers. - # But when we consider decimals : -3.5 ~~ 4 .. 7; # False -3.5 ~~ 3 ^.. 7; # True, This Range also contains decimals greater than 3. - # We describe it like this in some math books: 3.5 ∈ (3,7] - # If you don’t want to understand the concept of interval - # for the time being. At least we should know： -3 ^.. 7 ~~ 4 .. 7; # False - - -## This also works as a shortcut for `0..^N`: -^10; # means 0..^10 - -## This also allows us to demonstrate that Perl 6 has lazy/infinite arrays, -## using the Whatever Star: -my @array = 1..*; # 1 to Infinite! Equivalent to `1..Inf`. -say @array[^10]; # You can pass ranges as subscripts and it'll return - # an array of results. This will print - # "1 2 3 4 5 6 7 8 9 10" (and not run out of memory!) - -## Note: when reading an infinite list, Perl 6 will "reify" the elements -## it needs, then keep them in memory. They won't be calculated more than once. -## It also will never calculate more elements that are needed. - -## An array subscript can also be a closure. It'll be called with the length -## as the argument: -say join(' ', @array[15..*]); #=> 15 16 17 18 19 -## which is equivalent to: -say join(' ', @array[-> $n { 15..$n }]); - -## Note: if you try to do either of those with an infinite array, -## you'll trigger an infinite loop (your program won't finish). - -## You can use that in most places you'd expect, even when assigning to -## an array: -my @numbers = ^20; - -## Here the numbers increase by 6, like an arithmetic sequence; more on the -## sequence (`...`) operator later. -my @seq = 3, 9 ... * > 95; # 3 9 15 21 27 [...] 81 87 93 99; -@numbers[5..*] = 3, 9 ... *; # even though the sequence is infinite, - # only the 15 needed values will be calculated. -say @numbers; #=> 0 1 2 3 4 3 9 15 21 [...] 81 87 - # (only 20 values) - -## and (&&), or (||) -##------------------ -3 && 4; # 4, which is Truthy. Calls `.Bool` on both 3 and 4 and gets `True` - # so it returns 4 since both are `True`. -3 && 0; # 0 -0 && 4; # 0 - -0 || False; # False. Calls `.Bool` on `0` and `False` which are both `False` - # so it retusns `False` since both are `False`. - -## Short-circuit (and tight) versions of the above -## Return the first argument that evaluates to False, or the last argument. - -my ( $a, $b, $c ) = 1, 0, 2; -$a && $b && $c; # Returns 0, the first False value - -## || Returns the first argument that evaluates to True -$b || $a; # 1 - -## And because you're going to want them, you also have compound assignment -## operators: -$a *= 2; # multiply and assignment. Equivalent to $a = $a * 2; -$b %%= 5; # divisible by and assignment. Equivalent to $b = $b %% 2; -$c div= 3; # return divisor and assignment. Equivalent to $c = $c div 3; -$d mod= 4; # return remainder and assignment. Equivalent to $d = $d mod 4; -@array .= sort; # calls the `sort` method and assigns the result back -``` - -## More on subs! - -```perl6 -## As we said before, Perl 6 has *really* powerful subs. We're going -## to see a few more key concepts that make them better than in any -## other language :-). -``` - -### Unpacking! - -```perl6 -## Unpacking is the ability to "extract" arrays and keys -## (AKA "destructuring"). It'll work in `my`s and in parameter lists. -my ($f, $g) = 1, 2; -say $f; #=> 1 -my ($, $, $h) = 1, 2, 3; # keep the non-interesting values anonymous (`$`) -say $h; #=> 3 - -my ($head, *@tail) = 1, 2, 3; # Yes, it's the same as with "slurpy subs" -my (*@small) = 1; - -sub unpack_array( @array [$fst, $snd] ) { - say "My first is $fst, my second is $snd! All in all, I'm @array[]."; - # (^ remember the `[]` to interpolate the array) -} -unpack_array(@tail); #=> My first is 2, my second is 3! All in all, I'm 2 3. - - -## If you're not using the array itself, you can also keep it anonymous, -## much like a scalar: -sub first-of-array( @ [$fst] ) { $fst } -first-of-array(@small); #=> 1 -first-of-array(@tail); # Error: "Too many positional parameters passed" - # (which means the array is too big). - -## You can also use a slurp... -sub slurp-in-array(@ [$fst, *@rest]) { # You could keep `*@rest` anonymous - say $fst + @rest.elems; # `.elems` returns a list's length. - # Here, `@rest` is `(3,)`, since `$fst` - # holds the `2`. -} -slurp-in-array(@tail); #=> 3 - -## You could even extract on a slurpy (but it's pretty useless ;-).) -sub fst(*@ [$fst]) { # or simply: `sub fst($fst) { ... }` - say $fst; -} -fst(1); #=> 1 -fst(1, 2); # errors with "Too many positional parameters passed" - -## You can also destructure hashes (and classes, which you'll learn about -## later). The syntax is basically the same as -## `%hash-name (:key($variable-to-store-value-in))`. -## The hash can stay anonymous if you only need the values you extracted. -sub key-of( % (:value($val), :qua($qua)) ) { - say "Got val $val, $qua times."; -} - -## Then call it with a hash. You need to keep the curly braces for it to be a -## hash or use `%()` instead to indicate a hash is being passed. -key-of({value => 'foo', qua => 1}); #=> Got val foo, 1 times. -key-of(%(value => 'foo', qua => 1)); #=> Got val foo, 1 times. -#key-of(%hash); # the same (for an equivalent `%hash`) - -## The last expression of a sub is returned automatically (though you may -## indicate explicitly by using the `return` keyword, of course): -sub next-index( $n ) { - $n + 1; -} -my $new-n = next-index(3); # $new-n is now 4 - -## This is true for everything, except for the looping constructs (due to -## performance reasons): there's no reason to build a list if we're just going to -## discard all the results. If you still want to build one, you can use the -## `do` statement prefix or the `gather` prefix, which we'll see later: - -sub list-of( $n ) { - do for ^$n { # note the range-to prefix operator `^` (`0..^N`) - $_ # current loop iteration known as the "topic" variable - } -} -my @list3 = list-of(3); #=> (0, 1, 2) -``` - -### lambdas (or anonymous subroutines) - -```perl6 -## You can create a lambda with `-> {}` ("pointy block") , -## `{}` ("block") or `sub {}`. - -my &lambda1 = -> $argument { - "The argument passed to this lambda is $argument" -} - -my &lambda2 = { - "The argument passed to this lambda is $_" -} - -my &lambda3 = sub ($argument) { - "The argument passed to this lambda is $argument" -} - -## `-> {}` and `{}` are pretty much the same thing, except that the former can -## take arguments, and that the latter can be mistaken as a hash by the parser. - -## We can, for example, add 3 to each value of an array using the -## `map` function with a lambda: -my @arrayplus3 = map({ $_ + 3 }, @array); # $_ is the implicit argument - -## A sub (`sub {}`) has different semantics than a block (`{}` or `-> {}`): -## A block doesn't have a "function context" (though it can have arguments), -## which means that if you return from it, you're going to return from the -## parent function. Compare: -sub is-in( @array, $elem ) { - # this will `return` out of the `is-in` sub once the condition evaluated - ## to True, the loop won't be run anymore. - map({ return True if $_ == $elem }, @array); -} -## with: -sub truthy-array( @array ) { - # this will produce an array of `True` and `False`: - # (you can also say `anon sub` for "anonymous subroutine") - map(sub ($i) { if $i { return True } else { return False } }, @array); - # ^ the `return` only returns from the anonymous `sub` -} - -## The `anon` declarator can be used to create an anonymous sub from a -## regular subroutine. The regular sub knows its name but its symbol is -## prevented from getting installed in the lexical scope, the method table -## and everywhere else. - -my $anon-sum = anon sub summation(*@a) { [+] *@a } -say $anon-sum.name; #=> summation -say $anon-sum(2, 3, 5); #=> 10 -#say summation; #=> Error: Undeclared routine: ... - -## You can also use the "whatever star" to create an anonymous subroutine. -## (it'll stop at the furthest operator in the current expression) -my @arrayplus3 = map(*+3, @array); # `*+3` is the same as `{ $_ + 3 }` -my @arrayplus3 = map(*+*+3, @array); # Same as `-> $a, $b { $a + $b + 3 }` - # also `sub ($a, $b) { $a + $b + 3 }` -say (*/2)(4); #=> 2 - # Immediately execute the function Whatever created. -say ((*+3)/5)(5); #=> 1.6 - # It works even in parens! - -## But if you need to have more than one argument (`$_`) in a block (without -## wanting to resort to `-> {}`), you can also use the implicit argument -## syntax, `$^`: -map({ $^a + $^b + 3 }, @array); -# which is equivalent to the following which uses a `sub`: -map(sub ($a, $b) { $a + $b + 3 }, @array); - -## The parameters `$^a`, `$^b`, etc. are known as placeholder parameters or -## self-declared positional parameters. They're sorted lexicographically so -## `{ $^b / $^a }` is equivalent `-> $a, $b { $b / $a }`. -``` - -### About types... - -```perl6 -## Perl 6 is gradually typed. This means you can specify the type of your -## variables/arguments/return types, or you can omit the type annotations in -## in which case they'll default to `Any`. Obviously you get access to a few -## base types, like `Int` and `Str`. The constructs for declaring types are -## "subset", "class", "role", etc. which you'll see later. - -## For now, let us examine "subset" which is a "sub-type" with additional -## checks. For example, "a very big integer is an Int that's greater than 500". -## You can specify the type you're subtyping (by default, `Any`), and add -## additional checks with the `where` clause: -subset VeryBigInteger of Int where * > 500; -## Or the set of the whole numbers: -subset WholeNumber of Int where * >= 0; -``` - -### Multiple Dispatch - -```perl6 -## Perl 6 can decide which variant of a `sub` to call based on the type of the -## arguments, or on arbitrary preconditions, like with a type or `where`: - -## with types: -multi sub sayit( Int $n ) { # note the `multi` keyword here - say "Number: $n"; -} -multi sayit( Str $s ) { # a multi is a `sub` by default - say "String: $s"; -} -sayit("foo"); #=> "String: foo" -sayit(25); #=> "Number: 25" -sayit(True); # fails at *compile time* with "calling 'sayit' will never - # work with arguments of types ..." - -## with arbitrary preconditions (remember subsets?): -multi is-big(Int $n where * > 50) { "Yes!" } # using a closure -multi is-big(Int $n where {$_ > 50}) { "Yes!" } # similar to above -multi is-big(Int $ where 10..50) { "Quite." } # Using smart-matching - # (could use a regexp, etc) -multi is-big(Int $) { "No" } - -subset Even of Int where * %% 2; -multi odd-or-even(Even) { "Even" } # The main case using the type. - # We don't name the argument. -multi odd-or-even($) { "Odd" } # "everthing else" hence the $ variable - -## You can even dispatch based on the presence of positional and -## named arguments: -multi with-or-without-you($with) { - say "I wish I could but I can't"; -} -multi with-or-without-you(:$with) { - say "I can live! Actually, I can't."; -} -multi with-or-without-you { - say "Definitely can't live."; -} - -## This is very, very useful for many purposes, like `MAIN` subs (covered -## later), and even the language itself uses it in several places. -## -## - `is`, for example, is actually a `multi sub` named `trait_mod:<is>`, -## and it works off that. -## - `is rw`, is simply a dispatch to a function with this signature: -## sub trait_mod:<is>(Routine $r, :$rw!) {} -## -## (commented out because running this would be a terrible idea!) -``` - -## Scoping - -```perl6 -## In Perl 6, unlike many scripting languages, (such as Python, Ruby, PHP), -## you must declare your variables before using them. The `my` declarator -## you have learned uses "lexical scoping". There are a few other declarators, -## (`our`, `state`, ..., ) which we'll see later. This is called -## "lexical scoping", where in inner blocks, you can access variables from -## outer blocks. -my $file_scoped = 'Foo'; -sub outer { - my $outer_scoped = 'Bar'; - sub inner { - say "$file_scoped $outer_scoped"; - } - &inner; # return the function -} -outer()(); #=> 'Foo Bar' - -## As you can see, `$file_scoped` and `$outer_scoped` were captured. -## But if we were to try and use `$outer_scoped` outside the `outer` sub, -## the variable would be undefined (and you'd get a compile time error). -``` - -## Twigils - -```perl6 -## There are many special `twigils` (composed sigils) in Perl 6. Twigils -## define the variables' scope. -## The * and ? twigils work on standard variables: -## * Dynamic variable -## ? Compile-time variable -## The ! and the . twigils are used with Perl 6's objects: -## ! Attribute (instance attribute) -## . Method (not really a variable) - -## `*` twigil: Dynamic Scope -## These variables use the `*` twigil to mark dynamically-scoped variables. -## Dynamically-scoped variables are looked up through the caller, not through -## the outer scope. - -my $*dyn_scoped_1 = 1; -my $*dyn_scoped_2 = 10; - -sub say_dyn { - say "$*dyn_scoped_1 $*dyn_scoped_2"; -} - -sub call_say_dyn { - my $*dyn_scoped_1 = 25; # Defines $*dyn_scoped_1 only for this sub. - $*dyn_scoped_2 = 100; # Will change the value of the file scoped variable. - say_dyn(); #=> 25 100, $*dyn_scoped 1 and 2 will be looked - # for in the call. - # It uses the value of $*dyn_scoped_1 from inside - # this sub's lexical scope even though the blocks - # aren't nested (they're call-nested). -} -say_dyn(); #=> 1 10 -call_say_dyn(); #=> 25 100 - # Uses $*dyn_scoped_1 as defined in call_say_dyn even though - # we are calling it from outside. -say_dyn(); #=> 1 100 We changed the value of $*dyn_scoped_2 in - # call_say_dyn so now its value has changed. -``` - -## Object Model - -```perl6 -## To call a method on an object, add a dot followed by the method name: -## `$object.method` - -## Classes are declared with the `class` keyword. Attributes are declared -## with the `has` keyword, and methods declared with the `method` keyword. - -## Every attribute that is private uses the ! twigil. For example: `$!attr`. -## Immutable public attributes use the `.` twigil which creates a read-only -## method named after the attribute. In fact, declaring an attribute with `.` -## is equivalent to declaring the same attribute with `!` and then creating -## a read-only method with the attribute's name. However, this is done for us -## by Perl 6 automatically. The easiest way to remember the `$.` twigil is -## by comparing it to how methods are called. - -## Perl 6's object model ("SixModel") is very flexible, and allows you to -## dynamically add methods, change semantics, etc... Unfortunately, these will -## not all be covered here, and you should refer to: -## https://docs.perl6.org/language/objects.html. - -class Human { - has Str $.name; # `$.name` is immutable but with an accessor method. - has Str $.bcountry; # Use `$!bcountry` to modify it inside the class. - has Str $.ccountry is rw; # This attribute can be modified from outside. - has Int $!age = 0; # A private attribute with default value. - - method birthday { - $!age += 1; # Add a year to human's age - } - - method get-age { - return $!age; - } - - # This method is private to the class. Note the `!` before the - # method's name. - method !do-decoration { - return "$!name was born in $!bcountry and now lives in $!ccountry." - } - - # This method is public, just like `birthday` and `get-age`. - method get-info { - self.do-decoration; # Invoking a method on `self` inside the class. - # Use `self!priv-method` for private method. - # Use `self.publ-method` for public method. - } -}; - -## Create a new instance of Human class. -## Note: you can't set private-attribute from here (more later on). -my $person1 = Human.new( - name => "Jord", - bcountry = "Togo", - ccountry => "Togo" -); - -say $person1.name; #=> Jord -say $person1.bcountry; #=> Togo -say $person1.ccountry; #=> Togo - - -# $person1.bcountry = "Mali"; # This fails, because the `has $.bcountry` - # is immutable. Jord can't change his birthplace. -$person1.ccountry = "France"; # This works because the `$.ccountry` is mutable - # (`is rw`). Now Jord's current country is France. - -# Calling methods on the instance objects. -$person1.birthday; #=> 1 -$person1.get-info; #=> Jord was born in Togo and now lives in France. -$person1.do-decoration; # This fails since the method `do-decoration` is - # private. -``` - -### Object Inheritance - -```perl6 -## Perl 6 also has inheritance (along with multiple inheritance). While -## methods are inherited, submethods are not. Submethods are useful for -## object construction and destruction tasks, such as BUILD, or methods that -## must be overridden by subtypes. We will learn about BUILD later on. - -class Parent { - has $.age; - has $.name; - - # This submethod won't be inherited by the Child class. - submethod favorite-color { - say "My favorite color is Blue"; - } - - # This method is inherited - method talk { say "Hi, my name is $!name" } -} - -# Inheritance uses the `is` keyword -class Child is Parent { - method talk { say "Goo goo ga ga" } - # This shadows Parent's `talk` method. - # This child hasn't learned to speak yet! -} - -my Parent $Richard .= new(age => 40, name => 'Richard'); -$Richard.favorite-color; #=> "My favorite color is Blue" -$Richard.talk; #=> "Hi, my name is Richard" -## $Richard is able to access the submethod and he knows how to say his name. - -my Child $Madison .= new(age => 1, name => 'Madison'); -$Madison.talk; #=> "Goo goo ga ga", due to the overridden method. -# $Madison.favorite-color # does not work since it is not inherited. - -## When you use `my T $var`, `$var` starts off with `T` itself in it, -## so you can call `new` on it. -## (`.=` is just the dot-call and the assignment operator: -## `$a .= b` is the same as `$a = $a.b`) -## Also note that `BUILD` (the method called inside `new`) -## will set parent's properties too, so you can pass `val => 5`. -``` - -### Roles, or Mixins - -```perl6 -## Roles are supported too (which are called Mixins in other languages) -role PrintableVal { - has $!counter = 0; - method print { - say $.val; - } -} - -## you "apply" a role (or mixin) with `does` keyword: -class Item does PrintableVal { - has $.val; - - ## When `does`-ed, a `role` literally "mixes in" the class: - ## the methods and attributes are put together, which means a class - ## can access the private attributes/methods of its roles (but - ## not the inverse!): - method access { - say $!counter++; - } - - ## However, this: - ## method print {} - ## is ONLY valid when `print` isn't a `multi` with the same dispatch. - ## (this means a parent class can shadow a child class's `multi print() {}`, - ## but it's an error if a role does) - - ## NOTE: You can use a role as a class (with `is ROLE`). In this case, - ## methods will be shadowed, since the compiler will consider `ROLE` - ## to be a class. -} -``` - -## Exceptions - -```perl6 -## Exceptions are built on top of classes, in the package `X` (like `X::IO`). -## In Perl6 exceptions are automatically 'thrown': -open 'foo'; #=> Failed to open file foo: no such file or directory -## It will also print out what line the error was thrown at -## and other error info. - -## You can throw an exception using `die`: -die 'Error!'; #=> Error! - -## Or more explicitly: -X::AdHoc.new(payload => 'Error!').throw; #=> Error! - -## In Perl 6, `orelse` is similar to the `or` operator, except it only matches -## undefined variables instead of anything evaluating as `False`. -## Undefined values include: `Nil`, `Mu` and `Failure` as well as `Int`, `Str` -## and other types that have not been initialized to any value yet. -## You can check if something is defined or not using the defined method: -my $uninitialized; -say $uninitiazilzed.defined; #=> False - -## When using `orelse` it will disarm the exception and alias $_ to that -## failure. This will prevent it to being automatically handled and printing -## lots of scary error messages to the screen. We can use the `exception` -## method on the `$_` variable to access the exception -open 'foo' orelse say "Something happened {.exception}"; - -## This also works: -open 'foo' orelse say "Something happened $_"; #=> Something happened - #=> Failed to open file foo: no such file or directory -## Both of those above work but in case we get an object from the left side -## that is not a failure we will probably get a warning. We see below how we -## can use try` and `CATCH` to be more specific with the exceptions we catch. -``` - -### Using `try` and `CATCH` - -```perl6 -## By using `try` and `CATCH` you can contain and handle exceptions without -## disrupting the rest of the program. The `try` block will set the last -## exception to the special variable `$!` (known as the error variable). -## Note: This has no relation to $!variables seen inside class definitions. - -try open 'foo'; -say "Well, I tried! $!" if defined $!; -#=> Well, I tried! Failed to open file foo: no such file or directory - -## Now, what if we want more control over handling the exception? -## Unlike many other languages, in Perl 6, you put the `CATCH` block *within* -## the block to `try`. Similar to how the `$_` variable was set when we -## 'disarmed' the exception with `orelse`, we also use `$_` in the CATCH block. -## Note: The `$!` variable is only set *after* the `try` block has caught an -## exception. By default, a `try` block has a `CATCH` block of its own that -## catches any exception (`CATCH { default {} }`). - -try { - my $a = (0 %% 0); - CATCH { - say "Something happened: $_" - } -} -#=> Something happened: Attempt to divide by zero using infix:<%%> - -## You can redefine it using `when`s (and `default`) to handle the exceptions -## you want to catch explicitly: - -try { - open 'foo'; - CATCH { - # In the `CATCH` block, the exception is set to the $_ variable. - when X::AdHoc { - say "Error: $_" - } - when X::Numeric::DivideByZero { - say "Error: $_"; - } - ## Any other exceptions will be re-raised, since we don't have a `default`. - ## Basically, if a `when` matches (or there's a `default`), the - ## exception is marked as "handled" so as to prevent its re-throw - ## from the `CATCH` block. You still can re-throw the exception (see below) - ## by hand. - } -} -#=>Error: Failed to open file /dir/foo: no such file or directory - -## There are also some subtleties to exceptions. Some Perl 6 subs return a -## `Failure`, which is a wrapper around an `Exception` object which is -## "unthrown". They're not thrown until you try to use the variables containing -## them unless you call `.Bool`/`.defined` on them - then they're handled. -## (the `.handled` method is `rw`, so you can mark it as `False` back yourself) -## You can throw a `Failure` using `fail`. Note that if the pragma `use fatal` -## is on, `fail` will throw an exception (like `die`). - -fail "foo"; # We're not trying to access the value, so no problem. -try { - fail "foo"; - CATCH { - default { - say "It threw because we tried to get the fail's value!" - } - } -} - -## There is also another kind of exception: Control exceptions. -## Those are "good" exceptions, which happen when you change your program's -## flow, using operators like `return`, `next` or `last`. -## You can "catch" those with `CONTROL` (not 100% working in Rakudo yet). -``` - -## Packages - -```perl6 -## Packages are a way to reuse code. Packages are like "namespaces", and any -## element of the six model (`module`, `role`, `class`, `grammar`, `subset` and -## `enum`) are actually packages. (Packages are the lowest common denominator) -## Packages are important - especially as Perl is well-known for CPAN, -## the Comprehensive Perl Archive Network. - -## You can use a module (bring its declarations into scope) with -## the `use` keyword: -use JSON::Tiny; # if you installed Rakudo* or Panda, you'll have this module -say from-json('[1]').perl; #=> [1] - -## You should not declare packages using the `package` keyword (unlike Perl 5). -## Instead, use `class Package::Name::Here;` to declare a class, or if you only -## want to export variables/subs, you can use `module` instead. - -module Hello::World { # bracketed form - # If `Hello` doesn't exist yet, it'll just be a "stub", - # that can be redeclared as something else later. - - # ... declarations here ... -} - -unit module Parse::Text; # file-scoped form which extends until - # the end of the file - -grammar Parse::Text::Grammar { - # A grammar is a package, which you could `use`. - # You will learn more about grammars in the regex section -} - -## As said before, any part of the six model is also a package. -## Since `JSON::Tiny` uses its own `JSON::Tiny::Actions` class, you can use it: -my $actions = JSON::Tiny::Actions.new; - -## We'll see how to export variables and subs in the next part. -``` - -## Declarators - -```perl6 -## In Perl 6, you get different behaviors based on how you declare a variable. -## You've already seen `my` and `has`, we'll now explore the others. - -## `our` - these declarations happen at `INIT` time -- (see "Phasers" below). -## It's like `my`, but it also creates a package variable. All packagish -## things such as `class`, `role`, etc. are `our` by default. - -module Var::Increment { - our $our-var = 1; # Note: `our`-declared variables cannot be typed. - my $my-var = 22; - - our sub Inc { - our sub available { # If you try to make inner `sub`s `our`... - # ... Better know what you're doing (Don't !). - say "Don't do that. Seriously. You'll get burned."; - } - - my sub unavailable { # `sub`s are `my`-declared by default - say "Can't access me from outside, I'm 'my'!"; - } - say ++$our-var; # Increment the package variable and output its value - } - -} - -say $Var::Increment::our-var; #=> 1, this works! -say $Var::Increment::my-var; #=> (Any), this will not work! - -Var::Increment::Inc; #=> 2 -Var::Increment::Inc; #=> 3 , notice how the value of $our-var was - # retained. -Var::Increment::unavailable; #=> Could not find symbol '&unavailable' - -## `constant` - these declarations happen at `BEGIN` time. You can use -## the `constant` keyword to declare a compile-time variable/symbol: -constant Pi = 3.14; -constant $var = 1; - -## And if you're wondering, yes, it can also contain infinite lists. -constant why-not = 5, 15 ... *; -say why-not[^5]; #=> 5 15 25 35 45 - -## `state` - these declarations happen at run time, but only once. State -## variables are only initialized one time. In other languages such as C -## they exist as `static` variables. -sub fixed-rand { - state $val = rand; - say $val; -} -fixed-rand for ^10; # will print the same number 10 times - -## Note, however, that they exist separately in different enclosing contexts. -## If you declare a function with a `state` within a loop, it'll re-create the -## variable for each iteration of the loop. See: -for ^5 -> $a { - sub foo { - state $val = rand; # This will be a different value for - # every value of `$a` - } - for ^5 -> $b { - say foo; # This will print the same value 5 times, - # but only 5. Next iteration will re-run `rand`. - } -} -``` - -## Phasers - -```perl6 -## Phasers in Perl 6 are blocks that happen at determined points of time in -## your program. They are called phasers because they mark a change in the -## phase of a program. For example, when the program is compiled, a for loop -## runs, you leave a block, or an exception gets thrown (The `CATCH` block is -## actually a phaser!). Some of them can be used for their return values, -## some of them can't (those that can have a "[*]" in the beginning of their -## explanation text). Let's have a look! - -## Compile-time phasers -BEGIN { say "[*] Runs at compile time, as soon as possible, only once" } -CHECK { say "[*] Runs at compile time, as late as possible, only once" } - -## Run-time phasers -INIT { say "[*] Runs at run time, as soon as possible, only once" } -END { say "Runs at run time, as late as possible, only once" } - -## Block phasers -ENTER { say "[*] Runs everytime you enter a block, repeats on loop blocks" } -LEAVE { - say "Runs everytime you leave a block, even when an exception - happened. Repeats on loop blocks." -} - -PRE { - say "Asserts a precondition at every block entry, - before ENTER (especially useful for loops)"; - say "If this block doesn't return a truthy value, - an exception of type X::Phaser::PrePost is thrown."; -} - -## Example: -for 0..2 { - PRE { $_ > 1 } # This is going to blow up with "Precondition failed" -} - -POST { - say "Asserts a postcondition at every block exit, - after LEAVE (especially useful for loops)"; - say "If this block doesn't return a truthy value, - an exception of type X::Phaser::PrePost is thrown, like PRE."; -} - -for 0..2 { - POST { $_ < 2 } # This is going to blow up with "Postcondition failed" -} - -## Block/exceptions phasers -sub { - KEEP { say "Runs when you exit a block successfully - (without throwing an exception)" } - UNDO { say "Runs when you exit a block unsuccessfully - (by throwing an exception)" } -} - -## Loop phasers -for ^5 { - FIRST { say "[*] The first time the loop is run, before ENTER" } - NEXT { say "At loop continuation time, before LEAVE" } - LAST { say "At loop termination time, after LEAVE" } -} - -## Role/class phasers -COMPOSE { "When a role is composed into a class. /!\ NOT YET IMPLEMENTED" } - -## They allow for cute tricks or clever code...: -say "This code took " ~ (time - CHECK time) ~ "s to compile"; - -## ... or clever organization: -sub do-db-stuff { - $db.start-transaction; # start a new transaction - KEEP $db.commit; # commit the transaction if all went well - UNDO $db.rollback; # or rollback if all hell broke loose -} -``` - -## Statement prefixes - -```perl6 -## Those act a bit like phasers: they affect the behavior of the following -## code. Though, they run in-line with the executable code, so they're in -## lowercase. (`try` and `start` are theoretically in that list, but explained -## elsewhere) Note: all of these (except start) don't need explicit curly -## braces `{` and `}`. - -## `do` - (which you already saw) runs a block or a statement as a term. -## Normally you cannot use a statement as a value (or "term"). `do` helps us -## do it. - -# my $value = if True { 1 } # this fails since `if` is a statement -my $a = do if True { 5 } # with `do`, `if` is now a term returning a value - -## `once` - makes sure a piece of code only runs once. -for ^5 { - once say 1 -}; #=> 1, only prints ... once - -## Similar to `state`, they're cloned per-scope. -for ^5 { - sub { once say 1 }() -}; #=> 1 1 1 1 1, prints once per lexical scope. - -## `gather` - co-routine thread. The `gather` constructs allows us to `take` -## several values from an array/list, much like `do`. -say gather for ^5 { - take $_ * 3 - 1; - take $_ * 3 + 1; -} -#=> -1 1 2 4 5 7 8 10 11 13 - -say join ',', gather if False { - take 1; - take 2; - take 3; -} -# Doesn't print anything. - -## `eager` - evaluates a statement eagerly (forces eager context) -## Don't try this at home: -# eager 1..*; # this will probably hang for a while (and might crash ...). -## But consider: -constant thrice = gather for ^3 { say take $_ }; # Doesn't print anything -## versus: -constant thrice = eager gather for ^3 { say take $_ }; #=> 0 1 2 -``` - -## Iterables - -```perl6 -## Iterables are objects that can be iterated over which are -## are similar to the `for` construct. - -## `flat` - flattens iterables. -say (1, 10, (20, 10) ); #=> (1 10 (20 10)), notice how neste lists are - # preserved -say (1, 10, (20, 10) ).flat; #=> (1 10 20 10), now the iterable is flat - -## - `lazy` - defers actual evaluation until value is fetched by forcing -## lazy context. -my @lazy-array = (1..100).lazy; -say @lazy-array.is-lazy; #=> True, check for laziness with the `is-lazy` method. -say @lazy-array; #=> [...] List has not been iterated on! -my @lazy-array { .print }; # This works and will only do as much work as - # is needed. - -# ( **TODO** explain that gather/take and map are all lazy) - -## `sink` - an `eager` that discards the results by forcing sink context. -constant nilthingie = sink for ^3 { .say } #=> 0 1 2 -say nilthingie.perl; #=> Nil - -## `quietly` - suppresses warnings in blocks. -quietly { warn 'This is a warning!' }; #=> No output - -## `contend` - attempts side effects under STM -## Not yet implemented! -``` - -## More operators thingies! - -```perl6 -## Everybody loves operators! Let's get more of them. - -## The precedence list can be found here: -## https://docs.perl6.org/language/operators#Operator_Precedence -## But first, we need a little explanation about associativity: - -## Binary operators: -$a ! $b ! $c; # with a left-associative `!`, this is `($a ! $b) ! $c` -$a ! $b ! $c; # with a right-associative `!`, this is `$a ! ($b ! $c)` -$a ! $b ! $c; # with a non-associative `!`, this is illegal -$a ! $b ! $c; # with a chain-associative `!`, this is `($a ! $b) and ($b ! $c)` -$a ! $b ! $c; # with a list-associative `!`, this is `infix:<>` - -## Unary operators: -!$a! # with left-associative `!`, this is `(!$a)!` -!$a! # with right-associative `!`, this is `!($a!)` -!$a! # with non-associative `!`, this is illegal -``` - -### Create your own operators! - -```perl6 -## Okay, you've been reading all of that, so you might want to try something -## more exciting?! I'll tell you a little secret (or not-so-secret): -## In Perl 6, all operators are actually just funny-looking subroutines. - -## You can declare an operator just like you declare a sub: -# prefix refers to the operator categories (prefix, infix, postfix, etc). -sub prefix:<win>( $winner ) { - say "$winner Won!"; -} -win "The King"; #=> The King Won! - # (prefix means 'before') - -## you can still call the sub with its "full name": -say prefix:<!>(True); #=> False -prefix:<win>("The Queen"); #=> The Queen Won! - -sub postfix:<!>( Int $n ) { - [*] 2..$n; # using the reduce meta-operator... See below ;-)! -} -say 5!; #=> 120 - # Postfix operators ('after') have to come *directly* after the term. - # No whitespace. You can use parentheses to disambiguate, i.e. `(5!)!` - -sub infix:<times>( Int $n, Block $r ) { # infix ('between') - for ^$n { - $r(); # You need the explicit parentheses to call the function in `$r`, - # else you'd be referring at the variable itself, like with `&r`. - } -} -3 times -> { say "hello" }; #=> hello - #=> hello - #=> hello -## It's recommended to put spaces around your -## infix operator calls. - -## For circumfix and post-circumfix ones -sub circumfix:<[ ]>( Int $n ) { - $n ** $n -} -say [5]; #=> 3125 - # circumfix means 'around'. Again, no whitespace. - -sub postcircumfix:<{ }>( Str $s, Int $idx ) { - ## post-circumfix is 'after a term, around something' - $s.substr($idx, 1); -} -say "abc"{1}; #=> b - # after the term `"abc"`, and around the index (1) - -## This really means a lot -- because everything in Perl 6 uses this. -## For example, to delete a key from a hash, you use the `:delete` adverb -## (a simple named argument underneath): -%h{$key}:delete; -## equivalent to: -postcircumfix:<{ }>( %h, $key, :delete ); # (you can call operators like this) - -## It's *all* using the same building blocks! Syntactic categories -## (prefix infix ...), named arguments (adverbs), ..., etc. used to build -## the language - are available to you. Obviously, you're advised against -## making an operator out of *everything* -- with great power comes great -## responsibility. -``` - -### Meta operators! - -```perl6 -## Oh boy, get ready!. Get ready, because we're delving deep into the rabbit's -## hole, and you probably won't want to go back to other languages after -## reading this. (I'm guessing you don't want to go back at this point but -## let's continue, for the journey is long and enjoyable!). - -## Meta-operators, as their name suggests, are *composed* operators. -## Basically, they're operators that act on another operators. - -## The reduce meta-operator is a prefix meta-operator that takes a binary -## function and one or many lists. If it doesn't get passed any argument, -## it either returns a "default value" for this operator (a meaningless value) -## or `Any` if there's none (examples below). Otherwise, it pops an element -## from the list(s) one at a time, and applies the binary function to the last -## result (or the list's first element) and the popped element. - -## To sum a list, you could use the reduce meta-operator with `+`, i.e.: -say [+] 1, 2, 3; #=> 6, equivalent to (1+2)+3. - -## To multiply a list -say [*] 1..5; #=> 120, equivalent to ((((1*2)*3)*4)*5). - -## You can reduce with any operator, not just with mathematical ones. -## For example, you could reduce with `//` to get first defined element -## of a list: -say [//] Nil, Any, False, 1, 5; #=> False - # (Falsey, but still defined) -## Or with relational operators, i.e., `>` to check elements of a list -## are ordered accordingly: -say say [>] 234, 156, 6, 3, -20; #=> True - -## Default value examples: -say [*] (); #=> 1 -say [+] (); #=> 0 - # meaningless values, since N*1=N and N+0=N. -say [//]; #=> (Any) - # There's no "default value" for `//`. - -## You can also call it with a function you made up, using double brackets: -sub add($a, $b) { $a + $b } -say [[&add]] 1, 2, 3; #=> 6 - -## The zip meta-operator is an infix meta-operator that also can be used as a -## "normal" operator. It takes an optional binary function (by default, it -## just creates a pair), and will pop one value off of each array and call -## its binary function on these until it runs out of elements. It returns an -## array with all of these new elements. -say (1, 2) Z (3, 4); #=> ((1, 3), (2, 4)), since by default the function - # makes an array. -say 1..3 Z+ 4..6; #=> (5, 7, 9), using the custom infix:<+> function - -## Since `Z` is list-associative (see the list above), -## you can use it on more than one list -(True, False) Z|| (False, False) Z|| (False, False); # (True, False) - -## And, as it turns out, you can also use the reduce meta-operator with it: -[Z||] (True, False), (False, False), (False, False); # (True, False) - - -## And to end the operator list: - -## The sequence operator is one of Perl 6's most powerful features: -## it's composed of first, on the left, the list you want Perl 6 to deduce from -## (and might include a closure), and on the right, a value or the predicate -## that says when to stop (or a Whatever Star for a lazy infinite list). - -my @list = 1, 2, 3...10; # basic arithmetic sequence -# my @list = 1, 3, 6...10; # this dies because Perl 6 can't figure out the end -my @list = 1, 2, 3...^10; # as with ranges, you can exclude the last element - # (the iteration ends when the predicate matches). -my @list = 1, 3, 9...* > 30; # you can use a predicate (with the Whatever Star). -my @list = 1, 3, 9 ... { $_ > 30 }; # (equivalent to the above - # using a block here). - -my @fib = 1, 1, *+* ... *; # lazy infinite list of fibonacci sequence, - # computed using a closure! -my @fib = 1, 1, -> $a, $b { $a + $b } ... *; # (equivalent to the above) -my @fib = 1, 1, { $^a + $^b } ... *; # (also equivalent to the above) -## $a and $b will always take the previous values, meaning here -## they'll start with $a = 1 and $b = 1 (values we set by hand), -## then $a = 1 and $b = 2 (result from previous $a+$b), and so on. - -say @fib[^10]; #=> 1 1 2 3 5 8 13 21 34 55 - # (using a range as the index) -## Note: as for ranges, once reified, elements aren't re-calculated. -## That's why `@primes[^100]` will take a long time the first time you print -## it, then will be instateneous. -``` - -## Regular Expressions - -```perl6 -## I'm sure a lot of you have been waiting for this one. Well, now that you know -## a good deal of Perl 6 already, we can get started. First off, you'll have to -## forget about "PCRE regexps" (perl-compatible regexps). -## -## IMPORTANT: Don't skip them because you know PCRE. They're different. Some -## things are the same (like `?`, `+`, and `*`), but sometimes the semantics -## change (`|`). Make sure you read carefully, because you might trip over a -## new behavior. -## -## Perl 6 has many features related to RegExps. After all, Rakudo parses itself. -## We're first going to look at the syntax itself, then talk about grammars -## (PEG-like), differences between `token`, `regex` and `rule` declarators, -## and some more. Side note: you still have access to PCRE regexps using the -## `:P5` modifier which we won't be discussing this in this tutorial, though. -## -## In essence, Perl 6 natively implements PEG ("Parsing Expression Grammars"). -## The pecking order for ambiguous parses is determined by a multi-level -## tie-breaking test: -## - Longest token matching: `foo\s+` beats `foo` (by 2 or more positions) -## - Longest literal prefix: `food\w*` beats `foo\w*` (by 1) -## - Declaration from most-derived to less derived grammars -## (grammars are actually classes) -## - Earliest declaration wins -say so 'a' ~~ /a/; #=> True -say so 'a' ~~ / a /; #=> True, more readable with some spaces! - -## In all our examples, we're going to use the smart-matching operator against -## a regexp. We're converting the result using `so` to a Boolean value because, -## in fact, it's returning a `Match` object. They know how to respond to list -## indexing, hash indexing, and return the matched string. The results of the -## match are available in the `$/` variable (implicitly lexically-scoped). You -## can also use the capture variables which start at 0: `$0`, `$1', `$2`... -## -## You can also note that `~~` does not perform start/end checking, meaning -## the regexp can be matched with just one character of the string. We'll -## explain later how you can do it. - -## In Perl 6, you can have any alphanumeric as a literal, everything else has -## to be escaped by using a backslash or quotes. -say so 'a|b' ~~ / a '|' b /; #=> `True`, it wouldn't mean the same thing if - # `|` wasn't escaped. -say so 'a|b' ~~ / a \| b /; #=> `True`, another way to escape it. - -## The whitespace in a regexp is actually not significant, unless you use the -## `:s` (`:sigspace`, significant space) adverb. -say so 'a b c' ~~ / a b c /; #=> `False`, space is not significant here! -say so 'a b c' ~~ /:s a b c /; #=> `True`, we added the modifier `:s` here. - -## If we use only one space between strings in a regex, Perl 6 will warn us: -say so 'a b c' ~~ / a b c /; #=> `False`, with warning about space -say so 'a b c' ~~ / a b c /; #=> `False` - -## Please use quotes or :s (:sigspace) modifier (or, to suppress this warning, -## omit the space, or otherwise change the spacing). To fix this and make the -## spaces less ambiguous, either use at least two spaces between strings -## or use the `:s` adverb. - -## As we saw before, we can embed the `:s` inside the slash delimiters, but we -## can also put it outside of them if we specify `m` for 'match': -say so 'a b c' ~~ m:s/a b c/; #=> `True` - -## By using `m` to specify 'match', we can also use delimiters other than -## slashes: -say so 'abc' ~~ m{a b c}; #=> `True` -say so 'abc' ~~ m[a b c]; #=> `True` -# m/.../ is equivalent to /.../ - -## Use the :i adverb to specify case insensitivity: -say so 'ABC' ~~ m:i{a b c}; #=> `True` - -## However, whitespace is important as for how modifiers are applied ( -## (which you'll see just below) ... - -## Quantifying - `?`, `+`, `*` and `**`. -## `?` - zero or one match -so 'ac' ~~ / a b c /; #=> `False` -so 'ac' ~~ / a b? c /; #=> `True`, the "b" matched 0 times. -so 'abc' ~~ / a b? c /; #=> `True`, the "b" matched 1 time. - -## ...As you read before, whitespace is important because it determines which -## part of the regexp is the target of the modifier: -so 'def' ~~ / a b c? /; #=> `False`, only the `c` is optional -so 'def' ~~ / a b? c /; #=> `False`, whitespace is not significant -so 'def' ~~ / 'abc'? /; #=> `True`, the whole "abc" group is optional - -## Here (and below) the quantifier applies only to the `b` - -## `+` - one or more matches -so 'ac' ~~ / a b+ c /; #=> `False`, `+` wants at least one matching -so 'abc' ~~ / a b+ c /; #=> `True`, one is enough -so 'abbbbc' ~~ / a b+ c /; #=> `True`, matched 4 "b"s - -## `*` - zero or more matches -so 'ac' ~~ / a b* c /; #=> `True`, they're all optional. -so 'abc' ~~ / a b* c /; #=> `True` -so 'abbbbc' ~~ / a b* c /; #=> `True` -so 'aec' ~~ / a b* c /; #=> `False`. "b"(s) are optional, not replaceable. - -## `**` - (Unbound) Quantifier -## If you squint hard enough, you might understand why exponentation is used -## for quantity. -so 'abc' ~~ / a b**1 c /; #=> `True`, (exactly one time) -so 'abc' ~~ / a b**1..3 c /; #=> `True`, (one to three times) -so 'abbbc' ~~ / a b**1..3 c /; #=> `True` -so 'abbbbbbc' ~~ / a b**1..3 c /; #=> `False, (too much) -so 'abbbbbbc' ~~ / a b**3..* c /; #=> `True`, (infinite ranges are okay) - -## `<[]>` - Character classes -## Character classes are the equivalent of PCRE's `[]` classes, but they use a -## more perl6-ish syntax: -say 'fooa' ~~ / f <[ o a ]>+ /; #=> 'fooa' - -## You can use ranges: -say 'aeiou' ~~ / a <[ e..w ]> /; #=> 'ae' - -## Just like in normal regexes, if you want to use a special character, escape -## it (the last one is escaping a space which would be equivalent to using -## ' '): -say 'he-he !' ~~ / 'he-' <[ a..z \! \ ]> + /; #=> 'he-he !' - -## You'll get a warning if you put duplicate names (which has the nice effect -## of catching the raw quoting): -'he he' ~~ / <[ h e ' ' ]> /; -# Warns "Repeated character (') unexpectedly found in character class" - -## You can also negate character classes... (`<-[]>` equivalent to `[^]` in PCRE) -so 'foo' ~~ / <-[ f o ]> + /; #=> False - -## ... and compose them: -so 'foo' ~~ / <[ a..z ] - [ f o ]> + /; #=> `False`, (any letter except f and o) -so 'foo' ~~ / <-[ a..z ] + [ f o ]> + /; #=> `True`, (no letter except f and o) -so 'foo!' ~~ / <-[ a..z ] + [ f o ]> + /; #=> `True`, (the + doesn't replace the - # left part) -``` - -### Grouping and capturing - -```perl6 -## Group: you can group parts of your regexp with `[]`. Unlike PCRE's `(?:)`, -## these groups are *not* captured. -so 'abc' ~~ / a [ b ] c /; # `True`. The grouping does pretty much nothing -so 'foo012012bar' ~~ / foo [ '01' <[0..9]> ] + bar /; - -## The previous line returns `True`. The regex matches "012" 1 or more time -## (achieved by the the `+` applied to the group). - -## But this does not go far enough, because we can't actually get back what -## we matched. - -## Capture: The results of a regexp can be *captured* by using parentheses. -so 'fooABCABCbar' ~~ / foo ( 'A' <[A..Z]> 'C' ) + bar /; # `True`. (using `so` - # here, `$/` below) - -## So, starting with the grouping explanations. -## As we said before, our `Match` object is stored inside the `$/` variable: -say $/; # Will either print some weird stuff or `Nil` if nothing matched. - -## As we also said before, it has array indexing: -say $/[0]; #=> ｢ABC｣ ｢ABC｣ - # These corner brackets are `Match` objects. - # Here, we have an array of these. -say $0; # The same as above. - -## Our capture is `$0` because it's the first and only one capture in the -## regexp. You might be wondering why it's an array, and the answer is simple: -## Some captures (indexed using `$0`, `$/[0]` or a named one) will be an array -## if and only if they can have more than one element. Thus any capture with -## `*`, `+` and `**` (whatever the operands), but not with `?`. -## Let's use examples to see that: - -## Note: We quoted A B C to demonstrate that the whitespace between them isn't -## significant. If we want the whitespace to *be* significant there, we -## can use the :sigspace modifier. -say so 'fooABCbar' ~~ / foo ( "A" "B" "C" )? bar /; #=> `True` -say $/[0]; #=> ｢ABC｣ -say $0.WHAT; #=> (Match) - # There can't be more than one, so it's only a single match object. -say so 'foobar' ~~ / foo ( "A" "B" "C" )? bar /; #=> True -say $0.WHAT; #=> (Any) - # This capture did not match, so it's empty -so 'foobar' ~~ / foo ( "A" "B" "C" ) ** 0..1 bar /; #=> `True` -say $0.WHAT; #=> (Array) - # A specific quantifier will always capture an Array, - # be a range or a specific value (even 1). - -## The captures are indexed per nesting. This means a group in a group will be -## nested under its parent group: `$/[0][0]`, for this code: -'hello-~-world' ~~ / ( 'hello' ( <[ \- \~ ]> + ) ) 'world' /; -say $/[0].Str; #=> hello~ -say $/[0][0].Str; #=> ~ - -## This stems from a very simple fact: `$/` does not contain strings, integers -## or arrays, it only contains Match objects. These contain the `.list`, `.hash` -## and `.Str` methods but you can also just use `match<key>` for hash access -## and `match[idx]` for array access. -say $/[0].list.perl; #=> (Match.new(...),).list - # We can see it's a list of Match objects. These contain - # a bunch of info: where the match started/ended, - # the "ast" (see actions later), etc. - # You'll see named capture below with grammars. - -## Alternation - the `or` of regexps -## WARNING: They are DIFFERENT from PCRE regexps. -say so 'abc' ~~ / a [ b | y ] c /; #=> `True`. Either "b" or "y". -say so 'ayc' ~~ / a [ b | y ] c /; #=> `True`. Obviously enough... - -## The difference between this `|` and the one you're used to is -## LTM ("Longest Token Matching"). This means that the engine will always -## try to match as much as possible in the string. -say 'foo' ~~ / fo | foo /; #=> `foo`, instead of `fo`, because it's longer. - -## To decide which part is the "longest", it first splits the regex in -## two parts: -## The "declarative prefix" (the part that can be statically analyzed) -## and the procedural parts: -## - The declarative prefixes include alternations (`|`), conjunctions (`&`), -## sub-rule calls (not yet introduced), literals, characters classes and -## quantifiers. -## - The procedural part include everything else: back-references, -## code assertions, and other things that can't traditionnaly be represented -## by normal regexps. -## -## Then, all the alternatives are tried at once, and the longest wins. -## Examples: -## DECLARATIVE | PROCEDURAL -/ 'foo' \d+ [ <subrule1> || <subrule2> ] /; -## DECLARATIVE (nested groups are not a problem) -/ \s* [ \w & b ] [ c | d ] /; -## However, closures and recursion (of named regexps) are procedural. -## There are also more complicated rules, like specificity (literals win over -## character classes). - -## Note: the first-matching `or` still exists, but is now spelled `||` -say 'foo' ~~ / fo || foo /; #=> `fo` now. -``` - -## Extra: the MAIN subroutine - -```perl6 -## The `MAIN` subroutine is called when you run a Perl 6 file directly. It's -## very powerful, because Perl 6 actually parses the arguments and pass them -## as such to the sub. It also handles named argument (`--foo`) and will even -## go as far as to autogenerate a `--help` flag. -sub MAIN($name) { - say "Hello, $name!"; -} -## This produces: -## $ perl6 cli.pl -## Usage: -## t.pl <name> - -## And since it's a regular Perl 6 sub, you can have multi-dispatch: -## (using a "Bool" for the named argument so that we can do `--replace` -## instead of `--replace=1`. The presence of `--replace` indicates truthness -## while its absence falseness). - -subset File of Str where *.IO.d; # convert to IO object to check the file exists - -multi MAIN('add', $key, $value, Bool :$replace) { ... } -multi MAIN('remove', $key) { ... } -multi MAIN('import', File, Str :$as) { ... } # omitting parameter name - -## This produces: -## $ perl6 cli.pl -## Usage: -## cli.p6 [--replace] add <key> <value> -## cli.p6 remove <key> -## cli.p6 [--as=<Str>] import <File> - -## As you can see, this is *very* powerful. It even went as far as to show inline -## the constants (the type is only displayed if the argument is `$`/is named). -``` - -## APPENDIX A: -### List of things - -```perl6 -## It's assumed by now you know the Perl6 basics. This section is just here to -## list some common operations, but which are not in the "main part" of the -## tutorial to avoid bloating it up. - -## Operators - -## Sort comparison - they return one value of the `Order` enum: `Less`, `Same` -## and `More` (which numerify to -1, 0 or +1 respectively). -1 <=> 4; # sort comparison for numerics -'a' leg 'b'; # sort comparison for string -$obj eqv $obj2; # sort comparison using eqv semantics - -## Generic ordering -3 before 4; # True -'b' after 'a'; # True - -## Short-circuit default operator - similar to `or` and `||`, but instead -## returns the first *defined* value: -say Any // Nil // 0 // 5; #=> 0 - -## Short-circuit exclusive or (XOR) - returns `True` if one (and only one) of -## its arguments is true -say True ^^ False; #=> True - -## Flip flops - these operators (`ff` and `fff`, equivalent to P5's `..` -## and `...`) are operators that take two predicates to test: They are `False` -## until their left side returns `True`, then are `True` until their right -## side returns `True`. Similar to ranges, you can exclude the iteration when -## it become `True`/`False` by using `^` on either side. Let's start with an -## example : -for <well met young hero we shall meet later> { - # by default, `ff`/`fff` smart-match (`~~`) against `$_`: - if 'met' ^ff 'meet' { # Won't enter the if for "met" - .say # (explained in details below). - } - - if rand == 0 ff rand == 1 { # compare variables other than `$_` - say "This ... probably will never run ..."; - } -} - -## This will print "young hero we shall meet" (excluding "met"): the flip-flop -## will start returning `True` when it first encounters "met" (but will still -## return `False` for "met" itself, due to the leading `^` on `ff`), until it -## sees "meet", which is when it'll start returning `False`. - -## The difference between `ff` (awk-style) and `fff` (sed-style) is that `ff` -## will test its right side right when its left side changes to `True`, and can -## get back to `False` right away (*except* it'll be `True` for the iteration -## that matched) while `fff` will wait for the next iteration to try its right -## side, once its left side changed: -.say if 'B' ff 'B' for <A B C B A>; #=> B B - # because the right-hand-side was tested - # directly (and returned `True`). - # "B"s are printed since it matched that - # time (it just went back to `False` - # right away). -.say if 'B' fff 'B' for <A B C B A>; #=> B C B - # The right-hand-side wasn't tested until - # `$_` became "C" - # (and thus did not match instantly). - -## A flip-flop can change state as many times as needed: -for <test start print it stop not printing start print again stop not anymore> { - .say if $_ eq 'start' ^ff^ $_ eq 'stop'; # exclude both "start" and "stop", - #=> "print it print again" -} - -## You might also use a Whatever Star, which is equivalent to `True` for the -## left side or `False` for the right: -for (1, 3, 60, 3, 40, 60) { # Note: the parenthesis are superfluous here - # (sometimes called "superstitious parentheses") - .say if $_ > 50 ff *; # Once the flip-flop reaches a number greater - # than 50, it'll never go back to `False` - #=> 60 3 40 60 -} - -## You can also use this property to create an `if` that'll not go through the -## first time: -for <a b c> { - .say if * ^ff *; # the flip-flop is `True` and never goes back to `False`, - # but the `^` makes it *not run* on the first iteration - #=> b c -} - -## The `===` operator is the value identity operator and uses `.WHICH` on the -## objects to compare them while `=:=` is the container identity operator -## and uses `VAR()` on the objects to compare them. -``` - -If you want to go further, you can: - - - Read the [Perl 6 Docs](https://docs.perl6.org/). This is a great - resource on Perl6. If you are looking for something, use the search bar. - This will give you a dropdown menu of all the pages referencing your search - term (Much better than using Google to find Perl 6 documents!). - - Read the [Perl 6 Advent Calendar](http://perl6advent.wordpress.com/). This - is a great source of Perl 6 snippets and explanations. If the docs don't - describe something well enough, you may find more detailed information here. - This information may be a bit older but there are many great examples and - explanations. Posts stopped at the end of 2015 when the language was declared - stable and Perl 6.c was released. - - Come along on `#perl6` at `irc.freenode.net`. The folks here are - always helpful. - - Check the [source of Perl 6's functions and - classes](https://github.com/rakudo/rakudo/tree/nom/src/core). Rakudo is - mainly written in Perl 6 (with a lot of NQP, "Not Quite Perl", a Perl 6 subset - easier to implement and optimize). - - Read [the language design documents](http://design.perl6.org). They explain - P6 from an implementor point-of-view, but it's still very interesting. diff --git a/pl-pl/bf-pl.html.markdown b/pl-pl/bf-pl.html.markdown index 88f928cf..54772961 100644 --- a/pl-pl/bf-pl.html.markdown +++ b/pl-pl/bf-pl.html.markdown @@ -7,6 +7,7 @@ contributors: - ["Mathias Bynens", "http://mathiasbynens.be/"] translators: - ["Jakub Młokosiewicz", "https://github.com/hckr"] + - ["Mateusz Burniak", "https://gitbub.com/matbur"] lang: pl-pl --- @@ -32,9 +33,9 @@ Oto osiem poleceń brainfucka: . : wyświetla wartość bieżącej komórki (w formie znaku ASCII, np. 65 = 'A') , : wczytuje (jeden) znak z wejścia do bieżącej komórki (konkretnie jego numer z tabeli ASCII) -[ : jeśli wartość w bieżącej komórce jest rózna zero, przechodzi do +[ : jeśli wartość w bieżącej komórce jest równa zeru, przechodzi do odpowiadającego ]; w przeciwnym wypdaku przechodzi do następnej instrukcji -] : Jeśli wartość w bieżącej komórce jest rózna od zera, przechodzi do +] : Jeśli wartość w bieżącej komórce jest równa zeru, przechodzi do następnej instrukcji; w przeciwnym wypdaku przechodzi do odpowiadającego [ [ i ] oznaczają pętlę while. Oczywiście każda pętla rozpoczęta [ diff --git a/pt-br/bash-pt.html.markdown b/pt-br/bash-pt.html.markdown index 3a48d994..86d1a8ea 100644 --- a/pt-br/bash-pt.html.markdown +++ b/pt-br/bash-pt.html.markdown @@ -33,7 +33,7 @@ diretamente no shell. # Exemplo simples de hello world: echo Hello World! -# Cada comando começa com uma nova linha, ou após um ponto virgula: +# Cada comando começa com uma nova linha, ou após um ponto e vírgula: echo 'Essa é a primeira linha'; echo 'Essa é a segunda linha' # A declaração de variáveis é mais ou menos assim @@ -41,14 +41,14 @@ Variavel="Alguma string" # Mas não assim: Variavel = "Alguma string" -# Bash interpretará Variavel como um comando e tentará executar e lhe retornar +# Bash interpretará Variavel como um comando e tentará executar e lhe retornará # um erro porque o comando não pode ser encontrado. # Ou assim: Variavel= 'Alguma string' -# Bash interpretará 'Alguma string' como um comando e tentará executar e lhe retornar +# Bash interpretará 'Alguma string' como um comando e tentará executar e lhe retornará # um erro porque o comando não pode ser encontrado. (Nesse caso a a parte 'Variavel=' -# é vista com uma declaração de variável valida apenas para o escopo do comando 'Uma string'). +# é vista com uma declaração de variável válida apenas para o escopo do comando 'Uma string'). # Usando a variável: echo $Variavel @@ -65,12 +65,12 @@ echo ${Variavel/Alguma/Uma} # Substring de uma variável Tamanho=7 echo ${Variavel:0:Tamanho} -# Isso retornará apenas os 7 primeiros caractéres da variável +# Isso retornará apenas os 7 primeiros caracteres da variável # Valor padrão de uma variável echo ${Foo:-"ValorPadraoSeFooNaoExistirOuEstiverVazia"} # Isso funciona para nulo (Foo=) e (Foo=""); zero (Foo=0) retorna 0. -# Note que isso apenas retornar o valor padrão e não mudar o valor da variável. +# Note que isso apenas retornará o valor padrão e não mudará o valor da variável. # Variáveis internas # Tem algumas variáveis internas bem uteis, como @@ -86,7 +86,7 @@ read Nome # Note que nós não precisamos declarar a variável echo Ola, $Nome # Nós temos a estrutura if normal: -# use 'man test' para mais infomações para as condicionais +# use 'man test' para mais informações para as condicionais if [ $Nome -ne $USER ] then echo "Seu nome não é o seu username" @@ -109,7 +109,7 @@ then echo "Isso vai rodar se $Nome é Daniela ou Jose." fi -# Expressões são denotadas com o seguinte formato +# Expressões são escritas com o seguinte formato echo $(( 10 + 5)) # Diferentemente das outras linguagens de programação, bash é um shell, então ele @@ -118,9 +118,9 @@ echo $(( 10 + 5)) ls #Esse comando tem opções que controlam sua execução -ls -l # Lista todo arquivo e diretorio em linhas separadas +ls -l # Lista todo arquivo e diretório em linhas separadas -# Os resultados do comando anterior pode ser passado para outro comando como input. +# Os resultados do comando anterior podem ser passados para outro comando como input. # O comando grep filtra o input com o padrão passado. É assim que listamos apenas # os arquivos .txt no diretório atual: ls -l | grep "\.txt" @@ -241,7 +241,7 @@ head -n 10 arquivo.txt sort arquivo.txt # reporta ou omite as linhas repetidas, com -d você as reporta uniq -d arquivo.txt -# exibe apenas a primeira coluna após o caráctere ',' +# exibe apenas a primeira coluna após o caractere ',' cut -d ',' -f 1 arquivo.txt # substitui todas as ocorrencias de 'okay' por 'legal' em arquivo.txt (é compativel com regex) sed -i 's/okay/legal/g' file.txt diff --git a/pt-br/clojure-pt.html.markdown b/pt-br/clojure-pt.html.markdown index b88d4eec..409394f2 100644 --- a/pt-br/clojure-pt.html.markdown +++ b/pt-br/clojure-pt.html.markdown @@ -382,3 +382,6 @@ Clojuredocs.org tem documentação com exemplos para quase todas as funções pr Clojure-doc.org tem um bom número de artigos para iniciantes: [http://clojure-doc.org/](http://clojure-doc.org/) + +Clojure for the Brave and True é um livro de introdução ao Clojure e possui uma versão gratuita online: +[https://www.braveclojure.com/clojure-for-the-brave-and-true/](https://www.braveclojure.com/clojure-for-the-brave-and-true/) diff --git a/pt-br/csharp-pt.html.markdown b/pt-br/csharp-pt.html.markdown index 2ff59296..384ca325 100644 --- a/pt-br/csharp-pt.html.markdown +++ b/pt-br/csharp-pt.html.markdown @@ -78,15 +78,17 @@ namespace Learning.CSharp short fooShort = 10000; ushort fooUshort = 10000; - // Integer - 32-bit integer + // Integer - inteiro de 32 bits int fooInt = 1; // (-2,147,483,648 <= int <= 2,147,483,647) uint fooUint = 1; // (0 <= uint <= 4,294,967,295) - + //Números por padrão são int ou uint, dependendo do tamanho. + // Long - 64-bit integer long fooLong = 100000L; // (-9,223,372,036,854,775,808 <= long <= 9,223,372,036,854,775,807) ulong fooUlong = 100000L; // (0 <= ulong <= 18,446,744,073,709,551,615) - // Numbers default to being int or uint depending on size. - // L is used to denote that this variable value is of type long or ulong + + // Números por padrão são int ou uint dependendo do tamanho. + // L é usado para denotar que o valor da variável é do tipo long ou ulong. // Double - Double-precision 64-bit IEEE 754 Floating Point double fooDouble = 123.4; // Precision: 15-16 digits @@ -308,25 +310,26 @@ on a new line! ""Wow!"", the masses cried"; } /////////////////////////////////////// - // Converting Data Types And Typecasting + // Convertendo Data Types e Typecasting /////////////////////////////////////// - // Converting data + // Convertendo dados + + // Converter String para Integer - // Convert String To Integer - // this will throw a FormatException on failure - int.Parse("123");//returns an integer version of "123" + // isso vai jogar um erro FormatException quando houver falha + int.Parse("123");//retorna uma verão em Integer da String "123" - // try parse will default to type default on failure - // in this case: 0 + // try parse vai ir por padrão para o typo default quando houver uma falha + // nesse caso: 0 int tryInt; - if (int.TryParse("123", out tryInt)) // Function is boolean + if (int.TryParse("123", out tryInt)) // Função booleana Console.WriteLine(tryInt); // 123 - // Convert Integer To String - // Convert class has a number of methods to facilitate conversions + // Converter Integer para String + // A classe Convert possuí métodos para facilitar as conversões Convert.ToString(123); - // or + // ou tryInt.ToString(); // Casting @@ -407,12 +410,12 @@ on a new line! ""Wow!"", the masses cried"; return result; } - // You can narrow down the objects that are passed in + // Você pode pode restringir os objetos que são passados public static void IterateAndPrint<T>(T toPrint) where T: IEnumerable<int> { - // We can iterate, since T is a IEnumerable + // Nos podemos iterar, desde que T seja um "IEnumerable" foreach (var item in toPrint) - // Item is an int + // Item é um inteiro Console.WriteLine(item.ToString()); } @@ -720,9 +723,9 @@ on a new line! ""Wow!"", the masses cried"; _speed -= decrement; } - // properties get/set values - // when only data needs to be accessed, consider using properties. - // properties may have either get or set, or both + // propriedade recupera e/ou atribui valores (get/set). + // quando os dados precisam apenas ser acessados, considere o uso de propriedades. + // uma propriedade pode ter "get" ou "set", ou ambos. private bool _hasTassles; // private variable public bool HasTassles // public accessor { diff --git a/pt-br/css-pt.html.markdown b/pt-br/css-pt.html.markdown index c73669d0..38937894 100644 --- a/pt-br/css-pt.html.markdown +++ b/pt-br/css-pt.html.markdown @@ -14,15 +14,15 @@ translators: lang: pt-br --- -Nos primeiros dias da web não havia elementos visuais, apenas texto puro. Mas com maior desenvolvimento de navegadores da web, páginas web totalmente visuais também se tornou comum. +No início da web não havia elementos visuais, apenas texto puro. Mas com maior desenvolvimento de navegadores da web, páginas web totalmente visuais também se tornara comum. -CSS ajuda a manter a separação entre o conteúdo (HTML) e o look-and-feel de uma página web. +CSS ajuda a manter a separação entre o conteúdo (HTML) e o visual de uma página web. CSS permite atingir diferentes elementos em uma página HTML e atribuir diferentes propriedades visuais para eles. -Este guia foi escrito para CSS2, embora CSS3 está rapidamente se tornando popular. +Este guia foi escrito para CSS2, embora CSS3 esteja rapidamente se tornando popular. -**NOTA:** Porque CSS produz resultados visuais, a fim de aprender, você precisa tentar de tudo em um playground CSS como [dabblet](http://dabblet.com/). +**NOTA:** Porque CSS produz resultados visuais, a fim de aprender, você precisa treinar em um playground CSS como [dabblet](http://dabblet.com/). O foco principal deste artigo é sobre a sintaxe e algumas dicas gerais. ```css @@ -42,7 +42,7 @@ Abaixo um elemento de exemplo: <div class='class1 class2' id='anID' attr='value' otherAttr='pt-br foo bar' /> */ -/* Você pode direciona-lo usando uma das suas classes CSS */ +/* Você pode direcioná-lo usando uma das suas classes CSS */ .class1 { } /* ou ambas as classes! */ @@ -82,9 +82,9 @@ classe div.some [attr $ = 'ue'] {} /* Você pode selecionar um elemento que é filho de outro elemento */ div.some-parent> .class-name {} -/* Ou um descendente de um outro elemento. As crianças são os descendentes diretos de - seu elemento pai, apenas um nível abaixo da árvore. Pode ser qualquer descendentes - nivelar por baixo da árvore. */ +/* Ou um descendente de um outro elemento. Os filhos são os descendentes diretos de + seu elemento pai, apenas um nível abaixo da árvore. Pode ser quaisquer descendentes + nivelados por baixo da árvore. */ div.some-parent class-name {} /* Atenção: o mesmo seletor sem espaço tem um outro significado. @@ -97,7 +97,7 @@ div.some-parent.class-name {} /* Ou qualquer irmão que o precede */ .i am-qualquer-elemento antes ~ .Este elemento {} -/* Existem alguns selectores chamado pseudo classes que podem ser usados para selecionar um +/* Existem alguns seletores chamados pseudo classes que podem ser usados para selecionar um elemento quando ele está em um determinado estado */ /* Por exemplo, quando o cursor passa sobre um elemento */ @@ -118,7 +118,7 @@ seletor:first-child {} /* Qualquer elemento que é o último filho de seu pai */ seletor:last-child {} -/* Assim como pseudo classes, pseudo elementos permitem que você estilo certas partes de um documento */ +/* Assim como pseudo classes, pseudo elementos permitem que você estilize certas partes de um documento */ /* Corresponde a um primeiro filho virtual do elemento selecionado */ seletor::before {} @@ -127,7 +127,7 @@ seletor::before {} seletor::after {} /* Nos locais apropriados, um asterisco pode ser utilizado como um curinga para selecionar todos - elemento */ + os elementos */ * {} /* */ Todos os elementos .parent * {} /* */ todos os descendentes .parent> * {} /* */ todas as crianças @@ -181,7 +181,7 @@ seletor { ## Uso -Guardar uma folha de estilo CSS com a extensão `.css`. +Salvar uma folha de estilo CSS com a extensão `.css`. ```xml <!-- Você precisa incluir o arquivo css no da sua página <head>. Isto é o diff --git a/pt-br/cypher-pt.html.markdown b/pt-br/cypher-pt.html.markdown index 9b60f771..d4400148 100644 --- a/pt-br/cypher-pt.html.markdown +++ b/pt-br/cypher-pt.html.markdown @@ -101,7 +101,7 @@ path = shortestPath( (user)-[:KNOWS*..5]-(other) ) Crie consultas --- -Create a new node +Crie um novo nó ``` CREATE (a:Person {name:"Théo Gauchoux"}) RETURN a diff --git a/pt-br/groovy-pt.html.markdown b/pt-br/groovy-pt.html.markdown index aed23df1..1eab9cc3 100644 --- a/pt-br/groovy-pt.html.markdown +++ b/pt-br/groovy-pt.html.markdown @@ -17,7 +17,7 @@ Groovy - Uma linguagem dinâmica para a plataforma Java. [Leia mais aqui.](http: Prepara-se: 1) Instale a máquina virtual de Groovy - http://gvmtool.net/ - 2) Intalse o Groovy: gvm install groovy + 2) Instale o Groovy: gvm install groovy 3) Inicie o console groovy digitando: groovyConsole */ diff --git a/pt-br/javascript-pt.html.markdown b/pt-br/javascript-pt.html.markdown index ed4a6ff3..f12d275b 100644 --- a/pt-br/javascript-pt.html.markdown +++ b/pt-br/javascript-pt.html.markdown @@ -361,7 +361,7 @@ myObj.myFunc(); // = "Olá mundo!" var myFunc = myObj.myFunc; myFunc(); // = undefined -// Inversamente, uma função pode ser atribuída a um objeto e ganhar a acesso +// Inversamente, uma função pode ser atribuída à um objeto e ganhar a acesso // através do `this`, até mesmo se ela não for chamada quando foi definida. var myOtherFunc = function(){ return this.myString.toUpperCase(); @@ -416,7 +416,7 @@ myNewObj.myNumber; // = 5 // vai olhar imediatamente para o seu prototype. // Algumas implementações em JS deixam você acessar o objeto prototype com a -// propriedade mágica `__proto__`. Enquanto isso é util para explicar +// propriedade mágica `__proto__`. Enquanto isso é útil para explicar // prototypes, não é parte de um padrão; nós vamos falar de algumas formas de // usar prototypes depois. @@ -489,7 +489,7 @@ if (0){ } // Entretanto, esses objetos encapsulados e as funções originais compartilham -// um mesmo prototype, portanto você pode adicionar funcionalidades a uma string, +// um mesmo prototype, portanto você pode adicionar funcionalidades à uma string, // por exemplo. String.prototype.firstCharacter = function(){ return this.charAt(0); diff --git a/pt-br/julia-pt.html.markdown b/pt-br/julia-pt.html.markdown index 48d97e58..11771d96 100644 --- a/pt-br/julia-pt.html.markdown +++ b/pt-br/julia-pt.html.markdown @@ -8,7 +8,7 @@ translators: lang: pt-br --- -Julia é uma linguagem homoiconic funcional focada na computação tecnica. Ao mesmo tempo que ela tem todo o poder dos homoiconic macros, funções de primeira classe, e controle de baixo nivel, Julia é tão facil para aprender e usar quanto Python. +Julia é uma linguagem homoicônica funcional focada na computação técnica. Ao mesmo tempo que ela tem todo o poder dos macros homoicônicos, funções de primeira classe, e controle de baixo nível, Julia é tão fácil para aprender e usar quanto Python. Este tutorial é baseado no Julia 0.3. diff --git a/pt-br/latex-pt.html.markdown b/pt-br/latex-pt.html.markdown index 103af28e..58586522 100644 --- a/pt-br/latex-pt.html.markdown +++ b/pt-br/latex-pt.html.markdown @@ -62,7 +62,7 @@ Svetlana Golubeva} \newpage -% Muitos artigos de pesquisa possuem um resumo, e pode-se isar comandos +% Muitos artigos de pesquisa possuem um resumo, e pode-se usar comandos % predefinidos para isso. % Isso deve aparecer em sua ordem lógica, portanto, após o topo, % mas antes das seções principais do corpo. diff --git a/pt-br/markdown-pt.html.markdown b/pt-br/markdown-pt.html.markdown index c2aa515d..63afffd5 100644 --- a/pt-br/markdown-pt.html.markdown +++ b/pt-br/markdown-pt.html.markdown @@ -4,6 +4,7 @@ contributors: - ["Dan Turkel", "http://danturkel.com/"] translators: - ["Miguel Araújo", "https://github.com/miguelarauj1o"] + - ["Monique Baptista", "https://github.com/bfmonique"] lang: pt-br filename: learnmarkdown-pt.md --- @@ -11,23 +12,23 @@ filename: learnmarkdown-pt.md Markdown foi criado por John Gruber in 2004. Originado para ser fácil de ler e escrever sintaxe que converte facilmente em HTML (hoje, suporta outros formatos também). -Dê-me feedback tanto quanto você quiser! / Sinta-se livre para a garfar (fork) e +Dê-me feedback tanto quanto você quiser! / Sinta-se livre para fazer uma bifurcação (fork) e puxar o projeto (pull request) ```md -<!-- Markdown é um superconjunto do HTML, de modo que qualquer arvquivo HTML é -um arquivo Markdown válido, isso significa que nós podemos usar elementos HTML +<!-- Markdown é um superconjunto do HTML, de modo que qualquer arquivo HTML é +um arquivo Markdown válido. Isso significa que nós podemos usar elementos HTML em Markdown, como o elemento de comentário, e eles não serão afetados pelo analisador de remarcação. No entanto, se você criar um elemento HTML em seu arquivo Markdown, você -não pode usar sintaxe remarcação dentro desse conteúdo do elemento.--> +não pode usar sintaxe de remarcação dentro desse conteúdo do elemento.--> -<!--Markdown também varia de implementação de um analisador para uma próxima. +<!--A maneira como o Markdown é analisado varia de software para software. Este guia vai tentar esclarecer quando as características são universais, ou quando eles são -específico para um determinado parser --> +específico para um determinado interpretador --> <!-- Cabeçalhos --> <!-- Você pode criar elementos HTML <h1> até <h6> facilmente antecedendo o texto -que deseja estar nesse elemento por um número de hashes (#) --> +que deseja estar nesse elemento por um número de cerquilhas (#) --> # Isto é um cabeçalho <h1> ## Isto é um cabeçalho <h2> ### Isto é um cabeçalho <h3> @@ -65,7 +66,7 @@ uma ou múltiplas linhas em branco. --> Este é um parágrafo. Eu estou digitando em um parágrafo, não é legal? -Agora, eu estou no parágrado 2. +Agora, eu estou no parágrafo 2. ... Ainda continuo no parágrafo 2! :) Eu estou no parágrafo três. @@ -77,19 +78,20 @@ Termino com dois espaços (destacar-me para vê-los). Há um <br /> acima de mim! -<!-- Bloco de citações são fáceis e feito com o caractere >. --> - +<!-- Bloco de citações são fáceis e feitos com o caractere >. --> + > Este é um bloco de citação. Você pode -> Enrolar manualmente suas linhas e colocar um `>` antes de cada linha ou você pode -> deixar suas linhas ficarem muito longas e enrolar por conta própria. Não faz diferença, +> Quebrar manualmente suas linhas e colocar um `>` antes de cada linha ou você pode +> deixar suas linhas ficarem muito longas e quebrarem por conta própria. Não faz diferença, > desde que eles começam com um `>`. + > Você também pode usar mais de um nível >> De recuo? > Como pura é isso? <!-- Listas --> -<!-- As listas não ordenadas podem ser feitas usando asteriscos, positivos ou hífens --> +<!-- As listas não ordenadas podem ser feitas usando asteriscos, soma ou hífens --> * Item * Item @@ -111,10 +113,10 @@ ou 1. Item um 2. Item dois -3. Tem três +3. Item três -<!-- Você não tem poder para rotular os itens corretamente e a remarcação será ainda -tornar os números em ordem, mas isso pode não ser uma boa idéia --> +<!-- Você não tem poder para rotular os itens corretamente e a remarcação ainda deixará os +itens em ordem, mas isso pode não ser uma boa idéia --> 1. Item um 1. Item dois @@ -137,14 +139,14 @@ uma linha com quatro espaços ou uma guia --> Isto é código É assim, sacou? -<!-- Você pode também re-guia (ou adicionar mais quatro espaços adicionais) para o recuo +<!-- Você pode também tabular (ou adicionar mais quatro espaços adicionais) para o recuo dentro do seu código --> my_array.each do |item| puts item end -<!-- Código embutido pode ser criada usando o caractere de crase ` --> +<!-- Código embutido pode ser criado usando o caractere de crase ` --> John não sabia nem o que o função 'goto()' fazia! @@ -155,13 +157,13 @@ ruby! --> def foobar puts "Hello world!" end -\`\`\` <!-- Aqui também, não barras invertidas, apenas ``` --> +\`\`\` <!-- Aqui também, não use barras invertidas, apenas ``` --> <-- O texto acima não requer recuo, mas o GitHub vai usar a sintaxe destacando do idioma que você especificar após a ``` --> <!-- Regra Horizontal (<hr />) --> -<!-- Regras horizontais são facilmente adicionados com três ou mais asteriscos ou hífens, +<!-- Regras horizontais são facilmente adicionadas com três ou mais asteriscos ou hífens, com ou sem espaços. --> *** @@ -175,7 +177,7 @@ o texto a ser exibido entre parênteses rígidos [] seguido pela url em parênte [Click aqui!](http://test.com/) -<!-- Você também pode adicionar um título link usando aspas dentro dos parênteses --> +<!-- Você também pode adicionar um título para o link usando aspas dentro dos parênteses --> [Click aqui!](http://test.com/ "Link para Test.com") diff --git a/pt-br/php-pt.html.markdown b/pt-br/php-pt.html.markdown index 8a1c956e..e55f1100 100644 --- a/pt-br/php-pt.html.markdown +++ b/pt-br/php-pt.html.markdown @@ -20,7 +20,7 @@ Este documento descreve PHP 5+. // Duas barras iniciam o comentário de uma linha. -# O hash (aka pound symbol) também inicia, mas // é mais comum. +# O hash (conhecido como "pound symbol") também inicia, mas // é mais comum. /* O texto envolto por barra-asterisco e asterisco-barra diff --git a/pt-br/python3-pt.html.markdown b/pt-br/python3-pt.html.markdown index b72c732a..bc5f801c 100644 --- a/pt-br/python3-pt.html.markdown +++ b/pt-br/python3-pt.html.markdown @@ -7,15 +7,16 @@ contributors: - ["Zachary Ferguson", "http://github.com/zfergus2"] translators: - ["Paulo Henrique Rodrigues Pinheiro", "http://www.sysincloud.it"] + - ["Monique Baptista", "https://github.com/bfmonique"] lang: pt-br filename: learnpython3-pt.py --- -Python foi criado por Guido Van Rossum nos anos 1990. Ele é atualmente uma -das mais populares linguagens em existência. Eu fiquei morrendo de amor -pelo Python por sua clareza sintática. É praticamente pseudocódigo executável. +Python foi criada por Guido Van Rossum nos anos 1990. Ela é atualmente uma +das linguagens mais populares existentes. Eu me apaixonei por +Python por sua clareza sintática. É praticamente pseudocódigo executável. -Suas opiniões são grandemente apreciadas. Você pode encontrar-me em +Opniões são muito bem vindas. Você pode encontrar-me em [@louiedinh](http://twitter.com/louiedinh) ou louiedinh [em] [serviço de e-mail do google]. @@ -44,7 +45,7 @@ aprender o velho Python 2.7. 8 - 1 # => 7 10 * 2 # => 20 -# Números inteiros por padrão, exceto na divisão, que retorna número +# Números são inteiros por padrão, exceto na divisão, que retorna número # de ponto flutuante (float). 35 / 5 # => 7.0 @@ -64,7 +65,7 @@ aprender o velho Python 2.7. # Exponenciação (x**y, x elevado à potência y) 2**4 # => 16 -# Determine a precedência usando parêntesis +# Determine a precedência usando parênteses (1 + 3) * 2 # => 8 # Valores lógicos são primitivos (Atenção à primeira letra maiúscula) @@ -105,9 +106,8 @@ False or True # => True 1 < 2 < 3 # => True 2 < 3 < 2 # => False -# (operador 'is' e operador '==') is verifica se duas variáveis -# referenciam um mesmo objeto, mas == verifica se as variáveis -# apontam para o mesmo valor. +# 'is' verifica se duas variáveis representam o mesmo endereço +# na memória; '==' verifica se duas variáveis têm o mesmo valor a = [1, 2, 3, 4] # Referência a uma nova lista, [1, 2, 3, 4] b = a # b referencia o que está referenciado por a b is a # => True, a e b referenciam o mesmo objeto @@ -174,7 +174,7 @@ input_string_var = input("Digite alguma coisa: ") # Retorna o que foi digitado e # Observação: Em versões antigas do Python, o método input() era chamado raw_input() # Não é necessário declarar variáveis antes de iniciá-las -# È uma convenção usar letras_minúsculas_com_sublinhados +# É uma convenção usar letras_minúsculas_com_sublinhados alguma_variavel = 5 alguma_variavel # => 5 @@ -182,31 +182,31 @@ alguma_variavel # => 5 # Veja Controle de Fluxo para aprender mais sobre tratamento de exceções. alguma_variavel_nao_inicializada # Gera a exceção NameError -# Listas armazenam sequencias +# Listas armazenam sequências li = [] -# Você pode iniciar com uma lista com alguns valores +# Você pode iniciar uma lista com valores outra_li = [4, 5, 6] -# Adicionar conteúdo ao fim da lista com append +# Adicione conteúdo ao fim da lista com append li.append(1) # li agora é [1] li.append(2) # li agora é [1, 2] li.append(4) # li agora é [1, 2, 4] li.append(3) # li agora é [1, 2, 4, 3] -# Remover do final da lista com pop +# Remova do final da lista com pop li.pop() # => 3 e agora li é [1, 2, 4] # Vamos colocá-lo lá novamente! li.append(3) # li agora é [1, 2, 4, 3] novamente. -# Acessar uma lista da mesma forma que você faz com um array +# Acesse uma lista da mesma forma que você faz com um array li[0] # => 1 -# Acessa o último elemento +# Acessando o último elemento li[-1] # => 3 -# Acessando além dos limites gera um IndexError +# Acessar além dos limites gera um IndexError li[4] # Gera o IndexError # Você pode acessar vários elementos com a sintaxe de limites -# (É um limite fechado, aberto pra você que gosta de matemática.) +# Inclusivo para o primeiro termo, exclusivo para o segundo li[1:3] # => [2, 4] # Omitindo o final li[2:] # => [4, 3] diff --git a/pt-br/stylus-pt.html.markdown b/pt-br/stylus-pt.html.markdown index 804fa806..40c3c02c 100755 --- a/pt-br/stylus-pt.html.markdown +++ b/pt-br/stylus-pt.html.markdown @@ -132,7 +132,7 @@ body { background-color: $primary-color } -/* Apoś compilar ficaria assim: */ +/* Após compilar ficaria assim: */ div { display: block; margin-left: auto; @@ -184,13 +184,13 @@ button /* Funções ==============================*/ -/* Funções no Stylus permitem fazer uma variedade de tarefas, como por exemplo, menipular algum dado. */ +/* Funções no Stylus permitem fazer uma variedade de tarefas, como por exemplo, manipular algum dado. */ body { background darken(#0088DD, 50%) // Escurece a cor #0088DD em 50% } -/** Criando sua própria função */ +/* Criando sua própria função */ somar(a, b) a + b @@ -221,7 +221,7 @@ for <val-name> [, <key-name>] in <expression> for $item in (1..2) /* Repete o bloco 12 vezes */ .col-{$item} - width ($item / 12) * 100% /* Calcula a largula pelo número da coluna* + width ($item / 12) * 100% /* Calcula a largura pelo número da coluna* ``` diff --git a/pt-br/typescript-pt.html.markdown b/pt-br/typescript-pt.html.markdown index 077aa2cc..6ece02ff 100644 --- a/pt-br/typescript-pt.html.markdown +++ b/pt-br/typescript-pt.html.markdown @@ -10,7 +10,7 @@ lang: pt-br Typescript é uma linguagem que visa facilitar o desenvolvimento de aplicações em grande escala escritos em JavaScript. Typescript acrescenta conceitos comuns como classes, módulos, interfaces, genéricos e (opcional) tipagem estática para JavaScript. -É um super conjunto de JavaScript: todo o código JavaScript é o código do texto dactilografado válido para que possa ser adicionados diretamente a qualquer projeto. O compilador emite typescript JavaScript. +É um super conjunto de JavaScript: todo o código JavaScript é TypeScript válido então ele pode ser adicionado diretamente a qualquer projeto. O compilador emite typescript JavaScript. Este artigo irá se concentrar apenas em texto datilografado sintaxe extra, ao contrário de [JavaScript](javascript-pt.html.markdown). @@ -22,7 +22,7 @@ var isDone: boolean = false; var lines: number = 42; var name: string = "Anders"; -// Quando é impossível saber, há o "Qualquer" tipo +// Quando é impossível saber, há o tipo "Qualquer" var notSure: any = 4; notSure = "maybe a string instead"; notSure = false; // Ok, definitivamente um boolean @@ -65,7 +65,7 @@ interface Person { move(): void; } -// Objeto que implementa a "Pessoa" Interface +// Objeto que implementa a Interface "Pessoa" // Pode ser tratado como uma pessoa desde que tem o nome e mover propriedades var p: Person = { name: "Bobby", move: () => {} }; // Os objetos que têm a propriedade opcional: diff --git a/pt-br/yaml-pt.html.markdown b/pt-br/yaml-pt.html.markdown index 0b71877e..07903325 100644 --- a/pt-br/yaml-pt.html.markdown +++ b/pt-br/yaml-pt.html.markdown @@ -11,10 +11,10 @@ lang: pt-br YAML é uma linguagem de serialização de dados projetado para ser diretamente gravável e legível por seres humanos. -É um superconjunto de JSON, com a adição de indentação e quebras de linhas sintaticamente significativas, como Python. Ao contrário de Python, entretanto, YAML não permite o caracter literal tab para identação. +É um superconjunto de JSON, com a adição de identação e quebras de linhas sintaticamente significativas, como Python. Ao contrário de Python, entretanto, YAML não permite o caracter literal tab para identação. ```yaml -# Commentários em YAML são como este. +# Comentários em YAML são como este. ################### # TIPOS ESCALARES # @@ -33,7 +33,7 @@ chave com espaco: valor porem: "Uma string, entre aspas." "Chaves podem estar entre aspas tambem.": "É útil se você quiser colocar um ':' na sua chave." -# Seqüências de várias linhas podem ser escritos como um 'bloco literal' (utilizando |), +# Seqüências de várias linhas podem ser escritas como um 'bloco literal' (utilizando |), # ou em um 'bloco compacto' (utilizando '>'). bloco_literal: | Todo esse bloco de texto será o valor da chave 'bloco_literal', @@ -76,7 +76,7 @@ um_mapa_aninhado: # também permite tipos de coleção de chaves, mas muitas linguagens de programação # vão reclamar. -# Sequências (equivalente a listas ou arrays) semelhante à isso: +# Sequências (equivalente a listas ou arrays) semelhante a isso: uma_sequencia: - Item 1 - Item 2 @@ -118,7 +118,7 @@ datetime: 2001-12-15T02: 59: 43.1Z datetime_com_espacos 2001/12/14: 21: 59: 43.10 -5 Data: 2002/12/14 -# A tag !!binary indica que a string é na verdade um base64-encoded (condificado) +# A tag !!binary indica que a string é na verdade um base64-encoded (codificado) # representação de um blob binário. gif_file: !!binary | R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5 diff --git a/python3.html.markdown b/python3.html.markdown index 430927a9..d09c2819 100644 --- a/python3.html.markdown +++ b/python3.html.markdown @@ -8,6 +8,7 @@ contributors: - ["evuez", "http://github.com/evuez"] - ["Rommel Martinez", "https://ebzzry.io"] - ["Roberto Fernandez Diaz", "https://github.com/robertofd1995"] + - ["caminsha", "https://github.com/caminsha"] filename: learnpython3.py --- @@ -230,7 +231,7 @@ li[4] # Raises an IndexError # (It's a closed/open range for you mathy types.) li[1:3] # Return list from index 1 to 3 => [2, 4] li[2:] # Return list starting from index 2 => [4, 3] -li[:3] # Return list from beginning uptil index 3 => [1, 2, 4] +li[:3] # Return list from beginning until index 3 => [1, 2, 4] li[::2] # Return list selecting every second entry => [1, 4] li[::-1] # Return list in reverse order => [3, 4, 2, 1] # Use any combination of these to make advanced slices @@ -550,8 +551,14 @@ next(our_iterator) # => "three" # After the iterator has returned all of its data, it raises a StopIteration exception next(our_iterator) # Raises StopIteration -# You can grab all the elements of an iterator by calling list() on it. -list(filled_dict.keys()) # => Returns ["one", "two", "three"] +# We can also loop over it, in fact, "for" does this implicitly! +our_iterator = iter(our_iterable) +for i in our_iterator: + print(i) # Prints one, two, three + +# You can grab all the elements of an iterable or iterator by calling list() on it. +list(our_iterable) # => Returns ["one", "two", "three"] +list(our_iterator) # => Returns [] because state is saved #################################################### diff --git a/raku.html.markdown b/raku.html.markdown new file mode 100644 index 00000000..4f397589 --- /dev/null +++ b/raku.html.markdown @@ -0,0 +1,2412 @@ +--- +category: language +language: Raku +filename: learnraku.raku +contributors: + - ["vendethiel", "http://github.com/vendethiel"] + - ["Samantha McVey", "https://cry.nu"] +--- + +Raku (formerly Perl 6) is a highly capable, feature-rich programming language +made for at least the next hundred years. + +The primary Raku compiler is called [Rakudo](http://rakudo.org), which runs on +the JVM and the [MoarVM](http://moarvm.com). + +Meta-note: + +* Although the pound sign (`#`) is used for sentences and notes, Pod-styled + comments (more below about them) are used whenever it's convenient. +* `# OUTPUT:` is used to represent the output of a command to any standard + stream. If the output has a newline, it's represented by the `` symbol. + The output is always enclosed by angle brackets (`«` and `»`). +* `#=>` represents the value of an expression, return value of a sub, etc. + In some cases, the value is accompanied by a comment. +* Backticks are used to distinguish and highlight the language constructs + from the text. + +```perl6 +#################################################### +# 0. Comments +#################################################### + +# Single line comments start with a pound sign. + +#`( Multiline comments use #` and a quoting construct. + (), [], {}, 「」, etc, will work. +) + +=for comment +Use the same syntax for multiline comments to embed comments. +for #`(each element in) @array { + put #`(or print element) $_ #`(with newline); +} + +# You can also use Pod-styled comments. For example: + +=comment This is a comment that extends until an empty +newline is found. + +=comment +The comment doesn't need to start in the same line as the directive. + +=begin comment +This comment is multiline. + +Empty newlines can exist here too! +=end comment + +#################################################### +# 1. Variables +#################################################### + +# In Raku, you declare a lexical variable using the `my` keyword: +my $variable; + +# Raku has 3 basic types of variables: scalars, arrays, and hashes. + +# +# 1.1 Scalars +# + +# Scalars represent a single value. They start with the `$` sigil: +my $str = 'String'; + +# Double quotes allow for interpolation (which we'll see later): +my $str2 = "$str"; + +# Variable names can contain but not end with simple quotes and dashes, +# and can contain (and end with) underscores: +my $person's-belongings = 'towel'; # this works! + +my $bool = True; # `True` and `False` are Raku's boolean values. +my $inverse = !$bool; # Invert a bool with the prefix `!` operator. +my $forced-bool = so $str; # And you can use the prefix `so` operator +$forced-bool = ?$str; # to turn its operand into a Bool. Or use `?`. + +# +# 1.2 Arrays and Lists +# + +# Arrays represent multiple values. An array variable starts with the `@` +# sigil. Unlike lists, from which arrays inherit, arrays are mutable. + +my @array = 'a', 'b', 'c'; +# equivalent to: +my @letters = <a b c>; +# In the previous statement, we use the quote-words (`<>`) term for array +# of words, delimited by space. Similar to perl5's qw, or Ruby's %w. + +@array = 1, 2, 4; + +# Array indices start at 0. Here the third element is being accessed. +say @array[2]; # OUTPUT: «4» + +say "Interpolate an array using []: @array[]"; +# OUTPUT: «Interpolate an array using []: 1 2 3» + +@array[0] = -1; # Assigning a new value to an array index +@array[0, 1] = 5, 6; # Assigning multiple values + +my @keys = 0, 2; +@array[@keys] = @letters; # Assignment using an array containing index values +say @array; # OUTPUT: «a 6 b» + +# +# 1.3 Hashes, or key-value Pairs. +# + +=begin comment +Hashes are pairs of keys and values. You can construct a `Pair` object +using the syntax `key => value`. Hash tables are very fast for lookup, +and are stored unordered. Keep in mind that keys get "flattened" in hash +context, and any duplicated keys are deduplicated. +=end comment +my %hash = 'a' => 1, 'b' => 2; + +# Keys get auto-quoted when the fat comman (`=>`) is used. Trailing commas are +# okay. +%hash = a => 1, b => 2, ; + +# Even though hashes are internally stored differently than arrays, +# Raku allows you to easily create a hash from an even numbered array: +%hash = <key1 value1 key2 value2>; # Or: +%hash = "key1", "value1", "key2", "value2"; + +%hash = key1 => 'value1', key2 => 'value2'; # same result as above + +# You can also use the "colon pair" syntax. This syntax is especially +# handy for named parameters that you'll see later. +%hash = :n(2), # equivalent to `n => 2` + :is-even, # equivalent to `:is-even(True)` or `is-even => True` + :!is-odd, # equivalent to `:is-odd(False)` or `is-odd => False` +; +# The `:` (as in `:is-even`) and `:!` (as `:!is-odd`) constructs are known +# as the `True` and `False` shortcuts respectively. + +=begin comment +As demonstrated in the example below, you can use {} to get the value from a key. +If it's a string without spaces, you can actually use the quote-words operator +(`<>`). Since Raku doesn't have barewords, as Perl does, `{key1}` doesn't work +though. +=end comment +say %hash{'n'}; # OUTPUT: «2», gets value associated to key 'n' +say %hash<is-even>; # OUTPUT: «True», gets value associated to key 'is-even' + +#################################################### +# 2. Subroutines +#################################################### + +# Subroutines, or functions as most other languages call them, are +# created with the `sub` keyword. +sub say-hello { say "Hello, world" } + +# You can provide (typed) arguments. If specified, the type will be checked +# at compile-time if possible, otherwise at runtime. +sub say-hello-to( Str $name ) { + say "Hello, $name !"; +} + +# A sub returns the last value of the block. Similarly, the semicolon in +# the last expression can be omitted. +sub return-value { 5 } +say return-value; # OUTPUT: «5» + +sub return-empty { } +say return-empty; # OUTPUT: «Nil» + +# Some control flow structures produce a value, for instance `if`: +sub return-if { + if True { "Truthy" } +} +say return-if; # OUTPUT: «Truthy» + +# Some don't, like `for`: +sub return-for { + for 1, 2, 3 { 'Hi' } +} +say return-for; # OUTPUT: «Nil» + +=begin comment +Positional arguments are required by default. To make them optional, use +the `?` after the parameters' names. + +In the following example, the sub `with-optional` returns `(Any)` (Perl's +null-like value) if no argument is passed. Otherwise, it returns its argument. +=end comment +sub with-optional( $arg? ) { + $arg; +} +with-optional; # returns Any +with-optional(); # returns Any +with-optional(1); # returns 1 + +=begin comment +You can also give provide a default value when they're not passed. Doing +this make said parameter optional. Required parameters must come before +optional ones. + +In the sub `greeting`, the parameter `$type` is optional. +=end comment +sub greeting( $name, $type = "Hello" ) { + say "$type, $name!"; +} + +greeting("Althea"); # OUTPUT: «Hello, Althea!» +greeting("Arthur", "Good morning"); # OUTPUT: «Good morning, Arthur!» + +=begin comment +You can also, by using a syntax akin to the one of hashes (yay unified syntax!), +declared named parameters and thus pass named arguments to a subroutine. +By default, named parameter are optional and will default to `Any`. +=end comment +sub with-named( $normal-arg, :$named ) { + say $normal-arg + $named; +} +with-named(1, named => 6); # OUTPUT: «7» + +=begin comment +There's one gotcha to be aware of, here: If you quote your key, Raku +won't be able to see it at compile time, and you'll have a single `Pair` +object as a positional parameter, which means the function subroutine +`with-named(1, 'named' => 6);` fails. +=end comment +with-named(2, :named(5)); # OUTPUT: «7» + +# Similar to positional parameters, you can provide your named arguments with +# default values. +sub named-def( :$def = 5 ) { + say $def; +} +named-def; # OUTPUT: «5» +named-def(def => 15); # OUTPUT: «15» + +=begin comment +In order to make a named parameter mandatory, you can append `!` to the +parameter. This is the inverse of `?`, which makes a required parameter +optional. +=end comment + +sub with-mandatory-named( :$str! ) { + say "$str!"; +} +with-mandatory-named(str => "My String"); # OUTPUT: «My String!» +# with-mandatory-named; # runtime error: "Required named parameter not passed" +# with-mandatory-named(3);# runtime error: "Too many positional parameters passed" + +=begin comment +If a sub takes a named boolean argument, you can use the same "short boolean" +hash syntax we discussed earlier. +=end comment +sub takes-a-bool( $name, :$bool ) { + say "$name takes $bool"; +} +takes-a-bool('config', :bool); # OUTPUT: «config takes True» +takes-a-bool('config', :!bool); # OUTPUT: «config takes False» + +=begin comment +Since paranthesis can be omitted when calling a subroutine, you need to use +`&` in order to distinguish between a call to a sub with no arguments and +the code object. + +For instance, in this example we must use `&` to store the sub `say-hello` +(i.e., the sub's code object) in a variable, not a subroutine call. +=end comment +my &s = &say-hello; +my &other-s = sub { say "Anonymous function!" } + +=begin comment +A sub can have a "slurpy" parameter, or what one'd call a +"doesn't-matter-how-many" parameter. This is Raku's way of supporting variadic +functions. For this, you must use `*@` (slurpy) which will "take everything +else". You can have as many parameters *before* a slurpy one, but not *after*. +=end comment +sub as-many($head, *@rest) { + @rest.join(' / ') ~ " !"; +} +say as-many('Happy', 'Happy', 'Birthday'); # OUTPUT: «Happy / Birthday !» +say 'Happy', ['Happy', 'Birthday'], 'Day'; # OUTPUT: «Happy / Birthday / Day !» + +# Note that the splat (the *) did not consume the parameter before it. + +=begin comment +There are other two variations of slurpy parameters in Raku. The previous one +(namely, `*@`), known as flattened slurpy, flattens passed arguments. The other +two are `**@` and `+@` known as unflattened slurpy and "single argument rule" +slurpy respectively. The unflattened slurpy doesn't flatten its listy +arguments (or Iterable ones). +=end comment +sub b(**@arr) { @arr.perl.say }; +b(['a', 'b', 'c']); # OUTPUT: «[["a", "b", "c"],]» +b(1, $('d', 'e', 'f'), [2, 3]); # OUTPUT: «[1, ("d", "e", "f"), [2, 3]]» +b(1, [1, 2], ([3, 4], 5)); # OUTPUT: «[1, [1, 2], ([3, 4], 5)]» + +=begin comment +On the other hand, the "single argument rule" slurpy follows the "single argument +rule" which dictates how to handle the slurpy argument based upon context and +roughly states that if only a single argument is passed and that argument is +Iterable, that argument is used to fill the slurpy parameter array. In any +other case, `+@` works like `**@`. +=end comment +sub c(+@arr) { @arr.perl.say }; +c(['a', 'b', 'c']); # OUTPUT: «["a", "b", "c"]» +c(1, $('d', 'e', 'f'), [2, 3]); # OUTPUT: «[1, ("d", "e", "f"), [2, 3]]» +c(1, [1, 2], ([3, 4], 5)); # OUTPUT: «[1, [1, 2], ([3, 4], 5)]» + +=begin comment +You can call a function with an array using the "argument list flattening" +operator `|` (it's not actually the only role of this operator, +but it's one of them). +=end comment +sub concat3($a, $b, $c) { + say "$a, $b, $c"; +} +concat3(|@array); # OUTPUT: «a, b, c» + # `@array` got "flattened" as a part of the argument list + +#################################################### +# 3. Containers +#################################################### + +=begin comment +In Raku, values are actually stored in "containers". The assignment +operator asks the container on the left to store the value on its right. +When passed around, containers are marked as immutable which means that, +in a function, you'll get an error if you try to mutate one of your +arguments. If you really need to, you can ask for a mutable container by +using the `is rw` trait. +=end comment +sub mutate( $n is rw ) { + $n++; # postfix ++ operator increments its argument but returns its old value +} +my $m = 42; +mutate $m; #=> 42, the value is incremented but the old value is returned +say $m; # OUTPUT: «43» + +=begin comment +This works because we are passing the container $m to the `mutate` sub. +If we try to just pass a number instead of passing a variable, it won't work +because there is no container being passed and integers are immutable by +themselves: + +mutate 42; # Parameter '$n' expected a writable container, but got Int value +=end comment + +=begin comment +Similar error would be obtained, if a bound variable is passed to +to the subroutine. In Raku, you bind a value to a variable using the binding +operator `:=`. +=end comment +my $v := 50; # binding 50 to the variable $v +# mutate $v; # Parameter '$n' expected a writable container, but got Int value + +=begin comment +If what you want is a copy instead, use the `is copy` trait which will +cause the argument to be copied and allow you to modify the argument +inside the routine without modifying the passed argument. + +A sub itself returns a container, which means it can be marked as `rw`. +Alternatively, you can explicitly mark the returned container as mutable +by using `return-rw` instead of `return`. +=end comment +my $x = 42; +my $y = 45; +sub x-store is rw { $x } +sub y-store { return-rw $y } + +# In this case, the parentheses are mandatory or else Raku thinks that +# `x-store` and `y-store` are identifiers. +x-store() = 52; +y-store() *= 2; + +say $x; # OUTPUT: «52» +say $y; # OUTPUT: «90» + +#################################################### +# 4.Control Flow Structures +#################################################### + +# +# 4.1 if/if-else/if-elsif-else/unless +# + +=begin comment +Before talking about `if`, we need to know which values are "truthy" +(represent `True`), and which are "falsey" (represent `False`). Only these +values are falsey: 0, (), {}, "", Nil, a type (like `Str`, `Int`, etc.) and +of course, `False` itself. Any other value is truthy. +=end comment +my $number = 5; +if $number < 5 { + say "Number is less than 5" +} +elsif $number == 5 { + say "Number is equal to 5" +} +else { + say "Number is greater than 5" +} + +unless False { + say "It's not false!"; +} + +# `unless` is the equivalent of `if not (X)` which inverts the sense of a +# conditional statement. However, you cannot use `else` or `elsif` with it. + +# As you can see, you don't need parentheses around conditions. However, you +# do need the curly braces around the "body" block. For example, +# `if (True) say 'It's true';` doesn't work. + +# You can also use their statement modifier (postfix) versions: +say "Quite truthy" if True; # OUTPUT: «Quite truthy» +say "Quite falsey" unless False; # OUTPUT: «Quite falsey» + +=begin comment +The ternary operator (`??..!!`) is structured as follows `condition ?? +expression1 !! expression2` and it returns expression1 if the condition is +true. Otherwise, it returns expression2. +=end comment +my $age = 30; +say $age > 18 ?? "You are an adult" !! "You are under 18"; +# OUTPUT: «You are an adult» + +# +# 4.2 with/with-else/with-orwith-else/without +# + +=begin comment +The `with` statement is like `if`, but it tests for definedness rather than +truth, and it topicalizes on the condition, much like `given` which will +be discussed later. +=end comment +my $s = "raku"; +with $s.index("r") { say "Found a at $_" } +orwith $s.index("k") { say "Found c at $_" } +else { say "Didn't find r or k" } + +# Similar to `unless` that checks un-truthiness, you can use `without` to +# check for undefined-ness. +my $input01; +without $input01 { + say "No input given." +} +# OUTPUT: «No input given.» + +# There are also statement modifier versions for both `with` and `without`. +my $input02 = 'Hello'; +say $input02 with $input02; # OUTPUT: «Hello» +say "No input given." without $input02; + +# +# 4.3 given/when, or Raku's switch construct +# + +=begin comment +`given...when` looks like other languages' `switch`, but is much more +powerful thanks to smart matching and Raku's "topic variable", `$_`. + +The topic variable `$_ `contains the default argument of a block, a loop's +current iteration (unless explicitly named), etc. + +`given` simply puts its argument into `$_` (like a block would do), + and `when` compares it using the "smart matching" (`~~`) operator. + +Since other Raku constructs use this variable (as said before, like `for`, +blocks, `with` statement etc), this means the powerful `when` is not only +applicable along with a `given`, but instead anywhere a `$_` exists. +=end comment + +given "foo bar" { + say $_; # OUTPUT: «foo bar» + + # Don't worry about smart matching yet. Just know `when` uses it. This is + # equivalent to `if $_ ~~ /foo/`. + when /foo/ { + say "Yay !"; + } + + # smart matching anything with `True` is `True`, i.e. (`$a ~~ True`) + # so you can also put "normal" conditionals. For example, this `when` is + # equivalent to this `if`: `if $_ ~~ ($_.chars > 50) {...}` + # which means: `if $_.chars > 50 {...}` + when $_.chars > 50 { + say "Quite a long string !"; + } + + # same as `when *` (using the Whatever Star) + default { + say "Something else" + } +} + +# +# 4.4 Looping constructs +# + +# The `loop` construct is an infinite loop if you don't pass it arguments, but +# can also be a C-style `for` loop: +loop { + say "This is an infinite loop !"; + last; +} +# In the previous example, `last` breaks out of the loop very much +# like the `break` keyword in other languages. + +# The `next` keyword skips to the next iteration, like `continue` in other +# languages. Note that you can also use postfix conditionals, loops, etc. +loop (my $i = 0; $i < 5; $i++) { + next if $i == 3; + say "This is a C-style for loop!"; +} + +# The `for` constructs iterates over a list of elements. +my @odd-array = 1, 3, 5, 7, 9; + +# Accessing the array's elements with the topic variable $_. +for @odd-array { + say "I've got $_ !"; +} + +# Accessing the array's elements with a "pointy block", `->`. +# Here each element is read-only. +for @odd-array -> $variable { + say "I've got $variable !"; +} + +# Accessing the array's elements with a "doubly pointy block", `<->`. +# Here each element is read-write so mutating `$variable` mutates +# that element in the array. +for @odd-array <-> $variable { + say "I've got $variable !"; +} + +# As we saw with `given`, a `for` loop's default "current iteration" variable +# is `$_`. That means you can use `when` in a `for`loop just like you were +# able to in a `given`. +for @odd-array { + say "I've got $_"; + + # This is also allowed. A dot call with no "topic" (receiver) is sent to + # `$_` (topic variable) by default. + .say; + + # This is equivalent to the above statement. + $_.say; +} + +for @odd-array { + # You can... + next if $_ == 3; # Skip to the next iteration (`continue` in C-like lang.) + redo if $_ == 4; # Re-do iteration, keeping the same topic variable (`$_`) + last if $_ == 5; # Or break out of loop (like `break` in C-like lang.) +} + +# The "pointy block" syntax isn't specific to the `for` loop. It's just a way +# to express a block in Raku. +sub long-computation { "Finding factors of large primes" } +if long-computation() -> $result { + say "The result is $result."; +} + +#################################################### +# 5. Operators +#################################################### + +=begin comment +Since Perl languages are very much operator-based languages, Raku +operators are actually just funny-looking subroutines, in syntactic +categories, like infix:<+> (addition) or prefix:<!> (bool not). + +The categories are: + - "prefix": before (like `!` in `!True`). + - "postfix": after (like `++` in `$a++`). + - "infix": in between (like `*` in `4 * 3`). + - "circumfix": around (like `[`-`]` in `[1, 2]`). + - "post-circumfix": around, after another term (like `{`-`}` in + `%hash{'key'}`) + +The associativity and precedence list are explained below. + +Alright, you're set to go! +=end comment + +# +# 5.1 Equality Checking +# + +# `==` is numeric comparison +say 3 == 4; # OUTPUT: «False» +say 3 != 4; # OUTPUT: «True» + +# `eq` is string comparison +say 'a' eq 'b'; # OUTPUT: «False» +say 'a' ne 'b'; # OUTPUT: «True», not equal +say 'a' !eq 'b'; # OUTPUT: «True», same as above + +# `eqv` is canonical equivalence (or "deep equality") +say (1, 2) eqv (1, 3); # OUTPUT: «False» +say (1, 2) eqv (1, 2); # OUTPUT: «True» +say Int === Int; # OUTPUT: «True» + +# `~~` is the smart match operator which aliases the left hand side to $_ and +# then evaluates the right hand side. +# Here are some common comparison semantics: + +# String or numeric equality +say 'Foo' ~~ 'Foo'; # OUTPU: «True», if strings are equal. +say 12.5 ~~ 12.50; # OUTPU: «True», if numbers are equal. + +# Regex - For matching a regular expression against the left side. +# Returns a `Match` object, which evaluates as True if regexp matches. +my $obj = 'abc' ~~ /a/; +say $obj; # OUTPUT: «｢a｣» +say $obj.WHAT; # OUTPUT: «(Match)» + +# Hashes +say 'key' ~~ %hash; # OUTPUT:«True», if key exists in hash. + +# Type - Checks if left side "is of type" (can check superclasses and roles). +say 1 ~~ Int; # OUTPUT: «True» + +# Smart-matching against a boolean always returns that boolean (and will warn). +say 1 ~~ True; # OUTPUT: «True», smartmatch against True always matches +say False.so ~~ True; # OUTPUT: «True», use .so for truthiness + +# General syntax is `$arg ~~ &bool-returning-function;`. For a complete list +# of combinations, refer to the table at: +# https://docs.raku.org/language/operators#index-entry-smartmatch_operator + +# Of course, you also use `<`, `<=`, `>`, `>=` for numeric comparison. +# Their string equivalent are also available: `lt`, `le`, `gt`, `ge`. +say 3 > 4; # OUTPUT: «False» +say 3 >= 4; # OUTPUT: «False» +say 3 < 4; # OUTPUT: «True» +say 3 <= 4; # OUTPUT: «True» +say 'a' gt 'b'; # OUTPUT: «False» +say 'a' ge 'b'; # OUTPUT: «False» +say 'a' lt 'b'; # OUTPUT: «True» +say 'a' le 'b'; # OUTPUT: «True» + +# +# 5.2 Range constructor +# + +say 3 .. 7; # OUTPUT: «3..7», both included. +say 3 ..^ 7; # OUTPUT: «3..^7», exclude right endpoint. +say 3 ^.. 7; # OUTPUT: «3^..7», exclude left endpoint. +say 3 ^..^ 7; # OUTPUT: «3^..^7», exclude both endpoints. + +# The range 3 ^.. 7 is similar like 4 .. 7 when we only consider integers. +# But when we consider decimals: + +say 3.5 ~~ 4 .. 7; # OUTPUT: «False» +say 3.5 ~~ 3 ^.. 7; # OUTPUT: «True», + +# This is because the range `3 ^.. 7` only excludes anything strictly +# equal to 3. Hence, it contains decimals greater than 3. This could +# mathematically be described as 3.5 ∈ (3,7] or in set notation, +# 3.5 ∈ { x | 3 < x ≤ 7 }. + +say 3 ^.. 7 ~~ 4 .. 7; # OUTPUT: «False» + +# This also works as a shortcut for `0..^N`: +say ^10; # OUTPUT: «^10», which means 0..^10 + +# This also allows us to demonstrate that Raku has lazy/infinite arrays, +# using the Whatever Star: +my @natural = 1..*; # 1 to Infinite! Equivalent to `1..Inf`. + +# You can pass ranges as subscripts and it'll return an array of results. +say @natural[^10]; # OUTPUT: «1 2 3 4 5 6 7 8 9 10», doesn't run out of memory! + +=begin comment +NOTE: when reading an infinite list, Raku will "reify" the elements +it needs, then keep them in memory. They won't be calculated more than once. +It also will never calculate more elements that are needed. +=end comment + +# An array subscript can also be a closure. It'll be called with the array's +# length as the argument. The following two examples are equivalent: +say join(' ', @array[15..*]); # OUTPUT: «15 16 17 18 19» +say join(' ', @array[-> $n { 15..$n }]); # OUTPUT: «15 16 17 18 19» + +# NOTE: if you try to do either of those with an infinite array, you'll +# trigger an infinite loop (your program won't finish). + +# You can use that in most places you'd expect, even when assigning to an array: +my @numbers = ^20; + +# Here the numbers increase by 6, like an arithmetic sequence; more on the +# sequence (`...`) operator later. +my @seq = 3, 9 ... * > 95; # 3 9 15 21 27 [...] 81 87 93 99; + +# In this example, even though the sequence is infinite, only the 15 +# needed values will be calculated. +@numbers[5..*] = 3, 9 ... *; +say @numbers; # OUTPUT: «0 1 2 3 4 3 9 15 21 [...] 81 87», only 20 values + +# +# 5.3 and (&&), or (||) +# + +# Here `and` calls `.Bool` on both 3 and 4 and gets `True` so it returns +# 4 since both are `True`. +say (3 and 4); # OUTPUT: «4», which is truthy. +say (3 and 0); # OUTPUT: «0» +say (0 and 4); # OUTPUT: «0» + +# Here `or` calls `.Bool` on `0` and `False` which are both `False` +# so it returns `False` since both are `False`. +say (0 or False); # OUTPUT: «False». + +# Both `and` and `or` have tighter versions which also shortcut circuits. +# They're `&&` and `||` respectively. + +# `&&` returns the first operand that evaluates to `False`. Otherwise, +# it returns the last operand. +my ($a, $b, $c, $d, $e) = 1, 0, False, True, 'pi'; +say $a && $b && $c; # OUTPUT: «0», the first falsey value +say $a && $b && $c; # OUTPUT: «False», the first falsey value +say $a && $d && $e; # OUTPUT: «pi», last operand since everthing before is truthy + +# `||` returns the first argument that evaluates to `True`. +say $b || $a || $d; # OUTPUT: «1» +say $e || $d || $a; # OUTPUT: «pi» + +# And because you're going to want them, you also have compound assignment +# operators: +$a *= 2; # multiply and assignment. Equivalent to $a = $a * 2; +$b %%= 5; # divisible by and assignment. Equivalent to $b = $b %% 2; +$c div= 3; # return divisor and assignment. Equivalent to $c = $c div 3; +$d mod= 4; # return remainder and assignment. Equivalent to $d = $d mod 4; +@array .= sort; # calls the `sort` method and assigns the result back + +#################################################### +# 6. More on subs! +#################################################### + +# As we said before, Raku has *really* powerful subs. We're going +# to see a few more key concepts that make them better than in any +# other language :-). + +# +# 6.1 Unpacking! +# + +# Unpacking is the ability to "extract" arrays and keys +# (AKA "destructuring"). It'll work in `my`s and in parameter lists. +my ($f, $g) = 1, 2; +say $f; # OUTPUT: «1» +my ($, $, $h) = 1, 2, 3; # keep the non-interesting values anonymous (`$`) +say $h; # OUTPUT: «3» + +my ($head, *@tail) = 1, 2, 3; # Yes, it's the same as with "slurpy subs" +my (*@small) = 1; + +sub unpack_array( @array [$fst, $snd] ) { + say "My first is $fst, my second is $snd! All in all, I'm @array[]."; + # (^ remember the `[]` to interpolate the array) +} +unpack_array(@tail); +# OUTPUT: «My first is 3, my second is 3! All in all, I'm 2 3.» + +# If you're not using the array itself, you can also keep it anonymous, +# much like a scalar: +sub first-of-array( @ [$fst] ) { $fst } +first-of-array(@small); #=> 1 + +# However calling `first-of-array(@tail);` will throw an error ("Too many +# positional parameters passed"), which means the `@tail` has too many +# elements. + +# You can also use a slurpy parameter. You could keep `*@rest` anonymous +# Here, `@rest` is `(3,)`, since `$fst` holds the `2`. This results +# since the length (.elems) of `@rest` is 1. +sub slurp-in-array(@ [$fst, *@rest]) { + say $fst + @rest.elems; +} +slurp-in-array(@tail); # OUTPUT: «3» + +# You could even extract on a slurpy (but it's pretty useless ;-).) +sub fst(*@ [$fst]) { # or simply: `sub fst($fst) { ... }` + say $fst; +} +fst(1); # OUTPUT: «1» + +# Calling `fst(1, 2);` will throw an error ("Too many positional parameters +# passed") though. After all, the `fst` sub declares only a single positional +# parameter. + +=begin comment +You can also destructure hashes (and classes, which you'll learn about later). +The syntax is basically the same as +`%hash-name (:key($variable-to-store-value-in))`. +The hash can stay anonymous if you only need the values you extracted. + +In order to call the function, you must supply a hash wither created with +curly braces or with `%()` (recommended). Alternatively, you can pass +a variable that contains a hash. +=end comment + +sub key-of( % (:value($val), :qua($qua)) ) { + say "Got value $val, $qua time" ~~ + $qua == 1 ?? '' !! 's'; +} + +my %foo-once = %(value => 'foo', qua => 1); +key-of({value => 'foo', qua => 2}); # OUTPUT: «Got val foo, 2 times.» +key-of(%(value => 'foo', qua => 0)); # OUTPUT: «Got val foo, 0 times.» +key-of(%foo-once); # OUTPUT: «Got val foo, 1 time.» + +# The last expression of a sub is returned automatically (though you may +# indicate explicitly by using the `return` keyword, of course): +sub next-index( $n ) { + $n + 1; +} +my $new-n = next-index(3); # $new-n is now 4 + +=begin comment +This is true for everything, except for the looping constructs (due to +performance reasons): there's no reason to build a list if we're just going to +discard all the results. If you still want to build one, you can use the +`do` statement prefix or the `gather` prefix, which we'll see later: +=end comment + +sub list-of( $n ) { + do for ^$n { $_ } +} +my @list3 = list-of(3); #=> (0, 1, 2) + +# +# 6.2 Lambdas (or anonymous subroutines) +# + +# You can create a lambda by using a pointy block (`-> {}`), a +# block (`{}`) or creating a `sub` without a name. + +my &lambda1 = -> $argument { + "The argument passed to this lambda is $argument" +} + +my &lambda2 = { + "The argument passed to this lambda is $_" +} + +my &lambda3 = sub ($argument) { + "The argument passed to this lambda is $argument" +} + +=begin comment +Both pointy blocks and blocks are pretty much the same thing, except that +the former can take arguments, and that the latter can be mistaken as +a hash by the parser. That being said, blocks can declare what's known +as placeholders parameters through the twigils `$^` (for positional +parameters) and `$:` (for named parameters). More on them latern on. +=end comment + +my &mult = { $^numbers * $:times } +say mult 4, :times(6); #=> «24» + +# Both pointy blocks and blocks are quite versatile when working with functions +# that accepts other functions such as `map`, `grep`, etc. For example, +# we add 3 to each value of an array using the `map` function with a lambda: +my @nums = 1..4; +my @res1 = map -> $v { $v + 3 }, @nums; # pointy block, explicit parameter +my @res2 = map { $_ + 3 }, @nums; # block using an implicit parameter +my @res3 = map { $^val + 3 }, @nums; # block with placeholder parameter + +=begin comment +A sub (`sub {}`) has different semantics than a block (`{}` or `-> {}`): +A block doesn't have a "function context" (though it can have arguments), +which means that if you return from it, you're going to return from the +parent function. +=end comment + +# Compare: +sub is-in( @array, $elem ) { + say map({ return True if $_ == $elem }, @array); + say 'Hi'; +} + +# with: +sub truthy-array( @array ) { + say map sub ($i) { $i ?? return True !! return False }, @array; + say 'Hi'; +} + +=begin comment +In the `is-in` sub, the block will `return` out of the `is-in` sub once the +condition evaluates to `True`, the loop won't be run anymore and the +following statement won't be executed. The last statement is only executed +if the block never returns. + +On the contrary, the `truthy-array` sub will produce an array of `True` and +`False`, which will printed, and always execute the last execute statement. +Thus, the `return` only returns from the anonymous `sub` +=end comment + +=begin comment +The `anon` declarator can be used to create an anonymous sub from a +regular subroutine. The regular sub knows its name but its symbol is +prevented from getting installed in the lexical scope, the method table +and everywhere else. +=end comment +my $anon-sum = anon sub summation(*@a) { [+] @a } +say $anon-sum.name; # OUTPUT: «summation» +say $anon-sum(2, 3, 5); # OUTPUT: «10» +#say summation; # Error: Undeclared routine: ... + +# You can also use the Whatever Star to create an anonymous subroutine. +# (it'll stop at the furthest operator in the current expression). +# The following is the same as `{$_ + 3 }`, `-> { $a + 3 }`, +# `sub ($a) { $a + 3 }`, or even `{$^a + 3}` (more on this later). +my @arrayplus3v0 = map * + 3, @nums; + +# The following is the same as `-> $a, $b { $a + $b + 3 }`, +# `sub ($a, $b) { $a + $b + 3 }`, or `{ $^a + $^b + 3 }` (more on this later). +my @arrayplus3v1 = map * + * + 3, @nums; + +say (*/2)(4); # OUTPUT: «2», immediately execute the Whatever function created. +say ((*+3)/5)(5); # OUTPUT: «1.6», it works even in parens! + +# But if you need to have more than one argument (`$_`) in a block (without +# wanting to resort to `-> {}`), you can also either `$^` and `$:` which +# declared placeholder parameters or self-declared positional/named parameters. +say map { $^a + $^b + 3 }, @nums; + +# which is equivalent to the following which uses a `sub`: +map sub ($a, $b) { $a + $b + 3 }, @nums; + +# Placeholder parameters are sorted lexicographically so the following two +# statements are equivalent: +say sort { $^b <=> $^a }, @nums; +say sort -> $a, $b { $b <=> $a }, @nums; + +# +# 6.3 Multiple Dispatch +# + +# Raku can decide which variant of a `sub` to call based on the type of the +# arguments, or on arbitrary preconditions, like with a type or `where`: + +# with types: +multi sub sayit( Int $n ) { # note the `multi` keyword here + say "Number: $n"; +} +multi sayit( Str $s ) { # a multi is a `sub` by default + say "String: $s"; +} +sayit "foo"; # OUTPUT: «String: foo» +sayit 25; # OUTPUT: «Number: 25» +sayit True; # fails at *compile time* with "calling 'sayit' will never + # work with arguments of types ..." + +# with arbitrary preconditions (remember subsets?): +multi is-big(Int $n where * > 50) { "Yes!" } # using a closure +multi is-big(Int $n where {$_ > 50}) { "Yes!" } # similar to above +multi is-big(Int $ where 10..50) { "Quite." } # Using smart-matching +multi is-big(Int $) { "No" } + +subset Even of Int where * %% 2; +multi odd-or-even(Even) { "Even" } # Using the type. We don't name the argument. +multi odd-or-even($) { "Odd" } # "everything else" hence the $ variable + +# You can even dispatch based on the presence of positional and named arguments: +multi with-or-without-you($with) { + say "I wish I could but I can't"; +} +multi with-or-without-you(:$with) { + say "I can live! Actually, I can't."; +} +multi with-or-without-you { + say "Definitely can't live."; +} + +=begin comment +This is very, very useful for many purposes, like `MAIN` subs (covered +later), and even the language itself uses it in several places. + +For example, the `is` trait is actually a `multi sub` named `trait_mod:<is>`, +and it works off that. Thus, `is rw`, is simply a dispatch to a function with +this signature `sub trait_mod:<is>(Routine $r, :$rw!) {}` +=end comment + +#################################################### +# 7. About types... +#################################################### + +=begin comment +Raku is gradually typed. This means you can specify the type of your +variables/arguments/return types, or you can omit the type annotations in +in which case they'll default to `Any`. Obviously you get access to a few +base types, like `Int` and `Str`. The constructs for declaring types are +`subset`, `class`, `role`, etc. which you'll see later. + +For now, let us examine `subset` which is a "sub-type" with additional +checks. For example, "a very big integer is an `Int` that's greater than 500". +You can specify the type you're subtyping (by default, `Any`), and add +additional checks with the `where` clause. +=end comment +subset VeryBigInteger of Int where * > 500; + +# Or the set of the whole numbers: +subset WholeNumber of Int where * >= 0; +my WholeNumber $whole-six = 6; # OK +#my WholeNumber $nonwhole-one = -1; # Error: type check failed... + +# Or the set of Positive Even Numbers whose Mod 5 is 1. Notice we're +# using the previously defined WholeNumber subset. +subset PENFO of WholeNumber where { $_ %% 2 and $_ mod 5 == 1 }; +my PENFO $yes-penfo = 36; # OK +#my PENFO $no-penfo = 2; # Error: type check failed... + +#################################################### +# 8. Scoping +#################################################### + +=begin comment +In Raku, unlike many scripting languages, (such as Python, Ruby, PHP), +you must declare your variables before using them. The `my` declarator +we've used so far uses "lexical scoping". There are a few other declarators, +(`our`, `state`, ..., ) which we'll see later. This is called +"lexical scoping", where in inner blocks, you can access variables from +outer blocks. +=end comment + +my $file_scoped = 'Foo'; +sub outer { + my $outer_scoped = 'Bar'; + sub inner { + say "$file_scoped $outer_scoped"; + } + &inner; # return the function +} +outer()(); # OUTPUT: «Foo Bar» + +# As you can see, `$file_scoped` and `$outer_scoped` were captured. +# But if we were to try and use `$outer_scoped` outside the `outer` sub, +# the variable would be undefined (and you'd get a compile time error). + +#################################################### +# 9. Twigils +#################################################### + +=begin comment +There are many special `twigils` (composed sigils) in Raku. Twigils +define a variable's scope. +The `*` and `?` twigils work on standard variables: + * for dynamic variables + ? for compile-time variables + +The `!` and the `.` twigils are used with Raku's objects: + ! for attributes (instance attribute) + . for methods (not really a variable) +=end comment + +# +# `*` twigil: Dynamic Scope +# + +# These variables use the `*` twigil to mark dynamically-scoped variables. +# Dynamically-scoped variables are looked up through the caller, not through +# the outer scope. + +my $*dyn_scoped_1 = 1; +my $*dyn_scoped_2 = 10; + +sub say_dyn { + say "$*dyn_scoped_1 $*dyn_scoped_2"; +} + +sub call_say_dyn { + # Defines $*dyn_scoped_1 only for this sub. + my $*dyn_scoped_1 = 25; + + # Will change the value of the file scoped variable. + $*dyn_scoped_2 = 100; + + # $*dyn_scoped 1 and 2 will be looked for in the call. + say_dyn(); # OUTPUT: «25 100» + + # The call to `say_dyn` uses the value of $*dyn_scoped_1 from inside + # this sub's lexical scope even though the blocks aren't nested (they're + # call-nested). +} +say_dyn(); # OUTPUT: «1 10» + +# Uses $*dyn_scoped_1 as defined in `call_say_dyn` even though we are calling it +# from outside. +call_say_dyn(); # OUTPUT: «25 100» + +# We changed the value of $*dyn_scoped_2 in `call_say_dyn` so now its +# value has changed. +say_dyn(); # OUTPUT: «1 100» + +# TODO: Add information about remaining twigils + +#################################################### +# 10. Object Model +#################################################### + +=begin comment +To call a method on an object, add a dot followed by the method name: +`$object.method` + +Classes are declared with the `class` keyword. Attributes are declared +with the `has` keyword, and methods declared with the `method` keyword. + +Every attribute that is private uses the `!` twigil. For example: `$!attr`. +Immutable public attributes use the `.` twigil which creates a read-only +method named after the attribute. In fact, declaring an attribute with `.` +is equivalent to declaring the same attribute with `!` and then creating +a read-only method with the attribute's name. However, this is done for us +by Raku automatically. The easiest way to remember the `$.` twigil is +by comparing it to how methods are called. + +Raku's object model ("SixModel") is very flexible, and allows you to +dynamically add methods, change semantics, etc... Unfortunately, these will +not all be covered here, and you should refer to: +https://docs.raku.org/language/objects.html. +=end comment + +class Human { + has Str $.name; # `$.name` is immutable but with an accessor method. + has Str $.bcountry; # Use `$!bcountry` to modify it inside the class. + has Str $.ccountry is rw; # This attribute can be modified from outside. + has Int $!age = 0; # A private attribute with default value. + + method birthday { + $!age += 1; # Add a year to human's age + } + + method get-age { + return $!age; + } + + # This method is private to the class. Note the `!` before the + # method's name. + method !do-decoration { + return "$!name born in $!bcountry and now lives in $!ccountry." + } + + # This method is public, just like `birthday` and `get-age`. + method get-info { + # Invoking a method on `self` inside the class. + # Use `self!priv-method` for private method. + say self!do-decoration; + + # Use `self.public-method` for public method. + say "Age: ", self.get-age; + } +}; + +# Create a new instance of Human class. +# NOTE: Only attributes declared with the `.` twigil can be set via the +# default constructor (more later on). This constructor only accepts named +# arguments. +my $person1 = Human.new( + name => "Jord", + bcountry => "Togo", + ccountry => "Togo" +); + +# Make human 10 years old. +$person1.birthday for 1..10; + +say $person1.name; # OUTPUT: «Jord» +say $person1.bcountry; # OUTPUT: «Togo» +say $person1.ccountry; # OUTPUT: «Togo» +say $person1.get-age; # OUTPUT: «10» + +# This fails, because the `has $.bcountry`is immutable. Jord can't change +# his birthplace. +# $person1.bcountry = "Mali"; + +# This works because the `$.ccountry` is mutable (`is rw`). Now Jord's +# current country is France. +$person1.ccountry = "France"; + +# Calling methods on the instance objects. +$person1.birthday; #=> 1 +$person1.get-info; #=> Jord born in Togo and now lives in France. Age: 10 +# $person1.do-decoration; # This fails since the method `do-decoration` is private. + +# +# 10.1 Object Inheritance +# + +=begin comment +Raku also has inheritance (along with multiple inheritance). While +methods are inherited, submethods are not. Submethods are useful for +object construction and destruction tasks, such as `BUILD`, or methods that +must be overridden by subtypes. We will learn about `BUILD` later on. +=end comment + +class Parent { + has $.age; + has $.name; + + # This submethod won't be inherited by the Child class. + submethod favorite-color { + say "My favorite color is Blue"; + } + + # This method is inherited + method talk { say "Hi, my name is $!name" } +} + +# Inheritance uses the `is` keyword +class Child is Parent { + method talk { say "Goo goo ga ga" } + # This shadows Parent's `talk` method. + # This child hasn't learned to speak yet! +} + +my Parent $Richard .= new(age => 40, name => 'Richard'); +$Richard.favorite-color; # OUTPUT: «My favorite color is Blue» +$Richard.talk; # OUTPUT: «Hi, my name is Richard» +# $Richard is able to access the submethod and he knows how to say his name. + +my Child $Madison .= new(age => 1, name => 'Madison'); +$Madison.talk; # OUTPUT: «Goo goo ga ga», due to the overridden method. +# $Madison.favorite-color # does not work since it is not inherited. + +=begin comment +When you use `my T $var`, `$var` starts off with `T` itself in it, so you can +call `new` on it. (`.=` is just the dot-call and the assignment operator). +Thus, `$a .= b` is the same as `$a = $a.b`. Also note that `BUILD` (the method +called inside `new`) will set parent's properties too, so you can pass `val => +5`. +=end comment + +# +# 10.2 Roles, or Mixins +# + +# Roles are supported too (which are called Mixins in other languages) +role PrintableVal { + has $!counter = 0; + method print { + say $.val; + } +} + +# you "apply" a role (or mixin) with the `does` keyword: +class Item does PrintableVal { + has $.val; + + =begin comment + When `does`-ed, a `role` literally "mixes in" the class: + the methods and attributes are put together, which means a class + can access the private attributes/methods of its roles (but + not the inverse!): + =end comment + method access { + say $!counter++; + } + + =begin comment + However, this: method print {} is ONLY valid when `print` isn't a `multi` + with the same dispatch. This means a parent class can shadow a child class's + `multi print() {}`, but it's an error if a role does) + + NOTE: You can use a role as a class (with `is ROLE`). In this case, + methods will be shadowed, since the compiler will consider `ROLE` + to be a class. + =end comment +} + +#################################################### +# 11. Exceptions +#################################################### + +=begin comment +Exceptions are built on top of classes, in the package `X` (like `X::IO`). +In Raku, exceptions are automatically 'thrown': + +open 'foo'; # OUTPUT: «Failed to open file foo: no such file or directory» + +It will also print out what line the error was thrown at +and other error info. +=end comment + +# You can throw an exception using `die`. Here it's been commented out to +# avoid stopping the program's execution: +# die 'Error!'; # OUTPUT: «Error!» + +# Or more explicitly (commented out too): +# X::AdHoc.new(payload => 'Error!').throw; # OUTPUT: «Error!» + +=begin comment +In Raku, `orelse` is similar to the `or` operator, except it only matches +undefined variables instead of anything evaluating as `False`. +Undefined values include: `Nil`, `Mu` and `Failure` as well as `Int`, `Str` +and other types that have not been initialized to any value yet. +You can check if something is defined or not using the defined method: +=end comment +my $uninitialized; +say $uninitialized.defined; # OUTPUT: «False» + +=begin comment +When using `orelse` it will disarm the exception and alias $_ to that +failure. This will prevent it to being automatically handled and printing +lots of scary error messages to the screen. We can use the `exception` +method on the `$_` variable to access the exception +=end comment +open 'foo' orelse say "Something happened {.exception}"; + +# This also works: +open 'foo' orelse say "Something happened $_"; +# OUTPUT: «Something happened Failed to open file foo: no such file or directory» + +=begin comment +Both of those above work but in case we get an object from the left side +that is not a failure we will probably get a warning. We see below how we +can use try` and `CATCH` to be more specific with the exceptions we catch. +=end comment + +# +# 11.1 Using `try` and `CATCH` +# + +=begin comment +By using `try` and `CATCH` you can contain and handle exceptions without +disrupting the rest of the program. The `try` block will set the last +exception to the special variable `$!` (known as the error variable). +NOTE: This has no relation to $!variables seen inside class definitions. +=end comment + +try open 'foo'; +say "Well, I tried! $!" if defined $!; +# OUTPUT: «Well, I tried! Failed to open file foo: no such file or directory» + +=begin comment +Now, what if we want more control over handling the exception? +Unlike many other languages, in Raku, you put the `CATCH` block *within* +the block to `try`. Similar to how the `$_` variable was set when we +'disarmed' the exception with `orelse`, we also use `$_` in the CATCH block. +NOTE: The `$!` variable is only set *after* the `try` block has caught an +exception. By default, a `try` block has a `CATCH` block of its own that +catches any exception (`CATCH { default {} }`). +=end comment + +try { + my $a = (0 %% 0); + CATCH { + default { say "Something happened: $_" } + } +} +# OUTPUT: «Something happened: Attempt to divide by zero using infix:<%%>» + +# You can redefine it using `when`s (and `default`) to handle the exceptions +# you want to catch explicitly: + +try { + open 'foo'; + CATCH { + # In the `CATCH` block, the exception is set to the $_ variable. + when X::AdHoc { + say "Error: $_" + } + when X::Numeric::DivideByZero { + say "Error: $_"; + } + + =begin comment + Any other exceptions will be re-raised, since we don't have a `default`. + Basically, if a `when` matches (or there's a `default`), the + exception is marked as "handled" so as to prevent its re-throw + from the `CATCH` block. You still can re-throw the exception + (see below) by hand. + =end comment + default { + say "Any other error: $_" + } + } +} +# OUTPUT: «Failed to open file /dir/foo: no such file or directory» + +=begin comment +There are also some subtleties to exceptions. Some Raku subs return a +`Failure`, which is a wrapper around an `Exception` object which is +"unthrown". They're not thrown until you try to use the variables containing +them unless you call `.Bool`/`.defined` on them - then they're handled. +(the `.handled` method is `rw`, so you can mark it as `False` back yourself) +You can throw a `Failure` using `fail`. Note that if the pragma `use fatal` +is on, `fail` will throw an exception (like `die`). +=end comment + +my $value = 0/0; # We're not trying to access the value, so no problem. +try { + say 'Value: ', $value; # Trying to use the value + CATCH { + default { + say "It threw because we tried to get the fail's value!" + } + } +} + +=begin comment +There is also another kind of exception: Control exceptions. Those are "good" +exceptions, which happen when you change your program's flow, using operators +like `return`, `next` or `last`. You can "catch" those with `CONTROL` (not 100% +working in Rakudo yet). +=end comment + +#################################################### +# 12. Packages +#################################################### + +=begin comment +Packages are a way to reuse code. Packages are like "namespaces", and any +element of the six model (`module`, `role`, `class`, `grammar`, `subset` and +`enum`) are actually packages. (Packages are the lowest common denominator) +Packages are important - especially as Perl is well-known for CPAN, +the Comprehensive Perl Archive Network. +=end comment + +# You can use a module (bring its declarations into scope) with `use`: +use JSON::Tiny; # if you installed Rakudo* or Panda, you'll have this module +say from-json('[1]').perl; # OUTPUT: «[1]» + +=begin comment +You should not declare packages using the `package` keyword (unlike Perl 5). +Instead, use `class Package::Name::Here;` to declare a class, or if you only +want to export variables/subs, you can use `module` instead. +=end comment + +# If `Hello` doesn't exist yet, it'll just be a "stub", that can be redeclared +# as something else later. +module Hello::World { # bracketed form + # declarations here +} + +# The file-scoped form which extends until the end of the file. For +# instance, `unit module Parse::Text;` will extend until of the file. + +# A grammar is a package, which you could `use`. You will learn more about +# grammars in the regex section. +grammar Parse::Text::Grammar { +} + +# As said before, any part of the six model is also a package. +# Since `JSON::Tiny` uses its own `JSON::Tiny::Actions` class, you can use it: +my $actions = JSON::Tiny::Actions.new; + +# We'll see how to export variables and subs in the next part. + +#################################################### +# 13. Declarators +#################################################### + +=begin comment +In Raku, you get different behaviors based on how you declare a variable. +You've already seen `my` and `has`, we'll now explore the others. + +`our` - these declarations happen at `INIT` time -- (see "Phasers" below). +It's like `my`, but it also creates a package variable. All packagish +things such as `class`, `role`, etc. are `our` by default. +=end comment + +module Var::Increment { + # NOTE: `our`-declared variables cannot be typed. + our $our-var = 1; + my $my-var = 22; + + our sub Inc { + our sub available { # If you try to make inner `sub`s `our`... + # ... Better know what you're doing (Don't !). + say "Don't do that. Seriously. You'll get burned."; + } + + my sub unavailable { # `sub`s are `my`-declared by default + say "Can't access me from outside, I'm 'my'!"; + } + say ++$our-var; # Increment the package variable and output its value + } + +} + +say $Var::Increment::our-var; # OUTPUT: «1», this works! +say $Var::Increment::my-var; # OUTPUT: «(Any)», this will not work! + +say Var::Increment::Inc; # OUTPUT: «2» +say Var::Increment::Inc; # OUTPUT: «3», notice how the value of $our-var was retained. + +# Var::Increment::unavailable; # OUTPUT: «Could not find symbol '&unavailable'» + +# `constant` - these declarations happen at `BEGIN` time. You can use +# the `constant` keyword to declare a compile-time variable/symbol: +constant Pi = 3.14; +constant $var = 1; + +# And if you're wondering, yes, it can also contain infinite lists. +constant why-not = 5, 15 ... *; +say why-not[^5]; # OUTPUT: «5 15 25 35 45» + +# `state` - these declarations happen at run time, but only once. State +# variables are only initialized one time. In other languages such as C +# they exist as `static` variables. +sub fixed-rand { + state $val = rand; + say $val; +} +fixed-rand for ^10; # will print the same number 10 times + +# Note, however, that they exist separately in different enclosing contexts. +# If you declare a function with a `state` within a loop, it'll re-create the +# variable for each iteration of the loop. See: +for ^5 -> $a { + sub foo { + # This will be a different value for every value of `$a` + state $val = rand; + } + for ^5 -> $b { + # This will print the same value 5 times, but only 5. Next iteration + # will re-run `rand`. + say foo; + } +} + +#################################################### +# 14. Phasers +#################################################### + +=begin comment +Phasers in Raku are blocks that happen at determined points of time in +your program. They are called phasers because they mark a change in the +phase of a program. For example, when the program is compiled, a for loop +runs, you leave a block, or an exception gets thrown (The `CATCH` block is +actually a phaser!). Some of them can be used for their return values, +some of them can't (those that can have a "[*]" in the beginning of their +explanation text). Let's have a look! +=end comment + +# +# 14.1 Compile-time phasers +# +BEGIN { say "[*] Runs at compile time, as soon as possible, only once" } +CHECK { say "[*] Runs at compile time, as late as possible, only once" } + +# +# 14.2 Run-time phasers +# +INIT { say "[*] Runs at run time, as soon as possible, only once" } +END { say "Runs at run time, as late as possible, only once" } + +# +# 14.3 Block phasers +# +ENTER { say "[*] Runs everytime you enter a block, repeats on loop blocks" } +LEAVE { + say "Runs everytime you leave a block, even when an exception + happened. Repeats on loop blocks." +} + +PRE { + say "Asserts a precondition at every block entry, + before ENTER (especially useful for loops)"; + say "If this block doesn't return a truthy value, + an exception of type X::Phaser::PrePost is thrown."; +} + +# Example (commented out): +for 0..2 { + # PRE { $_ > 1 } # OUTPUT: «Precondition '{ $_ > 1 }' failed +} + +POST { + say "Asserts a postcondition at every block exit, + after LEAVE (especially useful for loops)"; + say "If this block doesn't return a truthy value, + an exception of type X::Phaser::PrePost is thrown, like PRE."; +} + +# Example (commented out): +for 0..2 { + # POST { $_ < 1 } # OUTPUT: «Postcondition '{ $_ < 1 }' failed +} + +# +# 14.4 Block/exceptions phasers +# +{ + KEEP { say "Runs when you exit a block successfully + (without throwing an exception)" } + UNDO { say "Runs when you exit a block unsuccessfully + (by throwing an exception)" } +} + +# +# 14.5 Loop phasers +# +for ^5 { + FIRST { say "[*] The first time the loop is run, before ENTER" } + NEXT { say "At loop continuation time, before LEAVE" } + LAST { say "At loop termination time, after LEAVE" } +} + +# +# 14.6 Role/class phasers +# +COMPOSE { + say "When a role is composed into a class. /!\ NOT YET IMPLEMENTED" +} + +# They allow for cute tricks or clever code...: +say "This code took " ~ (time - CHECK time) ~ "s to compile"; + +# ... or clever organization: +class DB { + method start-transaction { say "Starting transation!" } + method commit { say "Commiting transaction..." } + method rollback { say "Something went wrong. Rollingback!" } +} + +sub do-db-stuff { + my DB $db .= new; + $db.start-transaction; # start a new transaction + KEEP $db.commit; # commit the transaction if all went well + UNDO $db.rollback; # or rollback if all hell broke loose +} + +do-db-stuff(); + +#################################################### +# 15. Statement prefixes +#################################################### + +=begin comment +Those act a bit like phasers: they affect the behavior of the following +code. Though, they run in-line with the executable code, so they're in +lowercase. (`try` and `start` are theoretically in that list, but explained +elsewhere) NOTE: all of these (except start) don't need explicit curly +braces `{` and `}`. + +=end comment + +# +# 15.1 `do` - It runs a block or a statement as a term. +# + +# Normally you cannot use a statement as a value (or "term"). `do` helps +# us do it. With `do`, an `if`, for example, becomes a term returning a value. +=for comment :reason<this fails since `if` is a statement> +my $value = if True { 1 } + +# this works! +my $get-five = do if True { 5 } + +# +# 15.1 `once` - makes sure a piece of code only runs once. +# +for ^5 { + once say 1 +}; +# OUTPUT: «1», only prints ... once + +# Similar to `state`, they're cloned per-scope. +for ^5 { + sub { once say 1 }() +}; +# OUTPUT: «1 1 1 1 1», prints once per lexical scope. + +# +# 15.2 `gather` - co-routine thread. +# + +# The `gather` constructs allows us to `take` several values from an array/list, +# much like `do`. +say gather for ^5 { + take $_ * 3 - 1; + take $_ * 3 + 1; +} +# OUTPUT: «-1 1 2 4 5 7 8 10 11 13» + +say join ',', gather if False { + take 1; + take 2; + take 3; +} +# Doesn't print anything. + +# +# 15.3 `eager` - evaluates a statement eagerly (forces eager context). + +# Don't try this at home. This will probably hang for a while (and might crash) +# so commented out. +# eager 1..*; + +# But consider, this version which doesn't print anything +constant thricev0 = gather for ^3 { say take $_ }; +# to: +constant thricev1 = eager gather for ^3 { say take $_ }; # OUTPUT: «0 1 2» + +#################################################### +# 16. Iterables +#################################################### + +# Iterables are objects that can be iterated over for things such as +# the `for` construct. + +# +# 16.1 `flat` - flattens iterables. +# +say (1, 10, (20, 10) ); # OUTPUT: «(1 10 (20 10))», notice how nested + # lists are preserved +say (1, 10, (20, 10) ).flat; # OUTPUT: «(1 10 20 10)», now the iterable is flat + +# +# 16.2 `lazy` - defers actual evaluation until value is fetched by forcing lazy context. +# +my @lazy-array = (1..100).lazy; +say @lazy-array.is-lazy; # OUTPUT: «True», check for laziness with the `is-lazy` method. + +say @lazy-array; # OUTPUT: «[...]», List has not been iterated on! + +# This works and will only do as much work as is needed. +for @lazy-array { .print }; + +# (**TODO** explain that gather/take and map are all lazy) + +# +# 16.3 `sink` - an `eager` that discards the results by forcing sink context. +# +constant nilthingie = sink for ^3 { .say } #=> 0 1 2 +say nilthingie.perl; # OUTPUT: «Nil» + +# +# 16.4 `quietly` - suppresses warnings in blocks. +# +quietly { warn 'This is a warning!' }; # No output + +#################################################### +# 17. More operators thingies! +#################################################### + +# Everybody loves operators! Let's get more of them. + +# The precedence list can be found here: +# https://docs.raku.org/language/operators#Operator_Precedence +# But first, we need a little explanation about associativity: + +# +# 17.1 Binary operators +# + +my ($p, $q, $r) = (1, 2, 3); + +=begin comment +Given some binary operator § (not a Raku-supported operator), then: + +$p § $q § $r; # with a left-associative §, this is ($p § $q) § $r +$p § $q § $r; # with a right-associative §, this is $p § ($q § $r) +$p § $q § $r; # with a non-associative §, this is illegal +$p § $q § $r; # with a chain-associative §, this is ($p § $q) and ($q § $r)§ +$p § $q § $r; # with a list-associative §, this is `infix:<>` +=end comment + +# +# 17.2 Unary operators +# + +=begin comment +Given some unary operator § (not a Raku-supported operator), then: +§$p§ # with left-associative §, this is (§$p)§ +§$p§ # with right-associative §, this is §($p§) +§$p§ # with non-associative §, this is illegal +=end comment + +# +# 17.3 Create your own operators! +# + +=begin comment +Okay, you've been reading all of that, so you might want to try something +more exciting?! I'll tell you a little secret (or not-so-secret): +In Raku, all operators are actually just funny-looking subroutines. + +You can declare an operator just like you declare a sub. In the following +example, `prefix` refers to the operator categories (prefix, infix, postfix, +circumfix, and post-circumfix). +=end comment +sub prefix:<win>( $winner ) { + say "$winner Won!"; +} +win "The King"; # OUTPUT: «The King Won!» + +# you can still call the sub with its "full name": +say prefix:<!>(True); # OUTPUT: «False» +prefix:<win>("The Queen"); # OUTPUT: «The Queen Won!» + +sub postfix:<!>( Int $n ) { + [*] 2..$n; # using the reduce meta-operator... See below ;-)! +} +say 5!; # OUTPUT: «120» + +# Postfix operators ('after') have to come *directly* after the term. +# No whitespace. You can use parentheses to disambiguate, i.e. `(5!)!` + +sub infix:<times>( Int $n, Block $r ) { # infix ('between') + for ^$n { + # You need the explicit parentheses to call the function in `$r`, + # else you'd be referring at the code object itself, like with `&r`. + $r(); + } +} +3 times -> { say "hello" }; # OUTPUT: «hellohellohello» + +# It's recommended to put spaces around your infix operator calls. + +# For circumfix and post-circumfix ones +multi circumfix:<[ ]>( Int $n ) { + $n ** $n +} +say [5]; # OUTPUT: «3125» + +# Circumfix means 'around'. Again, no whitespace. + +multi postcircumfix:<{ }>( Str $s, Int $idx ) { + $s.substr($idx, 1); +} +say "abc"{1}; # OUTPUT: «b», after the term `"abc"`, and around the index (1) + +# Post-circumfix is 'after a term, around something' + +=begin comment +This really means a lot -- because everything in Raku uses this. +For example, to delete a key from a hash, you use the `:delete` adverb +(a simple named argument underneath). For instance, the following statements +are equivalent. +=end comment +my %person-stans = + 'Giorno Giovanna' => 'Gold Experience', + 'Bruno Bucciarati' => 'Sticky Fingers'; +my $key = 'Bruno Bucciarati'; +%person-stans{$key}:delete; +postcircumfix:<{ }>( %person-stans, 'Giorno Giovanna', :delete ); +# (you can call operators like this) + +=begin comment +It's *all* using the same building blocks! Syntactic categories +(prefix infix ...), named arguments (adverbs), ..., etc. used to build +the language - are available to you. Obviously, you're advised against +making an operator out of *everything* -- with great power comes great +responsibility. +=end comment + +# +# 17.4 Meta operators! +# + +=begin comment +Oh boy, get ready!. Get ready, because we're delving deep into the rabbit's +hole, and you probably won't want to go back to other languages after +reading this. (I'm guessing you don't want to go back at this point but +let's continue, for the journey is long and enjoyable!). + +Meta-operators, as their name suggests, are *composed* operators. Basically, +they're operators that act on another operators. + +The reduce meta-operator is a prefix meta-operator that takes a binary +function and one or many lists. If it doesn't get passed any argument, +it either returns a "default value" for this operator (a meaningless value) +or `Any` if there's none (examples below). Otherwise, it pops an element +from the list(s) one at a time, and applies the binary function to the last +result (or the first element of a list) and the popped element. +=end comment + +# To sum a list, you could use the reduce meta-operator with `+`, i.e.: +say [+] 1, 2, 3; # OUTPUT: «6», equivalent to (1+2)+3. + +# To multiply a list +say [*] 1..5; # OUTPUT: «120», equivalent to ((((1*2)*3)*4)*5). + +# You can reduce with any operator, not just with mathematical ones. +# For example, you could reduce with `//` to get first defined element +# of a list: +say [//] Nil, Any, False, 1, 5; # OUTPUT: «False» + # (Falsey, but still defined) +# Or with relational operators, i.e., `>` to check elements of a list +# are ordered accordingly: +say [>] 234, 156, 6, 3, -20; # OUTPUT: «True» + +# Default value examples: +say [*] (); # OUTPUT: «1», empty product +say [+] (); # OUTPUT: «0», empty sum +say [//]; # OUTPUT: «(Any)» + # There's no "default value" for `//`. + +# You can also use it with a function you made up, +# You can also surround using double brackets: +sub add($a, $b) { $a + $b } +say [[&add]] 1, 2, 3; # OUTPUT: «6» + +=begin comment +The zip meta-operator is an infix meta-operator that also can be used as a +"normal" operator. It takes an optional binary function (by default, it +just creates a pair), and will pop one value off of each array and call +its binary function on these until it runs out of elements. It returns an +array with all of these new elements. +=end comment +say (1, 2) Z (3, 4); # OUTPUT: «((1, 3), (2, 4))» +say 1..3 Z+ 4..6; # OUTPUT: «(5, 7, 9)» + +# Since `Z` is list-associative (see the list above), you can use it on more +# than one list. +(True, False) Z|| (False, False) Z|| (False, False); # (True, False) + +# And, as it turns out, you can also use the reduce meta-operator with it: +[Z||] (True, False), (False, False), (False, False); # (True, False) + +# And to end the operator list: + +=begin comment +The sequence operator (`...`) is one of Raku's most powerful features: +It's composed by the list (which might include a closure) you want Raku to +deduce from on the left and a value (or either a predicate or a Whatever Star +for a lazy infinite list) on the right that states when to stop. +=end comment + +# Basic arithmetic sequence +my @listv0 = 1, 2, 3...10; + +# This dies because Raku can't figure out the end +# my @list = 1, 3, 6...10; + +# As with ranges, you can exclude the last element (the iteration ends when +# the predicate matches). +my @listv1 = 1, 2, 3...^10; + +# You can use a predicate (with the Whatever Star). +my @listv2 = 1, 3, 9...* > 30; + +# Equivalent to the example above but using a block here. +my @listv3 = 1, 3, 9 ... { $_ > 30 }; + +# Lazy infinite list of fibonacci sequence, computed using a closure! +my @fibv0 = 1, 1, *+* ... *; + +# Equivalent to the above example but using a pointy block. +my @fibv1 = 1, 1, -> $a, $b { $a + $b } ... *; + +# Equivalent to the above example but using a block with placeholder parameters. +my @fibv2 = 1, 1, { $^a + $^b } ... *; + +=begin comment +In the examples with explicit parameters (i.e., $a and $b), $a and $b +will always take the previous values, meaning that for the Fibonacci sequence, +they'll start with $a = 1 and $b = 1 (values we set by hand), then $a = 1 +and $b = 2 (result from previous $a + $b), and so on. +=end comment + +=begin comment +# In the example we use a range as an index to access the sequence. However, +# it's worth noting that for ranges, once reified, elements aren't re-calculated. +# That's why, for instance, `@primes[^100]` will take a long time the first +# time you print it but then it will be instateneous. +=end comment +say @fibv0[^10]; # OUTPUT: «1 1 2 3 5 8 13 21 34 55» + +#################################################### +# 18. Regular Expressions +#################################################### + +=begin comment +I'm sure a lot of you have been waiting for this one. Well, now that you know +a good deal of Raku already, we can get started. First off, you'll have to +forget about "PCRE regexps" (perl-compatible regexps). + +IMPORTANT: Don't skip them because you know PCRE. They're different. Some +things are the same (like `?`, `+`, and `*`), but sometimes the semantics +change (`|`). Make sure you read carefully, because you might trip over a +new behavior. + +Raku has many features related to RegExps. After all, Rakudo parses itself. +We're first going to look at the syntax itself, then talk about grammars +(PEG-like), differences between `token`, `regex` and `rule` declarators, +and some more. Side note: you still have access to PCRE regexps using the +`:P5` modifier which we won't be discussing this in this tutorial, though. + +In essence, Raku natively implements PEG ("Parsing Expression Grammars"). +The pecking order for ambiguous parses is determined by a multi-level +tie-breaking test: + - Longest token matching: `foo\s+` beats `foo` (by 2 or more positions) + - Longest literal prefix: `food\w*` beats `foo\w*` (by 1) + - Declaration from most-derived to less derived grammars + (grammars are actually classes) + - Earliest declaration wins +=end comment +say so 'a' ~~ /a/; # OUTPUT: «True» +say so 'a' ~~ / a /; # OUTPUT: «True», more readable with some spaces! + +=begin comment +In all our examples, we're going to use the smart-matching operator against +a regexp. We're converting the result using `so` to a Boolean value because, +in fact, it's returning a `Match` object. They know how to respond to list +indexing, hash indexing, and return the matched string. The results of the +match are available in the `$/` variable (implicitly lexically-scoped). You +can also use the capture variables which start at 0: `$0`, `$1', `$2`... + +You can also note that `~~` does not perform start/end checking, meaning +the regexp can be matched with just one character of the string. We'll +explain later how you can do it. + +In Raku, you can have any alphanumeric as a literal, everything else has +to be escaped by using a backslash or quotes. +=end comment +say so 'a|b' ~~ / a '|' b /; # OUTPUT: «True», it wouldn't mean the same + # thing if `|` wasn't escaped. +say so 'a|b' ~~ / a \| b /; # OUTPUT: «True», another way to escape it. + +# The whitespace in a regex is actually not significant, unless you use the +# `:s` (`:sigspace`, significant space) adverb. +say so 'a b c' ~~ / a b c /; #=> `False`, space is not significant here! +say so 'a b c' ~~ /:s a b c /; #=> `True`, we added the modifier `:s` here. + +# If we use only one space between strings in a regex, Raku will warn us +# about space being not signicant in the regex: +say so 'a b c' ~~ / a b c /; # OUTPUT: «False» +say so 'a b c' ~~ / a b c /; # OUTPUT: «False» + +=begin comment +NOTE: Please use quotes or `:s` (`:sigspace`) modifier (or, to suppress this +warning, omit the space, or otherwise change the spacing). To fix this and make +the spaces less ambiguous, either use at least two spaces between strings +or use the `:s` adverb. +=end comment + +# As we saw before, we can embed the `:s` inside the slash delimiters, but we +# can also put it outside of them if we specify `m` for 'match': +say so 'a b c' ~~ m:s/a b c/; # OUTPUT: «True» + +# By using `m` to specify 'match', we can also use other delimiters: +say so 'abc' ~~ m{a b c}; # OUTPUT: «True» +say so 'abc' ~~ m[a b c]; # OUTPUT: «True» + +# `m/.../` is equivalent to `/.../`: +say 'raku' ~~ m/raku/; # OUTPUT: «True» +say 'raku' ~~ /raku/; # OUTPUT: «True» + +# Use the `:i` adverb to specify case insensitivity: +say so 'ABC' ~~ m:i{a b c}; # OUTPUT: «True» + +# However, whitespace is important as for how modifiers are applied +# (which you'll see just below) ... + +# +# 18.1 Quantifiers - `?`, `+`, `*` and `**`. +# + +# `?` - zero or one match +say so 'ac' ~~ / a b c /; # OUTPUT: «False» +say so 'ac' ~~ / a b? c /; # OUTPUT: «True», the "b" matched 0 times. +say so 'abc' ~~ / a b? c /; # OUTPUT: «True», the "b" matched 1 time. + +# ... As you read before, whitespace is important because it determines which +# part of the regex is the target of the modifier: +say so 'def' ~~ / a b c? /; # OUTPUT: «False», only the "c" is optional +say so 'def' ~~ / a b? c /; # OUTPUT: «False», whitespace is not significant +say so 'def' ~~ / 'abc'? /; # OUTPUT: «True», the whole "abc" group is optional + +# Here (and below) the quantifier applies only to the "b" + +# `+` - one or more matches +say so 'ac' ~~ / a b+ c /; # OUTPUT: «False», `+` wants at least one 'b' +say so 'abc' ~~ / a b+ c /; # OUTPUT: «True», one is enough +say so 'abbbbc' ~~ / a b+ c /; # OUTPUT: «True», matched 4 "b"s + +# `*` - zero or more matches +say so 'ac' ~~ / a b* c /; # OUTPU: «True», they're all optional +say so 'abc' ~~ / a b* c /; # OUTPU: «True» +say so 'abbbbc' ~~ / a b* c /; # OUTPU: «True» +say so 'aec' ~~ / a b* c /; # OUTPU: «False», "b"(s) are optional, not replaceable. + +# `**` - (Unbound) Quantifier +# If you squint hard enough, you might understand why exponentation is used +# for quantity. +say so 'abc' ~~ / a b**1 c /; # OUTPU: «True», exactly one time +say so 'abc' ~~ / a b**1..3 c /; # OUTPU: «True», one to three times +say so 'abbbc' ~~ / a b**1..3 c /; # OUTPU: «True» +say so 'abbbbbbc' ~~ / a b**1..3 c /; # OUTPU: «Fals», too much +say so 'abbbbbbc' ~~ / a b**3..* c /; # OUTPU: «True», infinite ranges are ok + +# +# 18.2 `<[]>` - Character classes +# + +# Character classes are the equivalent of PCRE's `[]` classes, but they use a +# more raku-ish syntax: +say 'fooa' ~~ / f <[ o a ]>+ /; # OUTPUT: «fooa» + +# You can use ranges (`..`): +say 'aeiou' ~~ / a <[ e..w ]> /; # OUTPUT: «ae» + +# Just like in normal regexes, if you want to use a special character, escape +# it (the last one is escaping a space which would be equivalent to using +# ' '): +say 'he-he !' ~~ / 'he-' <[ a..z \! \ ]> + /; # OUTPUT: «he-he !» + +# You'll get a warning if you put duplicate names (which has the nice effect +# of catching the raw quoting): +'he he' ~~ / <[ h e ' ' ]> /; +# Warns "Repeated character (') unexpectedly found in character class" + +# You can also negate character classes... (`<-[]>` equivalent to `[^]` in PCRE) +say so 'foo' ~~ / <-[ f o ]> + /; # OUTPUT: «False» + +# ... and compose them: +# any letter except "f" and "o" +say so 'foo' ~~ / <[ a..z ] - [ f o ]> + /; # OUTPUT: «False» + +# no letter except "f" and "o" +say so 'foo' ~~ / <-[ a..z ] + [ f o ]> + /; # OUTPUT: «True» + +# the + doesn't replace the left part +say so 'foo!' ~~ / <-[ a..z ] + [ f o ]> + /; # OUTPUT: «True» + +# +# 18.3 Grouping and capturing +# + +# Group: you can group parts of your regexp with `[]`. Unlike PCRE's `(?:)`, +# these groups are *not* captured. +say so 'abc' ~~ / a [ b ] c /; # OUTPUT: «True», the grouping does nothing +say so 'foo012012bar' ~~ / foo [ '01' <[0..9]> ] + bar /; # OUTPUT: «True» + +# The previous line returns `True`. The regex matches "012" one or more time +# (achieved by the the `+` applied to the group). + +# But this does not go far enough, because we can't actually get back what +# we matched. + +# Capture: The results of a regexp can be *captured* by using parentheses. +say so 'fooABCABCbar' ~~ / foo ( 'A' <[A..Z]> 'C' ) + bar /; # OUTPUT: «True» +# (using `so` here, see `$/` below) + +# So, starting with the grouping explanations. As we said before, our `Match` +# object is stored inside the `$/` variable: +say $/; # Will either print the matched object or `Nil` if nothing matched. + +# As we also said before, it has array indexing: +say $/[0]; # OUTPUT: «｢ABC｣ ｢ABC｣», + +# The corner brackets (｢..｣) represent (and are) `Match` objects. In the +# previous example, we have an array of them. + +say $0; # The same as above. + +=begin comment +Our capture is `$0` because it's the first and only one capture in the +regexp. You might be wondering why it's an array, and the answer is simple: +Some captures (indexed using `$0`, `$/[0]` or a named one) will be an array +if and only if they can have more than one element. Thus any capture with +`*`, `+` and `**` (whatever the operands), but not with `?`. +Let's use examples to see that: + +NOTE: We quoted A B C to demonstrate that the whitespace between them isn't +significant. If we want the whitespace to *be* significant there, we can use the +`:sigspace` modifier. +=end comment +say so 'fooABCbar' ~~ / foo ( "A" "B" "C" )? bar /; # OUTPUT: «True» +say $/[0]; # OUTPUT: «｢ABC｣» +say $0.WHAT; # OUTPUT: «(Match)» + # There can't be more than one, so it's only a single match object. + +say so 'foobar' ~~ / foo ( "A" "B" "C" )? bar /; # OUTPUT: «True» +say $0.WHAT; # OUTPUT: «(Any)», this capture did not match, so it's empty. + +say so 'foobar' ~~ / foo ( "A" "B" "C" ) ** 0..1 bar /; #=> OUTPUT: «True» +say $0.WHAT; # OUTPUT: «(Array)», A specific quantifier will always capture + # an Array, be a range or a specific value (even 1). + +# The captures are indexed per nesting. This means a group in a group will be +# nested under its parent group: `$/[0][0]`, for this code: +'hello-~-world' ~~ / ( 'hello' ( <[ \- \~ ]> + ) ) 'world' /; +say $/[0].Str; # OUTPUT: «hello~» +say $/[0][0].Str; # OUTPUT: «~» + +=begin comment +This stems from a very simple fact: `$/` does not contain strings, integers +or arrays, it only contains `Match` objects. These contain the `.list`, `.hash` +and `.Str` methods but you can also just use `match<key>` for hash access +and `match[idx]` for array access. + +In the following example, we can see `$_` is a list of `Match` objects. +Each of them contain a wealth of information: where the match started/ended, +the "ast" (see actions later), etc. You'll see named capture below with +grammars. +=end comment +say $/[0].list.perl; # OUTPUT: «(Match.new(...),).list» + +# Alternation - the `or` of regexes +# WARNING: They are DIFFERENT from PCRE regexps. +say so 'abc' ~~ / a [ b | y ] c /; # OUTPU: «True», Either "b" or "y". +say so 'ayc' ~~ / a [ b | y ] c /; # OUTPU: «True», Obviously enough... + +# The difference between this `|` and the one you're used to is +# LTM ("Longest Token Matching") strategy. This means that the engine will +# always try to match as much as possible in the string. +say 'foo' ~~ / fo | foo /; # OUTPUT: «foo», instead of `fo`, because it's longer. + +=begin comment +To decide which part is the "longest", it first splits the regex in two parts: + + * The "declarative prefix" (the part that can be statically analyzed) + which includes alternations (`|`), conjunctions (`&`), sub-rule calls (not + yet introduced), literals, characters classes and quantifiers. + + * The "procedural part" includes everything else: back-references, + code assertions, and other things that can't traditionnaly be represented + by normal regexps. + +Then, all the alternatives are tried at once, and the longest wins. +=end comment + +# Examples: +# DECLARATIVE | PROCEDURAL +/ 'foo' \d+ [ <subrule1> || <subrule2> ] /; + +# DECLARATIVE (nested groups are not a problem) +/ \s* [ \w & b ] [ c | d ] /; + +# However, closures and recursion (of named regexes) are procedural. +# There are also more complicated rules, like specificity (literals win +# over character classes). + +# NOTE: The alternation in which all the branches are tried in order +# until the first one matches still exists, but is now spelled `||`. +say 'foo' ~~ / fo || foo /; # OUTPUT: «fo», in this case. + +#################################################### +# 19. Extra: the MAIN subroutine +#################################################### + +=begin comment +The `MAIN` subroutine is called when you run a Raku file directly. It's +very powerful, because Raku actually parses the arguments and pass them +as such to the sub. It also handles named argument (`--foo`) and will even +go as far as to autogenerate a `--help` flag. +=end comment + +sub MAIN($name) { + say "Hello, $name!"; +} +=begin comment +Supposing the code above is in file named cli.raku, then running in the command +line (e.g., $ raku cli.raku) produces: +Usage: + cli.raku <name> +=end comment + +=begin comment +And since MAIN is a regular Raku sub, you can have multi-dispatch: +(using a `Bool` for the named argument so that we can do `--replace` +instead of `--replace=1`. The presence of `--replace` indicates truthness +while its absence falseness). For example: + + # convert to IO object to check the file exists + subset File of Str where *.IO.d; + + multi MAIN('add', $key, $value, Bool :$replace) { ... } + multi MAIN('remove', $key) { ... } + multi MAIN('import', File, Str :$as) { ... } # omitting parameter name + +Thus $ raku cli.raku produces: +Usage: + cli.raku [--replace] add <key> <value> + cli.raku remove <key> + cli.raku [--as=<Str>] import <File> + +As you can see, this is *very* powerful. It even went as far as to show inline +the constants (the type is only displayed if the argument is `$`/is named). +=end comment + +#################################################### +# 20. APPENDIX A: +#################################################### + +=begin comment +It's assumed by now you know the Raku basics. This section is just here to +list some common operations, but which are not in the "main part" of the +tutorial to avoid bloating it up. +=end comment + +# +# 20.1 Operators +# + +# Sort comparison - they return one value of the `Order` enum: `Less`, `Same` +# and `More` (which numerify to -1, 0 or +1 respectively). +say 1 <=> 4; # OUTPUT: «More», sort comparison for numerics +say 'a' leg 'b'; # OUTPUT: «Lessre», sort comparison for string +say 1 eqv 1; # OUTPUT: «Truere», sort comparison using eqv semantics +say 1 eqv 1.0; # OUTPUT: «False» + +# Generic ordering +say 3 before 4; # OUTPUT: «True» +say 'b' after 'a'; # OUTPUT: «True» + +# Short-circuit default operator - similar to `or` and `||`, but instead +# returns the first *defined* value: +say Any // Nil // 0 // 5; # OUTPUT: «0» + +# Short-circuit exclusive or (XOR) - returns `True` if one (and only one) of +# its arguments is true +say True ^^ False; # OUTPUT: «True» + +=begin comment +Flip flops. These operators (`ff` and `fff`, equivalent to P5's `..` +and `...`) are operators that take two predicates to test: They are `False` +until their left side returns `True`, then are `True` until their right +side returns `True`. Similar to ranges, you can exclude the iteration when +it become `True`/`False` by using `^` on either side. Let's start with an +example : +=end comment + +for <well met young hero we shall meet later> { + # by default, `ff`/`fff` smart-match (`~~`) against `$_`: + if 'met' ^ff 'meet' { # Won't enter the if for "met" + .say # (explained in details below). + } + + if rand == 0 ff rand == 1 { # compare variables other than `$_` + say "This ... probably will never run ..."; + } +} + +=begin comment +This will print "young hero we shall meet" (excluding "met"): the flip-flop +will start returning `True` when it first encounters "met" (but will still +return `False` for "met" itself, due to the leading `^` on `ff`), until it +sees "meet", which is when it'll start returning `False`. +=end comment + +=begin comment +The difference between `ff` (awk-style) and `fff` (sed-style) is that `ff` +will test its right side right when its left side changes to `True`, and can +get back to `False` right away (*except* it'll be `True` for the iteration +that matched) while `fff` will wait for the next iteration to try its right +side, once its left side changed: +=end comment + +# The output is due to the right-hand-side being tested directly (and returning +# `True`). "B"s are printed since it matched that time (it just went back to +# `False` right away). +.say if 'B' ff 'B' for <A B C B A>; # OUTPUT: «B B», + +# In this case the right-hand-side wasn't tested until `$_` became "C" +# (and thus did not match instantly). +.say if 'B' fff 'B' for <A B C B A>; #=> «B C B», + +# A flip-flop can change state as many times as needed: +for <test start print it stop not printing start print again stop not anymore> { + # exclude both "start" and "stop", + .say if $_ eq 'start' ^ff^ $_ eq 'stop'; # OUTPUT: «print it print again» +} + +# You might also use a Whatever Star, which is equivalent to `True` for the +# left side or `False` for the right, as shown in this example. +# NOTE: the parenthesis are superfluous here (sometimes called "superstitious +# parentheses"). Once the flip-flop reaches a number greater than 50, it'll +# never go back to `False`. +for (1, 3, 60, 3, 40, 60) { + .say if $_ > 50 ff *; # OUTPUT: «6034060» +} + +# You can also use this property to create an `if` that'll not go through the +# first time. In this case, the flip-flop is `True` and never goes back to +# `False`, but the `^` makes it *not run* on the first iteration +for <a b c> { .say if * ^ff *; } # OUTPUT: «bc» + +# The `===` operator, which uses `.WHICH` on the objects to be compared, is +# the value identity operator whereas the `=:=` operator, which uses `VAR()` on +# the objects to compare them, is the container identity operator. +``` + +If you want to go further and learn more about Raku, you can: + +- Read the [Raku Docs](https://docs.raku.org/). This is a great +resource on Raku. If you are looking for something, use the search bar. +This will give you a dropdown menu of all the pages referencing your search +term (Much better than using Google to find Raku documents!). + +- Read the [Raku Advent Calendar](http://perl6advent.wordpress.com/). This +is a great source of Raku snippets and explanations. If the docs don't +describe something well enough, you may find more detailed information here. +This information may be a bit older but there are many great examples and +explanations. Posts stopped at the end of 2015 when the language was declared +stable and Raku 6.c was released. + +- Come along on `#raku` at `irc.freenode.net`. The folks here are +always helpful. + +- Check the [source of Raku's functions and +classes](https://github.com/rakudo/rakudo/tree/nom/src/core). Rakudo is +mainly written in Raku (with a lot of NQP, "Not Quite Perl", a Raku subset +easier to implement and optimize). + +- Read [the language design documents](https://design.raku.org/). They explain +Raku from an implementor point-of-view, but it's still very interesting. + diff --git a/reason.html.markdown b/reason.html.markdown index 62d809cf..b8a2215d 100644 --- a/reason.html.markdown +++ b/reason.html.markdown @@ -162,7 +162,7 @@ let maxPassengers = firstTrip.capacity; /* If you define the record type in a different file, you have to reference the filename, if trainJourney was in a file called Trips.re */ -let secondTrip: Trips.firstTrip = { +let secondTrip: Trips.trainJourney = { destination: "Paris", capacity: 50, averageSpeed: 150.0, diff --git a/ru-ru/c++-ru.html.markdown b/ru-ru/c++-ru.html.markdown index 35994749..3acfafa3 100644 --- a/ru-ru/c++-ru.html.markdown +++ b/ru-ru/c++-ru.html.markdown @@ -43,11 +43,11 @@ int main(int argc, char** argv) // Аргументы командной строки, переданные в программу, хранятся в переменных // argc и argv, так же, как и в C. // argc указывает на количество аргументов, - // а argv является массивом C-подобных строк (char*), который непосредсвенно + // а argv является массивом C-подобных строк (char*), который непосредственно // содержит аргументы. // Первым аргументом всегда передается имя программы. - // argc и argv могут быть опущены, если вы не планируете работать с аругментами - // коммандной строки. + // argc и argv могут быть опущены, если вы не планируете работать с аргументами + // командной строки. // Тогда сигнатура функции будет иметь следующий вид: int main() // Возвращаемое значение 0 указывает на успешное завершение программы. @@ -162,7 +162,7 @@ void foo() int main() { - // Включает все функци из пространства имен Second в текущую область видимости. + // Включает все функции из пространства имен Second в текущую область видимости. // Обратите внимание, что простой вызов foo() больше не работает, // так как теперь не ясно, вызываем ли мы foo из пространства имен Second, или // из глобальной области видимости. @@ -471,6 +471,7 @@ int main() { // членам\методам без открытых или защищенных методов для этого. class OwnedDog : public Dog { +public: void setOwner(const std::string& dogsOwner); // Переопределяем поведение функции печати для всех OwnedDog. Смотрите @@ -582,10 +583,10 @@ public: // Во время компиляции компилятор фактически генерирует копии каждого шаблона // с замещенными параметрами, поэтому полное определение класса должно присутствовать -// при каждом вызове. Именно поэтому классы шаблонов полностью определены в +// при каждом вызове. Именно поэтому шаблоны классов полностью определены в // заголовочных файлах. -// Чтобы создать экземпляр класса шаблона на стеке: +// Чтобы создать экземпляр шаблона класса на стеке: Box<int> intBox; // и вы можете использовать его, как и ожидалось: @@ -605,7 +606,7 @@ boxOfBox.insert(intBox); // http://en.wikipedia.org/wiki/Typename // (да-да, это ключевое слово имеет собственную страничку на вики). -// Аналогичным образом, шаблонная функция: +// Аналогичным образом, шаблон функции: template<class T> void barkThreeTimes(const T& input) { @@ -622,7 +623,7 @@ Dog fluffy; fluffy.setName("Fluffy"); barkThreeTimes(fluffy); // Печатает "Fluffy barks" три раза. -//Параметры шаблона не должны быть классами: +// Параметры шаблона не должны быть классами: template<int Y> void printMessage() { cout << "Learn C++ in " << Y << " minutes!" << endl; @@ -680,7 +681,7 @@ catch (...) // некоторого ресурса неразрывно совмещается с инициализацией, а освобождение - // с уничтожением объекта. -// Чтобы понять, на сколько это полезно, +// Чтобы понять, насколько это полезно, // рассмотрим функцию, которая использует обработчик файлов в С: void doSomethingWithAFile(const char* filename) { @@ -796,7 +797,7 @@ void doSomethingWithAFile(const std::string& filename) // - Контейнеры - стандартная библиотека связанных списков, векторы // (т.е. самоизменяемые массивы), хэш-таблицы и все остальное автоматически // уничтожается сразу же, когда выходит за пределы области видимости. -// - Ипользование мьютексов lock_guard и unique_lock +// - Использование мьютексов lock_guard и unique_lock // Контейнеры с пользовательскими классами в качестве ключей требуют // сравнивающих функций в самом объекте или как указатель на функцию. Примитивы diff --git a/ru-ru/c-ru.html.markdown b/ru-ru/c-ru.html.markdown index 44e7ad3b..389c8bc9 100644 --- a/ru-ru/c-ru.html.markdown +++ b/ru-ru/c-ru.html.markdown @@ -77,7 +77,7 @@ int main() { // sizeof(obj) возвращает размер объекта obj в байтах. printf("%zu\n", sizeof(int)); // => 4 (на большинстве машин int занимает 4 байта) - // Если аргуметом sizeof будет выражение, то этот аргумент вычисляется + // Если аргументом sizeof будет выражение, то этот аргумент вычисляется // ещё во время компиляции кода (кроме динамических массивов). int a = 1; // size_t это беззнаковый целый тип который использует как минимум 2 байта @@ -308,7 +308,7 @@ int main() { // Это работает, потому что при обращении к имени массива возвращается // указатель на первый элемент. // Например, когда массив передаётся в функцию или присваивается указателю, он - // неяввно преобразуется в указатель. + // неявно преобразуется в указатель. // Исключения: когда массив является аргументом для оператор '&': int arr[10]; int (*ptr_to_arr)[10] = &arr; // &arr не является 'int *'! @@ -335,7 +335,7 @@ int main() { // Работа с памятью с помощью указателей может давать неожиданные и // непредсказуемые результаты. - printf("%d\n", *(my_ptr + 21)); // => Напечатает кто-нибудь-знает-что? + printf("%d\n", *(my_ptr + 21)); // => Напечатает кто-нибудь знает, что? // Скорей всего программа вылетит. // Когда вы закончили работать с памятью, которую ранее выделили, вам необходимо @@ -426,7 +426,7 @@ void function_1() { // Можно получить доступ к структуре и через указатель (*my_rec_ptr).width = 30; - // ... или ещё лучше: используйте оператор -> для лучшей читабельночти + // ... или ещё лучше: используйте оператор -> для лучшей читабельности my_rec_ptr->height = 10; // то же что и "(*my_rec_ptr).height = 10;" } diff --git a/ru-ru/go-ru.html.markdown b/ru-ru/go-ru.html.markdown index 6c8622cc..37592258 100644 --- a/ru-ru/go-ru.html.markdown +++ b/ru-ru/go-ru.html.markdown @@ -35,7 +35,7 @@ package main // Import предназначен для указания зависимостей этого файла. import ( "fmt" // Пакет в стандартной библиотеке Go - "io/ioutil" // Реализация функций ввод/ввывода. + "io/ioutil" // Реализация функций ввод/вывода. "net/http" // Да, это веб-сервер! "strconv" // Конвертирование типов в строки и обратно m "math" // Импортировать math под локальным именем m. @@ -270,7 +270,7 @@ func learnErrorHandling() { // c – это тип данных channel (канал), объект для конкурентного взаимодействия. func inc(i int, c chan int) { - c <- i + 1 // когда channel слева, <- являтся оператором "отправки". + c <- i + 1 // когда channel слева, <- является оператором "отправки". } // Будем использовать функцию inc для конкурентной инкрементации чисел. diff --git a/ru-ru/kotlin-ru.html.markdown b/ru-ru/kotlin-ru.html.markdown index 58dab4cd..85f44c96 100644 --- a/ru-ru/kotlin-ru.html.markdown +++ b/ru-ru/kotlin-ru.html.markdown @@ -8,7 +8,7 @@ translators: - ["Vadim Toptunov", "https://github.com/VadimToptunov"] --- -Kotlin - статистически типизированный язык для JVM, Android и браузера. Язык полностью совместим c Java. +Kotlin - статически типизированный язык для JVM, Android и браузера. Язык полностью совместим c Java. [Более детальная информация здесь.](https://kotlinlang.org/) ```kotlin diff --git a/ru-ru/rust-ru.html.markdown b/ru-ru/rust-ru.html.markdown index 7bd2809a..9293a40e 100644 --- a/ru-ru/rust-ru.html.markdown +++ b/ru-ru/rust-ru.html.markdown @@ -6,36 +6,33 @@ contributors: - ["P1start", "http://p1start.github.io/"] translators: - ["Anatolii Kosorukov", "https://github.com/java1cprog"] + - ["Vasily Starostin", "https://github.com/Basil22"] lang: ru-ru --- -Rust сочетает в себе низкоуровневый контроль над производительностью с удобством высокого уровня и предоставляет гарантии -безопасности. -Он достигает этих целей, не требуя сборщика мусора или времени выполнения, что позволяет использовать библиотеки Rust как замену -для C-библиотек. +Язык Rust разработан в Mozilla Research. Он сочетает низкоуровневую производительность с удобством языка высокого уровня и одновременно гарантирует безопасность памяти. -Первый выпуск Rust, 0.1, произошел в январе 2012 года, и в течение 3 лет развитие продвигалось настолько быстро, что до -недавнего времени использование стабильных выпусков было затруднено, и вместо этого общий совет заключался в том, чтобы -использовать последние сборки. +Он достигает этих целей без сборщика мусора или сложной среды выполнения, что позволяет использовать библиотеки Rust как прямую замену +C-библиотек. И наоборот, Rust умеет использовать готовые С-библиотеки как есть, без накладных расходов. -15 мая 2015 года был выпущен Rust 1.0 с полной гарантией обратной совместимости. Усовершенствования времени компиляции и -других аспектов компилятора в настоящее время доступны в ночных сборках. Rust приняла модель выпуска на поезде с регулярными выпусками каждые шесть недель. Rust 1.1 beta был доступен одновременно с выпуском Rust 1.0. +Первый выпуск Rust, 0.1, произошел в январе 2012 года. В течение 3 лет развитие продвигалось настолько быстро, что язык серьезно менялся без сохранения совместимости. Это дало возможность обкатать и отполировать синтаксис и возможности языка. -Хотя Rust является языком относительно низкого уровня, Rust имеет некоторые функциональные концепции, которые обычно -встречаются на языках более высокого уровня. Это делает Rust не только быстрым, но и простым и эффективным для ввода кода. +15 мая 2015 года был выпущен Rust 1.0 с полной гарантией обратной совместимости. Сборка поставляется в трех вариантах: стабильная версия, бета-версия, ночная версия. Все нововведения языка сперва обкатываются на ночной и бета-версиях, и только потом попадают в стабильную. Выход очередной версии происходит раз в 6 недель. В 2018 году вышло второе большое обновление языка, добавившее ему новых возможностей. + +Хотя Rust является языком относительно низкого уровня, он имеет все возможности высокоуровневых языков: процедурное, объектное, функциональное, шаблонное и другие виды программирования. На данный момент Rust является одним из самых мощных (а может быть и самым) по возможностям среди статически типизированных языков. Это делает Rust не только быстрым, но и простым и эффективным для разработки сложного кода. ```rust -// Это однострочный комментарии +// Это однострочный комментарий // /// Так выглядит комментарий для документации /// # Examples /// -/// +/// ``` /// let seven = 7 -/// +/// ``` /////////////// // 1. Основы // @@ -63,10 +60,9 @@ fn main() { let y: i32 = 13i32; let f: f64 = 1.3f64; - // Автоматическое выявление типа данных + // Автоматическое выведение типа данных // В большинстве случаев компилятор Rust может вычислить - // тип переменной, поэтому - // вам не нужно писать явные аннотации типа. + // тип переменной, поэтому вам не нужно явно указывать тип. let implicit_x = 1; let implicit_f = 1.3; @@ -87,12 +83,11 @@ fn main() { // Печать на консоль println!("{} {}", f, x); // 1.3 hello world - // `String` – изменяемя строка + // `String` – изменяемая строка let s: String = "hello world".to_string(); - // Строковый срез - неизменяемый вид в строки - // Это в основном неизменяемая пара указателей на строку - - // Это указатель на начало и конец строкового буфера + // Строковый срез - неизменяемое представление части строки + // Представляет собой пару из указателя на начало фрагмента и его длины let s_slice: &str = &s; @@ -130,7 +125,7 @@ fn main() { // 2. Типы // ////////////// - // Struct + // Структура struct Point { x: i32, y: i32, @@ -154,6 +149,8 @@ fn main() { let up = Direction::Up; // Перечисление с полями + // В отличие от C и C++ компилятор автоматически следит за тем, + // какой именно тип хранится в перечислении. enum OptionalI32 { AnI32(i32), Nothing, @@ -175,7 +172,7 @@ fn main() { // Методы // impl<T> Foo<T> { - fn get_bar(self) -> T { + fn get_bar(self) -> T { self.bar } } @@ -198,9 +195,9 @@ fn main() { let another_foo = Foo { bar: 1 }; println!("{:?}", another_foo.frobnicate()); // Some(1) - ///////////////////////// - // 3. Поиск по шаблону // - ///////////////////////// + ///////////////////////////////// + // 3. Сопоставление по шаблону // + ///////////////////////////////// let foo = OptionalI32::AnI32(1); match foo { @@ -223,9 +220,9 @@ fn main() { println!("The second number is Nothing!"), } - ///////////////////// + ////////////////////////////////////////////// // 4. Управление ходом выполнения программы // - ///////////////////// + ////////////////////////////////////////////// // `for` loops/iteration let array = [1, 2, 3]; @@ -233,7 +230,7 @@ fn main() { println!("{}", i); } - // Отрезки + // Диапазоны for i in 0u32..10 { print!("{} ", i); } @@ -266,12 +263,12 @@ fn main() { break; } - ///////////////////////////////// + ////////////////////////////////// // 5. Защита памяти и указатели // - ///////////////////////////////// + ////////////////////////////////// // Владеющий указатель – такой указатель может быть только один - // Это значит, что при вызоде из блока переменная автоматически становится недействительной. + // Это значит, что при выходе из блока переменная автоматически становится недействительной. let mut mine: Box<i32> = Box::new(3); *mine = 5; // dereference // Здесь, `now_its_mine` получает во владение `mine`. Т.е. `mine` была перемещена. diff --git a/ru-ru/sql-ru.html.markdown b/ru-ru/sql-ru.html.markdown index 64b7ab71..7353a175 100644 --- a/ru-ru/sql-ru.html.markdown +++ b/ru-ru/sql-ru.html.markdown @@ -5,25 +5,41 @@ contributors: - ["Bob DuCharme", "http://bobdc.com/"] translators: - ["Shaltaev", "https://github.com/shaltaev"] + - ["Andre Polykanine", "https://github.com/Menelion"] lang: ru-ru --- -Язык структурированных запросов (SQL) - это стандартный язык ISO для создания и работы с базами данных, хранящимися в наборе таблиц. Реализации обычно добавляют свои собственные расширения к языку; [Сравнение различных реализаций SQL](http://troels.arvin.dk/db/rdbms/) хороший справочник по различиям в продуктах. - -Реализации обычно предоставляют приглашение командной строки, где вы можете вводить команды (описанные ниже) в интерактивном режиме, также есть способ выполнить серию этих команд, сохраненных в файле сценария. (Результат того, что вы сделали с помощью интерактивного режима, является хорошим примером того, что не стандартизировано - большинство реализаций SQL поддерживают ключевые слова QUIT, EXIT или оба.) - -Некоторый команды ниже предполагают использование [демонстрационный образец базы данных сотрудников от MySQL](https://dev.mysql.com/doc/employee/en/) доступный на [github](https://github.com/datacharmer/test_db) следовательно для повторения команд в локальном окружении он должен быть загружен. Файлы и скрипты на github, схожи с командами ниже, которые манипулируют базами, таблицами и данными. Синтаксис для запуска этих сценариев будет зависеть от используемой вами реализации SQL. Способ запуска из командной строки обычный для вашей операционной системе. +Язык структурированных запросов (SQL) — это стандартный язык ISO для создания +и работы с базами данных, хранящимися в наборе таблиц. Реализации обычно +добавляют свои собственные расширения к языку; +[Сравнение различных реализаций SQL](http://troels.arvin.dk/db/rdbms/) — хороший справочник по различиям в продуктах. + +Реализации обычно предоставляют приглашение командной строки, где вы можете +вводить команды, описанные ниже, в интерактивном режиме, также есть способ +выполнить серию таких команд, сохранённых в файле скрипта. +(Результат того, что вы сделали с помощью интерактивного режима, является +хорошим примером того, что не стандартизировано, — большинство реализаций SQL +поддерживают ключевые слова QUIT, EXIT или оба). + +Некоторые команды ниже предполагают использование +[демонстрационного образца базы данных сотрудников от MySQL](https://dev.mysql.com/doc/employee/en/), доступного на [Github](https://github.com/datacharmer/test_db). +Следовательно, для повторения команд в локальном окружении он должен быть загружен. +Файлы на github — это скрипты с командами, которые схожи с командами ниже, +которые создают и манипулируют таблицами и данными о сотрудниках вымышленной +компании. Синтаксис для запуска этих скриптов будет зависеть от используемой +вами реализации SQL. Обычно используется утилита, запускаемая из командной +строки в вашей операционной системе. ```sql --- Комментарии начинаются с двух дефисов. Завершите каждую команду +-- Комментарии начинаются с двух дефисов. Завершайте каждую команду -- точкой с запятой. --- SQL не учитывает регистр ключевых слов. Образцы команд здесь --- следуйте соглашению о написании их в верхнем регистре, потому что --- это позволяет легче их отличить от имен баз, таблиц и колонок. +-- SQL не учитывает регистр букв для ключевых слов. Примеры команд здесь +-- следуют соглашению о написании в верхнем регистре, потому что +-- это позволяет легче отличить их от имён баз, таблиц и колонок. -- Создание и удаление базы данных. Имена базы и таблицы чувствительны --- к регистру. +-- к регистру букв. CREATE DATABASE someDatabase; DROP DATABASE someDatabase; @@ -33,71 +49,72 @@ SHOW DATABASES; -- Выбор базы для работы. USE employees; --- Выбрать все колонки и строки из таблицы текущей базы. --- В интерактивном режиме обычно результат будет выведен на экран. +-- Выбрать все строки и колонки из таблицы «departments» (отделы) текущей базы. +-- В интерактивном режиме обыч но результат будет выведен на экран. SELECT * FROM departments; --- Тот же запрос что и вышеБ но выбор только колонок dept_no и dept_name. +-- Тот же запрос, что и выше, но выбор только колонок «dept_no» и «dept_name». -- Разбиение команд на несколько строк допустимо. SELECT dept_no, dept_name FROM departments; --- В данном случае будут выбраны только первые 5 результатов. +-- В данном случае будут выбраны все колонки, но только первые 5 строк. SELECT * FROM departments LIMIT 5; --- Выбор имен депортаментов где имена содержат в себе 'en'. +-- Выбор названий отделов, содержащих подстроку «en». SELECT dept_name FROM departments WHERE dept_name LIKE '%en%'; --- Выбор всех колонок где имена начинаются 'S' и 4 любых символа после. +-- Выбор всех колонок, где названия отделов начинаются на «S», +-- после которой идёт ровно четыре символа. SELECT * FROM departments WHERE dept_name LIKE 'S____'; --- Выбор всех должностей, но без повторений. +-- Выбор всех должностей из таблицы «titles», но без повторений. SELECT DISTINCT title FROM titles; -- В дополнение к предыдущему запросу результат будет отсортирован --- в алфавитном порядке (С учетом регистра). +-- в алфавитном порядке (с учётом регистра). SELECT DISTINCT title FROM titles ORDER BY title; --- Вычислить количество строк в таблице депортамента. +-- Показать число строк в таблице отделов. SELECT COUNT(*) FROM departments; --- Вычислить количество строк где имя депортамента содержит 'en' --- в любой части имени. +-- Показать число строк, где название отдела содержит подстроку «en» SELECT COUNT(*) FROM departments WHERE dept_name LIKE '%en%'; --- ОБЪЕДИНЕНИЕ информации из нескольких таблиц: должность, когда ее занимал, --- имя и фамилия сотрудника, объединить по идентификатору сотрудника --- вывести только 10 строк. - +-- Объединение информации из нескольких таблиц: +-- В таблице «titles» перечислены должности, кто их занимал по номеру сотрудника, +-- а также с какой даты по какую. Получим эту информацию, но используем номера +-- сотрудников как ссылку на таблицу «employees», чтобы получить имя и фамилию +-- каждого сотрудника. Выводим только 10 строк. SELECT employees.first_name, employees.last_name, titles.title, titles.from_date, titles.to_date FROM titles INNER JOIN employees ON employees.emp_no = titles.emp_no LIMIT 10; -- Список всех таблиц во всех базах. Реализации обычно предоставляют --- их собственные сокращения чтобы сделать это для текущей базы. +-- собственные сокращения, чтобы показать все таблицы текущей базы. SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE='BASE TABLE'; --- Создать таблицу с именем tablename1, с двумя колонками, для колонок --- доступно множество опций вроде типа и других, конкретнее уточняйте для --- своей реализации. +-- Создать таблицу с именем tablename1 и двумя колонками в текущей базе. +-- Для колонок имеется множество параметров, таких как тип данных. CREATE TABLE tablename1 (fname VARCHAR(20), lname VARCHAR(20)); --- Вставляем строку в таблице созданную в предыдущем запросе . +-- Вставляем строку данных в таблицу «tablename1». Предполагаем, что таблица +-- настроена таким образом, чтобы принимать эти значения. INSERT INTO tablename1 VALUES('Richard','Mutt'); --- В tablename1, изменить значение fname на 'John' --- для каждой строки где lname имеет значение 'Mutt'. +-- В таблице «tablename1» изменить значение fname на «John» +-- для каждой строки, где колонка lname равна «Mutt». UPDATE tablename1 SET fname='John' WHERE lname='Mutt'; --- Удалить строки из таблицы tablename1 --- где lname начинается с 'M'. +-- Удалить из таблицы «tablename1» строки, +-- где значение колонки lname начинается с «M». DELETE FROM tablename1 WHERE lname like 'M%'; --- Удалить все строки из таблицы tablename1, в итоге получим пустую таблицу. +-- Удалить все строки из таблицы «tablename1». В итоге получим пустую таблицу. DELETE FROM tablename1; --- Удалить таблицу tablename1. +-- Удалить таблицу «tablename1» полностью. DROP TABLE tablename1; ``` diff --git a/ru-ru/yaml-ru.html.markdown b/ru-ru/yaml-ru.html.markdown index 6eb580d9..0f805681 100644 --- a/ru-ru/yaml-ru.html.markdown +++ b/ru-ru/yaml-ru.html.markdown @@ -24,7 +24,7 @@ YAML как язык сериализации данных предназнач # Скалярные величины # ###################### -# Наш корневой объект (который продолжается для всего документа) будет соответствовать +# Наш корневой объект (который продолжается до конца документа) будет соответствовать # типу map, который в свою очередь соответствует словарю, хешу или объекту в других языках. key: value another_key: Другое значение ключа. diff --git a/ruby.html.markdown b/ruby.html.markdown index d77672ab..f437adcf 100644 --- a/ruby.html.markdown +++ b/ruby.html.markdown @@ -410,7 +410,7 @@ def guests(&block) end # The 'call' method on the Proc is similar to calling 'yield' when a block is -# present. The arguments passed to 'call' will be forwarded to the block as arugments. +# present. The arguments passed to 'call' will be forwarded to the block as arguments. guests { |n| "You have #{n} guests." } # => "You have 4 guests." diff --git a/swift.html.markdown b/swift.html.markdown index c2fb3471..1f9fe897 100644 --- a/swift.html.markdown +++ b/swift.html.markdown @@ -91,7 +91,7 @@ let multiLineString = """ This is a multi-line string. It's called that because it takes up multiple lines (wow!) Any indentation beyond the closing quotation marks is kept, the rest is discarded. - You can include " or "" in multi-line strings because the delimeter is three "s. + You can include " or "" in multi-line strings because the delimiter is three "s. """ // Arrays @@ -159,12 +159,12 @@ let `class` = "keyword" or contains nil (no value) to indicate that a value is missing. Nil is roughly equivalent to `null` in other languages. A question mark (?) after the type marks the value as optional of that type. - + If a type is not optional, it is guaranteed to have a value. - + Because Swift requires every property to have a type, even nil must be explicitly stored as an Optional value. - + Optional<T> is an enum, with the cases .none (nil) and .some(T) (the value) */ @@ -178,7 +178,7 @@ let someOptionalString4 = String?.none //nil To access the value of an optional that has a value, use the postfix operator !, which force-unwraps it. Force-unwrapping is like saying, "I know that this optional definitely has a value, please give it to me." - + Trying to use ! to access a non-existent optional value triggers a runtime error. Always make sure that an optional contains a non-nil value before using ! to force-unwrap its value. @@ -194,7 +194,7 @@ if someOptionalString != nil { // Swift supports "optional chaining," which means that you can call functions // or get properties of optional values and they are optionals of the appropriate type. // You can even do this multiple times, hence the name "chaining." - + let empty = someOptionalString?.isEmpty // Bool? // if-let structure - @@ -370,7 +370,7 @@ func say(_ message: String) { } say("Hello") -// Default parameters can be ommitted when calling the function. +// Default parameters can be omitted when calling the function. func printParameters(requiredParameter r: Int, optionalParameter o: Int = 10) { print("The required parameter was \(r) and the optional parameter was \(o)") } @@ -443,7 +443,7 @@ func testGuard() { return // guard statements MUST exit the scope that they are in. // They generally use `return` or `throw`. } - + print("number is \(aNumber)") } testGuard() @@ -564,7 +564,7 @@ enum Furniture { case desk(height: Int) // Associate with String and Int case chair(String, Int) - + func description() -> String { //either placement of let is acceptable switch self { @@ -591,15 +591,15 @@ print(chair.description()) // "Chair of Foo with 40 cm" - Define initializers to set up their initial state - Be extended to expand their functionality beyond a default implementation - Conform to protocols to provide standard functionality of a certain kind - + Classes have additional capabilities that structures don't have: - Inheritance enables one class to inherit the characteristics of another. - Type casting enables you to check and interpret the type of a class instance at runtime. - Deinitializers enable an instance of a class to free up any resources it has assigned. - Reference counting allows more than one reference to a class instance. - + Unless you need to use a class for one of these reasons, use a struct. - + Structures are value types, while classes are reference types. */ @@ -607,7 +607,7 @@ print(chair.description()) // "Chair of Foo with 40 cm" struct NamesTable { let names: [String] - + // Custom subscript subscript(index: Int) -> String { return names[index] @@ -629,7 +629,7 @@ class Shape { class Rect: Shape { var sideLength: Int = 1 - + // Custom getter and setter property var perimeter: Int { get { @@ -640,16 +640,16 @@ class Rect: Shape { sideLength = newValue / 4 } } - + // Computed properties must be declared as `var`, you know, cause' they can change var smallestSideLength: Int { return self.sideLength - 1 } - + // Lazily load a property // subShape remains nil (uninitialized) until getter called lazy var subShape = Rect(sideLength: 4) - + // If you don't need a custom getter and setter, // but still want to run code before and after getting or setting // a property, you can use `willSet` and `didSet` @@ -659,19 +659,19 @@ class Rect: Shape { print(someIdentifier) } } - + init(sideLength: Int) { self.sideLength = sideLength // always super.init last when init custom properties super.init() } - + func shrink() { if sideLength > 0 { sideLength -= 1 } } - + override func getArea() -> Int { return sideLength * sideLength } @@ -703,13 +703,13 @@ class Circle: Shape { override func getArea() -> Int { return 3 * radius * radius } - + // Place a question mark postfix after `init` is an optional init // which can return nil init?(radius: Int) { self.radius = radius super.init() - + if radius <= 0 { return nil } @@ -813,7 +813,7 @@ for _ in 0..<10 { - Internal: Accessible and subclassible in the module it is declared in. - Fileprivate: Accessible and subclassible in the file it is declared in. - Private: Accessible and subclassible in the enclosing declaration (think inner classes/structs/enums) - + See more here: https://docs.swift.org/swift-book/LanguageGuide/AccessControl.html */ @@ -878,11 +878,11 @@ extension Int { var doubled: Int { return self * 2 } - + func multipliedBy(num: Int) -> Int { return num * self } - + mutating func multiplyBy(num: Int) { self *= num } @@ -965,18 +965,18 @@ func fakeFetch(value: Int) throws -> String { guard 7 == value else { throw MyError.reallyBadValue(msg: "Some really bad value") } - + return "test" } func testTryStuff() { // assumes there will be no error thrown, otherwise a runtime exception is raised let _ = try! fakeFetch(value: 7) - + // if an error is thrown, then it proceeds, but if the value is nil // it also wraps every return value in an optional, even if its already optional let _ = try? fakeFetch(value: 7) - + do { // normal try operation that provides error handling via `catch` block try fakeFetch(value: 1) diff --git a/th-th/typescript.th.html.markdown b/th-th/typescript.th.html.markdown index fc2a823b..5395c2a7 100644 --- a/th-th/typescript.th.html.markdown +++ b/th-th/typescript.th.html.markdown @@ -190,7 +190,7 @@ interface Person { } var p1: Person = { name: "Tyrone", age: 42 }; -p1.age = 25; // Error แน่นอน เพราะ p1.x ถูกกำหนดเป็น read-only +p1.age = 25; // Error แน่นอน เพราะ p1.age ถูกกำหนดเป็น read-only var p2 = { name: "John", age: 60 }; // สังเกตว่า p2 ไม่ได้กำหนดเป็น Person var p3: Person = p2; // ทำได้ เป็น read-only alias ของ p2 และกำหนดเป็น Person diff --git a/typescript.html.markdown b/typescript.html.markdown index cf2111d5..00f0cbc5 100644 --- a/typescript.html.markdown +++ b/typescript.html.markdown @@ -16,7 +16,7 @@ This article will focus only on TypeScript extra syntax, as opposed to [JavaScript](/docs/javascript). To test TypeScript's compiler, head to the -[Playground] (http://www.typescriptlang.org/Playground) where you will be able +[Playground](https://www.typescriptlang.org/play) where you will be able to type code, have auto completion and directly see the emitted JavaScript. ```ts @@ -199,7 +199,7 @@ interface Person { } var p1: Person = { name: "Tyrone", age: 42 }; -p1.age = 25; // Error, p1.x is read-only +p1.age = 25; // Error, p1.age is read-only var p2 = { name: "John", age: 60 }; var p3: Person = p2; // Ok, read-only alias for p2 diff --git a/uk-ua/cypher-ua.html.markdown b/uk-ua/cypher-ua.html.markdown new file mode 100644 index 00000000..0911793b --- /dev/null +++ b/uk-ua/cypher-ua.html.markdown @@ -0,0 +1,254 @@ +--- +language: cypher +filename: LearnCypher-ua.cql +contributors: + - ["Théo Gauchoux", "https://github.com/TheoGauchoux"] +translators: + - ["AstiaSun", "https://github.com/AstiaSun"] +lang: uk-ua +--- + +Cypher - це мова запитів Neo4j для спрощення роботи з графами. Вона повторює синтаксис SQL та перемішує його з таким собі ascii стилем для відображення структури графа. +Цей навчальний матеріал передбачає, що ви вже знайомі із концепцією графів, зобрема що таке вершини та зв'язки між ними. + +[Деталі тут](https://neo4j.com/developer/cypher-query-language/) + + +Вершини +--- + +**Відображує запис у графі.** + +`()` +Таким чином у запиті позначається пуста *вершина*. Використовується зазвичай для того, щоб позначити, що вона є, проте це не так вже й важливо для запиту. + +`(n)` +Це вершина, яка має назву **n**, до неї можна повторно звертатись у запиті. Звернення до вершини **n** починається з нижнього підкреслення та використовує camelCase (верблюжий регіст). + +`(p:Person)` +Можна також додати *ярлик* до вершини, в данному випадку - **Person**. Це як тип / клас / категорія. Назва *ярлика* починається з великої літери та використовує верблюжу нотацію. + +`(p:Person:Manager)` +Вершина може мати кілька *ярликів*. + +`(p:Person {name : 'Théo Gauchoux', age : 22})` +Вершина також може мати різні *властивості*, в данному випадку - **name** та **age**. Також мають починатися з великої літери та використовувати верблюжу нотацію. + +Наступні типи дозволяється використовувати у властивостях: + + - Чиселиний + - Булевий + - Рядок + - Списки попередніх примітивних типів + +*Увага! В Cypher не існує типу, що відображає час. Замість нього можна використовувати рядок із визначеним шаблоном або чисельне відображення певної дати.* + +`p.name` +За допомогою крапки можна звернутись до властивості вершини. + + +Зв'язки (або ребра) +--- + +**Сполучають дві вершини** + +`[:KNOWS]` +Це *зв'язок* з *ярликом* **KNOWS**. Це такий же самий *ярлик* як і у вершини. Починається з великої літери та використовує ВЕРХНІЙ\_РЕГІСТР\_ІЗ\_ЗМІЇНОЮ\_НОТАЦІЄЮ. + +`[k:KNOWS]` +Це той же самий *зв'язок*, до якого можна звертатись через змінну **k**. Можна подалі використовувати у запиті, хоч це і не обов'язково. + +`[k:KNOWS {since:2017}]` +Той же *зв'язок*, але вже із *властивостями* (як у *вершини*), в данному випадку властивість - це **since**. + +`[k:KNOWS*..4]` +Це структурна інформація, яку використовують *шляхи*, які розглянуті нижче. В данному випадку, **\*..4** говорить: "Сумістити шаблон із зв'язком **k**, що повторюватиметься від одного до чотирьох разів." + + +Шляхи +--- + +**Спосіб поєднувати вершини та зв'язки.** + +`(a:Person)-[:KNOWS]-(b:Person)` +Шлях описує, що вершини **a** та **b** знають (knows) один одного. + +`(a:Person)-[:MANAGES]->(b:Person)` +Шлях може бути направленим. Цей описує, що **а** є менеджером **b**. + +`(a:Person)-[:KNOWS]-(b:Person)-[:KNOWS]-(c:Person)` +Можна створювати ланцюги зі зв'язків. Цей шлях описує друга друга (**a** знає **b**, який в свою чергу знає **c**). + +`(a:Person)-[:MANAGES]->(b:Person)-[:MANAGES]->(c:Person)` +Ланцюг, аналогічно, також може бути направленим. Шлях описує, що **a** - бос **b** і супер бос для **c**. + +Шаблони, які часто використовуються (з документації Neo4j): + +``` +// Друг-мого-друга +(user)-[:KNOWS]-(friend)-[:KNOWS]-(foaf) + +// Найкоротший шлях +path = shortestPath( (user)-[:KNOWS*..5]-(other) ) + +// Спільна фільтрація +(user)-[:PURCHASED]->(product)<-[:PURCHASED]-()-[:PURCHASED]->(otherProduct) + +// Навігація по дереву +(root)<-[:PARENT*]-(leaf:Category)-[:ITEM]->(data:Product) + +``` + + +Запити на створення +--- + +Створити нову вершину: +``` +CREATE (a:Person {name:"Théo Gauchoux"}) +RETURN a +``` +*`RETURN` дозволяє повернути результат після виконання запиту. Можна повертати кілька значень, наприклад, `RETURN a, b`.* + +Створити новий зв'язок (із двома вершинами): +``` +CREATE (a:Person)-[k:KNOWS]-(b:Person) +RETURN a,k,b +``` + +Запити на знаходження +--- + +Знайти всі вершини: +``` +MATCH (n) +RETURN n +``` + +Знайти вершини за ярликом: +``` +MATCH (a:Person) +RETURN a +``` + +Знайти вершини за ярликом та властивістю: +``` +MATCH (a:Person {name:"Théo Gauchoux"}) +RETURN a +``` + +Знайти вершини відповідно до зв'язків (ненаправлених): +``` +MATCH (a)-[:KNOWS]-(b) +RETURN a,b +``` + +Знайти вершини відповідно до зв'язків (направлених): +``` +MATCH (a)-[:MANAGES]->(b) +RETURN a,b +``` + +Знайти вершини за допомогою `WHERE`: +``` +MATCH (p:Person {name:"Théo Gauchoux"})-[s:LIVES_IN]->(city:City) +WHERE s.since = 2015 +RETURN p,state +``` + +Можна використовувати вираз `MATCH WHERE` разом із операцією `CREATE`: +``` +MATCH (a), (b) +WHERE a.name = "Jacquie" AND b.name = "Michel" +CREATE (a)-[:KNOWS]-(b) +``` + + +Запити на оновлення +--- + +Оновити окрему властивість вершини: +``` +MATCH (p:Person) +WHERE p.name = "Théo Gauchoux" +SET p.age = 23 +``` + +Оновити всі властивості вершини: +``` +MATCH (p:Person) +WHERE p.name = "Théo Gauchoux" +SET p = {name: "Michel", age: 23} +``` + +Додати нову властивіcть до вершини: +``` +MATCH (p:Person) +WHERE p.name = "Théo Gauchoux" +SET p + = {studies: "IT Engineering"} +``` + +Повісити ярлик на вершину: +``` +MATCH (p:Person) +WHERE p.name = "Théo Gauchoux" +SET p:Internship +``` + + +Запити на видалення +--- + +Видалити окрему вершину (пов'язані ребра повинні бути видалені перед цим): +``` +MATCH (p:Person)-[relationship]-() +WHERE p.name = "Théo Gauchoux" +DELETE relationship, p +``` + +Видалити властивість певної вершини: +``` +MATCH (p:Person) +WHERE p.name = "Théo Gauchoux" +REMOVE p.age +``` + +*Зверніть увагу, що ключове слово `REMOVE` це не те саме, що й `DELETE`!* + +Видалити ярлик певної вершини: +``` +MATCH (p:Person) +WHERE p.name = "Théo Gauchoux" +DELETE p:Person +``` + +Видалити всю базу даних: +``` +MATCH (n) +OPTIONAL MATCH (n)-[r]-() +DELETE n, r +``` + +*Так, це `rm -rf /` на мові Cypher !* + + +Інші корисні запити +--- + +`PROFILE` +Перед виконанням, показати план виконання запитів. + +`COUNT(e)` +Порахувати елементи (вершини та зв'язки), що відповідають **e**. + +`LIMIT x` +Обмежити результат до x перших результатів. + + +Особливі підказки +--- + +- У мові Cypher існують лише однорядкові коментарі, що позначаються двійним слешем : // Коментар +- Можна виконати скрипт Cypher, збережений у файлі **.cql** прямо в Neo4j (прямо як імпорт). Проте, не можна мати мати кілька виразів в цьому файлі (розділених **;**). +- Використовуйте командний рядок Neo4j для написання запитів Cypher, це легко і швидко. +- Cypher планує бути стандартною мовою запитів для всіх графових баз даних (більш відома як **OpenCypher**). diff --git a/uk-ua/go-ua.html.markdown b/uk-ua/go-ua.html.markdown new file mode 100644 index 00000000..f980f7b1 --- /dev/null +++ b/uk-ua/go-ua.html.markdown @@ -0,0 +1,449 @@ +--- +name: Go +category: language +language: Go +filename: learngo-ua.go +contributors: + - ["Sonia Keys", "https://github.com/soniakeys"] + - ["Christopher Bess", "https://github.com/cbess"] + - ["Jesse Johnson", "https://github.com/holocronweaver"] + - ["Quint Guvernator", "https://github.com/qguv"] + - ["Jose Donizetti", "https://github.com/josedonizetti"] + - ["Alexej Friesen", "https://github.com/heyalexej"] + - ["Clayton Walker", "https://github.com/cwalk"] + - ["Leonid Shevtsov", "https://github.com/leonid-shevtsov"] +translators: + - ["AstiaSun", "https://github.com/AstiaSun"] +lang: uk-ua +--- + +Go був створений для того, щоб виконати задачу. Це не останній тренд в теорії мов програмування, а спосіб вирішення реальних проблем. + +Він увібрав принципи з імперативних мов зі статичною типізацією. +Go швидко компілюється та виконується, а його багатопоточність легка для +вивчення, оскільки багатоядерні CPU стали буденністю. Ця мова програмування успішно використовується у кодах великих продуктів (~100 мільйонів в Google, Inc.) + +Go має чудову стандартну бібліотеку та чимале ком'юніті. + +```go +// Однорядковий коментар +/* Багато- + рядковий коментар */ + +// Кожен файл вихідного коду має починатись із ключового слова package. +// main - це спеціальна назва, що оголошує виконуваний код, а не бібліотеку. +package main + +// import оголошує бібліотеки, що використовуються в даному файлі. +import ( + "fmt" // Пакет стандартної бібліотеки Go. + "io/ioutil" // Цей пакет реалізує деякі I/O функції утиліт. + m "math" // Бібліотека математичних операцій з локальним псевдонімом m. + "net/http" // Так, веб сервер! + "os" // Функції операційної системи, такі як робота з файловою системою. + "strconv" // Перетворення текстових змінних. +) + +// Оголошення функції. +// Функція main - особлива. Це вхідна точка для виконуваних програм. +// Ви можете любити це, або ж ненавидіти, але Go використовує фігурні дужки. +func main() { + // Println виводить рядок в stdout. + // Ця функція входить у пакет fmt. + fmt.Println("Hello world!") + + // Викликати іншу функцію з цього файлу. + beyondHello() +} + +// Аргументи функцій описуються у круглих дужках. +// Навіть якщо ніякі аргументи не передаються, пусті круглі дужки - обов`язкові. +func beyondHello() { + var x int // Оголошення змінної. Перед використанням змінні обов'язково мають бути оголошені. + x = 3 // Присвоєння значення. + // "Короткі" оголошення використовують := щоб окреслити тип, оголосити та присвоїти значення. + y := 4 + sum, prod := learnMultiple(x, y) // Функція повертає два значення. + fmt.Println("sum:", sum, "prod:", prod) // Просто вивід. + learnTypes() // < y хвилин, потрібно вивчити більше! +} + +/* <- багаторядковий коментар +Функції можуть мати параметри та повертати довільну кількість значень. +В цьому прикладі `x`, `y` - це аргументи, а `sum`, `prod` - це змінні, що повертаються. +Зверніть увагу, що `x` та `sum` мають тип `int`. +*/ +func learnMultiple(x, y int) (sum, prod int) { + return x + y, x * y // Повернути два значення. +} + +// Кілька вбудованих типів та літералів. +func learnTypes() { + // Короткі оголошення зазвичай виконують все, що необхідно. + str := "Вчи Go!" // рядок (string). + + s2 := `"Необроблений" текст +може містити переноси рядків.` // Також має тип рядок. + + // Не ASCII символи. Go використовує UTF-8. + g := 'Σ' // руничний тип, псевдонім для int32, містить позицію юнікод кода. + + f := 3.14195 // float64, IEEE-754 64-бітне число з плаваючою крапкою. + c := 3 + 4i // complex128, комплексні числа, що являють собою два float64. + + // Синтаксис ініціалізації з var. + var u uint = 7 // Беззнаковий цілочисельний тип, проте розмір залежить від імплементації, так само як і int. + var pi float32 = 22. / 7 + + // Синтаксис перетворення типів з коротким оголошенням. + n := byte('\n') // Байт - це переіменований uint8. + + // Розмір масива фіксований протягом часу виконання. + var a4 [4]int // Масив з 4 чисел, всі проініціалізовані 0. + a5 := [...]int{3, 1, 5, 10, 100} // Масив проініціалізованих чисел з фіксованим розміром у + // п'ять елементів, що мають значення 3, 1, 5, 10, та 100. + + // Зрізи мають динамічний розмір. Переваги є і у масивів, й у зрізів, проте + // останні використовуються частіше. + s3 := []int{4, 5, 9} // Порівняйте з a5. Тут немає трьокрапки. + s4 := make([]int, 4) // Виділяє пам'ять для зрізу з 4 чисел, проініціалізованих 0. + var d2 [][]float64 // Декларація, нічого не виділяється. + bs := []byte("a slice") // Синтаксис переведення у інший тип. + + // Оскільки зрізи динамічні, до них можна додавати елементи за необхідністю. + // Для цієї операції використовується вбудована функція append(). + // Перший аргумент - це зріз, до якого додається елемент. Зазвичай + // змінна масиву оновлюється на місці, як у прикладі нижче. + s := []int{1, 2, 3} // В результаті отримуємо зріз із 3 чисел. + s = append(s, 4, 5, 6) // додаємо 3 елементи. Зріз тепер довжини 6. + fmt.Println(s) // Оновлений зріз тепер має значення [1 2 3 4 5 6] + + // Щоб об'єднати два зрізи, замість того, щоб проходитись по всім елементам, + // можна передати посилання на зріз із трьокрапкою, як у прикладі нижче. Таким чином, + // зріз розпакується і його елементи додадуться до зріза s. + s = append(s, []int{7, 8, 9}...) + fmt.Println(s) // Оновлений зріз тепер дорівнює [1 2 3 4 5 6 7 8 9] + + p, q := learnMemory() // Оголошує змінні p, q, що є вказівниками на числа. + fmt.Println(*p, *q) // * іде попереду вказівника. Таким чином, виводяться числа. + + // Асоціативний масив (map) - це динамічно розширюваний тип даних, як хеш + // або словник в інших мовах програмування + m := map[string]int{"three": 3, "four": 4} + m["one"] = 1 + + // В Go змінні, які не використовуються, вважаються помилкою. + // Нижнє підкреслення дозволяє "використати" змінну, але проігнорувати значення. + _, _, _, _, _, _, _, _, _, _ = str, s2, g, f, u, pi, n, a5, s4, bs + // Зазвичай це використовується, щоб проігнорувати значення, що повертає функція. + // Наприклад, в скрипті нашвидкоруч можна проігнорувати помилку, яку повертає + // функція os.Create, вважаючи, що файл буде створений за будь-яких умов. + file, _ := os.Create("output.txt") + fmt.Fprint(file, "Приклад, як відбувається запис у файл.") + file.Close() + + // Вивід значень змінних. + fmt.Println(s, c, a4, s3, d2, m) + + learnFlowControl() // Рухаємось далі. +} + +// Навідміну від більшості інших мов програмування, функції в Go підтримують +// іменоване значення, що повертається. +// Змінні, значення яких повертається функцією, вказуються із зазначенням типу при +// оголошенні функції. Таким чином, можна з легкістю повернути їхні значення в різних +// точках коду, не перелічуючи їх після ключового слова return. +func learnNamedReturns(x, y int) (z int) { + z = x * y + return // z не потрібно вказувати, при оголошенні описано змінну для повернення. +} + +// Go використовує сміттєзбірник. В ньому використовуються вказівники, проте немає +// операцій з вказівниками. Можлива помилка при використовуванні вказівника nil, але не +// при збільшенні значення вказівника (перехід по адресам пам'яті). +func learnMemory() (p, q *int) { + // Іменовані змінні, що повертаються, p та q, мають тип вказівника на чисельне значення. + p = new(int) // Вбудована функція виділяє нову пам'ять. + // Виділена адреса пам'яті чисельного типу int ініціалізовується 0, p більше не nil. + s := make([]int, 20) // Виділити пам'ять для 20 чисел у вигляді суцільного блоку в пам'яті. + s[3] = 7 // Присвоїти значення одному з них. + r := -2 // Оголосити нову локальну змінну. + return &s[3], &r // Оператор & повертає адресу в пам'яті об'єкта. +} + +func expensiveComputation() float64 { + return m.Exp(10) +} + +func learnFlowControl() { + // if твердження вимагає фігурні дужки, але не вимагає округлих. + if true { + fmt.Println("Кажу ж") + } + // Форматування стандартизовано командою командного рядка "go fmt". + if false { + // Pout. + } else { + // Gloat. + } + // Використання перемикача (switch) замість ланцюга if-тверджень. + x := 42.0 + switch x { + case 0: + case 1: + case 42: + // Кейси не "провалюються". Натомість, є ключове слово `fallthrough`: + // https://github.com/golang/go/wiki/Switch#fall-through (англ) + case 43: + // Недоступний. + default: + // Кейс за замовчуванням не обов'язковий. + } + // Як і if, формат оголошення циклу for не вимагає круглих дужок: + // Змінні, оголошені всередині if та for - належать цій області видимості. + for x := 0; x < 3; x++ { // ++ - це твердження. + fmt.Println("iteration", x) + } + // Тут x == 42. + + // For - це єдиний цикл в Go, проте він має кілька різних форм. + for { // Ініціалізація циклу. + break // Упс, помилково зайшли. + continue // Недоступне твердження. + } + + // Можна використовувати діапазони, зрізи, рядки, асоціативні масиви, або ж + // канал для ітерації в циклі. Діапазон (range) повертає один (канал) або два + // значення (масив, зріз, рядок та асоціативний масив). + for key, value := range map[string]int{"one": 1, "two": 2, "three": 3} { + // для кожної пари в асоціативному масиві, надрукувати ключ та значення + fmt.Printf("key=%s, value=%d\n", key, value) + } + // якщо потрібне тільки значення, можна застосувати нижнє підкреслення як ключ + for _, name := range []string{"Bob", "Bill", "Joe"} { + fmt.Printf("Hello, %s\n", name) + } + + // так само, як і з циклом for, оператор := в розгалуженні означає оголосити + // локальну змінну в області видимості if та присвоїти значення. Далі + // значення змінної проходить перевірку y > x. + if y := expensiveComputation(); y > x { + x = y + } + // Літерали функцій - це замикання + xBig := func() bool { + return x > 10000 // Посилання на x, що був оголошений раніше, перед switch. + } + x = 99999 + fmt.Println("xBig:", xBig()) // true + x = 1.3e3 // Тобто, тепер x == 1300 + fmt.Println("xBig:", xBig()) // false тепер. + + // Функція може бути оголошена та викликана в одному рядку, поводячи себе + // як аргумент функції, але за наступних умов: + // 1) літерал функції негайно викликається за допомогою () + // 2) тип значення, що повертається, точно відповідає очікуваному типу аргументу + fmt.Println("Add + double two numbers: ", + func(a, b int) int { + return (a + b) * 2 + }(10, 2)) // Викликаємо з аргументами 10 та 2 + // => Додати + подвоїти два числа: 24 + + // Коли вам це знадобиться, ви полюбите це + goto love +love: + + learnFunctionFactory() // функція, що повертає функцію - це весело(3)(3) + learnDefer() // Швидкий обхід до важливого ключового слова. + learnInterfaces() // Тут на вас чекає крута штука! +} + +func learnFunctionFactory() { + // Два наступних твердження роблять однакові дії, але другий приклад частіше + // застосовується + fmt.Println(sentenceFactory("summer")("A beautiful", "day!")) + + d := sentenceFactory("summer") + fmt.Println(d("A beautiful", "day!")) + fmt.Println(d("A lazy", "afternoon!")) +} + +// Декоратори звична річ для багатьох мов програмування. В Go їх можна реалізувати +// за допомогою літералів функцій, що приймають аргументи. +func sentenceFactory(mystring string) func(before, after string) string { + return func(before, after string) string { + return fmt.Sprintf("%s %s %s", before, mystring, after) // новий рядок + } +} + +func learnDefer() (ok bool) { + // твердження defer змушує функцію посилатись на список. Список + // збережених викликів виконується ПІСЛЯ того, як оточуюча функція закінчує + // виконання. + defer fmt.Println("відкладені твердження виконуються у зворотньому порядку (LIFO).") + defer fmt.Println("\nЦей рядок надрукується першим, тому що") + // Відкладення зазвичай використовується для того, щоб закрити файл. Таким чином, + // функція, що закриває файл, залишається близькою до функції, що відкриває файл. + return true +} + +// Оголошує Stringer як тип інтерфейсу з одним методом, String. +type Stringer interface { + String() string +} + +// Оголошує pair як структуру з двома полями, цілими числами x та y. +type pair struct { + x, y int +} + +// Оголошує метод для типу pair. pair тепер реалізує Stringer, оскільки pair оголосив +// всі методи в цьому інтерфейсі. +func (p pair) String() string { // p тепер називається "приймачем" + // Sprintf - ще одна функція з пакету fmt. + // Крапка використовується, щоб звернутись до полів об'єкту p. + return fmt.Sprintf("(%d, %d)", p.x, p.y) +} + +func learnInterfaces() { + // Синтаксис з використанням фігурних дужок називається "літералом структури". + // Він застосовується до ініціалізованої структури. Оператор := оголошує + // та ініціалізує p цією структурою. + p := pair{3, 4} + fmt.Println(p.String()) // Викликає метод String об'єкта p типу pair. + var i Stringer // Оголошує і інтерфейсного типу Stringer. + i = p // Допустиме, оскільки pair реалізує Stringer + // Викликає метод String об'єкта і, що має тип Stringer. Виводить те ж саме, що й + // аналогічний метод вище. + fmt.Println(i.String()) + + // Функції з бібліотеки fmt викликають метод String, щоб запросити у об'єкта + // своє представлення, яке можна надрукувати. + fmt.Println(p) // Виводить те ж саме, що й раніше. + fmt.Println(i) // Виводить те ж саме, що й раніше. + + learnVariadicParams("great", "learning", "here!") +} + +// Кількість аргументів функції може бути змінною. +func learnVariadicParams(myStrings ...interface{}) { + // Пройтись по значенням всіх аргументів. + // _ - це ігнорування порядкового номеру аргумента в масиві. + for _, param := range myStrings { + fmt.Println("param:", param) + } + + // Передати значення аргументів як параметр змінної величини. + fmt.Println("params:", fmt.Sprintln(myStrings...)) + + learnErrorHandling() +} + +func learnErrorHandling() { + // Ідіома ", ok"використовується, щоб перевірити виконання команди без помилок. + m := map[int]string{3: "three", 4: "four"} + if x, ok := m[1]; !ok { // ok буде мати значення false, тому що 1 не знаходиться + // в асоціативному масиві. + fmt.Println("немає таких") + } else { + fmt.Print(x) // x буде мати значення 1, якщо 1 знаходиться в m. + } + // Значення помилки повідомляє не тільки, що все добре, але й може розповісти + // більше про проблему. + if _, err := strconv.Atoi("non-int"); err != nil { // _ ігнорує значення + // виводить помилку 'strconv.ParseInt: parsing "non-int": invalid syntax' + fmt.Println(err) + } + // Ми розглянемо інтерфейси дещо пізніше. А поки, розглянемо багатопоточність. + learnConcurrency() +} + +// Канал с - це потокозохищений об'єкт для спілкування між потоками. +func inc(i int, c chan int) { + c <- i + 1 // Оператор <- виконує операцію "надіслати",якщо змінна каналу + // знаходиться зліва від нього. +} + +// inc виконує збільшення значення на 1. Ми використаємо його, щоб збільшувати +// числа рівночасно. +func learnConcurrency() { + // вже знайома функція make, яка раніше використовувалась для виділення пам'яті, + // тут використовується для створення каналу. Make виділяє пам'ять та ініціалізує + // зрізи, асоційовані масиви та канали. Новостворений канал буде передавати + // цілочисельні значення. + c := make(chan int) + // Запустити три одночасні ґорутини. Числа будуть збільшуватись рівночасно, імовірно + // паралельно якщо пристрій здатний до цього та правильно сконфігурований. + // Всі три ґорутини надсилають значення в один канал. + go inc(0, c) // Твердження go запускає нову ґорутину. + go inc(10, c) + go inc(-805, c) + // Читаємо три результати з каналу та друкуємо їх. + // Порядок результатів - невідомий! + fmt.Println(<-c, <-c, <-c) // якщо канал знаходиться справа від оператора <-, + // він виконує функцію "приймача". + + cs := make(chan string) // Ще один канал, який примає рядки. + ccs := make(chan chan string) // Канал каналів рядків. + go func() { c <- 84 }() // Запустимо нову ґорутину, щоб надіслати значення в канал с. + go func() { cs <- "wordy" }() // Надсилаємо "wordy" в канал cs. + // Ключове слово select має синтаксис, подібний до switch, проте кожен кейс + // включає в себе операцію з каналом. Він обирає довільний кейс з наявних, які готові + // комунікувати (передавати дані). + select { + case i := <-c: // Отримане значення може бути присвоєно змінній, + fmt.Printf("it's a %T", i) + case <-cs: // або значення може бути проігнороване. + fmt.Println("it's a string") + case <-ccs: // Пустий канал, не готовий комунікувати. + fmt.Println("Не відбудеться.") + } + // На цьому етапі, значення було прочитане або з с або з cs. Одна з двох + // ґорутин завершилась, але інша все ще заблокована. + + learnWebProgramming() // Go вміє й у веб. Так, ти хочеш зробити це. +} + +// Лиш одна функція з пакету http запускає веб сервер. +func learnWebProgramming() { + + // перший аргумент ListenAndServe - це TCP адреса, який сервер буде слухати. + // Другий аргумент - це інтерфейс, а точніше http.Handler. + go func() { + err := http.ListenAndServe(":8080", pair{}) + fmt.Println(err) // не ігноруйте помилки + }() + + requestServer() +} + +// pair матиме тип http.Handler, якщо реалізувати один його метод, ServeHTTP. +func (p pair) ServeHTTP(w http.ResponseWriter, r *http.Request) { + // Відповідати на запити можна методом, що належить http.ResponseWriter. + w.Write([]byte("Ти вивчив Go за Y хвилин!")) +} + +func requestServer() { + resp, err := http.Get("http://localhost:8080") + fmt.Println(err) + defer resp.Body.Close() + body, err := ioutil.ReadAll(resp.Body) + fmt.Printf("\nWebserver said: `%s`", string(body)) +} +``` + +## Подальше вивчення + +Основним джерелом всієї інформації про Go залишається [офіційна веб-сторінка](http://golang.org/). Там можна знайти уроки, інтерактивно пограти та багато про що почитати. +Окрім туру, у [документації](https://golang.org/doc/) міститься інформація як писати чистий та ефективний код на Go, документація пакетів та окремих команд, а також історія релізів. + +Надзвичайно рекомендується ознайомитись із визначенням мови. Вона легко читається та на диво коротка (в порівнянні з іншими сучасними мовами). + +Можна погратись з кодом вище на [Go playground](https://play.golang.org/p/tnWMjr16Mm). Спробуй змінити його та запустити із свого браузера. Поміть, що можна використовувати [https://play.golang.org](https://play.golang.org) як [REPL](https://uk.wikipedia.org/wiki/REPL) до тестів та коду в твоєму браузері, без встановлення Go. + +В списку для прочитання новачкам в Go - [вихідний код стандартної бібліотеки](http://golang.org/src/pkg/). Код всеосяжно задокоментований, тому є найкращим прикладом з боку зручного для прочитання та швидкості розуміння коду на цій мові програмування. Приведений стиль та ідіоми Go. +Крім того, можна просто натиснути на назву функції в [документації](http://golang.org/pkg/), щоб перейти до її реалізації. + +Іншим прекрасним посиланням для вивчення Go є [Go by example](https://gobyexample.com/). + +Go Mobile додає підтримку мобільних платформ (Android та iOS). Можна написати нативний код на Go для мобільних застосунків або написати бібліотеку, що міститиме прив'язки (bindings) з пакету Go, які можуть бути викликані з Java (Android) та Objective-C (iOS). Деталі можна дізнатись на [веб-сторінці Go Mobile](https://github.com/golang/go/wiki/Mobile). diff --git a/uk-ua/kotlin-ua.html.markdown b/uk-ua/kotlin-ua.html.markdown new file mode 100644 index 00000000..5e79cc48 --- /dev/null +++ b/uk-ua/kotlin-ua.html.markdown @@ -0,0 +1,464 @@ +--- +language: kotlin +filename: LearnKotlin-uk.kt +lang: uk-ua +contributors: + - ["S Webber", "https://github.com/s-webber"] +translators: + - ["AstiaSun", "https://github.com/AstiaSun"] +--- + +Kotlin - це мова програмування зі статичною типізацією для JVM, Android та браузера. +Вона має 100% сумісність із Java. + +[Детальніше](https://kotlinlang.org/) + +```kotlin +// Однорядкові коментарі починаються з // +/* +Такий вигляд мають багаторядкові коментарі +*/ + +// Ключове слово package працює так само, як і в Java. +package com.learnxinyminutes.kotlin + +/* +Точкою входу для програм на Kotlin є функція під назвою main. +Вона приймає масив із аргументів, що були передані через командний рядок. +Починаючи з Kotlin 1.3, функція main може бути оголошена без параметрів взагалі. +*/ +fun main(args: Array<String>) { + /* + Оголошення змінних відбувається за допомогою ключових слів var або val. + Відмінність між ними полягає в тому, що значення змінних, оголошених через + val, не можна змінювати. Водночас, змінній "var" можна переприсвоїти нове + значення в подальшому. + */ + val fooVal = 10 // більше ми не можемо змінити значення fooVal на інше + var fooVar = 10 + fooVar = 20 // fooVar може змінювати значення + + /* + В більшості випадків Kotlin може визначати, якого типу змінна, тому не + потрібно щоразу точно вказувати її тип. + Тип змінної вказується наступним чином: + */ + val foo: Int = 7 + + /* + Рядки мають аналогічне з Java представлення. Спеціальні символи + позначаються за допомогою зворотнього слеша. + */ + val fooString = "My String Is Here!" + val barString = "Printing on a new line?\nNo Problem!" + val bazString = "Do you want to add a tab?\tNo Problem!" + println(fooString) + println(barString) + println(bazString) + + /* + Необроблений рядок розмежовується за допомогою потрійних лапок ("""). + Необроблені рядки можуть містити переніс рядка (не спеціальний символ \n) та + будь-які інші символи. + */ + val fooRawString = """ +fun helloWorld(val name : String) { + println("Hello, world!") +} +""" + println(fooRawString) + + /* + Рядки можуть містити шаблонні вирази. + Шаблонний вираз починається із символа доллара "$". + */ + val fooTemplateString = "$fooString has ${fooString.length} characters" + println(fooTemplateString) // => My String Is Here! has 18 characters + + /* + Щоб змінна могла мати значення null, потрібно це додатково вказати. + Для цього після оголошеного типу змінної додається спеціальний символ "?". + Отримати значення такої змінної можна використавши оператор "?.". + Оператор "?:" застосовується, щоб оголосити альтернативне значення змінної + у випадку, якщо вона буде рівна null. + */ + var fooNullable: String? = "abc" + println(fooNullable?.length) // => 3 + println(fooNullable?.length ?: -1) // => 3 + fooNullable = null + println(fooNullable?.length) // => null + println(fooNullable?.length ?: -1) // => -1 + + /* + Функції оголошуються з використанням ключового слова fun. + Аргументи функції перелічуються у круглих дужках після назви функції. + Аргументи можуть мати значення за замовчуванням. Тип значення, що повертатиметься + функцією, вказується після оголошення аргументів за необхідністю. + */ + fun hello(name: String = "world"): String { + return "Hello, $name!" + } + println(hello("foo")) // => Hello, foo! + println(hello(name = "bar")) // => Hello, bar! + println(hello()) // => Hello, world! + + /* + Аргументи функції можуть бути помічені ключовим словом vararg. Це дозволяє + приймати довільну кількість аргументів функції зазначеного типу. + */ + fun varargExample(vararg names: Int) { + println("Argument has ${names.size} elements") + } + varargExample() // => Argument has 0 elements + varargExample(1) // => Argument has 1 elements + varargExample(1, 2, 3) // => Argument has 3 elements + + /* + Коли функція складається з одного виразу, фігурні дужки не є обов'язковими. + Тіло функції вказується після оператора "=". + */ + fun odd(x: Int): Boolean = x % 2 == 1 + println(odd(6)) // => false + println(odd(7)) // => true + + // Якщо тип значення, що повертається функцією, може бути однозначно визначено, + // його непотрібно вказувати. + fun even(x: Int) = x % 2 == 0 + println(even(6)) // => true + println(even(7)) // => false + + // Функції можуть приймати інші функції як аргументи, а також повертати інші функції. + fun not(f: (Int) -> Boolean): (Int) -> Boolean { + return {n -> !f.invoke(n)} + } + // Іменовані функції можуть бути вказані як аргументи за допомогою оператора "::". + val notOdd = not(::odd) + val notEven = not(::even) + // Лямбда-вирази також можуть бути аргументами функції. + val notZero = not {n -> n == 0} + /* + Якщо лямбда-вираз приймає лише один параметр, його оголошення може бути пропущене + (разом із ->). Всередині виразу до цього параметра можна звернутись через + змінну "it". + */ + val notPositive = not {it > 0} + for (i in 0..4) { + println("${notOdd(i)} ${notEven(i)} ${notZero(i)} ${notPositive(i)}") + } + + // Ключове слово class використовується для оголошення класів. + class ExampleClass(val x: Int) { + fun memberFunction(y: Int): Int { + return x + y + } + + infix fun infixMemberFunction(y: Int): Int { + return x * y + } + } + /* + Щоб створити новий об'єкт, потрібно викликати конструктор класу. + Зазначте, що в Kotlin немає ключового слова new. + */ + val fooExampleClass = ExampleClass(7) + // Методи класу викликаються через крапку. + println(fooExampleClass.memberFunction(4)) // => 11 + /* + Якщо функція була позначена ключовим словом infix, тоді її можна викликати через + інфіксну нотацію. + */ + println(fooExampleClass infixMemberFunction 4) // => 28 + + /* + Класи даних - це лаконічний спосіб створювати класи, що містимуть тільки дані. + Методи "hashCode"/"equals" та "toString" автоматично генеруються. + */ + data class DataClassExample (val x: Int, val y: Int, val z: Int) + val fooData = DataClassExample(1, 2, 4) + println(fooData) // => DataClassExample(x=1, y=2, z=4) + + // Класи даних також мають функцію "copy". + val fooCopy = fooData.copy(y = 100) + println(fooCopy) // => DataClassExample(x=1, y=100, z=4) + + // Об'єкти можуть бути деструктурувані кількома способами. + val (a, b, c) = fooCopy + println("$a $b $c") // => 1 100 4 + + // деструктурування у циклі for + for ((a, b, c) in listOf(fooData)) { + println("$a $b $c") // => 1 100 4 + } + + val mapData = mapOf("a" to 1, "b" to 2) + // Map.Entry також деструктурувуються + for ((key, value) in mapData) { + println("$key -> $value") + } + + // Функція із "with" працює майже так само як це ж твердження у JavaScript. + data class MutableDataClassExample (var x: Int, var y: Int, var z: Int) + val fooMutableData = MutableDataClassExample(7, 4, 9) + with (fooMutableData) { + x -= 2 + y += 2 + z-- + } + println(fooMutableData) // => MutableDataClassExample(x=5, y=6, z=8) + + /* + Список можна створити використовуючи функцію listOf. + Список буде незмінним, тобто елементи не можна буде додавати або видаляти. + */ + val fooList = listOf("a", "b", "c") + println(fooList.size) // => 3 + println(fooList.first()) // => a + println(fooList.last()) // => c + // доступ до елементів здійснюється через їхні порядковий номер. + println(fooList[1]) // => b + + // Змінні списки можна створити використовуючи функцію mutableListOf. + val fooMutableList = mutableListOf("a", "b", "c") + fooMutableList.add("d") + println(fooMutableList.last()) // => d + println(fooMutableList.size) // => 4 + + // Функція setOf створює об'єкт типу множина. + val fooSet = setOf("a", "b", "c") + println(fooSet.contains("a")) // => true + println(fooSet.contains("z")) // => false + + // mapOf створює асоціативний масив. + val fooMap = mapOf("a" to 8, "b" to 7, "c" to 9) + // Доступ до значень в асоціативних масивах здійснюється через їхні ключі. + println(fooMap["a"]) // => 8 + + /* + Послідовності представлені як колекції лінивих обчислень. Функція generateSequence + створює послідовність. + */ + val fooSequence = generateSequence(1, { it + 1 }) + val x = fooSequence.take(10).toList() + println(x) // => [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] + + // Приклад використання послідовностей, генерація чисел Фібоначчі: + fun fibonacciSequence(): Sequence<Long> { + var a = 0L + var b = 1L + + fun next(): Long { + val result = a + b + a = b + b = result + return a + } + + return generateSequence(::next) + } + val y = fibonacciSequence().take(10).toList() + println(y) // => [1, 1, 2, 3, 5, 8, 13, 21, 34, 55] + + // Kotlin має функції вищого порядку для роботи з колекціями. + val z = (1..9).map {it * 3} + .filter {it < 20} + .groupBy {it % 2 == 0} + .mapKeys {if (it.key) "even" else "odd"} + println(z) // => {odd=[3, 9, 15], even=[6, 12, 18]} + + // Цикл for може використовуватись з будь-чим, що має ітератор. + for (c in "hello") { + println(c) + } + + // Принцип роботи циклів "while" не відрізняється від інших мов програмування. + var ctr = 0 + while (ctr < 5) { + println(ctr) + ctr++ + } + do { + println(ctr) + ctr++ + } while (ctr < 10) + + /* + if може бути використаний як вираз, що повертає значення. Тому тернарний + оператор ?: не потрібний в Kotlin. + */ + val num = 5 + val message = if (num % 2 == 0) "even" else "odd" + println("$num is $message") // => 5 is odd + + // "when" використовується як альтернатива ланцюгам "if-else if". + val i = 10 + when { + i < 7 -> println("first block") + fooString.startsWith("hello") -> println("second block") + else -> println("else block") + } + + // "when" може приймати аргумент. + when (i) { + 0, 21 -> println("0 or 21") + in 1..20 -> println("in the range 1 to 20") + else -> println("none of the above") + } + + // "when" також може використовуватись як функція, що повертає значення. + var result = when (i) { + 0, 21 -> "0 or 21" + in 1..20 -> "in the range 1 to 20" + else -> "none of the above" + } + println(result) + + /* + Тип об'єкта можна перевірити використавши оператор is. Якщо перевірка проходить + успішно, тоді можна використовувати об'єкт як данний тип не приводячи до нього + додатково. + */ + fun smartCastExample(x: Any) : Boolean { + if (x is Boolean) { + // x тепер має тип Boolean + return x + } else if (x is Int) { + // x тепер має тип Int + return x > 0 + } else if (x is String) { + // x тепер має тип String + return x.isNotEmpty() + } else { + return false + } + } + println(smartCastExample("Hello, world!")) // => true + println(smartCastExample("")) // => false + println(smartCastExample(5)) // => true + println(smartCastExample(0)) // => false + println(smartCastExample(true)) // => true + + // Smartcast (розумне приведення) також працює з блоком when + fun smartCastWhenExample(x: Any) = when (x) { + is Boolean -> x + is Int -> x > 0 + is String -> x.isNotEmpty() + else -> false + } + + /* + Розширення - це ще один спосіб розширити функціонал класу. + Подібні методи розширення реалізовані у С#. + */ + fun String.remove(c: Char): String { + return this.filter {it != c} + } + println("Hello, world!".remove('l')) // => Heo, word! +} + +// Класи перелічення також подібні до тих типів, що і в Java. +enum class EnumExample { + A, B, C // Константи перелічення розділені комами. +} +fun printEnum() = println(EnumExample.A) // => A + +// Оскільки кожне перелічення - це об'єкт класу enum, воно може бути +// проініціалізоване наступним чином: +enum class EnumExample(val value: Int) { + A(value = 1), + B(value = 2), + C(value = 3) +} +fun printProperty() = println(EnumExample.A.value) // => 1 + +// Кожне перелічення має властивості, які дозволяють отримати його ім'я +// та порядок (позицію) в класі enum: +fun printName() = println(EnumExample.A.name) // => A +fun printPosition() = println(EnumExample.A.ordinal) // => 0 + +/* +Ключове слово object можна використати для створення об'єкту сінглтону. Об'єкт не +можна інстанціювати, проте на його унікальний екземпляр можна посилатись за іменем. +Подібна можливість є в сінглтон об'єктах у Scala. +*/ +object ObjectExample { + fun hello(): String { + return "hello" + } + + override fun toString(): String { + return "Hello, it's me, ${ObjectExample::class.simpleName}" + } +} + + +fun useSingletonObject() { + println(ObjectExample.hello()) // => hello + // В Kotlin, "Any" - це корінь ієрархії класів, так само, як і "Object" у Java. + val someRef: Any = ObjectExample + println(someRef) // => Hello, it's me, ObjectExample +} + + +/* +Оператор перевірки на те, що об'єкт не рівний null, (!!) перетворює будь-яке значення в ненульовий тип і кидає виняток, якщо значення рівне null. +*/ +var b: String? = "abc" +val l = b!!.length + +// Далі - приклади перевизначення методів класу Any в класі-насліднику +data class Counter(var value: Int) { + // перевизначити Counter += Int + operator fun plusAssign(increment: Int) { + this.value += increment + } + + // перевизначити Counter++ та ++Counter + operator fun inc() = Counter(value + 1) + + // перевизначити Counter + Counter + operator fun plus(other: Counter) = Counter(this.value + other.value) + + // перевизначити Counter * Counter + operator fun times(other: Counter) = Counter(this.value * other.value) + + // перевизначити Counter * Int + operator fun times(value: Int) = Counter(this.value * value) + + // перевизначити Counter in Counter + operator fun contains(other: Counter) = other.value == this.value + + // перевизначити Counter[Int] = Int + operator fun set(index: Int, value: Int) { + this.value = index + value + } + + // перевизначити виклик екземпляру Counter + operator fun invoke() = println("The value of the counter is $value") + +} +// Можна також перевизначити оператори через методи розширення. +// перевизначити -Counter +operator fun Counter.unaryMinus() = Counter(-this.value) + +fun operatorOverloadingDemo() { + var counter1 = Counter(0) + var counter2 = Counter(5) + counter1 += 7 + println(counter1) // => Counter(value=7) + println(counter1 + counter2) // => Counter(value=12) + println(counter1 * counter2) // => Counter(value=35) + println(counter2 * 2) // => Counter(value=10) + println(counter1 in Counter(5)) // => false + println(counter1 in Counter(7)) // => true + counter1[26] = 10 + println(counter1) // => Counter(value=36) + counter1() // => The value of the counter is 36 + println(-counter2) // => Counter(value=-5) +} +``` + +### Подальше вивчення + +* [Уроки Kotlin](https://kotlinlang.org/docs/tutorials/) +* [Спробувати попрацювати з Kotlin в браузері](https://play.kotlinlang.org/) +* [Список корисних посилань](http://kotlin.link/) diff --git a/uk-ua/mips-ua.html.markdown b/uk-ua/mips-ua.html.markdown new file mode 100644 index 00000000..8d4517fe --- /dev/null +++ b/uk-ua/mips-ua.html.markdown @@ -0,0 +1,366 @@ +--- +language: "MIPS Assembly" +filename: MIPS.asm +contributors: + - ["Stanley Lim", "https://github.com/Spiderpig86"] +translators: + - ["AstiaSun", "https://github.com/AstiaSun"] +lang: uk-ua +--- + +Мова ассемблера MIPS (англ. Microprocessor without Interlocked Pipeline Stages) була написана для роботи з мікропроцесорами MIPS, парадигма яких була описана в 1981 році [Джоном Геннессі](https://uk.wikipedia.org/wiki/Джон_Лерой_Геннессі). Ці RISC процесори використовуються у таких вбудованих системах, як маршрутизатори та мережеві шлюзи. + +[Детальніше](https://en.wikipedia.org/wiki/MIPS_architecture) + +```asm +# Коментарі позначені як'#' + +# Всі символи після '#' ігноруються лексичним аналізатором асемблера. + +# Зазвичай програми поділяються на .data та .text частини + +.data # У цьому розділі дані зберігаються у пам'яті, виділеній в RAM, подібно до змінних + # в мовах програмування вищого рівня + + # Змінна оголошується наступним чином: [назва]: .[тип] [значення] + # Наприклад: + hello_world: .asciiz "Hello World\n" # Оголосити текстову змінну + num1: .word 42 # word - це чисельний тип 32-бітного розряду + + arr1: .word 1, 2, 3, 4, 5 # Масив чисел + arr2: .byte 'a', 'b' # Масив буквених символів (розмір кожного - 1 байт) + buffer: .space 60 # Виділити місце в RAM + # (не очищується, тобто не заповнюється 0) + + # Розміри типів даних + _byte: .byte 'a' # 1 байт + _halfword: .half 53 # 2 байти + _word: .word 3 # 4 байти + _float: .float 3.14 # 4 байти + _double: .double 7.0 # 8 байтів + + .align 2 # Вирівнювання пам'яті даних, де число + # показує кількість байтів, вирівнених + # у степені 2. (.align 2 означає + # чисельне (word) вирівнювання оскільки + # 2^2 = 4 байти) + +.text # Розділ, що містить інструкції та + # логіку програми + +.globl _main # Оголошує назву інструкції як + # глобальну, тобто, яка є доступною для + # всіх інших файлів + + _main: # програми MIPS виконують інструкції + # послідовно, тобто першочергово код + # буде виконуватись після цієї позначки + + # Виведемо на екран "hello world" + la $a0, hello_world # Завантажує адресу тексту у пам'яті + li $v0, 4 # Завантажує значення системної + # команди (вказуючи тип функціоналу) + syscall # Виконує зазначену системну команду + # з обраним аргументом ($a0) + + # Регістри (використовуються, щоб тримати дані протягом виконання програми) + # $t0 - $t9 # Тимчасові регістри використовуються + # для проміжних обчислень всередині + # підпрограм (не зберігаються між + # викликами функцій) + + # $s0 - $s7 # Збережені регістри, у яких значення + # зберігаються між викликами підпрограм. + # Зазвичай зберігаються у стеку. + + # $a0 - $a3 # Регістри для передачі аргументів для + # підпрограм + # $v0 - $v1 # Регістри для значень, що повертаються + # від викликаної функції + + # Типи інструкції завантаження / збереження + la $t0, label # Скопіювати адресу в пам'яті, де + # зберігається значення змінної label + # в регістр $t0 + lw $t0, label # Скопіювати чисельне значення з пам'яті + lw $t1, 4($s0) # Скопіювати чисельне значення з адреси + # пам'яті регістра зі зміщенням в + # 4 байти (адреса + 4) + lb $t2, label # Скопіювати буквений символ в частину + # нижчого порядку регістра $t2 + lb $t2, 0($s0) # Скопіювати буквений символ з адреси + # в $s0 із зсувом 0 + # Подібне використання і 'lh' для halfwords + + sw $t0, label # Зберегти чисельне значення в адресу в + # пам'яті, що відповідає змінній label + sw $t0, 8($s0) # Зберегти чисельне значення в адресу, + # що зазначена у $s0, та зі зсувом у 8 байтів + # Така ж ідея використання 'sb' та 'sh' для буквених символів та halfwords. + # 'sa' не існує + + +### Математичні операції ### + _math: + # Пам'ятаємо, що попередньо потрібно завантажити дані в пам'ять + lw $t0, num # Із розділа з даними + li $t0, 5 # Або безпосередньо з константи + li $t1, 6 + add $t2, $t0, $t1 # $t2 = $t0 + $t1 + sub $t2, $t0, $t1 # $t2 = $t0 - $t1 + mul $t2, $t0, $t1 # $t2 = $t0 * $t1 + div $t2, $t0, $t1 # $t2 = $t0 / $t1 (Може не підтримуватись + # деякими версіями MARS) + div $t0, $t1 # Виконує $t0 / $t1. Отримати частку можна + # за допомогою команди 'mflo', остаток - 'mfhi' + + # Бітовий зсув + sll $t0, $t0, 2 # Побітовий зсув вліво на 2. Біти вищого порядку + # не зберігаються, нищого - заповнюються 0 + sllv $t0, $t1, $t2 # Зсув вліво зі змінною кількістю у + # регістрі + srl $t0, $t0, 5 # Побітовий зсув вправо на 5 (не зберігає + # біти, біти зліва заповнюються 0) + srlv $t0, $t1, $t2 # Зсув вправо зі змінною кількістю у + # регістрі + sra $t0, $t0, 7 # Побітовий арифметичний зсув вправо + # (зберігає біти) + srav $t0, $t1, $t2 # Зсув вправо зі змінною кількістю у + # регістрі зі збереження значеннь бітів + + # Побітові операції + and $t0, $t1, $t2 # Побітове І (AND) + andi $t0, $t1, 0xFFF # Побітове І з безпосереднім значенням + or $t0, $t1, $t2 # Побітове АБО (OR) + ori $t0, $t1, 0xFFF # Побітове АБО з безпосереднім значенням + xor $t0, $t1, $t2 # Побітова виключна диз'юнкція (XOR) + xori $t0, $t1, 0xFFF # Побітове XOR з безпосереднім значенням + nor $t0, $t1, $t2 # Побітова стрілка Пірса (NOR) + +## Розгалуження ## + _branching: + # В основному інструкції розгалуження мають наступну форму: + # <instr> <reg1> <reg2> <label> + # де label - це назва змінної, в яку ми хочемо перейти, якщо зазначене твердження + # правдиве + + beq $t0, $t1, reg_eq # Перейдемо у розгалуження reg_eq + # якщо $t0 == $t1, інакше - + # виконати наступний рядок + bne $t0, $t1, reg_neq # Розгалужується, якщо $t0 != $t1 + b branch_target # Розгалуження без умови завжди виконується + beqz $t0, req_eq_zero # Розгалужується, якщо $t0 == 0 + bnez $t0, req_neq_zero # Розгалужується, якщо $t0 != 0 + bgt $t0, $t1, t0_gt_t1 # Розгалужується, якщо $t0 > $t1 + bge $t0, $t1, t0_gte_t1 # Розгалужується, якщо $t0 >= $t1 + bgtz $t0, t0_gt0 # Розгалужується, якщо $t0 > 0 + blt $t0, $t1, t0_gt_t1 # Розгалужується, якщо $t0 < $t1 + ble $t0, $t1, t0_gte_t1 # Розгалужується, якщо $t0 <= $t1 + bltz $t0, t0_lt0 # Розгалужується, якщо $t0 < 0 + slt $s0, $t0, $t1 # Інструкція, що посилає сигнал коли + # $t0 < $t1, результат зберігається в $s0 + # (1 - правдиве твердження) + + # Просте твердження якщо (if) + # if (i == j) + # f = g + h; + # f = f - i; + + # Нехай $s0 = f, $s1 = g, $s2 = h, $s3 = i, $s4 = j + bne $s3, $s4, L1 # if (i !=j) + add $s0, $s1, $s2 # f = g + h + + L1: + sub $s0, $s0, $s3 # f = f - i + + # Нижче наведений приклад знаходження максимального значення з 3 чисел + # Пряма трансляція в Java з логіки MIPS: + # if (a > b) + # if (a > c) + # max = a; + # else + # max = c; + # else + # max = b; + # else + # max = c; + + # Нехай $s0 = a, $s1 = b, $s2 = c, $v0 = повернути регістр + ble $s0, $s1, a_LTE_b # якщо (a <= b) розгалуження(a_LTE_b) + ble $s0, $s2, max_C # якщо (a > b && a <=c) розгалуження(max_C) + move $v0, $s1 # інакше [a > b && a > c] max = a + j done # Перейти в кінець програми + + a_LTE_b: # Мітка розгалуження, коли a <= b + ble $s1, $s2, max_C # якщо (a <= b && b <= c) розгалуження(max_C) + move $v0, $s1 # якщо (a <= b && b > c) max = b + j done # Перейти в кінець програми + + max_C: + move $v0, $s2 # max = c + + done: # Кінець програми + +## Цикли ## + _loops: + # Цикл складається з умови виходу та з інструкції переходу після його завершення + li $t0, 0 + while: + bgt $t0, 10, end_while # Коли $t0 менше 10, продовжувати ітерації + addi $t0, $t0, 1 # Збільшити значення + j while # Перейти на початок циклу + end_while: + + # Транспонування 2D матриці + # Припустимо, що $a0 зберігає адресу цілочисельної матриці розмірністю 3 x 3 + li $t0, 0 # Лічильник для i + li $t1, 0 # Лічильник для j + matrix_row: + bgt $t0, 3, matrix_row_end + + matrix_col: + bgt $t1, 3, matrix_col_end + + # ... + + addi $t1, $t1, 1 # Збільшити лічильник стовпця (col) + matrix_col_end: + + # ... + + addi $t0, $t0, 1 + matrix_row_end: + +## Функції ## + _functions: + # Функції - це процедури, що викликаються, приймають аргументи та повертають значення + + main: # Програма починається з головної функції + jal return_1 # jal збереже поточний ПЦ (програмний центр) в $ra, + # а потім перейде до return_1 + + # Як передати аргументи? + # По-перше, ми маємо передати значення аргументів у регістри аргументів + li $a0, 1 + li $a1, 2 + jal sum # Тепер ми можемо викликати функцію + + # Як щодо рекурсії? + # Тут потрібно дещо більше роботи оскільки ми маємо впевнитись, що ми збережемо + # та зчитаємо попередній ПЦ в $ra, оскільки jal автоматично перепише її при виклику + li $a0, 3 + jal fact + + li $v0, 10 + syscall + + # Ця функція повертає 1 + return_1: + li $v0, 1 # Завантажити val в регіст $v0 + jr $ra # Повернутись до попереднього ПЦ і продовжити виконання + + + # Функція з двома аргументами + sum: + add $v0, $a0, $a1 + jr $ra # Повернутись + + # Рекурсивна функція, яка знаходить факторіал + fact: + addi $sp, $sp, -8 # Виділити місце в стеку + sw $s0, ($sp) # Зберегти регістр, що містить поточне число + sw $ra, 4($sp) # Зберегти попередній ПЦ + + li $v0, 1 # Проініціалізувати значення, що повертатиметься + beq $a0, 0, fact_done # Закінчити, якщо параметр 0 + + # Інакше, продовжити рекурсію + move $s0, $a0 # Скопіювати $a0 в $s0 + sub $a0, $a0, 1 + jal fact + + mul $v0, $s0, $v0 # Множення + + fact_done: + lw $s0, ($sp) + lw $ra, ($sp) # Відновити ПЦ + addi $sp, $sp, 8 + + jr $ra + +## Макроси ## + _macros: + # Макроси надзвичайно корисні для заміни блоків коду, що повторюються, за допомогою + # однієї змінної, для покращення читабельності + # Це не заміна функцій. + # Вони мають бути оголошені перед використанням + + # Макрос для виведення нових рядків (оскільки операція досить часто виконується) + .macro println() + la $a0, newline # Значення нового рядка зберігатиметься тут + li $v0, 4 + syscall + .end_macro + + println() # Асемблер скопіює цей блок коду сюди + # перед тим, як виконувати його + + # Можна передавати параметри у макроси. + # Параметри позначаються знаком '%' з довільною назвою + .macro print_int(%num) + li $v0, 1 + lw $a0, %num + syscall + .end_macro + + li $t0, 1 + print_int($t0) + + # Значення також можна передавати безпосередньо в макроси + .macro immediates(%a, %b) + add $t0, %a, %b + .end_macro + + immediates(3, 5) + + # Одночасно із назвами змінних + .macro print(%string) + la $a0, %string + li $v0, 4 + syscall + .end_macro + + print(hello_world) + +## Масиви ## +.data + list: .word 3, 0, 1, 2, 6 # Це масив чисел + char_arr: .asciiz "hello" # Це текстовий масив + buffer: .space 128 # Виділяє блок пам'яті, що + # автоматично не очищується + # Ці блоки пам'яті вирівнені + # вирівнені поруч один з одним + +.text + la $s0, list # Завантажити адресу списку + li $t0, 0 # Лічильник + li $t1, 5 # Довжина списку + + loop: + bgt $t0, $t1, end_loop + + lw $a0, ($s0) + li $v0, 1 + syscall # Вивести число + + addi $s0, $s0, 4 # Розмір числа - 4 байти + addi $t0, $t0, 1 # Збільшити + j loop + end_loop: + +## Включення ## +# Потрібно для імпорту сторонніх файлів у програму (насправді, код з цього файлу +# копіюється та вставляється в місце, де оголошений імпорт) +.include "somefile.asm" + +``` diff --git a/uk-ua/python-ua.html.markdown b/uk-ua/python-ua.html.markdown index 23bc1796..4091e433 100644 --- a/uk-ua/python-ua.html.markdown +++ b/uk-ua/python-ua.html.markdown @@ -9,7 +9,7 @@ contributors: - ["asyne", "https://github.com/justblah"] - ["habi", "http://github.com/habi"] translators: - - ["Oleg Gromyak", "https://github.com/ogroleg"] + - ["Oleh Hromiak", "https://github.com/ogroleg"] filename: learnpython-ua.py --- diff --git a/uk-ua/wasm-ua.html.markdown b/uk-ua/wasm-ua.html.markdown new file mode 100644 index 00000000..34f8cef8 --- /dev/null +++ b/uk-ua/wasm-ua.html.markdown @@ -0,0 +1,226 @@ +--- +language: WebAssembly +lang: uk-ua +filename: learnwasm-ua.wast +contributors: + - ["Dean Shaff", "http://dean-shaff.github.io"] +translators: + - ["Oleh Hromiak", "https://github.com/ogroleg"] +--- + +``` +;; learnwasm-ua.wast + +(module + ;; У WebAssembly весь код знаходиться в модулях. Будь-яка операція + ;; може бути записана за допомогою s-виразу. Також існує синтаксис "стек машини", + ;; втім, він не сумісний з проміжним бінарним представленням коду. + + ;; Формат бінарного проміжного представлення майже повністю сумісний + ;; з текстовим форматом WebAssembly. + ;; Деякі відмінності: + ;; local_set -> local.set + ;; local_get -> local.get + + ;; Код розміщується у функціях + + ;; Типи даних + (func $data_types + ;; WebAssembly має чотири типи даних: + ;; i32 - ціле число, 32 біти + ;; i64 - ціле число, 64 біти (не підтримується у JavaScript) + ;; f32 - число з плаваючою комою, 32 біти + ;; f64 - число з плаваючою комою, 64 біти + + ;; Створити локальну змінну можна за допомогою ключового слова "local". + ;; Змінні потрібно оголошувати на початку функції. + + (local $int_32 i32) + (local $int_64 i64) + (local $float_32 f32) + (local $float_64 f64) + + ;; Змінні, оголошені вище, ще не ініціалізовані, себто, не мають значення. + ;; Давайте присвоїмо їм значення за допомогою <тип даних>.const: + + (local.set $int_32 (i32.const 16)) + (local.set $int_32 (i64.const 128)) + (local.set $float_32 (f32.const 3.14)) + (local.set $float_64 (f64.const 1.28)) + ) + + ;; Базові операції + (func $basic_operations + + ;; Нагадаємо, у WebAssembly будь-що є s-виразом, включно + ;; з математичними виразами або зчитуванням значень змінних + + (local $add_result i32) + (local $mult_result f64) + + (local.set $add_result (i32.add (i32.const 2) (i32.const 4))) + ;; тепер add_result дорівнює 6! + + ;; Для кожної операції потрібно використовувати правильний тип: + ;; (local.set $mult_result (f32.mul (f32.const 2.0) (f32.const 4.0))) ;; Ніт! mult_result має тип f64! + (local.set $mult_result (f64.mul (f64.const 2.0) (f64.const 4.0))) ;; Ніт! mult_result має тип f64! + + ;; У WebAssembly є вбудовані функції накшталт математики та побітових операцій. + ;; Варто зазначити, що тут відсутні вбудовані тригонометричні функції. + ;; Тож нам потрібно: + ;; - написати їх самостійно (не найкраща ідея) + ;; - звідкись їх імпортувати (як саме - побачимо згодом) + ) + + ;; Функції + ;; Параметри вказуються ключовим словом `param`, значення, що повертається - `result` + ;; Поточне значення стеку і є значенням функції, що повертається + + ;; Ми можемо викликати інші функції за допомогою `call` + + (func $get_16 (result i32) + (i32.const 16) + ) + + (func $add (param $param0 i32) (param $param1 i32) (result i32) + (i32.add + (local.get $param0) + (local.get $param1) + ) + ) + + (func $double_16 (result i32) + (i32.mul + (i32.const 2) + (call $get_16)) + ) + + ;; Досі ми не могли що-небудь вивести на консоль і не мали доступу + ;; до високорівневої математики (степеневі функції, обрахунок експоненти або тригонометрія). + ;; Більше того, ми навіть не могли викликати WASM функції у Javascript! + ;; Виклик цих функцій у WebAssembly залежить від того, + ;; де ми знаходимось - чи це Node.js, чи середовище браузера. + + ;; Якщо ми у Node.js, то потрібно виконати два кроки. По-перше, ми маємо сконвертувати + ;; текстове представлення WASM у справжній код webassembly. + ;; Наприклад, ось так (Binaryen): + + ;; wasm-as learn-wasm.wast -o learn-wasm.wasm + + ;; Давай також застосуємо оптимізації: + + ;; wasm-opt learn-wasm.wasm -o learn-wasm.opt.wasm -O3 --rse + + ;; Тепер наш скомпільований WebAssembly можна завантажити у Node.js: + ;; const fs = require('fs') + ;; const instantiate = async function (inFilePath, _importObject) { + ;; var importObject = { + ;; console: { + ;; log: (x) => console.log(x), + ;; }, + ;; math: { + ;; cos: (x) => Math.cos(x), + ;; } + ;; } + ;; importObject = Object.assign(importObject, _importObject) + ;; + ;; var buffer = fs.readFileSync(inFilePath) + ;; var module = await WebAssembly.compile(buffer) + ;; var instance = await WebAssembly.instantiate(module, importObject) + ;; return instance.exports + ;; } + ;; + ;; const main = function () { + ;; var wasmExports = await instantiate('learn-wasm.wasm') + ;; wasmExports.print_args(1, 0) + ;; } + + ;; Цей код зчитує функції з importObject + ;; (вказано у асинхронній JavaScript функції instantiate), а потім експортує функцію + ;; "print_args", яку ми викликаємо у Node.js + + (import "console" "log" (func $print_i32 (param i32))) + (import "math" "cos" (func $cos (param f64) (result f64))) + + (func $print_args (param $arg0 i32) (param $arg1 i32) + (call $print_i32 (local.get $arg0)) + (call $print_i32 (local.get $arg1)) + ) + (export "print_args" (func $print_args)) + + ;; Завантаження даних з пам'яті WebAssembly. + ;; Наприклад, ми хочемо порахувати cos для елементів Javascript масиву. + ;; Нам потрібно отримати доступ до масиву і можливість ітерувати по ньому. + ;; У прикладі нижче ми змінимо існуючий масив. + ;; f64.load і f64.store приймають адресу числа у пам'яті *у байтах*. + ;; Для того, щоб отримати доступ до 3-го елементу масиву, ми маємо передати щось + ;; накшталт (i32.mul (i32.const 8) (i32.const 2)) у функцію f64.store. + + ;; У JavaScript ми викличемо `apply_cos64` таким чином + ;; (використаємо функцію instantiate з попереднього прикладу): + ;; + ;; const main = function () { + ;; var wasm = await instantiate('learn-wasm.wasm') + ;; var n = 100 + ;; const memory = new Float64Array(wasm.memory.buffer, 0, n) + ;; for (var i=0; i<n; i++) { + ;; memory[i] = i; + ;; } + ;; wasm.apply_cos64(n) + ;; } + ;; + ;; Ця функція не буде працювати, якщо ми виділимо пам'ять для (створимо) Float32Array у JavaScript. + + (memory (export "memory") 100) + + (func $apply_cos64 (param $array_length i32) + ;; визначаємо змінну циклу або лічильник + (local $idx i32) + ;; визначаємо змінну для доступу до пам'яті + (local $idx_bytes i32) + ;; константа - кількість байтів у числі типу f64. + (local $bytes_per_double i32) + + ;; визначаємо змінну, яка зберігатиме значення з пам'яті + (local $temp_f64 f64) + + (local.set $idx (i32.const 0)) + (local.set $idx_bytes (i32.const 0)) ;; не обов'язково + (local.set $bytes_per_double (i32.const 8)) + + (block + (loop + ;; записуємо у idx_bytes необхідне зміщення в пам'яті - для поточного числа. + (local.set $idx_bytes (i32.mul (local.get $idx) (local.get $bytes_per_double))) + + ;; отримуємо число з пам'яті (за зміщенням): + (local.set $temp_f64 (f64.load (local.get $idx_bytes))) + + ;; рахуємо cos: + (local.set $temp_64 (call $cos (local.get $temp_64))) + + ;; тепер зберігаємо результат обчислень у пам'ять: + (f64.store + (local.get $idx_bytes) + (local.get $temp_64)) + + ;; або робимо все за один крок (альтернативний код) + (f64.store + (local.get $idx_bytes) + (call $cos + (f64.load + (local.get $idx_bytes)))) + + ;; збільшуємо лічильник на одиницю (інкремент) + (local.set $idx (i32.add (local.get $idx) (i32.const 1))) + + ;; якщо лічильник дорівнює довжині масиву, то завершуємо цикл + (br_if 1 (i32.eq (local.get $idx) (local.get $array_length))) + (br 0) + ) + ) + ) + (export "apply_cos64" (func $apply_cos64)) +) + +``` diff --git a/zh-cn/yaml-cn.html.markdown b/zh-cn/yaml-cn.html.markdown index de933d12..3ba2afd8 100644 --- a/zh-cn/yaml-cn.html.markdown +++ b/zh-cn/yaml-cn.html.markdown @@ -33,8 +33,13 @@ scientific_notation: 1e+12 boolean: true null_value: null key with spaces: value -# 注意到字符串不需要被括在引号中。但是，它们可以被括起来。 -"Keys can be quoted too.": "Useful if you want to put a ':' in your key." +# 注意，字符串不必被括在引号中，但也可以被括起来。 +however: 'A string, enclosed in quotes.' +'Keys can be quoted too.': "Useful if you want to put a ':' in your key." +single quotes: 'have ''one'' escape pattern' +double quotes: "have many: \", \0, \t, \u263A, \x0d\x0a == \r\n, and more." +# UTF-8/16/32 字符需要被转义(encoded) +Superscript two: \u00B2 # 多行字符串既可以写成像一个'文字块'(使用 |)， # 或像一个'折叠块'(使用 '>')。 @@ -73,8 +78,8 @@ a_nested_map: # 键也可以是复合型的，比如多行对象 # 我们用 ? 后跟一个空格来表示一个复合键的开始。 ? | - This is a key - that has multiple lines + This is a key + that has multiple lines : and this is its value # YAML 也允许使用复杂键语法表示序列间的映射关系。 @@ -85,6 +90,7 @@ a_nested_map: : [ 2001-01-01, 2002-02-02 ] # 序列 (等价于列表或数组) 看起来像这样： +# 注意 '-' 算作缩进 a_sequence: - Item 1 - Item 2 @@ -95,6 +101,8 @@ a_sequence: - - This is a sequence - inside another sequence + - - - Nested sequence indicators + - can be collapsed # 因为 YAML 是 JSON 的超集，你也可以写 JSON 风格的映射和序列： json_map: {"key": "value"} @@ -157,15 +165,18 @@ gif_file: !!binary | # YAML 还有一个集合类型，它看起来像这样： set: - ? item1 - ? item2 - ? item3 + ? item1 + ? item2 + ? item3 +or: {item1, item2, item3} # 集合只是值为 null 的映射；上面的集合等价于： set2: - item1: null - item2: null - item3: null + item1: null + item2: null + item3: null + +... # document end ``` ### 更多资源 |