diff options
| -rw-r--r-- | bc.html.markdown | 98 | ||||
| -rw-r--r-- | c++.html.markdown | 4 | ||||
| -rw-r--r-- | dhall.html.markdown | 362 | ||||
| -rw-r--r-- | emacs.html.markdown | 320 | ||||
| -rw-r--r-- | es-es/dart-es.html.markdown | 529 | ||||
| -rw-r--r-- | es-es/scala-es.html.markdown | 741 | ||||
| -rw-r--r-- | ja-jp/asciidoc.html.markdown | 135 | ||||
| -rw-r--r-- | ja-jp/python3-jp.html.markdown | 240 | ||||
| -rw-r--r-- | linker.html.markdown | 9 | ||||
| -rw-r--r-- | opengl.html.markdown | 765 | ||||
| -rw-r--r-- | perl6.html.markdown | 5 | ||||
| -rw-r--r-- | pug.html.markdown | 204 | ||||
| -rw-r--r-- | ru-ru/linker-ru.html.markdown | 203 | ||||
| -rw-r--r-- | scala.html.markdown | 2 | ||||
| -rw-r--r-- | swift.html.markdown | 991 | ||||
| -rw-r--r-- | th-th/pascal.th.html.markdown | 2 | ||||
| -rw-r--r-- | typescript.html.markdown | 17 | ||||
| -rw-r--r-- | wolfram.html.markdown | 4 | ||||
| -rw-r--r-- | yaml.html.markdown | 2 | ||||
| -rw-r--r-- | zh-cn/lambda-calculus-cn.html.markdown | 223 | ||||
| -rw-r--r-- | zh-cn/markdown-cn.html.markdown | 58 |
21 files changed, 4487 insertions, 427 deletions
diff --git a/bc.html.markdown b/bc.html.markdown new file mode 100644 index 00000000..9d63acfb --- /dev/null +++ b/bc.html.markdown @@ -0,0 +1,98 @@ +--- +language: bc +contributors: + - ["Btup"] +filename: learnbc.bc +--- +```c +/*This is a multi- +line comment.*/ +# This is also a (one-line) comment! (in GNU bc). + + /*1. Variables and control structures*/ +num = 45 /*All variables save only doubles, and you cannot save + string constants directly.*/ +num = 45; /*You can choose to add a semicolon after + every statement. This is optional.*/ +/*Blocks are denoted using the {} operators(similar to C):*/ +while(num < 50) { + num += 1 /*equivalent to num=num+1. + a = a op b is equivalent to a op= b.*/ +} +/*And there are ++(increment) and --(decrement) operators.*/ +/*There are 3 special variables: +scale: defines the scale of the double numbers. +ibase: defines the base of input. +obase: defines the base of output.*/ +/*If clauses:*/ +hour = read() /*Input a number*/ + +if(hour < 12) { /*Operators are exactly like C.*/ + print "Good morning\n" /*"print" outputs strings or variables + separated by commas.*/ +} else if(hour == 12) { + print "Hello\n" + /*Escaping sequences start with a \ in a string. + In order to make the escaping sequences clearer, here + is a simplified list of them that will work in bc: + \b: backspace + \c: carriage return + \n: newline + \t: tab + \\: backslash*/ +} else { + /*Variables are global by default.*/ + thisIsGlobal = 5 + /*You can make a variable local. Use the "auto" keyword in a function.*/ +} + +/*Every variable is pre-set to 0.*/ +num = blankVariable /*num is set to 0.*/ + +/*Like C, only 0 is falsy.*/ +if(!num) {print "false\n"} + +/*Unlike C, bc does not have the ?: operators. For example, + this block of code will cause an error: +a = (num) ? 1 : 0 +However, you can simulate one:*/ +a = (num) && (1) || (0) /*&& is and, || is or*/ + +/*For loops*/ +num = 0 +for(i = 1; i <= 100; i++) {/*Similar to the C for loop.*/ + num += i +} + + /*2.Functions and Arrays*/ +define fac(n) { /*define a function using define.*/ + if(n == 1 || n == 0) { + return 1 /*return a value*/ + } + return n * fac(n - 1) /*recursion is possible*/ +} + +/*Closures and anonymous functions are impossible.*/ + +num = fac(4) /*24*/ + +/*This is an example of local variables:*/ +define x(n) { + auto x + x = 1 + return n + x +} +x(3) /*4*/ +print x /*It turns out that x is not accessible out of the function.*/ +/*Arrays are equivalent to the C array.*/ +for(i = 0; i <= 3; i++) { + a[i] = 1 +} +/*Access it like this:*/ +print a[0], " ", a[1], " ", a[2], " ", a[3], "\n" +quit /*Add this line of code to make sure +that your program exits. This line of code is optional.*/ +``` +Enjoy this simple calculator! (Or this programming language, to be exact.) + +This whole program is written in GNU bc. To run it, use ```bc learnbc.bc```. diff --git a/c++.html.markdown b/c++.html.markdown index 80ad3a6c..fc9f6ce2 100644 --- a/c++.html.markdown +++ b/c++.html.markdown @@ -553,10 +553,14 @@ Point Point::operator+(const Point& rhs) const return Point(x + rhs.x, y + rhs.y); } +// It's good practice to return a reference to the leftmost variable of +// an assignment. `(a += b) == c` will work this way. Point& Point::operator+=(const Point& rhs) { x += rhs.x; y += rhs.y; + + // `this` is a pointer to the object, on which a method is called. return *this; } diff --git a/dhall.html.markdown b/dhall.html.markdown new file mode 100644 index 00000000..21126c8a --- /dev/null +++ b/dhall.html.markdown @@ -0,0 +1,362 @@ +--- +language: Dhall +filename: learndhall.dhall +contributors: + - ["Gabriel Gonzalez", "http://www.haskellforall.com/"] +--- + +Dhall is a programmable configuration language that provides a non-repetitive +alternative to YAML. + +You can think of Dhall as: JSON + functions + types + imports + +Note that while Dhall is programmable, Dhall is not Turing-complete. Many +of Dhall's features take advantage of this restriction to provider stronger +safety guarantees and more powerful tooling. + +```haskell +-- Single-line comment + +{- Multi-line comment + + Unicode is fine 🙂 + + This file is a valid Dhall expression that evaluates to a large record + collecting the results of each step. + + You can view the results by interpreting the file: + + $ dhall --file learndhall.dhall + + {- Comments can be nested -} +-} + +let greeting = "Hello, world!" + +let fruits = "🍋🍓🍍🍉🍌" + +let interpolation = "Enjoy some delicious fruit: ${fruits}" + +let multilineText {- Inline comments work, too -} = + '' + Leading whitespace is stripped from multi-line text literals. + + That means you can freely indent or dedent a text literal without + changing the result. + + Relative indentation within the literal is still preserved. + + Other than that, the text literal is preserved verbatim, similar to a + "literal" YAML multiline string. + '' + +let bool = True + +-- Type annotations on bindings are optional, but helpful, so we'll use them +let annotation : Bool = True + +let renderedBool : Text = if bool then "True" else "False" + +-- Natural numbers are non-negative and are unsigned +let naturalNumber : Natural = 42 + +-- Integers may be negative, but require an explicit sign, even if positive +let positiveInteger : Integer = +1 + +let negativeInteger : Integer = -12 + +let pi : Double = 3.14159265359 + +{- You can use a wider character range for identifiers (such as quotation + marks and whitespace) if you quote them using backticks +-} +let `Avogadro's Number` : Double = 6.0221409e+23 + +let origin : { x : Double, y : Double } = { x = 0.0, y = 0.0 } + +let somePrimes : List Natural = [ 2, 3, 5, 7, 11 ] + +{- A schema is the same thing as a type + + Types begin with an uppercase letter by convention, but this convention is + not enforced +-} +let Profile : Type + = { person : + { name : Text + , age : Natural + } + , address : + { country : Text + , state : Text + , city : Text + } + } + +let john : Profile = + { person = + { name = "John Doe" + , age = 67 + } + , address = + { country = "United States" + , state = "Pennsylvania" + , city = "Philadelphia" + } + } + +let philadelphia : Text = john.address.city + +{- Enum alternatives also begin with an uppercase letter by convention. This + convention is not enforced +-} +let DNA : Type = < Adenine | Cytosine | Guanine | Thymine > + +let dnaSequence : List DNA = [ DNA.Thymine, DNA.Guanine, DNA.Guanine ] + +let compactDNASequence : List DNA = + let a = DNA.Adenine + let c = DNA.Cytosine + let g = DNA.Guanine + let t = DNA.Thymine + in [ c, t, t, a, t, c, g, g, c ] + +-- You can transform enums by providing a record with one field per alternative +let theLetterG : Text = + merge + { Adenine = "A" + , Cytosine = "C" + , Guanine = "G" + , Thymine = "T" + } + DNA.Guanine + +let presentOptionalValue : Optional Natural = Some 1 + +let absentOptionalValue : Optional Natural = None Natural + +let points : List { x : Double, y : Double } = + [ { x = 1.1, y = -4.2 } + , { x = 4.4, y = -3.0 } + , { x = 8.2, y = -5.5 } + ] + +{- `Natural -> List Natural` is the type of a function whose input type is a + `Natural` and whose output type is a `List Natural` + + All functions in Dhall are anonymous functions (a.k.a. "lambdas"), + which you can optionally give a name + + For example, the following function is equivalent to this Python code: + + lambda n : [ n, n + 1 ] + + ... and this JavaScript code: + + function (n) { return [ n, n + 1 ]; } +-} +let exampleFunction : Natural -> List Natural = + \(n : Natural) -> [ n, n + 1 ] + +-- Dhall also supports Unicode syntax, but this tutorial will stick to ASCII +let unicodeFunction : Natural → List Natural = + λ(n : Natural) → [ n, n + 1 ] + +-- You don't need to parenthesize function arguments +let exampleFunctionApplication : List Natural = + exampleFunction 2 + +let functionOfMultipleArguments : Natural -> Natural -> List Natural = + \(x : Natural) -> \(y : Natural) -> [ x, y ] + +let functionAppliedToMultipleArguments : List Natural = + functionOfMultipleArguments 2 3 + +{- Same as `exampleFunction` except we gave the function's input type a + name: "n" +-} +let namedArgumentType : forall (n : Natural) -> List Natural = + \(n : Natural) -> [ n, n + 1 ] + +{- If you name a function's input type, you can use that name later within the + same type + + This lets you write a function that works for more than one type of input + (a.k.a. a "polymorphic" function) +-} +let duplicate : forall (a : Type) -> a -> List a = + \(a : Type) -> \(x : a) -> [ x, x ] + +let duplicatedNumber : List Natural = + duplicate Natural 2 + +let duplicatedBool : List Bool = + duplicate Bool False + +{- The language also has some built-in polymorphic functions, such as: + + List/head : forall (a : Type) -> List a -> Optional a +-} +let firstPrime : Optional Natural = List/head Natural somePrimes + +let functionOfARecord : { x : Natural, y : Natural } -> List Natural = + \(args : { x : Natural, y : Natural }) -> [ args.x, args.y ] + +let functionAppliedToARecord : List Natural = + functionOfARecord { x = 2, y = 5 } + +{- All type conversions are explicit + + `Natural/show` is a built-in function of the following type: + + Natural/show : Natural -> Text + + ... that converts `Natural` numbers to their `Text` representation +-} +let typeConversion : Natural -> Text = + \(age : Natural) -> "I am ${Natural/show age} years old!" + +-- A template is the same thing as a function whose output type is `Text` +let mitLicense : { year : Natural, copyrightHolder : Text } -> Text = + \(args : { year : Natural, copyrightHolder : Text }) -> +'' +Copyright ${Natural/show args.year} ${args.copyrightHolder} + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +'' + +-- Template instantiation is the same thing as function application +let templatedLicense : Text = + mitLicense { year = 2019, copyrightHolder = "Jane Smith" } + +{- You can import expressions by URL + + Also, like Bash, you can import code from your local filesystem (not shown) + + Security-conscious users can pin remotely-imported expressions by adding a + semantic integrity check. The interpreter rejects any attempt to tamper with + an expression pinned in this way. However, behavior-preserving refactors + of imported content will not perturb the hash. + + Imported expressions pinned in this way are also locally cached in a + content-addressable store (typically underneath `~/.cache/dhall`) +-} +let Natural/sum : List Natural -> Natural = + https://prelude.dhall-lang.org/Natural/sum + sha256:33f7f4c3aff62e5ecf4848f964363133452d420dcde045784518fb59fa970037 + +let twentyEight : Natural = Natural/sum somePrimes + +-- A package is the same thing as a (possibly nested) record that you can import +let Prelude = https://prelude.dhall-lang.org/package.dhall + +let false : Bool = Prelude.Bool.not True + +-- You can import the raw contents of a file by adding `as Text` to an import +let sourceCode : Text = https://prelude.dhall-lang.org/Bool/not as Text + +-- You can import environment variables, too: +let presentWorkingDirectory = env:PWD as Text + +-- You can provide a fallback expression if an import fails +let home : Optional Text = Some env:HOME ? None Text + +-- Fallback expressions can contain alternative imports of their own +let possiblyCustomPrelude = + env:DHALL_PRELUDE + ? https://prelude.dhall-lang.org/package.dhall + +{- Tie everything together by auto-generating configurations for 10 build users + using the `generate` function: + + Prelude.List.generate + : Natural -> forall (a : Type) -> (Natural -> a) -> List a +-} +let buildUsers = + let makeUser = \(user : Text) -> + let home = "/home/${user}" + let privateKey = "${home}/.ssh/id_ed25519" + let publicKey = "${privateKey}.pub" + in { home = home + , privateKey = privateKey + , publicKey = publicKey + } + + let buildUser = + \(index : Natural) -> makeUser "build${Natural/show index}" + + let Config = + { home : Text + , privateKey : Text + , publicKey : Text + } + + in Prelude.List.generate 10 Config buildUser + +-- Present all of the results in a final record +in { greeting = greeting + , fruits = fruits + , interpolation = interpolation + , multilineText = multilineText + , bool = bool + , annotation = annotation + , renderedBool = renderedBool + , naturalNumber = naturalNumber + , positiveInteger = positiveInteger + , negativeInteger = negativeInteger + , pi = pi + , `Avogadro's Number` = `Avogadro's Number` + , origin = origin + , somePrimes = somePrimes + , john = john + , philadelphia = philadelphia + , dnaSequence = dnaSequence + , compactDNASequence = compactDNASequence + , theLetterG = theLetterG + , presentOptionalValue = presentOptionalValue + , absentOptionalValue = absentOptionalValue + , points = points + , exampleFunction = exampleFunction + , unicodeFunction = unicodeFunction + , exampleFunctionApplication = exampleFunctionApplication + , functionOfMultipleArguments = functionOfMultipleArguments + , functionAppliedToMultipleArguments = functionAppliedToMultipleArguments + , namedArgumentType = namedArgumentType + , duplicate = duplicate + , duplicatedNumber = duplicatedNumber + , duplicatedBool = duplicatedBool + , firstPrime = firstPrime + , functionOfARecord = functionOfARecord + , functionAppliedToARecord = functionAppliedToARecord + , typeConversion = typeConversion + , mitLicense = mitLicense + , templatedLicense = templatedLicense + , twentyEight = twentyEight + , false = false + , sourceCode = sourceCode + , presentWorkingDirectory = presentWorkingDirectory + , home = home + , buildUsers = buildUsers + } +``` + +To learn more, visit the official website, which also lets you try the +language live in your browser: + +* [https://dhall-lang.org](http://dhall-lang.org/) diff --git a/emacs.html.markdown b/emacs.html.markdown new file mode 100644 index 00000000..ff4d3c03 --- /dev/null +++ b/emacs.html.markdown @@ -0,0 +1,320 @@ +--- +category: tool +tool: emacs +filename: emacs.txt +contributors: + - ["Joseph Riad", "https://github.com/Joseph-Riad"] +--- + +Emacs started its life as ["the extensible, customizable display +editor"](https://www.gnu.org/software/emacs/emacs-paper.html) and grew +over the years into a full-blown ecosystem. Many tasks, usually +relegated to a diverse set of tools can be accomplished from within +Emacs in a consistent, familiar interface. Examples include directory +management, viewing PDF documents, editing files over SSH, managing git +repos,… (the list is quite long). In short, Emacs is yours to make of it +what you will: the spectrum of users varies from those who use it to +edit text files to extreme purists who use it to virtually replace their +operating system. + +Emacs is extensible via a specialized dialect of Lisp known as Emacs +Lisp (Elisp) which has a lot of macros geared towards editing text and +managing text buffers. Any key (combination) you use in Emacs is bound +to an Emacs Lisp function and may be remapped to any other function, +including ones you write +yourself. + +# Key Notation + +``` text +The Emacs manual and the community in general uses a convention to refer to different key combinations used within Emacs. Specifically, Emacs has the notion of a "modifier key" that is pressed along with another key to modify its action. + +An example of this notation is "C-c". In this key combination "C" is the modifier and stands for the "Ctrl" key and "c" is the key whose action is being modified (the literal character "c"). + +The modifier shorthand: +"C-" --> The "CTRL" key +"M-" --> The "Meta" key (usually, the "Alt" key) +"s-" --> The "Super" key (the "Cmd" key on Macs and the "Windows" key on PCs) + +There are other, less commonly used modifiers that I will not get into here. + +The key combination "C-x C-s" means you press "Ctrl+x" followed by "Ctrl+s" + +In addition to the above modifiers, the special keys "Esc", "Return (Enter)" and "Shift" are denoted by "ESC", "RET" and "S", respectively. +``` + +# Basic Emacs Concepts + +Here, I discuss some basic Emacs concepts and terminology that may be +confusing to newcomers (especially to people used to Vim terminology) + + - A bunch of text that Emacs is editing is known as a **buffer** + - A buffer does not necessarily correspond to an actual file on disk. + It may be just a bunch of text in memory. + - When a buffer corresponds to a file on disk, we say that the buffer + is **visiting** that file. + - Emacs typically has many buffers open at once. + - The display of Emacs may be split into different **windows** (not to + be confused with your operating system's windows: the operating + system window for Emacs can have multiple Emacs windows inside it). + - An operating system window for Emacs is called an Emacs **frame**. + Thus, when the Emacs manual talks about opening a new frame, this + essentially means opening a new OS *window* containing an(other) + instance of Emacs. + - The concepts conventionally known as cutting and pasting are + referred to as **killing** and **yanking**, respectively in Emacs + parlance. + - The current position of the cursor is called the **point** in Emacs. + Technically, **point** is defined as the position right before the + character where the cursor currently is. + - Finally, each buffer may have several **modes** associated with it: + a **major mode** and possibly several **minor modes**. + - The **major mode** defines the main behavior of Emacs in the + currently selected buffer. This can be roughly thought of as the + file type. For example, if you're editing a Python file, the major + mode is (by default) `python-mode` which causes Emacs to highlight + Python syntax and automatically indent and outdent your code blocks + as syntactically required by your Python code. + - **Minor modes** define subtle changes in behavior and several minor + modes may be active at once in the same buffer. An example minor + mode is `flyspell-mode` which automatically highlights spelling + errors in your +buffer. + +# Navigation Basics + +``` text +The GUI version of Emacs can be navigated with the mouse like you would expect from a conventional GUI text editor. + +The aim here is to focus on navigation solely using the keyboard as this enhances productivity immensely. + + +* Line movement + +C-n --> Next line +C-p --> Previous line + +* Character movement + +C-f --> Go forward one character +C-b --> Go backward one character + +* Word movement + +M-f --> Go forward one word +M-b --> Go backward one word + +* Sentence movement + +M-a --> Move to the beginning of the sentence +M-e --> Move to the end of the sentence + +* Beginning and end of line + +C-a --> Move to the beginning of the line +C-e --> Move to the end of the line + +* Beginning and end of buffer + +M-< ("Meta+Shift+,") --> Go to the beginning of the buffer +M-> ("Meta+Shift+.") --> Go to the end of the buffer + +* Screen movement + +C-v --> Scroll down by one screen-full (the last two lines of the previous screen are kept as overlap for a smoother transition) +M-v --> Scroll up by one screen-full (same as above but with the first two lines) + +* Centering the screen + +C-l --> Move current line to the screen's center + +The above key combination actually cycles through different states depending on how many times it's been pressed. + +C-l --> Move current line to the screen's center +C-l C-l --> Move current line to the top of the screen +C-l C-l C-l --> Restore the position of the current line to where it was before the first C-l was pressed + +If you press "C-l" a 4th time, it cycles back to centering the current line. + +* Repeating movement commands + +Most movement commands take a numerical prefix argument that says "repeat the following command that many times". + +Example: + +C-u 3 C-p --> Go up 3 lines +C-u 5 C-f --> Go forward 5 characters + +One notable exception are the screen scrolling commands: + +C-u 3 C-v --> Scroll downward 3 lines (maintaining the position of the cursor) +``` + +Bonus: many of the above navigation commands are the default navigation +commands in Bash (e.g. pressing "C-b" while entering a Bash command +takes you back one +character). + +# File editing basics + +``` text +* Quitting Emacs [ Now you can't say you don't know how to quit Emacs :-) ] + +C-x C-c --> Quit Emacs and get prompted to save any unsaved files (buffers not visiting a file will simply be discarded unless you're running in client-server mode) + +* Saving a buffer + +C-x C-s --> Save the current buffer. If not visiting a file, it will prompt you for a file name to use to save the buffer. + +* Searching within a buffer + +C-s --> Search forwards within the buffer. Search is incremental and case-insensitive by default. + Press C-s to move to the next match. + If you press "RET", point is moved to the currently highlighted word and the search ends. +C-r --> Same as C-s except it searches backward + +C-_ or C-/ --> Undo the last action. Keep pressing it to move up the undo tree. +C-? or M-_ --> Redo the previous change + +The "undo" and "redo" commands can take prefix numerical arguments to undo or redo that many actions: + +C-u 3 C-_ --> Undo the last 3 changes. +``` + +# Executing Elisp Functions + +``` text +You can execute any currently loaded Elisp functions (including ones you have written yourself) via "M-x" + +M-x RET --> Prompts you for name of function to execute (Tab completion is available). + +Example: + +M-x RET search-forward-regexp RET --> Prompts you for a regular expression and searches forward in the buffer for it +``` + +# Emacs Configuration + +Emacs is configured using Elisp. On startup, it looks for a +configuration file either in `~/.emacs` or `~/.emacs.d/init.el` where +`~` refers to your home directory. If you're on Windows, consult [this +article](https://www.gnu.org/software/emacs/manual/html_node/efaq-w32/Location-of-init-file.html) +for the appropriate location of your configuration file. + +# Vim inside Emacs + +If you are considering the transition from Vim to Emacs and you're put +off by the non-modal nature of Emacs editing, there is an Emacs +extension known as `evil-mode` which lets you have many Vim concepts +inside Emacs. Here are some things added to Emacs by `evil-mode`: + + - Modal editing: you get normal, insert, visual and block visual modes + like Vim. In addition, you get an "Emacs" mode where movement and + navigation follow the Emacs bindings. + - Same movement keys as Vim in normal mode + - Leader key combinations + - Pressing ":" in normal mode allows you to execute commands + (including system commands) + +In my own experience, `evil-mode` helps make the transition seamless and +allows you to blend the arguably more intuitive and ergonomic +keybindings of Vim with the unbridled power of Emacs for a truly +superior editing experience. + +# Discoverable Help + +Emacs features a pretty powerful help system that allows you to discover +new functionality all the +time. + +``` text +Obtaining help on specific topics. Tab completion is available for function and variable names. + +C-h f RET --> Prompts you for the name of an elisp function and + displays help text on it along with a clickable link + to its source code. +C-h v RET --> Same as above with variables + +C-h k RET --> Allows you to enter a key combination and displays the + name of the elisp function bound to it. + +Searching for help: + +C-h a --> Prompts you for a string to search for a command in the + help system. Similar to the 'apropos' or 'man -k' + commands in Unix systems. + +Starting a tutorial: + +C-h C-t --> Starts a tutorial designed to familiarize you with + basic Emacs functionality. +``` + +# Emacs "Killer Apps" + +As I hinted above, Emacs functionality goes way beyond being a mere text +editor. I will list here a couple of Emacs "apps" that are fairly +powerful and popular and may interest you in and of themselves. + +## Org + +Technnically, `org-mode`, a major mode for buffer editing that provides +organizational tools. It is very difficult to succinctly describe what +Org can do because it's a behemoth of a tool that has many diverse uses +to different people. I will attempt to describe the main features I use +briefly. + + - Divide your file into sections and sub-sections for easy outlining + and organizing of concepts. + - Different headings in the outline are foldable/expandable so that + you can focus on what you need to focus on and eliminate + distractions. + - You can maintain a TODO list within Org + - You can compile TODO lists from many files into an agenda + - Track the time you spend on each TODO task + - Manage tables in plain text (including spreadsheet-like + capabilities) + - Using the extension `org-babel`, write and execute code blocks in + your file. The results are captured and are re-usable within the + file itself. Think Jupyter notebook for any language. + - Display inline images and LaTeX formulas as images within your file + (makes for a great note-taking system and/or personal wiki) + - Export your file into many different formats (LaTeX, PDF, html,…) + +Org mode is a very powerful tool to add to your productivity arsenal +and, on a personal note, was the reason that caused me to start using +Emacs after years of using Vim. + +## Magit + +This is a frontend to `git` from within Emacs. It features a very +intuitive and discoverable interface, yet exposes very powerful +functionality that allows you to manage commits at the chunk level, +inspect diffs, rebase, cherry-pick, … all from within the comfort of +your own editor. + +# A Word of Advice + +If you are considering using Emacs, a common trap that beginning users +fall into is to copy someone else's configuration file and use it as is. +I highly recommend against doing this for several reasons: + + - It will discourage you from learning and finding things out for + yourself + - Someone else's configuration will probably contain many things + relevant to them that you won't need or ever use. + - It defeats the purpose of having a customizable text editor that can + fit your own needs. + +What I encourage you to do is to look at other people's configurations +and seek to understand them and adapt only what makes sense to you. You +can find out about new features of Emacs through many YouTube videos, +screencasts or blog posts and then learn for yourself how to add them to +your configuration and workflow. This way, you grow your configuration +incrementally while increasing your knowledge of Emacs along the way. + +# Additional Resources + + - [The GNU Emacs Manual](https://www.gnu.org/software/emacs/manual/emacs.html) + - [Emacs Stack Exchange](https://emacs.stackexchange.com/) + - [Emacs Wiki](https://www.emacswiki.org/emacs/EmacsWiki) diff --git a/es-es/dart-es.html.markdown b/es-es/dart-es.html.markdown new file mode 100644 index 00000000..d0f57b95 --- /dev/null +++ b/es-es/dart-es.html.markdown @@ -0,0 +1,529 @@ +--- +language: dart +contributors: + - ["Joao Pedrosa", "https://github.com/jpedrosa/"] +translators: + - ["Jorge Antonio Atempa", "http://www.twitter.com/atempa09"] +filename: dart-es.md +lang: es-es +--- + +Dart es un recién llegado al ámbito de los lenguajes de programación. +Toma prestado mucho de otros lenguajes principales, con el objetivo de no desviarse demasiado de +su hermano JavaScript. Tal como JavaScript, Dart tiene como objetivo una gran integración en el navegador. + +La característica más controvertida de Dart debe ser su escritura opcional. + +```dart +import "dart:collection"; +import "dart:math" as DM; + +// Bienvenido a Aprende Dart en 15 minutos. http://www.dartlang.org/ +// Este es un tutorial ejecutable. Puedes ejecutarlo con Dart o en +// el sitio de ¡Try Dart! solo copiando y pegando en http://try.dartlang.org/ + +// La declaración de función y de método tienen el mismo aspecto. +// Las funciones pueden estar anidadas. +// La declaración toma la forma name() {} o name() => expresionEnUnaLinea; +// La declaración de la función de flecha gorda, tiene un retorno implícito +// para el resultado de la expresión. +example1() { + nested1() { + nested2() => print("example1 anidado 1 anidado 2"); + nested2(); + } + nested1(); +} + +// Las funciones anónimas no incluyen un nombre. +example2() { + nested1(fn) { + fn(); + } + nested1(() => print("example2 anidado 1")); +} + +// Cuando se declara un parámetro de función, la declaración puede incluir el +// número de parámetros que toma la función especificando los nombres de los +// parámetros que lleva. +example3() { + planA(fn(informSomething)) { + fn("example3 plan A"); + } + planB(fn) { // O no declarar el número de parámetros. + fn("example3 plan B"); + } + planA((s) => print(s)); + planB((s) => print(s)); +} + +// Las funciones tienen acceso de cierre a variables externas. +var example4Something = "Example4 anidado 1"; +example4() { + nested1(fn(informSomething)) { + fn(example4Something); + } + nested1((s) => print(s)); +} + +// La declaración de la clase con un método sayIt, el cual también tiene acceso de cierre +// a la variable exterior como si fuera una función como se ha visto antes. +var example5method = "example5 sayIt"; +class Example5Class { + sayIt() { + print(example5method); + } +} +example5() { + // Crear una instancia anónima de Example5Class y la llamada del método sayIt + new Example5Class().sayIt(); +} + +// La declaración de clase toma la forma NombreDeClase { [cuerpoDeClase] }. +// Donde cuerpoDeClase puede incluir métodos de instancia y variables, pero también +// métodos y variables de clase. +class Example6Class { + var instanceVariable = "Example6 variable de instancia"; + sayIt() { + print(instanceVariable); + } +} +example6() { + new Example6Class().sayIt(); +} + +// Los métodos y variables de clase son declarados con términos "static". +class Example7Class { + static var classVariable = "Example7 variable de clase"; + static sayItFromClass() { + print(classVariable); + } + sayItFromInstance() { + print(classVariable); + } +} +example7() { + Example7Class.sayItFromClass(); + new Example7Class().sayItFromInstance(); +} + +// Las literales son geniales, pero hay una restricción para lo que pueden ser las literales +// fuera de los cuerpos de función/método. Literales en el ámbito exterior de clase +// o fuera de clase tienen que ser constantes. Las cadenas de caracteres y los números +// son constantes por defecto. Pero los arreglos y mapas no lo son. +// Ellos pueden hacerse constante anteponiendo en la declaración el término "const". +var example8Array = const ["Example8 arreglo constante"], + example8Map = const {"algunaKey": "Example8 mapa constante"}; +example8() { + print(example8Array[0]); + print(example8Map["algunaKey"]); +} + +// Los bucles en Dart toman la forma estándar para for () {} o ciclos while () {} , +// ligeramente más moderno for (.. in ..) {}, o llamadas funcionales con muchas +// características soportadas, comenzando con forEach. +var example9Array = const ["a", "b"]; +example9() { + for (var i = 0; i < example9Array.length; i++) { + print("example9 ciclo for '${example9Array[i]}'"); + } + var i = 0; + while (i < example9Array.length) { + print("example9 ciclo while '${example9Array[i]}'"); + i++; + } + for (var e in example9Array) { + print("example9 ciclo for-in '${e}'"); + } + example9Array.forEach((e) => print("example9 ciclo forEach '${e}'")); +} + +// Para recorrer los caracteres de una cadena o para extraer una subcadena. +var example10String = "ab"; +example10() { + for (var i = 0; i < example10String.length; i++) { + print("example10 Recorrido de caracteres en la cadena '${example10String[i]}'"); + } + for (var i = 0; i < example10String.length; i++) { + print("example10 ciclo de subcadena '${example10String.substring(i, i + 1)}'"); + } +} + +// Formato de números Int y double son soportados. +example11() { + var i = 1 + 320, d = 3.2 + 0.01; + print("example11 int ${i}"); + print("example11 double ${d}"); +} + +// DateTime ofrece aritmética de fecha/hora. +example12() { + var now = new DateTime.now(); + print("example12 ahora '${now}'"); + now = now.add(new Duration(days: 1)); + print("example12 manana '${now}'"); +} + +// Expresiones regulares son soportadas. +example13() { + var s1 = "alguna cadena", s2 = "alguna", re = new RegExp("^s.+?g\$"); + match(s) { + if (re.hasMatch(s)) { + print("example13 regexp embona '${s}'"); + } else { + print("example13 regexp no embona '${s}'"); + } + } + match(s1); + match(s2); +} + +// Las expresiones booleanas admiten conversiones implícitas y tipos dinámicos. +example14() { + var a = true; + if (a) { + print("true, a is $a"); + } + a = null; + if (a) { + print("true, a es $a"); + } else { + print("false, a es $a"); // corre aquí + } + + // el tipado dinámico null puede convertirse a bool + var b; // b es de tipo dinámico + b = "abc"; + try { + if (b) { + print("true, b es $b"); + } else { + print("false, b es $b"); + } + } catch (e) { + print("error, b es $b"); // esto podría ser ejecutado pero consiguió error + } + b = null; + if (b) { + print("true, b es $b"); + } else { + print("false, b es $b"); // corre aquí + } + + // tipado estático null no puede ser convertido a bool + var c = "abc"; + c = null; + // compilación fallida + // if (c) { + // print("true, c is $c"); + // } else { + // print("false, c is $c"); + // } +} + +// try/catch/finally y throw son utilizados para el manejo de excepciones. +// throw toma cualquier objeto como parámetro; +example15() { + try { + try { + throw "Algun error inesperado."; + } catch (e) { + print("example15 una excepcion: '${e}'"); + throw e; // Re-throw + } + } catch (e) { + print("example15 atrapa la excepcion que ha sido relanzada: '${e}'"); + } finally { + print("example15 aún ejecuta finally"); + } +} + +// Para ser eficiente cuando creas una cadena larga dinámicamente, usa +// StringBuffer. O podrías unir un arreglo de cadena de caracteres. +example16() { + var sb = new StringBuffer(), a = ["a", "b", "c", "d"], e; + for (e in a) { sb.write(e); } + print("example16 cadena de caracteres dinamica creada con " + "StringBuffer '${sb.toString()}'"); + print("example16 union de arreglo de cadena de caracteres '${a.join()}'"); +} + +// Las cadenas de caracteres pueden ser concatenadas contando solo +// con literales una después de la otra sin algún otro operador necesario. +example17() { + print("example17 " + "concatenar " + "cadenas " + "asi"); +} + +// Las cadenas de caracteres utilizan comilla simple o comillas dobles como delimitadores +// sin ninguna diferencia entre ambas. Esto proporciona flexibilidad que puede ser efectiva +// para evitar la necesidad de 'escapar' el contenido. Por ejemplo, +// las dobles comillas de los atributos HTML. +example18() { + print('Example18 <a href="etc">' + "Don't can't I'm Etc" + '</a>'); +} + +// Las cadenas de caracteres con triple comilla simple o triple comillas dobles +// dividen múltiples lineas e incluyen como delimitador el salto de línea. +example19() { + print('''Example19 <a href="etc"> +Example19 Don't can't I'm Etc +Example19 </a>'''); +} + +// Las cadenas de caracteres cuentan con una extraordinaria característica +// para la interpolación de caracteres utilizando el operador $ +// Con $ { [expresion] }, devolvemos la expresion interpolada. +// $ seguido por el nombre de una variable interpola el contenido de dicha variable. +// $ puede ser escapado con \$ para solo agregarlo a la cadena. +example20() { + var s1 = "'\${s}'", s2 = "'\$s'"; + print("Example20 \$ interpolation ${s1} or $s2 works."); +} + +// Hasta ahora no hemos declarado ningún tipo de dato y los programas +// han funcionado bien. De hecho, los tipos no se toman en cuenta durante +// el tiempo de ejecución. +// Los tipos incluso pueden estar equivocados y al programa todavía se le dará +// el beneficio de la duda y se ejecutará como si los tipos no importaran. +// Hay un parámetro de tiempo de ejecución que comprueba los errores de tipo que es +// el modo de verificación, el cuál es útil durante el tiempo de desarrollo, +// pero que también es más lento debido a la comprobación adicional y, por lo tanto +// se evita durante el tiempo de ejecución de la implementación. +class Example21 { + List<String> _names; + Example21() { + _names = ["a", "b"]; + } + List<String> get names => _names; + set names(List<String> list) { + _names = list; + } + int get length => _names.length; + void add(String name) { + _names.add(name); + } +} +void example21() { + Example21 o = new Example21(); + o.add("c"); + print("example21 nombres '${o.names}' y longitud '${o.length}'"); + o.names = ["d", "e"]; + print("example21 nombres '${o.names}' y longitud '${o.length}'"); +} + +// La herencia de clases toma la forma NombreDeClase extends OtraClase {}. +class Example22A { + var _name = "¡Algun Nombre!"; + get name => _name; +} +class Example22B extends Example22A {} +example22() { + var o = new Example22B(); + print("example22 herencia de clase '${o.name}'"); +} + +// La mezcla de clases también esta disponible y toman la forma de +// NombreDeClase extends AlgunaClase with OtraClase {}. +// Es necesario extender de alguna clase para poder mezclar con otra. +// La clase de plantilla de mixin no puede en este momento tener un constructor. +// Mixin se utiliza principalmente para compartir métodos con clases distantes, +// por lo que la herencia única no interfiere con el código reutilizable. +// Mixins se colocan despues de la palabra "with" durante la declaración de la clase. +class Example23A {} +class Example23Utils { + addTwo(n1, n2) { + return n1 + n2; + } +} +class Example23B extends Example23A with Example23Utils { + addThree(n1, n2, n3) { + return addTwo(n1, n2) + n3; + } +} +example23() { + var o = new Example23B(), r1 = o.addThree(1, 2, 3), + r2 = o.addTwo(1, 2); + print("Example23 addThree(1, 2, 3) results in '${r1}'"); + print("Example23 addTwo(1, 2) results in '${r2}'"); +} + +// El método constructor de la clase utiliza el mismo nombre de la clase +// y toma la forma de AlgunaClase() : super() {}, donde la parte ": super()" +// es opcional y es utilizado para delegar parametros constantes +// al método constructor de la clase padre o super clase. +class Example24A { + var _value; + Example24A({value: "algunValor"}) { + _value = value; + } + get value => _value; +} +class Example24B extends Example24A { + Example24B({value: "algunOtroValor"}) : super(value: value); +} +example24() { + var o1 = new Example24B(), + o2 = new Example24B(value: "aunMas"); + print("example24 llama al método super desde el constructor '${o1.value}'"); + print("example24 llama al método super desde el constructor '${o2.value}'"); +} + +// Hay un atajo para configurar los parámetros del constructor en el caso de clases más simples. +// Simplemente use el prefijo this.nombreParametro y establecerá el parámetro +// en una variable de instancia del mismo nombre. +class Example25 { + var value, anotherValue; + Example25({this.value, this.anotherValue}); +} +example25() { + var o = new Example25(value: "a", anotherValue: "b"); + print("example25 atajo para el constructor '${o.value}' y " + "'${o.anotherValue}'"); +} + +// Los parámetros con nombre están disponibles cuando se declaran entre {}. +// El orden de los parámetros puede ser opcional cuando se declara entre {}. +// Los parámetros pueden hacerse opcionales cuando se declaran entre []. +example26() { + var _name, _surname, _email; + setConfig1({name, surname}) { + _name = name; + _surname = surname; + } + setConfig2(name, [surname, email]) { + _name = name; + _surname = surname; + _email = email; + } + setConfig1(surname: "Doe", name: "John"); + print("example26 name '${_name}', surname '${_surname}', " + "email '${_email}'"); + setConfig2("Mary", "Jane"); + print("example26 name '${_name}', surname '${_surname}', " + "email '${_email}'"); +} + +// Las variables declaradas con final solo se pueden establecer una vez. +// En el caso de las clases, las variables de instancia final se pueden establecer +// a través de la constante del parámetro constructor. +class Example27 { + final color1, color2; + // Un poco de flexibilidad para establecer variables de instancia finales con la sintaxis + // que sigue a : + Example27({this.color1, color2}) : color2 = color2; +} +example27() { + final color = "orange", o = new Example27(color1: "lilac", color2: "white"); + print("example27 color es '${color}'"); + print("example27 color es '${o.color1}' y '${o.color2}'"); +} + +// Para importar una librería utiliza la palabra reservada import "rutaLibrería" o si es una biblioteca central, +// import "dart:NombreLibrería". También está el "pub" administrador de paquetes con +// su propia convensión import "package:NombrePaquete". +// Ve import "dart:collection"; al inicio. Las importaciones deben venir antes +// de la delcaración de algún otro código. IterableBase proviene de dart:collection. +class Example28 extends IterableBase { + var names; + Example28() { + names = ["a", "b"]; + } + get iterator => names.iterator; +} +example28() { + var o = new Example28(); + o.forEach((name) => print("example28 '${name}'")); +} + +// Para el control de flujo tenemos: +// * estandard switch +// * if-else if-else y el operador ternario ..?..:.. +// * closures y funciones anonimas +// * sentencias break, continue y return +example29() { + var v = true ? 30 : 60; + switch (v) { + case 30: + print("example29 sentencia switch"); + break; + } + if (v < 30) { + } else if (v > 30) { + } else { + print("example29 sentencia if-else"); + } + callItForMe(fn()) { + return fn(); + } + rand() { + v = new DM.Random().nextInt(50); + return v; + } + while (true) { + print("example29 callItForMe(rand) '${callItForMe(rand)}'"); + if (v != 30) { + break; + } else { + continue; + } + // Nunca llega aquí. + } +} + +// La sentencia int.parse, convierte de tipo double a int, o simplemente mantener int cuando se dividen los números +// utilizando ~/ como operación. Vamos a jugar un juego de adivinanzas también. +example30() { + var gn, tooHigh = false, + n, n2 = (2.0).toInt(), top = int.parse("123") ~/ n2, bottom = 0; + top = top ~/ 6; + gn = new DM.Random().nextInt(top + 1); // +1 porque nextInt top es exclusivo + print("example30 Adivina un número entre 0 y ${top}"); + guessNumber(i) { + if (n == gn) { + print("example30 ¡Adivinaste correctamente! El número es ${gn}"); + } else { + tooHigh = n > gn; + print("example30 Número ${n} es demasiado " + "${tooHigh ? 'high' : 'low'}. Intenta nuevamente"); + } + return n == gn; + } + n = (top - bottom) ~/ 2; + while (!guessNumber(n)) { + if (tooHigh) { + top = n - 1; + } else { + bottom = n + 1; + } + n = bottom + ((top - bottom) ~/ 2); + } +} + +// Los programas tienen un solo punto de entrada en la función principal. +// No se espera que se ejecute nada en el ámbito externo antes de que un programa +// comience a funcionar con su función principal. +// Esto ayuda con una carga más rápida e incluso con una carga lenta +// de lo que necesita el programa para iniciar. +main() { + print("Learn Dart in 15 minutes!"); + [example1, example2, example3, example4, example5, example6, example7, + example8, example9, example10, example11, example12, example13, example14, + example15, example16, example17, example18, example19, example20, + example21, example22, example23, example24, example25, example26, + example27, example28, example29, example30 + ].forEach((ef) => ef()); +} + +``` + +## Lecturas adicionales + +Dart tiene un sitio web muy completo. Cubre referencias de API, tutoriales, artículos y más, incluyendo una +útil sección en línea Try Dart. +[https://www.dartlang.org](https://www.dartlang.org) +[https://try.dartlang.org](https://try.dartlang.org) diff --git a/es-es/scala-es.html.markdown b/es-es/scala-es.html.markdown new file mode 100644 index 00000000..2dcb9e7f --- /dev/null +++ b/es-es/scala-es.html.markdown @@ -0,0 +1,741 @@ +--- +language: Scala +filename: learnscala-es.scala +contributors: + - ["George Petrov", "http://github.com/petrovg"] + - ["Dominic Bou-Samra", "http://dbousamra.github.com"] + - ["Geoff Liu", "http://geoffliu.me"] + - ["Ha-Duong Nguyen", "http://reference-error.org"] +translators: + - ["Pablo Arranz Ropero", "http://arranzropablo.com"] +lang: es-es +--- + +Scala - El lenguaje escalable + +```scala + +///////////////////////////////////////////////// +// 0. Básicos +///////////////////////////////////////////////// +/* + Configurar Scala: + + 1) Descarga Scala - http://www.scala-lang.org/downloads + 2) Unzip/untar a tu carpeta elegida y pon la subcarpeta bin en tu variable de entorno `PATH` +*/ + +/* + Prueba REPL + + Scala tiene una herramienta llamada REPL (Read-Eval-Print Loop, en español: Bucle de lectura-evaluación-impresión) que es analogo a interpretes de la linea de comandos en muchos otros lenguajes. + Puedes escribir cualquier expresión en Scala y el resultado será evaluado e impreso. + + REPL es una herramienta muy práctica para testear y verificar código. + Puedes usarla mientras lees este tutorial para explorar conceptos por tu cuenta. +*/ + +// Inicia Scala REPL ejecutando `scala` en tu terminal. Deberías ver: +$ scala +scala> + +// Por defecto cada expresión que escribes es guardada como un nuevo valor numerado: +scala> 2 + 2 +res0: Int = 4 + +// Los valores por defecto pueden ser reusados. Fíjate en el tipo del valor mostrado en el resultado... +scala> res0 + 2 +res1: Int = 6 + +// Scala es un lenguaje fuertemente tipado. Puedes usar REPL para comprobar el tipo sin evaluar una expresión. +scala> :type (true, 2.0) +(Boolean, Double) + +// Las sesiones REPL pueden ser guardadas +scala> :save /sites/repl-test.scala + +// Se pueden cargar archivos en REPL +scala> :load /sites/repl-test.scala +Loading /sites/repl-test.scala... +res2: Int = 4 +res3: Int = 6 + +// Puedes buscar en tu historial reciente +scala> :h? +1 2 + 2 +2 res0 + 2 +3 :save /sites/repl-test.scala +4 :load /sites/repl-test.scala +5 :h? + +// Ahora que sabes como jugar, aprendamos un poco de Scala... + +///////////////////////////////////////////////// +// 1. Básicos +///////////////////////////////////////////////// + +// Los comentarios de una linea comienzan con dos barras inclinadas + +/* + Los comentarios de varias lineas, como ya has visto arriba, se hacen de esta manera. +*/ + +// Así imprimimos forzando una nueva linea en la siguiente impresión +println("Hola mundo!") +println(10) +// Hola mundo! +// 10 + +// Así imprimimos sin forzar una nueva linea en la siguiente impresión +print("Hola mundo") +print(10) +// Hola mundo10 + +// Para declarar valores usamos var o val. +// Valores decalrados con val son inmutables, mientras que los declarados con var son mutables. +// La inmutabilidad es algo bueno. +val x = 10 // x es 10 +x = 20 // error: reassignment to val +var y = 10 +y = 20 // y es 20 + +/* + Scala es un lenguaje tipado estáticamente, aunque se puede ver en las expresiones anteriores que no hemos especificado un tipo. + Esto es debido a una funcionalidad del lenguaje llamada inferencia. En la mayoría de los casos, el compilador de Scala puede adivinar cual es el tipo de una variable, así que no hace falta escribirlo siempre. + Podemos declarar explicitamente el tipo de una variable de la siguiente manera: +*/ +val z: Int = 10 +val a: Double = 1.0 + +// Observa la conversión automática de Int a Double, el resultado será 10.0, no 10 +val b: Double = 10 + +// Valores Booleanos +true +false + +// Operaciones Booleanas +!true // false +!false // true +true == false // false +10 > 5 // true + +// Las operaciones matemáticas se realizan como siempre +1 + 1 // 2 +2 - 1 // 1 +5 * 3 // 15 +6 / 2 // 3 +6 / 4 // 1 +6.0 / 4 // 1.5 +6 / 4.0 // 1.5 + + +// Evaluar una expresión en REPL te da el tipo y valor del resultado + +1 + 7 + +/* La linea superior tienen como resultado: + + scala> 1 + 7 + res29: Int = 8 + + Esto quiere decir que el resultado de evaluar 1 + 7 es un objeto de tipo Int con valor 8 + + Observa que "res29" es un nombre de variable secuencialmente generado para almacenar los resultados de las expresiones escritas, la salida que observes puede diferir en este sentido. +*/ + +"Las cadenas en Scala están rodeadas por comillas dobles" +'a' // Un caracter en Scala +// 'Las cadenas con comillas simples no existen' <= Esto causa un error + +// Las cadenas tienen los los típicos metodos de Java definidos +"hello world".length +"hello world".substring(2, 6) +"hello world".replace("C", "3") + +// También tienen algunos métodos extra de Scala. Ver: scala.collection.immutable.StringOps +"hello world".take(5) +"hello world".drop(5) + +// Interpolación de cadenas: Observa el prefijo "s" +val n = 45 +s"Tengo $n manzanas" // => "Tengo 45 manzanas" + +// Es posible colocar expresiones dentro de cadenas interpoladas +val a = Array(11, 9, 6) +s"Mi segunda hija tiene ${a(0) - a(2)} años." // => "Mi segunda hija tiene 5 años." +s"Hemos doblado la cantidad de ${n / 2.0} manzanas." // => "Hemos doblado la cantidad de 22.5 manzanas." +s"Potencia de 2: ${math.pow(2, 2)}" // => "Potencia de 2: 4" + +// Podemos formatear cadenas interpoladas con el prefijo "f" +f"Potencia de 5: ${math.pow(5, 2)}%1.0f" // "Potencia de 5: 25" +f"Raiz cuadrada de 122: ${math.sqrt(122)}%1.4f" // "Raiz cuadrada de 122: 11.0454" + +// Las cadenas puras ignoran caracteres especiales. +raw"Nueva linea: \n. Retorno: \r." // => "Nueva linea: \n. Retorno: \r." + +// Algunos caracteres necesitn ser escapados, por ejemplo unas comillas dobles dentro de una cadena: +"Se quedaron fuera de \"Rose and Crown\"" // => "Se quedaron fuera de "Rose and Crown"" + +// Las triples comillas dobles dejan que las cadenas se expandan por multiples filas y contengan comillas dobles o simples +val html = """<form id="daform"> + <p>Press belo', Joe</p> + <input type="submit"> + </form>""" + + +///////////////////////////////////////////////// +// 2. Funciones +///////////////////////////////////////////////// + +// Las funciones se definen de la siguiente manera: +// +// def nombreFuncion(argumentos...): TipoRetorno = { cuerpo... } +// +// Si estás acostumbrado a lenguajes más tradicionales, observa la omisión de la palabra return. +// En Scala, la última expresión en el bloque de función es el valor de retorno. +def sumaDeCuadrados(x: Int, y: Int): Int = { + val x2 = x * x + val y2 = y * y + x2 + y2 +} + +// Los { } pueden omitirse si el cuerpo de la función es una única expresión: +def sumaDeCuadradosCorta(x: Int, y: Int): Int = x * x + y * y + +// La sintaxis para llamar funciones es familiar: +sumaDeCuadrados(3, 4) // => 25 + +// Puedes usar los nombres de los parámetros para llamarlos en orden diferente +def restar(x: Int, y: Int): Int = x - y + +restar(10, 3) // => 7 +restar(y=10, x=3) // => -7 + +// En la mayoría de los casos (siendo las funciones recursivas la excepción más notable), +// el tipo de retorno de la función puede ser omitido, y la misma inferencia de tipos que vimos con las variables +// funcionará con los valores de retorno de las funciones: +def sq(x: Int) = x * x // El compilador puede adivinar que el tipo de retorno es Int + +// Las funciones pueden tener parametros por defecto: +def sumarConDefecto(x: Int, y: Int = 5) = x + y +sumarConDefecto(1, 2) // => 3 +sumarConDefecto(1) // => 6 + + +// Las funciones anónimas se escriben así: +(x: Int) => x * x + +// Al contrario que los defs, incluso el tipo de entrada de las funciones anónimas puede ser omitido si +// el contexto lo deja claro. Observa el tipo "Int => Int" que significa que es una función +// que recibe Int y retorna Int. +val sq: Int => Int = x => x * x + +// Las funciones anónimas pueden ser llamadas como las demás: +sq(10) // => 100 + +// Si cada argumento en tu función anónima es usado solo una vez, +// Scala te da una manera incluso más corta de definirlos. +// Estas funciones anónimas son extremadamente comunes, +// como será obvio en la sección de estructuras de datos. +val sumarUno: Int => Int = _ + 1 +val sumaRara: (Int, Int) => Int = (_ * 2 + _ * 3) + +sumarUno(5) // => 6 +sumaRara(2, 4) // => 16 + + +// La palabra return existe en Scala, pero solo retorna desde la función más interna que la rodea. +// ADVERTENCIA: Usar return en Scala puede inducir a errores y debe ser evitado +// No tiene efecto en funciones anónimas. Por ejemplo: +def foo(x: Int): Int = { + val funcAnon: Int => Int = { z => + if (z > 5) + return z // Esta línea hace que z sea el valor de retorno de foo! + else + z + 2 // Esta línea es el valor de retorno de funcAnon + } + anonFunc(x) // Esta línea es el valor de retorno de foo +} + + +///////////////////////////////////////////////// +// 3. Control del flujo +///////////////////////////////////////////////// + +1 to 5 +val r = 1 to 5 +r.foreach(println) + +r foreach println +// Nota: Scala es un lenguaje muy permisivo cuando se trata de puntos y parentesis - estudia las +// reglas separadamente. Esto ayuda a escribir DSLs y APIs que se lean en lenguaje natural. + +// Por qué `println` no necesita parámetros aquí? +// Presta atención a las funciones de primera clase en la sección de Programación Funcional más abajo! +(5 to 1 by -1) foreach (println) + +// Un bucle while +var i = 0 +while (i < 10) { println("i " + i); i += 1 } + +while (i < 10) { println("i " + i); i += 1 } // Si, de nuevo. Qué ocurrió? Por qué? + +i // Muestra el valor de i. Observa que while es un loop en el sentido clásico - + // se ejecuta secuencialmente mientras cambia la variable del bucle. while es muy + // rápido, pero los combinadores y comprensiones anteriores son más sencillos + // de entender y paralelizar + +// Un bucle do-while +i = 0 +do { + println("i es aún menor que 10") + i += 1 +} while (i < 10) + +// La recursion es la manera idiomática de repetir una acción en Scala (como en la mayoría de +// lenguajes funcionales). +// Las funciones recursivas necesitan un tipo de retorno explicito, el compilador no puede inferirlo. +// En Scala tenemos Unit, que es análogo al tipo de retorno `void` en Java +def enseñaNumerosEnUnRango(a: Int, b: Int): Unit = { + print(a) + if (a < b) + enseñaNumerosEnUnRango(a + 1, b) +} +enseñaNumerosEnUnRango(1, 14) + + +// Condicionales + +val x = 10 + +if (x == 1) println("yeah") +if (x == 10) println("yeah") +if (x == 11) println("yeah") +if (x == 11) println("yeah") else println("nay") + +println(if (x == 10) "yeah" else "nope") +val text = if (x == 10) "yeah" else "nope" + + +///////////////////////////////////////////////// +// 4. Estructuras de datos +///////////////////////////////////////////////// + +val a = Array(1, 2, 3, 5, 8, 13) +a(0) // Int = 1 +a(3) // Int = 5 +a(21) // Lanza una excepción + +val m = Map("fork" -> "tenedor", "spoon" -> "cuchara", "knife" -> "cuchillo") +m("fork") // java.lang.String = tenedor +m("spoon") // java.lang.String = cuchara +m("bottle") // Lanza una excepción + +val mapaSeguro = m.withDefaultValue("no lo se") +mapaSeguro("bottle") // java.lang.String = no lo se + +val s = Set(1, 3, 7) +s(0) // Boolean = false +s(1) // Boolean = true + +/* Hecha un vistazo a la documentación de Map aquí - + * http://www.scala-lang.org/api/current/index.html#scala.collection.immutable.Map + * y asegúrate de que puedes leerla + */ + + +// Tuplas + +(1, 2) + +(4, 3, 2) + +(1, 2, "three") + +(a, 2, "three") + +// Por qué tener esto? +val dividirEnteros = (x: Int, y: Int) => (x / y, x % y) + +// La función dividirEnteros te da el resultado y el resto +dividirEnteros(10, 3) // (Int, Int) = (3,1) + +// Para acceder a los elementos de una tupla, usa _._n donde n es el indice (comenzando por 1) +// del elemento +val d = dividirEnteros(10, 3) // (Int, Int) = (3,1) + +d._1 // Int = 3 +d._2 // Int = 1 + +// Alternativamente puedes asignar multiples variables desde una tupla, lo que +// resulta más conveniente y legible en muchos casos. +val (div, mod) = dividirEnteros(10, 3) + +div // Int = 3 +mod // Int = 1 + + +///////////////////////////////////////////////// +// 5. Programación Orientada a Objetos +///////////////////////////////////////////////// + +/* + Nota: Todo lo que hemos hecho hasta ahora en este tutorial han sido + simples expresiones (valores, funciones, etc). Estas expresiones son validas + para hacer pruebas rapidas en el interprete de la linea de comandos, + pero no pueden existir por si solas en un archivo de Scala. Por ejemplo, + no puedes tener simplemente "val x = 5" en un archivo Scala. En lugar de eso, + las únicas construcciones de alto nivel en Scala son: + + - Objetos + - Clases + - Case clases + - Traits + + Y ahora explicaremos lo que son estas. +*/ + +// Las clases son similares a las clases de otros lenguajes. Los argumentos del constructor +// son declarados despues del nombre de la clase, y la inicialización se hace en el cuerpo de la clase. +class Perro(r: String) { + // Código del constructor aquí + var raza: String = r + + // Define un método llamado ladrar, que devuelva un String + def ladrar = "Woof, woof!" + + // Los valores y métodos son asumidos como públicos. + // Las palabras "protected" y "private" también son válidas. + private def dormir(horas: Int) = + println(s"Estoy durmiendo $horas horas") + + // Los métodos abstractos son simplemente métodos sin cuerpo. + // Si descomentamos la linea de debajo, la clase Perro necesitaría ser abstracta: + // abstract class Perro(...) { ... } + // def perseguir(algo: String): String +} + +val miperro = new Dog("greyhound") +println(mydog.raza) // => "greyhound" +println(mydog.ladrar) // => "Woof, woof!" + + +// La palabra "object" crea un tipo y una instancia singleton de ese tipo. +// Es común que las clases en Scala tengan un "companion object", de manera que +// el comportamiento por instancia es controlado por las clases y el comportamiento +// relacionado a todas las instancias de esa clase es controlado por el objeto +// La relación es similar a los métodos de las clases con los métodos estáticos +// en otros lenguajes. Observa que los objetos y clases pueden tener el mismo nombre. +object Perro { + def todasLasRazasConocidas = List("pitbull", "shepherd", "retriever") + def crearPerro(raza: String) = new Dog(breed) +} + + +// Case clases son clases que tienen funcionalidad extra añadida. Una pregunta +// común para los principiantes en Scala es cuando usar case clases y cuando usar +// clases. La linea no está bien definida, pero en general, las clases tienden a +// enfocarse en la encapsulación, polimorfismo y comportamiento. Los valores en +// estas clases tienden a ser privados, y solo se exponen los métodos. +// El propósito principal de las case clases es tener datos inmutables. +// A menudo tienen pocos métodos, y los métodos raramente tienen efectos secundarios. +case class Persona(nombre: String, telefono: String) + +// Para crear instancia nuevas, observa que las case clases no necesitan "new" +val george = Persona("George", "1234") +val kate = Persona("Kate", "4567") + +// Con las case clases tienes unas pocas ventajas, como el acceso a los campos: +george.telefono // => "1234" + +// Para la igualdad de campos no necesitas sobreescribir el método equals +Persona("George", "1234") == Persona("Kate", "1236") // => false + +// Manera fácil de copiar +// otroGeorge == Persona("George", "9876") +val otroGeorge = george.copy(telefono = "9876") + +// Y muchas otras. Las case clases también tienen comparación de patrones, que veremos más abajo. + +// Traits +// De manera similar a las interfaces Java, los traits definen un tipo de objeto y métodos. +// Scala permite la implementación parcial de dichos métodos. +// No se permiten parámetros de constructor. Los traits pueden heredar de otros traits o +// clases sin parámetros. + +trait Perro { + def raza: String + def color: String + def ladra: Boolean = true + def muerde: Boolean +} +class SanBernardo extends Perro { + val raza = "San Bernardo" + val color = "marrón" + def muerde = false +} + +scala> b +res0: SanBernardo = SanBernardo@3e57cd70 +scala> b.raza +res1: String = San Bernardo +scala> b.ladra +res2: Boolean = true +scala> b.muerde +res3: Boolean = false + +// Un trait tambien puede ser usado mezclado con otros traits. +// La clase extiende el primer trait, pero la palabra "with" +// puede añadir traits adicionales. + +trait Ladra { + def ladra: String = "Guau" +} +trait Perro { + def raza: String + def color: String +} +class SanBernardo extends Perro with Ladra { + val raza = "San Bernardo" + val color = "marrón" +} + +scala> val b = new SanBernardo +b: SanBernardo = SanBernardo@7b69c6ba +scala> b.ladra +res0: String = Guau + + +///////////////////////////////////////////////// +// 6. Comparación de patrones +///////////////////////////////////////////////// + +// La comparación de patrones es una poderosa función de Scala. +// Ahora veremos como comparar patrones en una case clase. +// Nota: A diferencia de otros lenguajes, Scala "cases" no necesitan +// "break", porque no ejecuta los "case" posteriores. + +def comparaPersona(persona: Persona): String = persona match { + // Aqui especificas los patrones: + case Persona("George", telefono) => "Hemos encontrado a George! Su número es " + telefono + case Persona("Kate", telefono) => "Hemos encontrado a Kate! Su número es " + telefono + case Persona(nombre, telefono) => "Hemos encontrado alguien : " + nombre + ", teléfono : " + telefono +} + +// Las expresiones regulares también están incorporadas. +// Creas una expresión regular con el método `r` en una cadena: +val email = "(.*)@(.*)".r + +// La comparación de patrones puede parecerse al bloque switch en la familia de lenguajes de C, +// pero aquí es mucho más poderosa. En Scala, puedes hacer más comparaciones: +def comparaTodo(obj: Any): String = obj match { + // Puedes comparar valores: + case "Hola mundo" => "Tengo la cadena Hola mundo" + + // Puedes comparar tipos: + case x: Double => "Tengo un double: " + x + + // Puedes especificar condiciones: + case x: Int if x > 10000 => "Tengo un número muy grande!" + + // Puedes comparar case clases como antes: + case Persona(nombre, telefono) => s"Tengo la información de contacto de $nombre!" + + // Puedes comparar expresiones regulares: + case email(nombre, dominio) => s"Tengo la dirección de correo $nombre@$dominio" + + // Puedes comparar tuplas: + case (a: Int, b: Double, c: String) => s"Tengo la tupla: $a, $b, $c" + + // Puedes comparar estructuras: + case List(1, b, c) => s"Tengo un alista con tres elementos que empieza con 1: 1, $b, $c" + + // Puedes anidar patrones: + case List(List((1, 2, "YAY"))) => "Tengo una lista de listas de tuplas" + + // Comparar cualquier case (default) si todos los anteriores no han coincido + case _ => "Tengo un objeto desconocido" +} + +// De hecho puedes comparar un patrón con cualquier objeto con el método "unapply". +// Esta función es tan poderosa que Scala te deja definir funciones enteras como patrones: +val funcPatron: Person => String = { + case Persona("George", telefono) => s"Teléfono de George: $telefono" + case Persona(nombre, telefono) => s"Teléfono de una persona aleatoria: $telefono" +} + + +///////////////////////////////////////////////// +// 7. Programación funcional +///////////////////////////////////////////////// + +// Scala permite a los métodos y funciones devolver o +// recibir como parámetros otras funciones o métodos + +val suma10: Int => Int = _ + 10 // Una función que recibe y devuelve un Int +List(1, 2, 3) map suma10 // List(11, 12, 13) - suma10 es aplicado a cada elemento + +// Las funciones anónimas pueden ser usadas en vez de funciones con nombre: +List(1, 2, 3) map (x => x + 10) + +// Y la barra baja puede ser usada si solo hay un argumento en la función anónima. +// Se usa como la variable. +List(1, 2, 3) map (_ + 10) + +// Si el bloque anónimo Y la función que estás usando usan los dos un argumento, +// puedes incluso omitir la barra baja. +List("Dom", "Bob", "Natalia") foreach println + + +// Combinadores +// Usando s de arriba: +// val s = Set(1, 3, 7) + +s.map(sq) + +val sCuadrado = s. map(sq) + +sSquared.filter(_ < 10) + +sSquared.reduce (_+_) + +// La función filter toma un predicado (una función A -> Boolean) y +// selecciona todos los elementos que satisfacen el predicado. +List(1, 2, 3) filter (_ > 2) // List(3) +case class Persona(nombre: String, edad: Int) +List( + Persona(nombre = "Dom", edad = 23), + Persona(nombre = "Bob", edad = 30) +).filter(_.edad > 25) // List(Persona("Bob", 30)) + + +// Ciertas colecciones (como List) en Scala tienen un método `foreach`, +// que toma como argumento un tipo que devuelva Unit (un método void) +val unaListaDeNumeros = List(1, 2, 3, 4, 10, 20, 100) +unaListaDeNumeros foreach (x => println(x)) +unaListaDeNumeros foreach println + +// Para comprensiones + +for { n <- s } yield sq(n) + +val nCuadrado2 = for { n <- s } yield sq(n) + +for { n <- nSquared2 if n < 10 } yield n + +for { n <- s; nSquared = n * n if nSquared < 10} yield nSquared + +/* Nota: Esos no son bucles. La semántica de un bucle es repetir, mientras que un for de comprension define una relación entre dos conjuntos de datos.*/ + + +///////////////////////////////////////////////// +// 8. Implicitos +///////////////////////////////////////////////// + +/* ATENCIÓN ATENCIÓN: Los implicitos son un conjunto de poderosas características de Scala + * y es fácil abusar de ellos. Si eres principiante en Scala deberías resistir la tentación + * de usarlos hasta que entiendas no solo como funcionan, sino también las mejores prácticas + * con ellos. Nosotros solo incluiremos esta sección en el tutorial porque son tan comunes + * en las librerias de Scala que es imposible hacer algo significativo sin usar una librería + * que tenga implicitos. Esto es para que entiendas como funcionan los implicitos, no para + * que definas los tuyos propios. + */ + +// Cualquier valor (val, funciones, objetos, etc) puede ser declarado como implicito usando +// la palabra "implicit". Observa que usamos la clase Perro de la sección 5. +implicit val miEnteroImplicito = 100 +implicit def miFunciónImplicita(raza: String) = new Perro("Golden " + raza) + +// Por si misma, la palabra implicit no cambia el comportamiento de un valor, +// así que estos valores pueden ser usados como siempre. +miEnteroImplicito + 2 // => 102 +miFunciónImplicita("Pitbull").raza // => "Golden Pitbull" + +// La diferencia es que estos valores ahora pueden ser usados cuando otra pieza de código +// necesite un valor implicito. Una situación así puede darse con argumentos implicitos de función: +def enviaSaludos(aQuien: String)(implicit cuantos: Int) = + s"Hola $aQuien, $cuantos saludos a ti y a los tuyos!" + +// Si proporcionamos un valor para "cuantos", la función se comporta como siempre +enviaSaludos("John")(1000) // => "Hola John, 1000 saludos a ti y a los tuyos!" + +// Pero si omitimos el parámetro implicito, un valor implicito del mismo tipo es usado, +// en este caso, "miEnteroImplicito": +enviaSaludos("Jane") // => "Hello Jane, 100 blessings to you and yours!" + +// Los parámetros de función implicit nos permiten simular clases tipo en otros lenguajes funcionales. +// Es usado tan a menudo que tiene su propio atajo. Las dos siguientes lineas significan lo mismo: +// def foo[T](implicit c: C[T]) = ... +// def foo[T : C] = ... + + +// Otra situación en la que el compilador busca un implicit es si tienes +// obj.método(...) +// pero "obj" no tiene "método" como un método. En este caso, si hay una conversión +// implicita de tipo A => B, donde A es el tipo de obj y B tiene un método llamado +// "método", esa conversión es aplicada. Así que teniendo miFunciónImplicita, podemos decir: +"Retriever".raza // => "Golden Retriever" +"Sheperd".ladra // => "Woof, woof!" + +// Aquí la cadena es convertida primero a Perro usando nuestra función miFunciónImplicita, +// y entonces el método apropiado es llamado. Esta es una herramienta extremadamente poderosa +// pero de nuevo, no puede usarse con ligereza. De hecho, cuando definiste la función implicita, +// tu compilador debería haber mostrado una advertencia, diciendo que no deberías hacer esto +// a no ser que realmente sepas lo que estás haciendo. + +///////////////////////////////////////////////// +// 9. Misc +///////////////////////////////////////////////// + +// Importando cosas +import scala.collection.immutable.List + +// Importando todos los "sub paquetes" +import scala.collection.immutable._ + +// Importando multiples clases en una línea +import scala.collection.immutable.{List, Map} + +// Renombrar un import usando '=>' +import scala.collection.immutable.{List => ImmutableList} + +// Importar todas las clases, excepto algunas. La siguiente linea excluye Map y Set: +import scala.collection.immutable.{Map => _, Set => _, _} + +// Las clases de Java pueden ser importadas también con sintaxis de Scala: +import java.swing.{JFrame, JWindow} + +// El punto de entrada de tus programas está definido en un fichero scala usando un object, +// con un solo método, main: +object Application { + def main(args: Array[String]): Unit = { + // Aquí va tu código. + } +} + +// Los ficheros pueden contener multiples clases y objetos. Compila con scalac + + +// Salida y entrada + +// Leer un fichero línea por línea +import scala.io.Source +for(line <- Source.fromFile("miarchivo.txt").getLines()) + println(line) + +// Para escribir un archivo usa el PrintWriter de Java +val writer = new PrintWriter("miarchivo.txt") +writer.write("Escribiendo linea por linea" + util.Properties.lineSeparator) +writer.write("Otra linea" + util.Properties.lineSeparator) +writer.close() + +``` + +## Más recursos + +* [Scala para los impacientes](http://horstmann.com/scala/) +* [Escuela de Scala en Twitter](http://twitter.github.io/scala_school/) +* [La documentación de Scala](http://docs.scala-lang.org/) +* [Prueba Scala en tu navegador](http://scalatutorials.com/tour/) +* Unete al [grupo de usuarios de Scala](https://groups.google.com/forum/#!forum/scala-user) diff --git a/ja-jp/asciidoc.html.markdown b/ja-jp/asciidoc.html.markdown new file mode 100644 index 00000000..7347589a --- /dev/null +++ b/ja-jp/asciidoc.html.markdown @@ -0,0 +1,135 @@ +--- +language: asciidoc +contributors: + - ["Ryan Mavilia", "http://unoriginality.rocks/"] + - ["Abel Salgado Romero", "https://twitter.com/abelsromero"] +translators: + - ["Ryota Kayanuma", "https://github.com/PicoSushi"] +filename: asciidoc-ja.md +lang: ja-jp +--- + +AsciiDocはMarkdownに似たマークアップ言語で、書籍の執筆からブログを書くことまでなんでも使うことができます。2002年、Stuart RackhamによりAsciiDocは作成され、シンプルでありつつも沢山のカスタマイズを可能にしています。 + +文書のヘッダー + +ヘッダーはオプションで、空行を含むことはできません。本文から1行以上の改行を開ける必要があります。 + +タイトルのみの例 + +``` += 文章タイトル + +文書の最初の行 +``` + +タイトルと著者 + +``` += 文書タイトル +文書 太郎 <first.last@learnxinyminutes.com> + +文書の開始 +``` + +複数の著者 + +``` += 文書タイトル +John Doe <john@go.com>; Jane Doe<jane@yo.com>; Black Beard <beardy@pirate.com> + +複数の著者による文書の始まり。 +``` + +版(著者の行を必要とします) + +``` += 第一版のタイトル +芋男 <chip@crunchy.com> +v1.0, 2016-01-13 + +このポテトについての文書は面白いです。 +``` + +段落 + +``` +段落は特別なことは不要です。 + +空行を段落の間に入れることで、段落を分けることができます。 + +折り返しをしたい場合、+ +を書くことで折り返せます! +``` + +文書の整形 + +``` +_アンダースコアで斜体になります。_ +*アスタリスクで太字になります。* +*_組み合わせると楽しい_* +`バッククォートで固定幅になります。` +`*太字の固定幅*` +``` + +節タイトル + +``` += Level 0 (文書のヘッダーにのみ使用してください) + +== Level 1 <h2> + +=== Level 2 <h3> + +==== Level 3 <h4> + +===== Level 4 <h5> + +``` + +リスト + +箇条書きリストを作るには、アスタリスクを使用してください。 + +``` +* foo +* bar +* baz +``` + +番号付きリストを作るには、ピリオドを使用してください。 + +``` +. item 1 +. item 2 +. item 3 +``` + +リストはアスタリスクやピリオドを追加することで5段階まで入れ子にできます。 + +``` +* foo 1 +** foo 2 +*** foo 3 +**** foo 4 +***** foo 5 + +. foo 1 +.. foo 2 +... foo 3 +.... foo 4 +..... foo 5 +``` + +## 補足資料 + +AsciiDocの文書を処理するツールは2種類あります。 + +1. [AsciiDoc](http://asciidoc.org/): オリジナルのPython実装で、Linuxで利用可能です。現在は開発されておらず、メンテナンスのみの状態です。 +2. [Asciidoctor](http://asciidoctor.org/): Rubyによる別実装で、JavaやJavascriptでも利用可能です。AsciiDocに新しい機能や出力形式を追加するため、現在活発に開発されています。 + +以下のリンクは `AsciiDoctor` 実装関連のものです。 + +* [Markdown - AsciiDoc syntax comparison](http://asciidoctor.org/docs/user-manual/#comparison-by-example): Common MarkdownとAsciidocの要素を並べて比較しています。 +* [Getting started](http://asciidoctor.org/docs/#get-started-with-asciidoctor): インストールから簡潔な文書を作るための簡単なガイドです。 +* [Asciidoctor User Manual](http://asciidoctor.org/docs/user-manual/): 文法のリファレンス、例、描画ツール、その他を含む完全なドキュメントです。 diff --git a/ja-jp/python3-jp.html.markdown b/ja-jp/python3-jp.html.markdown index 3b1a0d73..b9731411 100644 --- a/ja-jp/python3-jp.html.markdown +++ b/ja-jp/python3-jp.html.markdown @@ -6,13 +6,16 @@ contributors: - ["Andre Polykanine", "https://github.com/Oire"] - ["Zachary Ferguson", "http://github.com/zfergus2"] - ["evuez", "http://github.com/evuez"] + - ["Rommel Martinez", "https://ebzzry.io"] + - ["Roberto Fernandez Diaz", "https://github.com/robertofd1995"] translators: - ["kakakaya", "https://github.com/kakakaya"] + - ["Ryota Kayanuma", "https://github.com/PicoSushi"] filename: learnpython3-jp.py lang: ja-jp --- -90年代の初め、Guido Van RossumによってPythonは作成されました。現在となっては、最も有名な言語の1つです。 +90年代の初め、Guido van RossumによってPythonは作成されました。現在となっては、最も有名な言語の1つです。 私は構文の明快さによって、Pythonと恋に落ちました。 以下は基本的に実行可能な疑似コードです。 @@ -21,12 +24,11 @@ lang: ja-jp Note: この記事はPython 3に内容を絞っています。もし古いPython 2.7を学習したいなら、 [こちら](http://learnxinyminutes.com/docs/python/) をご確認下さい。 ```python - # 1行のコメントは番号記号(#)から始まります。 """ 複数行の文字は、"を3つ繋げることで 書くことができます。 - また、これはコメントとしてもよく使われます。 + また、これはドキュメントとしてもよく使われます。 """ #################################################### @@ -44,8 +46,8 @@ Note: この記事はPython 3に内容を絞っています。もし古いPython # 整数除算の結果は、正負に関わらず小数の切り捨てが行われます。 5 // 3 # => 1 -5.0 // 3.0 # => 1.0 # 浮動小数点でも同様に動作します。 -5 // 3 # => -2 +5.0 // 3.0 # => 1.0 # 浮動小数点でも同様に動作します。 -5.0 // 3.0 # => -2.0 # 除算の結果は常に浮動小数点になります。 @@ -55,7 +57,7 @@ Note: この記事はPython 3に内容を絞っています。もし古いPython 7 % 3 # => 1 # 冪乗 (x**y, x の y 乗) -2**4 # => 16 +2**3 # => 8 # 括弧により、計算の順番を優先させられます。 (1 + 3) * 2 # => 8 @@ -69,16 +71,28 @@ not True # => False not False # => True # ブール演算 -# 注意: "and" と "or" は小文字です +# 注意: "and" と "or" は小文字です。 True and False # => False False or True # => True -# 整数でブール演算をするときのメモ -0 and 2 # => 0 --5 or 0 # => -5 +# TrueとFalseは実際には1と0になるキーワードです。 +True + True # => 2 +True * 8 # => 8 +False - 5 # => -5 + +# 比較演算子はTrueとFalseを数値として扱います。 0 == False # => True -2 == True # => False 1 == True # => True +2 == True # => False +-5 != True # => True + +# bool論理演算子を整数に対して使うことで整数を真偽値に変換して評価できますが、キャストされていない値が +# bool(int)とビット演算子(& や |)を混同しないようにうにしましょう。 +bool(0) # => False +bool(4) # => True +bool(-6) # => True +0 and 2 # => 0 +-5 or 0 # => -5 # 値が等しいか確認するには == 1 == 1 # => True @@ -94,7 +108,11 @@ False or True # => True 2 <= 2 # => True 2 >= 2 # => True -# 比較は連結させられます! +# 値がある範囲の中にあるか調べる方法 +1 < 2 and 2 < 3 # => True +2 < 3 and 3 < 2 # => False + +# 連結させるともっと見やすくなります。 1 < 2 < 3 # => True 2 < 3 < 2 # => False @@ -115,7 +133,7 @@ b == a # => True, a と b が参照するオブジェクトの値 # 文字列も加算をすることができます!でも、あまり行わないように。 "Hello " + "world!" # => "Hello world!" -# '+' を使わなくても連結はできます。 +# '+' を使わなくても文字列リテラル(変数ではないもの)の連結ができます。 "Hello " "world!" # => "Hello world!" # 文字列は文字のリストであるかのように扱うことができます。 @@ -138,6 +156,12 @@ len("This is a string") # => 16 # 旧式のフォーマット方法を使うこともできます。 "%s can be %s the %s way" % ("Strings", "interpolated", "old") # => "Strings can be interpolated the old way" +# Python3.6以上では、f-stringsやフォーマット文字列を使ってフォーマットすることもできます。 +name = "Reiko" +f"She said her name is {name}." # => "She said her name is Reiko" + +# 基本的に、任意のPythonの文を中括弧に書くことができ、それは評価されて出力されます。 +f"{name} is {len(name)} characters long." # None はオブジェクトです(大文字からです!) None # => None @@ -170,7 +194,7 @@ print("Hello, World", end="!") # => Hello, World! input_string_var = input("Enter some data: ") # 入力を文字列として返します # Note: Python の初期のバージョンでは、 input() は raw_input() という名前で存在します。 -# 変数に代入する前に宣言する必要はありません。 +# Pythonでは変数の宣言は存在せず、代入のみです。 # 慣例的に、小文字でアンダースコア区切り ( lower_case_with_underscores ) の変数が使われます。 some_var = 5 some_var # => 5 @@ -207,10 +231,11 @@ li[-1] # => 3 li[4] # IndexError が発生します # スライス構文により範囲を参照できます。 +# 開始部分のインデックスに対応する部分は含まれますが、終了部分のインデックスに対応する部分は含まれません。 li[1:3] # => [2, 4] -# 先端を取り除く +# 先端を取り除いたリスト li[2:] # => [4, 3] -# 末尾を取り除く +# 末尾を取り除いたリスト li[:3] # => [1, 2, 4] # 1つ飛ばしで選択する li[::2] # =>[1, 4] @@ -272,7 +297,7 @@ a, b, c = (1, 2, 3) # a, b, c にはそれぞれ 1, 2, 3 が代入 # 拡張記法もあります。 a, *b, c = (1, 2, 3, 4) # a は 1 、 b は [2, 3] 、c は4 になります。 # 括弧を作成しなくてもデフォルトでタプルが作成されます。 -d, e, f = 4, 5, 6 +d, e, f = 4, 5, 6 # 4、5、6がそれぞれd、 e、 fに代入されます。 # 2つの変数を交換するのがどれほど簡単か見てみましょう。 e, d = d, e # d は 5 、 e は e になります。 @@ -293,14 +318,17 @@ filled_dict["one"] # => 1 # "keys()"により、全てのキーを反復可能な形式で取り出せます。 # これをリストにするために、"list()"で囲んでいます。これについては後程解説します。 -# Note: 辞書のキーの順番は考慮されていません。実行した結果がこれと異なる場合があります。 -list(filled_dict.keys()) # => ["three", "two", "one"] +# Note: Python3.7未満では、辞書のキーの順番は考慮されていません。実行した結果がこれと異なる場合があります。 +# しかし、Python3.7以降ではキーの挿入順を保つようになりました。 +list(filled_dict.keys()) # => ["three", "two", "one"] in Python <3.7 +list(filled_dict.keys()) # => ["one", "two", "three"] in Python 3.7+ + # "values()"により、全ての値を反復可能な形式で取り出せます。 # 前と同じように、これをリストにするために、"list()"で囲んでいます。 # Note: 辞書の値の順番は考慮されていません。実行した結果がこれと異なる場合があります。 -list(filled_dict.values()) # => [3, 2, 1] - +list(filled_dict.values()) # => [3, 2, 1] in Python <3.7 +list(filled_dict.values()) # => [1, 2, 3] in Python 3.7+ # "in" により、辞書のキーが存在するか確認できます。 "one" in filled_dict # => True @@ -322,7 +350,7 @@ filled_dict.setdefault("five", 6) # filled_dict["five"] は 5 のままです # 辞書にマップを追加する filled_dict.update({"four": 4}) # => {"one": 1, "two": 2, "three": 3, "four": 4} -# filled_dict["four"] = 4 # 辞書に追加する別の方法 +filled_dict["four"] = 4 # 辞書に追加する別の方法 # del により辞書からキーを削除できます。 del filled_dict["one"] # "one" キーを辞書から削除します。 @@ -341,11 +369,11 @@ some_set = {1, 1, 2, 2, 3, 4} # some_set is now {1, 2, 3, 4} invalid_set = {[1], 1} # => list はハッシュ化できないので、 TypeError が送出されます。 valid_set = {(1,), 1} -# 新しい値を集合にセットできます。 -filled_set = some_set - # 集合に新しい要素を追加できます。 +filled_set = some_set filled_set.add(5) # filled_set は {1, 2, 3, 4, 5} になりました。 +# 集合は重複した要素を持ちません。 +filled_set.add(5) # 以前の{1, 2, 3, 4, 5}のままです。 # & により、集合同士の共通部分が得られます。 other_set = {3, 4, 5, 6} @@ -378,7 +406,8 @@ filled_set | other_set # => {1, 2, 3, 4, 5, 6} # まずは変数を作りましょう。 some_var = 5 -# これはif文です。インデントがPythonでは特徴的ですね! +# これはif文です。Pythonではインデントが特徴的ですね! +# 規約ではタブではなく4つのスペースでインデントすることが推奨されています。 # 以下の例では"some_var is smaller than 10"と出力されます。 if some_var > 10: print("some_var is totally bigger than 10.") @@ -541,9 +570,9 @@ all_the_args(1, 2, a=3, b=4) prints: # * を使ってタプルを展開したり、 ** を使って辞書を展開できます。 args = (1, 2, 3, 4) kwargs = {"a": 3, "b": 4} -all_the_args(*args) # foo(1, 2, 3, 4) に対応します。 -all_the_args(**kwargs) # foo(a=3, b=4) に対応します。 -all_the_args(*args, **kwargs) # foo(1, 2, 3, 4, a=3, b=4) に対応します。 +all_the_args(*args) # all_the_args(1, 2, 3, 4) と等しいです。 +all_the_args(**kwargs) # all_the_args(a=3, b=4) と等しいです。 +all_the_args(*args, **kwargs) # all_the_args(1, 2, 3, 4, a=3, b=4) と等しいです。 # タプルで複数の値を返す @@ -646,7 +675,7 @@ dir(math) # 6. クラス #################################################### -# クラスを作成するために、"class"という演算子を使います。 +# クラスを作成するために、class文を使います。 class Human: # クラスの属性です。このクラスの全てのインスタンスで共有されます。 @@ -656,14 +685,14 @@ class Human: # 2つのアンダースコアがオブジェクトや属性の前後についているとき、これらはPythonによって利用され、 # ユーザーの名前空間には存在しないということに注意してください。 # __init__ や __str__ 、 __repr__ のようなメソッド(やオブジェクト、属性)は、 - # magic methods (または dunder methods)と呼ばれます。 - # このような名前を自分で発明しないほうがよいでしょう。 + # special methods (または dunder methods)と呼ばれます。 + # 同じような名前を自分で発明しないほうがよいでしょう。 def __init__(self, name): # 引数をインスタンスのname属性に設定します。 self.name = name # プロパティの初期化 - self.age = 0 + self._age = 0 # インスタンスメソッド。全てのメソッドは"self"を最初の引数に取ります。 def say(self, msg): @@ -686,6 +715,7 @@ class Human: # プロパティはgetterのようなものです。 # age() メソッドを同名の読取専用属性に変換します。 + # Pythonではわざわざgetterやsetterを書く必要はありません。 @property def age(self): return self._age @@ -720,24 +750,117 @@ if __name__ == '__main__': j.say(j.get_species()) # => "Joel: H. neanderthalensis" # スタティックメソッドを呼んでみましょう。 - print(Human.grunt()) # => "*grunt*" - print(i.grunt()) # => "*grunt*" + print(Human.grunt()) # => "*grunt*" + + # スタティックメソッドはインスタンスから呼ぶことはできません。 + # なぜならば、 i.grunt() は自動的に"self" ( i オブジェクト ) を引数として渡してしまうからです。 + print(i.grunt()) # => TypeError: grunt() takes 0 positional arguments but 1 was given # インスタンスのプロパティを更新してみましょう。 i.age = 42 # プロパティを取得してみましょう。 - i.say(i.age) # => 42 - j.say(j.age) # => 0 + i.say(i.age) # => "Ian: 42" + j.say(j.age) # => "Joel: 0" # プロパティを削除してみましょう。 del i.age # i.age # => AttributeError が発生します。 #################################################### -# 6.1 多重継承 +# 6.1 継承 +#################################################### +# 継承を行うことで、親クラスからメソッドと変数を継承する新しい子クラスを定義できます。 + +# 上記で定義されたHumanクラスを親クラス(基底クラス)として使い、Superheroという子クラスを定義します。 +# これは"species"、"name"や"age"といった変数や、"sing"や"grunt"のようなメソッドをHumanから継承しますが、 +# Superhero独自のプロパティを持つこともできます。 + +# ファイルを分割してモジュール化の利点を活用するために、上記のHumanクラスを独自のファイル、ここでは human.py に記述ましょう。 + +# 別のファイルから関数をインポートするには次の形式を利用してください: +# from "拡張子なしのファイル名" import "関数やクラス" + +from human import Human + + +# 親クラスを子クラスのパラメータとして指定します +class Superhero(Human): + + # もし子クラスが親クラスの全ての定義を変更なしで継承する場合、"pass"キーワードのみを書くだけで良いです。 + # しかし、今回は親クラスとは異なる子クラスを作成するので、今回は以下の通りコメントアウトしています。 + # pass + + # 子クラスは親クラスの属性を上書きできます。 + species = 'Superhuman' + + # 子クラスは親クラスのコンストラクタを引数含めて自動的に継承しますが、 + # 追加の引数や定義を行ってコンストラクタのようなメソッドを上書きすることもできます。 + # このコンストラクタは"name"引数を"Human"クラスから継承し、"superpower"と"movie"という引数を追加します。 + def __init__(self, name, movie=False, + superpowers=["super strength", "bulletproofing"]): + + # 追加のクラス属性を作成する + self.fictional = True + self.movie = movie + # デフォルト値は共有されるので、可変のデフォルト値には注意してください。 + self.superpowers = superpowers + + # "super"関数を使うと子クラスに上書きされた親クラスのメソッド(今回は "__init__")にアクセスできます。 + # これで、親クラスのコンストラクタを呼んでいます。 + super().__init__(name) + + # singメソッドを上書きし、 + def sing(self): + return 'Dun, dun, DUN!' + + # 追加のインスタンスメソッドを作成します。 + def boast(self): + for power in self.superpowers: + print("I wield the power of {pow}!".format(pow=power)) + + +if __name__ == '__main__': + sup = Superhero(name="Tick") + + # インスタンスの型を調べる + if isinstance(sup, Human): + print('I am human') + if type(sup) is Superhero: + print('I am a superhero') + + # getattr()とsuper()で使われるメソッドの解決順序を調べてみます。 + # この属性は動的であり、変更可能です。 + print(Superhero.__mro__) # => (<class '__main__.Superhero'>, + # => <class 'human.Human'>, <class 'object'>) + + # 親のメソッドを呼びだすものの、独自のクラス属性を参照します。 + print(sup.get_species()) # => Superhuman + + # 上書きされたメソッドを呼ぶ + print(sup.sing()) # => Dun, dun, DUN! + + # Humanのメソッドを呼ぶ + sup.say('Spoon') # => Tick: Spoon + + # Superhero限定のメソッドを呼ぶ + sup.boast() # => I wield the power of super strength! + # => I wield the power of bulletproofing! + + # 継承されたクラス属性 + sup.age = 31 + print(sup.age) # => 31 + + # Superhero限定の属性 + print('Am I Oscar eligible? ' + str(sup.movie)) + + + +#################################################### +# 6.2 多重継承 #################################################### # 別のクラスを定義します。 +# bat.py class Bat: species = 'Baty' @@ -759,31 +882,22 @@ if __name__ == '__main__': print(b.say('hello')) print(b.fly) -# ファイル単位のモジュール化を利用するために、上記のクラスを別々のファイルに配置することができます。 -# ここでは、human.pyとbat.pyを作成してみましょう。 - -# 他のファイルから関数をインポートするために、次のような形式を利用してください。 -# from "拡張子無しのファイル名" import "関数またはクラス" - # superhero.py -from human import Human +from superhero import Superhero from bat import Bat - -# BatmanはHumanとBatの両方を継承します。 -class Batman(Human, Bat): - - # Batmanは species のクラス属性に独自の値を持ちます。 - species = 'Superhero' +# BatmanをSuperheroとBatの両方を継承した子クラスとして定義します。 +class Batman(Superhero, Bat): def __init__(self, *args, **kwargs): # 通常、属性を継承するにはsuper()を呼び出します。 - # super(Batman, self).__init__(*args, **kwargs) + # super(Batman, self).__init__(*args, **kwargs) # しかし、ここでは多重継承を行っているので、 super() はMRO(メソッド解決順序)の次の基本クラスにのみ動作します。 # なので、全ての祖先に対して明示的に __init__ を呼ぶことにします。 # *args と **kwargs を使うことで、それぞれの継承元が # たまねぎの皮を剥がすごとく、引数を用いることができます。 - Human.__init__(self, 'anonymous', *args, **kwargs) + Superhero.__init__(self, 'anonymous', movie=True, + superpowers=['Wealthy'], *args, **kwargs) Bat.__init__(self, *args, can_fly=False, **kwargs) # 名前の属性の値を上書きします。 self.name = 'Sad Affleck' @@ -795,22 +909,18 @@ class Batman(Human, Bat): if __name__ == '__main__': sup = Batman() - # インスタンスの型を調べてみましょう。 - if isinstance(sup, Human): - print('I am human') - if isinstance(sup, Bat): - print('I am bat') - if type(sup) is Batman: - print('I am Batman') - # getattr() や super() の両方で使われるMROを取得します。 # この属性は動的であり、更新が可能です。 - print(Batman.__mro__) # => (<class '__main__.Batman'>, <class 'human.Human'>, <class 'bat.Bat'>, <class 'object'>) + print(Batman.__mro__) # => (<class '__main__.Batman'>, + # => <class 'superhero.Superhero'>, + # => <class 'human.Human'>, + # => <class 'bat.Bat'>, <class 'object'>) + # 親メソッドを呼び出しますが、独自のクラス属性を参照します。 - print(sup.get_species()) # => Superhero + print(sup.get_species()) # => Superhuman - # オーバーロードされたメソッドを呼び出します。 + # 上書きされたメソッドを呼び出します。 print(sup.sing()) # => nan nan nan nan nan batman! # 継承順により、Humanから継承されたメソッドを呼び出します。 @@ -821,10 +931,10 @@ if __name__ == '__main__': # 継承されたクラス属性 sup.age = 100 - print(sup.age) + print(sup.age) # => 100 # デフォルト値が上書きされて、2番目の先祖から継承された属性 - print('Can I fly? ' + str(sup.fly)) + print('Can I fly? ' + str(sup.fly)) # => Can I fly? False #################################################### diff --git a/linker.html.markdown b/linker.html.markdown new file mode 100644 index 00000000..ebe6233d --- /dev/null +++ b/linker.html.markdown @@ -0,0 +1,9 @@ +--- +category: tool +tool: linker +contributors: + - ["Alexander Kovalchuk", "https://github.com/Zamuhrishka"] +--- + +This article is available in [Russian](http://localhost:4567/docs/ru-ru/linker-ru/). + diff --git a/opengl.html.markdown b/opengl.html.markdown new file mode 100644 index 00000000..83ace3e8 --- /dev/null +++ b/opengl.html.markdown @@ -0,0 +1,765 @@ +---
+category: tool
+tool: OpenGL
+filename: learnopengl.cpp
+contributors:
+ - ["Simon Deitermann", "s.f.deitermann@t-online.de"]
+---
+
+**Open Graphics Library** (**OpenGL**) is a cross-language cross-platform application programming interface
+(API) for rendering 2D computer graphics and 3D vector graphics.<sup>[1]</sup> In this tutorial we will be
+focusing on modern OpenGL from 3.3 and above, ignoring "immediate-mode", Displaylists and
+VBO's without use of Shaders.
+I will be using C++ with SFML for window, image and context creation aswell as GLEW
+for modern OpenGL extensions, though there are many other librarys available.
+
+```cpp
+// Creating an SFML window and OpenGL basic setup.
+#include <GL/glew.h>
+#include <GL/gl.h>
+#include <SFML/Graphics.h>
+#include <iostream>
+
+int main() {
+ // First we tell SFML how to setup our OpenGL context.
+ sf::ContextSettings context{ 24, // depth buffer bits
+ 8, // stencil buffer bits
+ 4, // MSAA samples
+ 3, // major opengl version
+ 3 }; // minor opengl version
+ // Now we create the window, enable VSync
+ // and set the window active for OpenGL.
+ sf::Window window{ sf::VideoMode{ 1024, 768 },
+ "opengl window",
+ sf::Style::Default,
+ context };
+ window.setVerticalSyncEnabled(true);
+ window.setActive(true);
+ // After that we initialise GLEW and check if an error occured.
+ GLenum error;
+ glewExperimental = GL_TRUE;
+ if ((err = glewInit()) != GLEW_OK)
+ std::cout << glewGetErrorString(err) << std::endl;
+ // Here we set the color glClear will clear the buffers with.
+ glClearColor(0.0f, // red
+ 0.0f, // green
+ 0.0f, // blue
+ 1.0f); // alpha
+ // Now we can start the event loop, poll for events and draw objects.
+ sf::Event event{ };
+ while (window.isOpen()) {
+ while (window.pollEvent(event)) {
+ if (event.type == sf::Event::Closed)
+ window.close;
+ }
+ // Tell OpenGL to clear the color buffer
+ // and the depth buffer, this will clear our window.
+ glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
+ // Flip front- and backbuffer.
+ window.display();
+ }
+ return 0;
+}
+```
+
+## Loading Shaders
+
+After creating a window and our event loop we should create a function,
+that sets up our shader program.
+
+```cpp
+GLuint createShaderProgram(const std::string& vertexShaderPath,
+ const std::string& fragmentShaderPath) {
+ // Load the vertex shader source.
+ std::stringstream ss{ };
+ std::string vertexShaderSource{ };
+ std::string fragmentShaderSource{ };
+ std::ifstream file{ vertexShaderPath };
+ if (file.is_open()) {
+ ss << file.rdbuf();
+ vertexShaderSource = ss.str();
+ file.close();
+ }
+ // Clear the stringstream and load the fragment shader source.
+ ss.str(std::string{ });
+ file.open(fragmentShaderPath);
+ if (file.is_open()) {
+ ss << file.rdbuf();
+ fragmentShaderSource = ss.str();
+ file.close();
+ }
+ // Create the program.
+ GLuint program = glCreateProgram();
+ // Create the shaders.
+ GLuint vertexShader = glCreateShader(GL_VERTEX_SHADER);
+ GLuint fragmentShader = glCreateShader(GL_FRAGMENT_SHADER);
+ // Now we can load the shader source into the shader objects and compile them.
+ // Because glShaderSource() wants a const char* const*,
+ // we must first create a const char* and then pass the reference.
+ const char* cVertexSource = vertexShaderSource.c_str();
+ glShaderSource(vertexShader, // shader
+ 1, // number of strings
+ &cVertexSource, // strings
+ nullptr); // length of strings (nullptr for 1)
+ glCompileShader(vertexShader);
+ // Now we have to do the same for the fragment shader.
+ const char* cFragmentSource = fragmentShaderSource.c_str();
+ glShaderSource(fragmentShader, 1, &cFragmentSource, nullptr);
+ glCompileShader(fragmentShader);
+ // After attaching the source and compiling the shaders,
+ // we attach them to the program;
+ glAttachShader(program, vertexShader);
+ glAttachShader(program, fragmentShader);
+ glLinkProgram(program);
+ // After linking the shaders we should detach and delete
+ // them to prevent memory leak.
+ glDetachShader(program, vertexShader);
+ glDetachShader(program, fragmentShader);
+ glDeleteShader(vertexShader);
+ glDeleteShader(fragmentShader);
+ // With everything done we can return the completed program.
+ return program;
+}
+```
+
+If you want to check the compilation log you can add the following between <code>glCompileShader()</code> and <code>glAttachShader()</code>.
+
+```cpp
+GLint logSize = 0;
+std::vector<GLchar> logText{ };
+glGetShaderiv(vertexShader, // shader
+ GL_INFO_LOG_LENGTH, // requested parameter
+ &logSize); // return object
+if (logSize > 0) {
+ logText.resize(logSize);
+ glGetShaderInfoLog(vertexShader, // shader
+ logSize, // buffer length
+ &logSize, // returned length
+ logText.data()); // buffer
+ std::cout << logText.data() << std::endl;
+}
+```
+
+The same is possibile after <code>glLinkProgram()</code>, just replace <code>glGetShaderiv()</code> with <code>glGetProgramiv()</code>
+and <code>glGetShaderInfoLog()</code> with <code>glGetProgramInfoLog()</code>.
+
+```cpp
+// Now we can create a shader program with a vertex and a fragment shader.
+// ...
+glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
+
+GLuint program = createShaderProgram("vertex.glsl", "fragment.glsl");
+
+sf::Event event{ };
+// ...
+// We also have to delete the program at the end of the application.
+// ...
+ }
+ glDeleteProgram(program);
+ return 0;
+}
+// ...
+```
+
+Ofcourse we have to create the vertex and fragment shader before we can load them,
+so lets create two basic shaders.
+
+**Vertex Shader**
+
+```glsl
+// Declare which version of GLSL we use.
+// Here we declare, that we want to use the OpenGL 3.3 version of GLSL.
+#version 330 core
+// At attribute location 0 we want an input variable of type vec3,
+// that contains the position of the vertex.
+// Setting the location is optional, if you don't set it you can ask for the
+// location with glGetAttribLocation().
+layout(location = 0) in vec3 position;
+// Every shader starts in it's main function.
+void main() {
+ // gl_Position is a predefined variable that holds
+ // the final vertex position.
+ // It consists of a x, y, z and w coordinate.
+ gl_Position = vec4(position, 1.0);
+}
+```
+
+**Fragment Shader**
+
+```glsl
+#version 330 core
+// The fragment shader does not have a predefined variable for
+// the vertex color, so we have to define a output vec4,
+// that holds the final vertex color.
+out vec4 outColor;
+
+void main() {
+ // We simply set the ouput color to red.
+ // The parameters are red, green, blue and alpha.
+ outColor = vec4(1.0, 0.0, 0.0, 1.0);
+}
+```
+
+## VAO and VBO
+Now we need to define some vertex position we can pass to our shaders. Lets define a simple 2D quad.
+
+```cpp
+// The vertex data is defined in a counter-clockwise way,
+// as this is the default front face.
+std::vector<float> vertexData {
+ -0.5f, 0.5f, 0.0f,
+ -0.5f, -0.5f, 0.0f,
+ 0.5f, -0.5f, 0.0f,
+ 0.5f, 0.5f, 0.0f
+};
+// If you want to use a clockwise definition, you can simply call
+glFrontFace(GL_CW);
+// Next we need to define a Vertex Array Object (VAO).
+// The VAO stores the current state while its active.
+GLuint vao = 0;
+glGenVertexArrays(1, &vao);
+glBindVertexArray(vao);
+// With the VAO active we can now create a Vertex Buffer Object (VBO).
+// The VBO stores our vertex data.
+GLuint vbo = 0;
+glGenBuffers(1, &vbo);
+glBindBuffer(GL_ARRAY_BUFFER, vbo);
+// For reading and copying there are also GL_*_READ and GL_*_COPY,
+// if your data changes more often use GL_DYNAMIC_* or GL_STREAM_*.
+glBufferData(GL_ARRAY_BUFFER, // target buffer
+ sizeof(vertexData[0]) * vertexData.size(), // size
+ vertexData.data(), // data
+ GL_STATIC_DRAW); // usage
+// After filling the VBO link it to the location 0 in our vertex shader,
+// which holds the vertex position.
+// ...
+// To ask for the attibute location, if you haven't set it:
+GLint posLocation = glGetAttribLocation(program, "position");
+// ..
+glEnableVertexAttribArray(0);
+glVertexAttribPointer(0, 3, // location and size
+ GL_FLOAT, // type of data
+ GL_FALSE, // normalized (always false for floats)
+ 0, // stride (interleaved arrays)
+ nullptr); // offset (interleaved arrays)
+// Everything should now be saved in our VAO and we can unbind it and the VBO.
+glBindVertexArray(0);
+glBindBuffer(GL_ARRAY_BUFFER, 0);
+// Now we can draw the vertex data in our render loop.
+// ...
+glClear(GL_COLOR_BUFFER_BIT);
+// Tell OpenGL we want to use our shader program.
+glUseProgram(program);
+// Binding the VAO loads the data we need.
+glBindVertexArray(vao);
+// We want to draw a quad starting at index 0 of the VBO using 4 indices.
+glDrawArrays(GL_QUADS, 0, 4);
+glBindVertexArray(0);
+window.display();
+// ...
+// Ofcource we have to delete the allocated memory for the VAO and VBO at
+// the end of our application.
+// ...
+glDeleteBuffers(1, &vbo);
+glDeleteVertexArrays(1, &vao);
+glDeleteProgram(program);
+return 0;
+// ...
+```
+
+You can find the current code here: [OpenGL - 1](https://pastebin.com/W8jdmVHD).
+
+## More VBO's and Color
+Let's create another VBO for some colors.
+
+```cpp
+std::vector<float> colorData {
+ 1.0f, 0.0f, 0.0f,
+ 0.0f, 1.0f, 0.0f,
+ 0.0f, 0.0f, 1.0f,
+ 1.0f, 1.0f, 0.0f
+};
+```
+
+Next we can simply change some previous parameters to create a second VBO for our colors.
+
+```cpp
+// ...
+GLuint vbo[2];
+glGenBuffers(2, vbo);
+glBindBuffer(GL_ARRAY_BUFFER, vbo[0]);
+// ...
+glDeleteBuffers(2, vbo);
+/ ...
+// With these changes made we now have to load our color data into the new VBO
+// ...
+glVertexAttribPointer(0, 3, GL_FLOAT, GL_FALSE, 0, nullptr);
+
+glBindBuffer(GL_ARRAY_BUFFER, vbo[1]);
+glBufferData(GL_ARRAY_BUFFER, sizeof(colorData[0]) * colorData.size(),
+ colorData.data(), GL_STATIC_DRAW);
+glEnableVertexAttribArray(1);
+glVertexAttribPointer(1, 3, GL_FLOAT, GL_FALSE, 0, nullptr);
+
+glBindVertexArray(0);
+// ...
+```
+
+Next we have to change our vertex shader to pass the color data to the fragment shader.<br>
+**Vertex Shader**
+
+```glsl
+#version 330 core
+
+layout(location = 0) in vec3 position;
+// The new location has to differ from any other input variable.
+// It is the same index we need to pass to
+// glEnableVertexAttribArray() and glVertexAttribPointer().
+layout(location = 1) in vec3 color;
+
+out vec3 fColor;
+
+void main() {
+ fColor = color;
+ gl_Position = vec4(position, 1.0);
+}
+```
+
+**Fragment Shader**
+
+```glsl
+#version 330 core
+
+in vec3 fColor;
+
+out vec4 outColor;
+
+void main() {
+ outColor = vec4(fColor, 1.0);
+}
+```
+
+We define a new input variable ```color``` which represents our color data, this data
+is passed on to ```fColor```, which is an output variable of our vertex shader and
+becomes an input variable for our fragment shader.
+It is imporatant that variables passed between shaders have the exact same name
+and type.
+
+## Handling VBO's
+
+```cpp
+// If you want to completely clear and refill a VBO use glBufferData(),
+// just like we did before.
+// ...
+// There are two mains ways to update a subset of a VBO's data.
+// To update a VBO with existing data
+std::vector<float> newSubData {
+ -0.25f, 0.5f, 0.0f
+};
+glBindBuffer(GL_ARRAY_BUFFER, vbo[0]);
+glBufferSubData(GL_ARRAY_BUFFER, // target buffer
+ 0, // offset
+ sizeof(newSubData[0]) * newSubData.size(), // size
+ newSubData.data()); // data
+// This would update the first three values in our vbo[0] buffer.
+// If you want to update starting at a specific location just set the second
+// parameter to that value and multiply by the types size.
+// ...
+// If you are streaming data, for example from a file,
+// it is faster to directly pass the data to the buffer.
+// Other access values are GL_READ_ONLY and GL_READ_WRITE.
+glBindBuffer(GL_ARRAY_BUFFER, vbo[0]);
+// You can static_cast<float*>() the void* to be more safe.
+void* Ptr = glMapBuffer(GL_ARRAY_BUFFER, // buffer to map
+ GL_WRITE_ONLY); // access to buffer
+memcpy(Ptr, newSubData.data(), sizeof(newSubData[0]) * newSubData.size());
+// To copy to a specific location add a destination offset to memcpy().
+glUnmapBuffer(GL_ARRAY_BUFFER);
+// ...
+// There is also a way to copy data from one buffer to another,
+// If we have two VBO's vbo[0] and vbo[1], we can copy like so
+// You can also read from GL_ARRAY_BUFFER.
+glBindBuffer(GL_COPY_READ_BUFFER, vbo[0]);
+// GL_COPY_READ_BUFFER and GL_COPY_WRITE_BUFFER are specifically for
+// copying buffer data.
+glBindBuffer(GL_COPY_WRITE_BUFFER, vbo[1]);
+glCopyBufferSubData(GL_COPY_READ_BUFFER, // read buffer
+ GL_COPY_WRITE_BUFFER, // write buffer
+ 0, 0, // read and write offset
+ sizeof(vbo[0]) * 3); // copy size
+// This will copy the first three elements from vbo[0] to vbo[1].
+```
+
+## Uniforms
+
+**Fragment Shader**
+
+```glsl
+// Uniforms are variables like in and out, however,
+// we can change them easily by passing new values with glUniform().
+// Lets define a time variable in our fragment shader.
+#version 330 core
+// Unlike a in/out variable we can use a uniform in every shader,
+// without the need to pass it to the next one, they are global.
+// Don't use locations already used for attributes!
+// Uniform layout locations require OpenGL 4.3!
+layout(location = 10) uniform float time;
+
+in vec3 fColor;
+
+out vec4 outColor;
+
+void main() {
+ // Create a sine wave from 0 to 1 based on the time passed to the shader.
+ float factor = (sin(time * 2) + 1) / 2;
+ outColor = vec4(fColor.r * factor, fColor.g * factor, fColor.b * factor, 1.0);
+}
+```
+
+Back to our source code.
+
+```cpp
+// If we haven't set the layout location, we can ask for it.
+GLint timeLocation = glGetUniformLocation(program, "time");
+// ...
+// Also we should define a Timer counting the current time.
+sf::Clock clock{ };
+// In out render loop we can now update the uniform every frame.
+ // ...
+ window.display();
+ glUniform1f(10, // location
+ clock.getElapsedTime().asSeconds()); // data
+}
+// ...
+```
+
+With the time getting updated every frame the quad should now be changing from
+fully colored to pitch black.
+There are different types of glUniform() you can find simple documentation here:
+[glUniform - OpenGL Refpage](https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glUniform.xhtml)
+
+## Indexing and IBO's
+
+Element Array Buffers or more commonly Index Buffer Objects (IBO) allow us to use the
+same vertex data again which makes drawing a lot easier and faster. here's an example:
+
+```cpp
+// Lets create a quad from two rectangles.
+// We can simply use the old vertex data from before.
+// First, we have to create the IBO.
+// The index is referring to the first declaration in the VBO.
+std::vector<unsigned int> iboData {
+ 0, 1, 2,
+ 0, 2, 3
+};
+// That's it, as you can see we could reuse 0 - the top left
+// and 2 - the bottom right.
+// Now that we have our data, we have to fill it into a buffer.
+// Note that this has to happen between the two glBindVertexArray() calls,
+// so it gets saved into the VAO.
+GLuint ibo = 0;
+glGenBufferrs(1, &ibo);
+glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, ibo);
+glBufferData(GL_ELEMENT_ARRAY_BUFFER, sizeof(iboData[0]) * iboData.size(),
+ iboData.data(), GL_STATIC_DRAW);
+// Next in our render loop, we replace glDrawArrays() with:
+glDrawElements(GL_TRIANGLES, iboData.size(), GL_UNSINGED_INT, nullptr);
+// Remember to delete the allocated memory for the IBO.
+```
+
+You can find the current code here: [OpenGL - 2](https://pastebin.com/R3Z9ACDE).
+
+## Textures
+
+To load out texture we first need a library that loads the data, for simplicity I will be
+using SFML, however there are a lot of librarys for loading image data.
+
+```cpp
+// Lets save we have a texture called "my_tex.tga", we can load it with:
+sf::Image image;
+image.loadFromFile("my_tex.tga");
+// We have to flip the texture around the y-Axis, because OpenGL's texture
+// origin is the bottom left corner, not the top left.
+image.flipVertically();
+// After loading it we have to create a OpenGL texture.
+GLuint texture = 0;
+glGenTextures(1, &texture);
+glBindTexture(GL_TEXTURE_2D, texture);
+// Specify what happens when the coordinates are out of range.
+glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_REPEAT);
+glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_REPEAT);
+// Specify the filtering if the object is very large.
+glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+// Load the image data to the texture.
+glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, image.getSize().x, image.getSize().y,
+ 0, GL_RGBA, GL_UNSIGNED_BYTE, image.getPixelsPtr());
+// Unbind the texture to prevent modifications.
+glBindTexture(GL_TEXTURE_2D, 0);
+// Delete the texture at the end of the application.
+// ...
+glDeleteTextures(1, &texture);
+```
+
+Ofcourse there are more texture formats than only 2D textures,
+You can find further information on parameters here:
+[glBindTexture - OpenGL Refpage](https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glBindTexture.xhtml)<br>
+[glTexImage2D - OpenGL Refpage](https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glTexImage2D.xhtml)<br>
+[glTexParameter - OpenGL Refpage](https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glTexParameter.xhtml)<br>
+
+```cpp
+// With the texture created, we now have to specify the UV,
+// or in OpenGL terms ST coordinates.
+std::vector<float> texCoords {
+ // The texture coordinates have to match the triangles/quad
+ // definition.
+ 0.0f, 1.0f, // start at top-left
+ 0.0f, 0.0f, // go round counter-clockwise
+ 1.0f, 0.0f,
+ 1.0f, 1.0f // end at top-right
+};
+// Now we increase the VBO's size again just like we did for the colors.
+// ...
+GLuint vbo[3];
+glGenBuffers(3, vbo);
+// ...
+glDeleteBuffers(3, vbo);
+// ...
+// Load the texture coordinates into the new buffer.
+glBindBuffer(GL_ARRAY_BUFFER, vbo[2]);
+glBufferData(GL_ARRAY_BUFFER, sizeof(texCoords[0]) * texCoords.size(),
+ texCoords.data(), GL_STATIC_DRAW);
+glEnableVertexAttribArray(2);
+glVertexAttribPointer(2, 2, GL_FLOAT, GL_FALSE, 0, nullptr);
+// Because the VAO does not store the texture we have to bind it before drawing.
+// ...
+glBindVertexArray(vao);
+glBindTexture(GL_TEXTURE_2D, texture);
+glDrawElements(GL_TRIANGLES, iboData.size(), GL_UNSINGED_INT, nullptr);
+// ...
+```
+
+Change the shaders to pass the data to the fragment shader.<br>
+
+**Vertex Shader**
+
+```glsl
+#version 330 core
+
+layout(location = 0) in vec3 position;
+layout(location = 1) in vec3 color;
+layout(location = 2) in vec2 texCoords;
+
+out vec3 fColor;
+out vec2 fTexCoords;
+
+void main() {
+ fColor = color;
+ fTexCoords = texCoords;
+ gl_Position = vec4(position, 1.0);
+}
+```
+
+**Fragment Shader**
+
+```glsl
+#version 330 core
+// sampler2D represents our 2D texture.
+uniform sampler2D tex;
+uniform float time;
+
+in vec3 fColor;
+in vec2 fTexCoords;
+
+out vec4 outColor;
+
+void main() {
+ // texture() loads the current texure data at the specified texture coords,
+ // then we can simply multiply them by our color.
+ outColor = texture(tex, fTexCoords) * vec4(fColor, 1.0);
+}
+```
+
+You can find the current code here: [OpenGL - 3](https://pastebin.com/u3bcwM6q)
+
+## Matrix Transformation
+
+**Vertex Shader**
+
+```glsl
+#version 330 core
+
+layout(location = 0) in vec3 position;
+layout(location = 1) in vec3 color;
+layout(location = 2) in vec2 texCoords;
+// Create 2 4x4 matricies, 1 for the projection matrix
+// and 1 for the model matrix.
+// Because we draw in a static scene, we don't need a view matrix.
+uniform mat4 projection;
+uniform mat4 model;
+
+out vec3 fColor;
+out vec2 fTexCoords;
+
+void main() {
+ fColor = color;
+ fTexCoords = texCoords;
+ // Multiplay the position by the model matrix and then by the
+ // projection matrix.
+ // Beware order of multiplication for matricies!
+ gl_Position = projection * model * vec4(position, 1.0);
+}
+```
+
+In our source we now need to change the vertex data, create a model- and a projection matrix.
+
+```cpp
+// The new vertex data, counter-clockwise declaration.
+std::vector<float> vertexData {
+ 0.0f, 1.0f, 0.0f, // top left
+ 0.0f, 0.0f, 0.0f, // bottom left
+ 1.0f, 0.0f, 0.0f, // bottom right
+ 1.0f, 1.0f, 0.0f // top right
+};
+// Request the location of our matricies.
+GLint projectionLocation = glGetUniformLocation(program, "projection");
+GLint modelLocation = glGetUniformLocation(program, "model");
+// Declaring the matricies.
+// Orthogonal matrix for a 1024x768 window.
+std::vector<float> projection {
+ 0.001953f, 0.0f, 0.0f, 0.0f,
+ 0.0f, -0.002604f, 0.0f, 0.0f,
+ 0.0f, 0.0f, -1.0f, 0.0f,
+ -1.0f, 1.0f, 0.0f, 1.0f
+};
+// Model matrix translating to x 50, y 50
+// and scaling to x 200, y 200.
+std::vector<float> model {
+ 200.0f, 0.0f, 0.0f, 0.0f,
+ 0.0f, 200.0f, 0.0f, 0.0f,
+ 0.0f, 0.0f, 1.0f, 0.0f,
+ 50.0f, 50.0f, 0.0f, 1.0f
+};
+// Now we can send our calculated matricies to the program.
+glUseProgram(program);
+glUniformMatrix4fv(projectionLocation, // location
+ 1, // count
+ GL_FALSE, // transpose the matrix
+ projection.data()); // data
+glUniformMatrix4fv(modelLocation, 1, GL_FALSE, model.data());
+glUseProgram(0);
+// The glUniform*() calls have to be done, while the program is bound.
+```
+
+The application should now display the texture at the defined position and size.<br>
+You can find the current code here: [OpenGL - 4](https://pastebin.com/9ahpFLkY)
+
+```cpp
+// There are many math librarys for OpenGL, which create
+// matricies and vectors, the most used in C++ is glm (OpenGL Mathematics).
+// Its a header only library.
+// The same code using glm would look like:
+glm::mat4 projection{ glm::ortho(0.0f, 1024.0f, 768.0f, 0.0f) };
+glUniformMatrix4fv(projectionLocation, 1, GL_FALSE,
+ glm::value_ptr(projection));
+// Initialise the model matrix to the identity matrix, otherwise every
+// multiplication would be 0.
+glm::mat4 model{ 1.0f };
+model = glm::translate(model, glm::vec3{ 50.0f, 50.0f, 0.0f });
+model = glm::scale(model, glm::vec3{ 200.0f, 200.0f, 0.0f });
+glUniformMatrix4fv(modelLocation, 1, GL_FALSE,
+ glm::value_ptr(model));
+```
+
+## Geometry Shader
+
+Gemoetry shaders were introduced in OpenGL 3.2, they can produce vertices
+that are send to the rasterizer. They can also change the primitive type e.g.
+they can take a point as an input and output other primitives.
+Geometry shaders are inbetween the vertex and the fragment shader.
+
+**Vertex Shader**
+
+```glsl
+#version 330 core
+
+layout(location = 0) in vec3 position;
+layout(location = 1) in vec3 color;
+// Create an output interface block passed to the next shadaer stage.
+// Interface blocks can be used to structure data passed between shaders.
+out VS_OUT {
+ vec3 color;
+} vs_out;
+
+void main() {
+ vs_out.color = color
+ gl_Position = vec4(position, 1.0);
+}
+```
+
+**Geometry Shader**
+
+```glsl
+#version 330 core
+// The geometry shader takes in points.
+layout(points) in;
+// It outputs a triangle every 3 vertices emitted.
+layout(triangle_strip, max_vertices = 3) out;
+// VS_OUT becomes an input variable in the geometry shader.
+// Every input to the geometry shader in treated as an array.
+in VS_OUT {
+ vec3 color;
+} gs_in[];
+// Output color for the fragment shader.
+// You can also simply define color as 'out vec3 color',
+// If you don't want to use interface blocks.
+out GS_OUT {
+ vec3 color;
+} gs_out;
+
+void main() {
+ // Each emit calls the fragment shader, so we set a color for each vertex.
+ gs_out.color = mix(gs_in[0].color, vec3(1.0, 0.0, 0.0), 0.5);
+ // Move 0.5 units to the left and emit the new vertex.
+ // gl_in[] is the current vertex from the vertex shader, here we only
+ // use 0, because we are receiving points.
+ gl_Position = gl_in[0].gl_Position + vec4(-0.5, 0.0, 0.0, 0.0);
+ EmitVertex();
+ gs_out.color = mix(gs_in[0].color, vec3(0.0, 1.0, 0.0), 0.5);
+ // Move 0.5 units to the right and emit the new vertex.
+ gl_Position = gl_in[0].gl_Position + vec4(0.5, 0.0, 0.0, 0.0);
+ EmitVertex();
+ gs_out.color = mix(gs_in[0].color, vec3(0.0, 0.0, 1.0), 0.5);
+ // Move 0.5 units up and emit the new vertex.
+ gl_Position = gl_in[0].gl_Position + vec4(0.0, 0.75, 0.0, 0.0);
+ EmitVertex();
+ EndPrimitive();
+}
+```
+
+**Fragment Shader**
+
+```glsl
+in GS_OUT {
+ vec3 color;
+} fs_in;
+
+out vec4 outColor;
+
+void main() {
+ outColor = vec4(fs_in.color, 1.0);
+}
+```
+
+If you now store a single point with a single color in a VBO and draw them,
+you should see a triangle, with your color mixed half way between
+red, green and blue on each vertex.
+
+
+## Quotes
+<sup>[1]</sup>[OpenGL - Wikipedia](https://en.wikipedia.org/wiki/OpenGL)
+
+## Books
+
+- OpenGL Superbible - Fifth Edition (covering OpenGL 3.3)
+- OpenGL Programming Guide - Eighth Edition (covering OpenGL 4.3)
diff --git a/perl6.html.markdown b/perl6.html.markdown index cb64b646..6b0df0d4 100644 --- a/perl6.html.markdown +++ b/perl6.html.markdown @@ -247,11 +247,12 @@ concat3(|@array); #=> a, b, c ## 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++; + $n++; # postfix ++ operator increments its argument but returns its old value } my $m = 42; -mutate $m; #=> 43 +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. diff --git a/pug.html.markdown b/pug.html.markdown new file mode 100644 index 00000000..0187f1e0 --- /dev/null +++ b/pug.html.markdown @@ -0,0 +1,204 @@ +--- +language: Pug +contributors: + - ["Michael Warner", "https://github.com/MichaelJGW"] +filename: index.pug +--- + +## Getting Started with Pug + +Pug is a little language that compiles into the HTML. It has cleaner syntax +with additional features like if statements and loops. It can also be used +as a server side templating language for server languages like NodeJS. + +### The Language +```pug + +//- Single Line Comment + +//- Multi Line + Comment + +//- ---TAGS--- +//- Basic +div +//- <div></div> +h1 +//- <h1></h1> +my-customTag +//- <my-customTag></my-customTag> + +//- Sibling +div +div +//- <div></div> + <div></div> + +//- Child +div + div +//- <div> + <div></div> + </div> + +//- Text +h1 Hello there +//- <h1>Hello there</h1> + +//- Multi Line Text +div. + Hello + There +//- <div> + Hello + There + </div> + +//- ---ATTRIBUTES--- +div(class="my-class" id="my-id" my-custom-attrs="data" enabled) +//- <div class="my-class" id="my-id" my-custom-attrs="data" enabled></div> + +//- Short Hand +span.my-class +//- <span class="my-class"></span> +.my-class +//- <div class="my-class"></div> +div#my-id +//- <div id="my-id"></div> +div#my-id.my-class +//- <div class="my-class" id="my-id"></div> + + +//- ---JS--- +- const lang = "pug"; + +//- Multi Line JS +- + const lang = "pug"; + const awesome = true; + +//- JS Classes +- const myClass = ['class1', 'class2', 'class3'] +div(class=myClass) +//- <div class="class1 class2 class3"></div> + +//- JS Styles +- const myStyles = {'color':'white', 'background-color':'blue'} +div(styles=myStyles) +//- <div styles="{"color":"white","background-color":"blue"}"></div> + +//- JS Attributes +- const myAttributes = {"src": "photo.png", "alt": "My Photo"} +img&attributes(myAttributes) +//- <img src="photo.png" alt="My Photo"> +- let disabled = false +input(type="text" disabled=disabled) +//- <input type="text"> +- disabled = true +input(type="text" disabled=disabled) +//- <input type="text" disabled> + +//- JS Templating +- const name = "Bob"; +h1 Hi #{name} +h1= name +//- <h1>Hi Bob</h1> +//- <h1>Bob</h1> + +//- ---LOOPS--- + +//- 'each' and 'for' do the same thing we will use 'each' only. + +each value, i in [1,2,3] + p=value +//- + <p>1</p> + <p>2</p> + <p>3</p> + +each value, index in [1,2,3] + p=value + '-' + index +//- + <p>1-0</p> + <p>2-1</p> + <p>3-2</p> + +each value in [] + p=value +//- + +each value in [] + p=value +else + p No Values are here + +//- <p>No Values are here</p> + +//- ---CONDITIONALS--- + +- const number = 5 +if number < 5 + p number is less then 5 +else if number > 5 + p number is greater then 5 +else + p number is 5 +//- <p>number is 5</p> + +- const orderStatus = "Pending"; +case orderStatus + when "Pending" + p.warn Your order is pending + when "Completed" + p.success Order is Completed. + when -1 + p.error Error Occurred + default + p No Order Record Found +//- <p class="warn">Your order is pending</p> + +//- --INCLUDE-- +//- File path -> "includes/nav.png" +h1 Company Name +nav + a(href="index.html") Home + a(href="about.html") About Us + +//- File path -> "index.png" +html + body + include includes/nav.pug +//- + <html> + <body> + <h1>Company Name</h1> + <nav><a href="index.html">Home</a><a href="about.html">About Us</a></nav> + </body> + </html> + +//- Importing JS and CSS +script + include scripts/index.js +style + include styles/theme.css + +//- ---MIXIN--- +mixin basic() + div Hello ++basic("Bob") +//- <div>Hello</div> + +mixin comment(name, comment) + div + span.comment-name= name + div.comment-text= comment ++comment("Bob", "This is Awesome") +//- <div>Hello</div> + +``` + + +### Additional Resources +- [The Site](https://pugjs.org/) +- [The Docs](https://pugjs.org/api/getting-started.html) +- [Github Repo](https://github.com/pugjs/pug) diff --git a/ru-ru/linker-ru.html.markdown b/ru-ru/linker-ru.html.markdown new file mode 100644 index 00000000..7df29c23 --- /dev/null +++ b/ru-ru/linker-ru.html.markdown @@ -0,0 +1,203 @@ +--- +category: tool +tool: linker +contributors: + - ["Alexander Kovalchuk", "https://github.com/Zamuhrishka"] +translators: + - ["Alexander Kovalchuk", "https://github.com/Zamuhrishka"] +lang: ru-ru +--- + +# Основные понятия и определения +**Счетчик позиций** - у компоновщика есть специальная переменная +"." (точка) всегда содержит текущую позицию вывода. + +# Функции +**ADDR(section)** - возвращает абсолютный адрес указанной секции. Однако +данная секция должна быть определенна до использования функции ADDR. + +**ALIGN(exp)** - возвращает значение счетчика позиций, выравненное на границу +следующего за exp выражения. + +**SIZEOF(section)** - возвращает размер секции в байтах. + +**FILL(param)** - определяет образец заполнения для текущей секции. Все +остальные неуказанные регионы внутри секции заполняются значением указанными +в аргументе функции. + +**KEEP(param)** - используется чтобы помечать param как неустранимый. + +**ENTRY(func)** - определяет функцию, которая будет являться точкой входа +в программу. + +```bash +# Определяем точку входа в программу +ENTRY(Reset_Handler) + +# Определяем перемнную которая содержит адрес вершины стека +_estack = 0x20020000; +# Определяем перемнную которая содержит значение размера кучи +_Min_Heap_Size = 0x200; +# Определяем перемнную которая содержит значение размера стека +_Min_Stack_Size = 0x400; + +# Описание карты памяти доступной для данного процессора +# MEMORY +# { +# ИМЯ_ОБЛАСТИ_ПАМЯТИ (права доступа) : ORIGIN = АДРЕС_НАЧАЛА, LENGTH = РАЗМЕР +# } +# В нашем примере контроллер содержит три области памяти: +# RAM - начинается с адреса 0x20000000 и занимает 128 Кбайт; +# CCMRAM - начинается с адреса 0x10000000и занимает 64 Кбайт; +# FLASH - начинается с адреса 0x8000000 занимает 1024 Кбайт; +# Причем RAM память доступка для чтения, записи и исполнения. +# CCMRAM память доступна только на чтение и запись. +# FLASH память доступна на чтение и исполнение. +MEMORY +{ + RAM (xrw) : ORIGIN = 0x20000000, LENGTH = 128K + CCMRAM (rw) : ORIGIN = 0x10000000, LENGTH = 64K + FLASH (rx) : ORIGIN = 0x8000000, LENGTH = 1024K +} + +# Описываем выходные секции +SECTIONS +{ + # Первая секция содержит таблицу векторов прерываний + .isr_vector : + { + # Выравниваем текущую позицию на границу 4-х байт. + . = ALIGN(4); + + # Существует опция --gc-sections, которая позволяет собирать мусор из неиспользуемых + # входных разделов. И если есть разделы, которые сборщик муссора не должен трогать, + # то их необходимо указать в качестве аргумента функции KEEP() (аналог ключевого слова + # volatile). + # Запись (*(.isr_vector)) означает разделы .isr_vector во всех объектных файлах. Т.к. + # обращение к разделу в общем виде выглядит так: (ИМЯ_ФАЙЛА(ИМЯ_РАЗДЕЛА)) + KEEP(*(.isr_vector)) + + # Выравниваем текущую позицию на границу 4-х байт. + . = ALIGN(4); + + # Выражение ">ОБЛАСТЬ_ПАМЯТИ" указывает в какую именно область памяти будет помещенна + # данная секция. В нашем слущае секция .isr_vector будет размещена во FLASH памяти. + } >FLASH + +# ИТОГО: Секция .isr_vector, которая содержит таблицу векторов прерываний выравнивается +# по границе 4-х байт, помечается как недоступная для сборщика мусора и размещается в начале +# FLASH памяти микроконтроллера. + + # Вторая секция содержит код программы. + .text : + { + # Выравниваем текущую позицию на границу 4-х байт. + . = ALIGN(4); + + # Указываем, что в данной секции будут хранится области .text всех + # объектных файлов + *(.text) + *(.text*) + + # Защищаем от сборщика мусора секции .init и .fini + KEEP (*(.init)) + KEEP (*(.fini)) + + # Выравниваем текущую позицию на границу 4-х байт. + . = ALIGN(4); + + # Определяется переменная _etext, которая хранит в себе адрес конца секции .text и которая + # может быть доступна в исходном тексте программы через объявление + # volaile unsigned int extern _etext; + _etext = .; + } >FLASH + +# ИТОГО: Секция .text, которая содержит код программы выравнивается по границе 4-х байт, +# включает в себя: все секции с кодом программы во всех объектных файлах и защищенные +от сборщика муссора секции .init и .fini во всех объектных файлах, распологается во FLASH +памяти микроконтроллера сразу за таблицей векторов. +Секции text, .init и .fini. располагаются в памяти в той последовательности в которой они +объявлены в скрипте. + + # Третья секция содержит константные данные. + .rodata : + { + # Выравниваем текущую позицию на границу 4-х байт. + . = ALIGN(4); + + # Указываем, что в данной секции будут хранится области .rodataвсех + # объектных файлов + *(.rodata) + *(.rodata*) + + # Выравниваем текущую позицию на границу 4-х байт. + . = ALIGN(4); + } >FLASH + + # Сохраняем в переменной _sidata абсолютный адрес секции .data + _sidata = LOADADDR(.data); + + # Четвертая секция содержит инициализированные переменные. + .data : + { + # Выравниваем текущую позицию на границу 4-х байт. + . = ALIGN(4); + + # Сохраняем в переменной _sdata адрес текущей позиции (начала секции) + _sdata = .; + + # Указываем, что в данной секции будут хранится области .data всех + # объектных файлов + *(.data) + *(.data*) + + # Выравниваем текущую позицию на границу 4-х байт. + . = ALIGN(4); + + # Сохраняем в переменной _sdata адрес текущей позиции (конец секции) + _edata = .; + + # Функция AT указывает на то, что данный сектор хранится в одной области памяти + # (в нашем случае FLASH), а исполняться будет из другой обасти памяти (в нашем случае RAM). + # Есть два типа адрессов: + # * VMA (Virtual memory address) - это run-time адрес по которому уомпилятор ожидает + # видеть данные. + # * LMA (Load memory address) - это адрес по которому линкер хранит данные. + + #Startup должен код скопировать секцию .data из адрессов LMA в адресса VMA. + + } >RAM AT> FLASH + + # Пятая секция содержит инициализированные нулем переменные. + .bss : + { + # Сохраняем в переменной _sbss и __bss_start__ адрес текущей позиции (начала секции) + _sbss = .; + __bss_start__ = _sbss; + + # Указываем, что в данной секции будут хранится области .bss всех + # объектных файлов + *(.bss) + *(.bss*) + + # Выравниваем текущую позицию на границу 4-х байт. + . = ALIGN(4); + + # Сохраняем в переменной _ebss и __bss_end__ адрес текущей позиции (начала секции) + _ebss = .; + __bss_end__ = _ebss; + } >RAM + + # Шестая секция содержит кучу и стек. Размещается в самом конце RAM. + ._user_heap_stack : + { + . = ALIGN(4); + PROVIDE ( end = . ); + PROVIDE ( _end = . ); + . = . + _Min_Heap_Size; + . = . + _Min_Stack_Size; + . = ALIGN(4); + } >RAM +} +``` + diff --git a/scala.html.markdown b/scala.html.markdown index 28424684..c7a8842e 100644 --- a/scala.html.markdown +++ b/scala.html.markdown @@ -345,7 +345,7 @@ s(0) // Boolean = false s(1) // Boolean = true /* Look up the documentation of map here - - * http://www.scala-lang.org/api/current/index.html#scala.collection.immutable.Map + * https://www.scala-lang.org/api/current/scala/collection/immutable/Map.html * and make sure you can read it */ diff --git a/swift.html.markdown b/swift.html.markdown index f834f373..c2fb3471 100644 --- a/swift.html.markdown +++ b/swift.html.markdown @@ -8,22 +8,26 @@ contributors: - ["Clayton Walker", "https://github.com/cwalk"] - ["Fernando Valverde", "http://visualcosita.xyz"] - ["Alexey Nazaroff", "https://github.com/rogaven"] + - ["@Samasaur1", "https://github.com/Samasaur1"] filename: learnswift.swift --- Swift is a programming language for iOS and OS X development created by Apple. Designed to coexist with Objective-C and to be more resilient against erroneous code, Swift was introduced in 2014 at Apple's developer conference WWDC. It is built with the LLVM compiler included in Xcode 6+. -The official _[Swift Programming Language](https://itunes.apple.com/us/book/swift-programming-language/id881256329)_ book from Apple is now available via iBooks. +The official _[Swift Programming Language](https://itunes.apple.com/us/book/swift-programming-language/id881256329)_ book from Apple is now available via iBooks. It goes into much more detail than this guide, and if you have the time and patience to read it, it's recommended. Some of these examples are from that book. Another great reference is _About Swift_ on Swift's [website](https://docs.swift.org/swift-book/). ```swift // import a module -import UIKit +import Foundation -// -// MARK: Basics -// +// Single-line comments are prefixed with // +// Multi-line comments start with /* and end with */ +/* Nested multiline comments + /* ARE */ + allowed + */ // Xcode supports landmarks to annotate your code and lists them in the jump bar // MARK: Section mark @@ -31,220 +35,383 @@ import UIKit // TODO: Do something soon // FIXME: Fix this code -// In Swift 2, println and print were combined into one print method. Print automatically appends a new line. -print("Hello, world") // println is now print -print("Hello, world", terminator: "") // printing without appending a newline +//MARK: Hello, World +// From Swift 3 on, to print, just use the `print` method. +// It automatically appends a new line. +print("Hello, world") + +// +// MARK: - Variables +// + + +//Use `let` to declare a constant and `var` to declare a variable. +let theAnswer = 42 +var theQuestion = "What is the Answer?" +theQuestion = "How many roads must a man walk down?" +theQuestion = "What is six by nine?" +// Atttempting to reassign a constant throws a compile-time error +//theAnswer = 54 + +// Both variables and constants can be declared before they are given a value, +// but must be given a value before they are used +let someConstant: Int +var someVariable: String +// These lines will throw errors: +//print(someConstant) +//print(someVariable) +someConstant = 0 +someVariable = "0" +// These lines are now valid: +print(someConstant) +print(someVariable) + +// As you can see above, variable types are automatically inferred. +// To explicitly declare the type, write it after the variable name, +// separated by a colon. +let aString: String = "A string" +let aDouble: Double = 0 + +// Values are never implicitly converted to another type. +// Explicitly make instances of the desired type. +let stringWithDouble = aString + String(aDouble) +let intFromDouble = Int(aDouble) + +// For strings, use string interpolation +let descriptionString = "The value of aDouble is \(aDouble)" +// You can put any expression inside string interpolation. +let equation = "Six by nine is \(6 * 9), not 42!" +// To avoid escaping double quotes and backslashes, change the string delimiter +let explanationString = #"The string I used was "The value of aDouble is \(aDouble)" and the result was \#(descriptionString)"# +// You can put as many number signs as you want before the opening quote, +// just match them at the ending quote. They also change the escape character +// to a backslash followed by the same number of number signs. + +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. + """ + +// Arrays +let shoppingList = ["catfish", "water", "tulips",] //commas are allowed after the last element +let secondElement = shoppingList[1] // Arrays are 0-indexed + +// Arrays declared with let are immutable; the following line throws a compile-time error +//shoppingList[2] = "mango" + +// Arrays are structs (more on that later), so this creates a copy instead of referencing the same object +var mutableShoppingList = shoppingList +mutableShoppingList[2] = "mango" + +// == is equality +shoppingList == mutableShoppingList // false + +// Dictionaries declared with let are also immutable +var occupations = [ + "Malcolm": "Captain", + "Kaylee": "Mechanic" +] +occupations["Jayne"] = "Public Relations" +// Dictionaries are also structs, so this also creates a copy +let immutableOccupations = occupations + +immutableOccupations == occupations // true -// variables (var) value can change after being set -// constants (let) value can NOT be changed after being set +// Arrays and dictionaries both automatically grow as you add elements +mutableShoppingList.append("blue paint") +occupations["Tim"] = "CEO" -var myVariable = 42 +// They can both be set to empty +mutableShoppingList = [] +occupations = [:] + +let emptyArray = [String]() +let emptyArray2 = Array<String>() // same as above +// [T] is shorthand for Array<T> +let emptyArray3: [String] = [] // Declaring the type explicitly allows you to set it to an empty array +let emptyArray4: Array<String> = [] // same as above + +// [Key: Value] is shorthand for Dictionary<Key, Value> +let emptyDictionary = [String: Double]() +let emptyDictionary2 = Dictionary<String, Double>() // same as above +var emptyMutableDictionary: [String: Double] = [:] +var explicitEmptyMutableDictionary: Dictionary<String, Double> = [:] // same as above + +// MARK: Other variables let øπΩ = "value" // unicode variable names -let π = 3.1415926 -let convenience = "keyword" // contextual variable name -let weak = "keyword"; let override = "another keyword" // statements can be separated by a semi-colon -let `class` = "keyword" // backticks allow keywords to be used as variable names -let explicitDouble: Double = 70 -let intValue = 0007 // 7 -let largeIntValue = 77_000 // 77000 -let label = "some text " + String(myVariable) // String construction -let piText = "Pi = \(π), Pi 2 = \(π * 2)" // String interpolation - -// Build Specific values -// uses -D build configuration -#if false - print("Not printed") - let buildValue = 3 -#else - let buildValue = 7 -#endif -print("Build value: \(buildValue)") // Build value: 7 +let 🤯 = "wow" // emoji variable names -/* -Optionals are a Swift language feature that either contains a value, -or contains nil (no value) to indicate that a value is missing. -A question mark (?) after the type marks the value as optional. +// Keywords can be used as variable names +// These are contextual keywords that wouldn't be used now, so are allowed +let convenience = "keyword" +let weak = "another keyword" +let override = "another keyword" + +// Using backticks allows keywords to be used as variable names even if they wouldn't be allowed normally +let `class` = "keyword" -Because Swift requires every property to have a value, even nil must be -explicitly stored as an Optional value. +// MARK: - Optionals + +/* + Optionals are a Swift language feature that either contains a value, + 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) + */ -Optional<T> is an enum. -*/ var someOptionalString: String? = "optional" // Can be nil -// same as above, but ? is a postfix operator (syntax candy) -var someOptionalString2: Optional<String> = "optional" +// T? is shorthand for Optional<T> — ? is a postfix operator (syntax candy) +let someOptionalString2: Optional<String> = nil +let someOptionalString3 = String?.some("optional") // same as the first one +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. + */ if someOptionalString != nil { // I am not nil if someOptionalString!.hasPrefix("opt") { print("has the prefix") } - - let empty = someOptionalString?.isEmpty } -someOptionalString = nil -/* -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. -*/ - -// implicitly unwrapped optional -var unwrappedString: String! = "Value is expected." -// same as above, but ! is a postfix operator (more syntax candy) -var unwrappedString2: ImplicitlyUnwrappedOptional<String> = "Value is expected." - -// If let structure - -// If let is a special structure in Swift that allows you to check if an Optional rhs holds a value, and in case it does - unwraps and assigns it to the lhs. -if let someOptionalStringConstant = someOptionalString { +// 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 - +// if-let is a special structure in Swift that allows you to check +// if an Optional rhs holds a value, and if it does unwrap +// and assign it to the lhs. +if let someNonOptionalStringConstant = someOptionalString { // has `Some` value, non-nil - if !someOptionalStringConstant.hasPrefix("ok") { + // someOptionalStringConstant is of type String, not type String? + if !someNonOptionalStringConstant.hasPrefix("ok") { // does not have the prefix } } -// The nil-coalescing operator ?? unwraps an optional if it contains a non-nil value, or returns a default value. -var someOptionalString: String? -let someString = someOptionalString ?? "abc" -print(someString) // abc +//if-var is allowed too! +if var someNonOptionalString = someOptionalString { + someNonOptionalString = "Non optional AND mutable" + print(someNonOptionalString) +} -// Swift has support for storing a value of any type. -// For that purposes there is two keywords: `Any` and `AnyObject` -// `AnyObject` == `id` from Objective-C -// `Any` – also works with any scalar values (Class, Int, struct, etc.) -var anyVar: Any = 7 -anyVar = "Changed value to a string, not good practice, but possible." -let anyObjectVar: AnyObject = Int(1) as NSNumber +// You can bind multiple optional values in one if-let statement. +// If any of the bound values are nil, the if statement does not execute. +if let first = someOptionalString, let second = someOptionalString2, + let third = someOptionalString3, let fourth = someOptionalString4 { + print("\(first), \(second), \(third), and \(fourth) are all not nil") +} -/* - Comment here +//if-let supports "," (comma) clauses, which can be used to +// enforce conditions on newly-bound optional values. +// Both the assignment and the "," clause must pass. +let someNumber: Int? = 7 +if let num = someNumber, num > 3 { + print("num is not nil and is greater than 3") +} - /* - Nested comments are also supported - */ -*/ +// Implicitly unwrapped optional — An optional value that doesn't need to be unwrapped +let unwrappedString: String! = "Value is expected." -// -// MARK: Collections -// +// Here's the difference: +let forcedString = someOptionalString! // requires an exclamation mark +let implicitString = unwrappedString // doesn't require an exclamation mark /* -Array and Dictionary types are structs. So `let` and `var` also indicate -that they are mutable (var) or immutable (let) when declaring these types. -*/ - -// Array -var shoppingList = ["catfish", "water", "lemons"] -shoppingList[1] = "bottle of water" -let emptyArray = [String]() // let == immutable -let emptyArray2 = Array<String>() // same as above -var emptyMutableArray = [String]() // var == mutable -var explicitEmptyMutableStringArray: [String] = [] // same as above - + You can think of an implicitly unwrapped optional as giving permission + for the optional to be unwrapped automatically whenever it's used. + Rather than placing an exclamation mark after the optional's name each time you use it, + you place an exclamation mark after the optional's type when you declare it. + */ -// Dictionary -var occupations = [ - "Malcolm": "Captain", - "kaylee": "Mechanic" -] -occupations["Jayne"] = "Public Relations" -let emptyDictionary = [String: Float]() // let == immutable -let emptyDictionary2 = Dictionary<String, Float>() // same as above -var emptyMutableDictionary = [String: Float]() // var == mutable -var explicitEmptyMutableDictionary: [String: Float] = [:] // same as above +// Otherwise, you can treat an implicitly unwrapped optional the same way the you treat a normal optional +// (i.e., if-let, != nil, etc.) +// Pre-Swift 5, T! was shorthand for ImplicitlyUnwrappedOptional<T> +// Swift 5 and later, using ImplicitlyUnwrappedOptional throws a compile-time error. +//var unwrappedString2: ImplicitlyUnwrappedOptional<String> = "Value is expected." //error -// -// MARK: Control Flow -// - -// Condition statements support "," (comma) clauses, which can be used -// to help provide conditions on optional values. -// Both the assignment and the "," clause must pass. -let someNumber = Optional<Int>(7) -if let num = someNumber, num > 3 { - print("num is greater than 3") -} - -// for loop (array) -let myArray = [1, 1, 2, 3, 5] -for value in myArray { - if value == 1 { - print("One!") - } else { - print("Not one!") - } -} +// The nil-coalescing operator ?? unwraps an optional if it contains a non-nil value, or returns a default value. +someOptionalString = nil +let someString = someOptionalString ?? "abc" +print(someString) // abc +// a ?? b is shorthand for a != nil ? a! : b -// for loop (dictionary) -var dict = ["one": 1, "two": 2] -for (key, value) in dict { - print("\(key): \(value)") -} +// MARK: - Control Flow -// for loop (range) -for i in -1...shoppingList.count { - print(i) -} -shoppingList[1...2] = ["steak", "peacons"] -// use ..< to exclude the last number +let condition = true +if condition { print("condition is true") } // can't omit the braces -// while loop -var i = 1 -while i < 1000 { - i *= 2 +if theAnswer > 50 { + print("theAnswer > 50") +} else if condition { + print("condition is true") +} else { + print("Neither are true") } -// repeat-while loop -repeat { - print("hello") -} while 1 == 2 +// The condition in an `if` statement must be a `Bool`, so the following code is an error, not an implicit comparison to zero +//if 5 { +// print("5 is not zero") +//} // Switch +// Must be exhaustive +// Does not implicitly fall through, use the fallthrough keyword // Very powerful, think `if` statements with syntax candy // They support String, object instances, and primitives (Int, Double, etc) let vegetable = "red pepper" +let vegetableComment: String switch vegetable { case "celery": - let vegetableComment = "Add some raisins and make ants on a log." -case "cucumber", "watercress": - let vegetableComment = "That would make a good tea sandwich." + vegetableComment = "Add some raisins and make ants on a log." +case "cucumber", "watercress": // match multiple values + vegetableComment = "That would make a good tea sandwich." case let localScopeValue where localScopeValue.hasSuffix("pepper"): - let vegetableComment = "Is it a spicy \(localScopeValue)?" + vegetableComment = "Is it a spicy \(localScopeValue)?" default: // required (in order to cover all possible input) - let vegetableComment = "Everything tastes good in soup." + vegetableComment = "Everything tastes good in soup." +} +print(vegetableComment) + +// You use the `for-in` loop to iterate over a sequence, such as an array, dictionary, range, etc. +for element in shoppingList { + print(element) // shoppingList is of type `[String]`, so element is of type `String` +} +//Iterating through a dictionary does not guarantee any specific order +for (person, job) in immutableOccupations { + print("\(person)'s job is \(job)") +} +for i in 1...5 { + print(i, terminator: " ") // Prints "1 2 3 4 5" +} +for i in 0..<5 { + print(i, terminator: " ") // Prints "0 1 2 3 4" +} +//for index in range can replace a C-style for loop: +// for (int i = 0; i < 10; i++) { +// //code +// } +//becomes: +// for i in 0..<10 { +// //code +// } +//To step by more than one, use the stride(from:to:by:) or stride(from:through:by) functions +//`for i in stride(from: 0, to: 10, by: 2)` is the same as `for (int i = 0; i < 10; i += 2)` +//`for i in stride(from: 0, through: 10, by: 2)` is the same as `for (int i = 0; i <= 10; i += 2) + +// while loops are just like most languages +var i = 0 +while i < 5 { + i += Bool.random() ? 1 : 0 + print(i) } -// -// MARK: Functions -// +// This is like a do-while loop in other languages — the body of the loop executes a minimum of once +repeat { + i -= 1 + i += Int.random(in: 0...3) +} while i < 5 -// Functions are a first-class type, meaning they can be nested -// in functions and can be passed around +// The continue statement continues executing a loop at the next iteration +// The break statement ends a swift or loop immediately -// Function with Swift header docs (format as Swift-modified Markdown syntax) +// MARK: - Functions -/** -A greet operation +// Functions are a first-class type, meaning they can be nested in functions and can be passed around. -- A bullet in docs -- Another bullet in the docs +// Function with Swift header docs (format as Swift-modified Markdown syntax) -- Parameter name : A name -- Parameter day : A day -- Returns : A string containing the name and day value. -*/ +/// A greet operation. +/// +/// - Parameters: +/// - name: A name. +/// - day: A day. +/// - Returns: A string containing the name and day value. func greet(name: String, day: String) -> String { return "Hello \(name), today is \(day)." } greet(name: "Bob", day: "Tuesday") -// similar to above except for the function parameter behaviors -func greet2(name: String, externalParamName localParamName: String) -> String { - return "Hello \(name), the day is \(localParamName)" +// Ideally, function names and parameter labels combine to make function calls similar to sentences. +func sayHello(to name: String, onDay day: String) -> String { + return "Hello \(name), the day is \(day)" +} +sayHello(to: "John", onDay: "Sunday") + +//Functions that don't return anything can omit the return arrow; they don't need to say that they return Void (although they can). +func helloWorld() { + print("Hello, World!") +} + +// Argument labels can be blank +func say(_ message: String) { + print(#"I say "\#(message)""#) +} +say("Hello") + +// Default parameters can be ommitted 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)") +} +printParameters(requiredParameter: 3) +printParameters(requiredParameter: 3, optionalParameter: 6) + +// Variadic args — only one set per function. +func setup(numbers: Int...) { + // it's an array + let _ = numbers[0] + let _ = numbers.count +} + +// pass by ref +func swapTwoInts(a: inout Int, b: inout Int) { + let tempA = a + a = b + b = tempA +} +var someIntA = 7 +var someIntB = 3 +swapTwoInts(a: &someIntA, b: &someIntB) //must be called with an & before the variable name. +print(someIntB) // 7 + +type(of: greet) // (String, String) -> String +type(of: helloWorld) // () -> Void + +// Passing and returning functions +func makeIncrementer() -> ((Int) -> Int) { + func addOne(number: Int) -> Int { + return 1 + number + } + return addOne +} +var increment = makeIncrementer() +increment(7) + +func performFunction(_ function: (String, String) -> String, on string1: String, and string2: String) { + let result = function(string1, string2) + print("The result of calling the function on \(string1) and \(string2) was \(result)") } -greet2(name: "John", externalParamName: "Sunday") // Function that returns multiple items in a tuple func getGasPrices() -> (Double, Double, Double) { @@ -271,46 +438,24 @@ print("Highest gas price: \(pricesTuple2.highestPrice)") func testGuard() { // guards provide early exits or breaks, placing the error handler code near the conditions. // it places variables it declares in the same scope as the guard statement. + // They make it easier to avoid the "pyramid of doom" guard let aNumber = Optional<Int>(7) else { - return + return // guard statements MUST exit the scope that they are in. + // They generally use `return` or `throw`. } - + print("number is \(aNumber)") } testGuard() -// Variadic Args -func setup(numbers: Int...) { - // it's an array - let _ = numbers[0] - let _ = numbers.count -} - -// Passing and returning functions -func makeIncrementer() -> ((Int) -> Int) { - func addOne(number: Int) -> Int { - return 1 + number - } - return addOne -} -var increment = makeIncrementer() -increment(7) - -// pass by ref -func swapTwoInts(a: inout Int, b: inout Int) { - let tempA = a - a = b - b = tempA -} -var someIntA = 7 -var someIntB = 3 -swapTwoInts(a: &someIntA, b: &someIntB) -print(someIntB) // 7 +// Note that the print function is declared like so: +// func print(_ input: Any..., separator: String = " ", terminator: String = "\n") +// To print without a newline: +print("No newline", terminator: "") +print("!") +// MARK: - Closures -// -// MARK: Closures -// var numbers = [1, 2, 6] // Functions are special case closures ({}) @@ -336,85 +481,157 @@ numbers = numbers.sorted { $0 > $1 } print(numbers) // [18, 6, 3] -// -// MARK: Structures -// +// MARK: - Enums -// Structures and classes have very similar capabilities -struct NamesTable { - let names: [String] +// Enums can optionally be of a specific type or on their own. +// They can contain methods like classes. - // Custom subscript - subscript(index: Int) -> String { - return names[index] +enum Suit { + case spades, hearts, diamonds, clubs + var icon: Character { + switch self { + case .spades: + return "♤" + case .hearts: + return "♡" + case .diamonds: + return "♢" + case .clubs: + return "♧" + } } } -// Structures have an auto-generated (implicit) designated initializer -let namesTable = NamesTable(names: ["Me", "Them"]) -let name = namesTable[1] -print("Name is \(name)") // Name is Them - -// -// MARK: Error Handling -// +// Enum values allow short hand syntax, no need to type the enum type +// when the variable is explicitly declared +var suitValue: Suit = .hearts -// The `Error` protocol is used when throwing errors to catch -enum MyError: Error { - case badValue(msg: String) - case reallyBadValue(msg: String) +// Conforming to the CaseIterable protocol automatically synthesizes the allCases property, +// which contains all the values. It works on enums without associated values or @available attributes. +enum Rank: CaseIterable { + case ace + case two, three, four, five, six, seven, eight, nine, ten + case jack, queen, king + var icon: String { + switch self { + case .ace: + return "A" + case .two: + return "2" + case .three: + return "3" + case .four: + return "4" + case .five: + return "5" + case .six: + return "6" + case .seven: + return "7" + case .eight: + return "8" + case .nine: + return "9" + case .ten: + return "10" + case .jack: + return "J" + case .queen: + return "Q" + case .king: + return "K" + } + } } -// functions marked with `throws` must be called using `try` -func fakeFetch(value: Int) throws -> String { - guard 7 == value else { - throw MyError.reallyBadValue(msg: "Some really bad value") +for suit in [Suit.clubs, .diamonds, .hearts, .spades] { + for rank in Rank.allCases { + print("\(rank.icon)\(suit.icon)") } +} - return "test" +// String enums can have direct raw value assignments +// or their raw values will be derived from the Enum field +enum BookName: String { + case john + case luke = "Luke" } +print("Name: \(BookName.john.rawValue)") -func testTryStuff() { - // assumes there will be no error thrown, otherwise a runtime exception is raised - let _ = try! fakeFetch(value: 7) +// Enum with associated Values +enum Furniture { + // Associate with Int + case desk(height: Int) + // Associate with String and Int + case chair(String, Int) + + func description() -> String { + //either placement of let is acceptable + switch self { + case .desk(let height): + return "Desk with \(height) cm" + case let .chair(brand, height): + return "Chair of \(brand) with \(height) cm" + } + } +} - // 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) +var desk: Furniture = .desk(height: 80) +print(desk.description()) // "Desk with 80 cm" +var chair = Furniture.chair("Foo", 40) +print(chair.description()) // "Chair of Foo with 40 cm" - do { - // normal try operation that provides error handling via `catch` block - try fakeFetch(value: 1) - } catch MyError.badValue(let msg) { - print("Error message: \(msg)") - } catch { - // must be exhaustive +// MARK: - Structures & Classes + +/* + Structures and classes in Swift have many things in common. Both can: + - Define properties to store values + - Define methods to provide functionality + - Define subscripts to provide access to their values using subscript syntax + - 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. + */ + +// MARK: Structures + +struct NamesTable { + let names: [String] + + // Custom subscript + subscript(index: Int) -> String { + return names[index] } } -testTryStuff() -// -// MARK: Classes -// +// Structures have an auto-generated (implicit) designated "memberwise" initializer +let namesTable = NamesTable(names: ["Me", "Them"]) +let name = namesTable[1] +print("Name is \(name)") // Name is Them -// Classes, structures and its members have three levels of access control -// They are: internal (default), public, private +// MARK: Classes -public class Shape { - public func getArea() -> Int { +class Shape { + func getArea() -> Int { return 0 } } -// All methods and properties of a class are public. -// If you just need to store data in a -// structured object, you should use a `struct` - -internal class Rect: Shape { +class Rect: Shape { var sideLength: Int = 1 - + // Custom getter and setter property - private var perimeter: Int { + var perimeter: Int { get { return 4 * sideLength } @@ -423,16 +640,16 @@ internal 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` @@ -442,19 +659,19 @@ internal 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 } @@ -486,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 } @@ -509,104 +726,143 @@ if let circle = myEmptyCircle { print("circle is not nil") } +// MARK: - Protocols -// -// MARK: Enums -// +// protocols are also known as interfaces in some other languages -// Enums can optionally be of a specific type or on their own. -// They can contain methods like classes. +// `protocol`s can require that conforming types have specific +// instance properties, instance methods, type methods, +// operators, and subscripts. -enum Suit { - case spades, hearts, diamonds, clubs - func getIcon() -> String { - switch self { - case .spades: return "♤" - case .hearts: return "♡" - case .diamonds: return "♢" - case .clubs: return "♧" - } - } +protocol ShapeGenerator { + var enabled: Bool { get set } + func buildShape() -> Shape } -// Enum values allow short hand syntax, no need to type the enum type -// when the variable is explicitly declared -var suitValue: Suit = .hearts +// MARK: - Other -// String enums can have direct raw value assignments -// or their raw values will be derived from the Enum field -enum BookName: String { - case john - case luke = "Luke" -} -print("Name: \(BookName.john.rawValue)") +// MARK: Typealiases -// Enum with associated Values -enum Furniture { - // Associate with Int - case desk(height: Int) - // Associate with String and Int - case chair(String, Int) +// Typealiases allow one type (or composition of types) to be referred to by another name +typealias Integer = Int +let myInteger: Integer = 0 - func description() -> String { - switch self { - case .desk(let height): - return "Desk with \(height) cm" - case .chair(let brand, let height): - return "Chair of \(brand) with \(height) cm" - } - } -} +// MARK: = Operator -var desk: Furniture = .desk(height: 80) -print(desk.description()) // "Desk with 80 cm" -var chair = Furniture.chair("Foo", 40) -print(chair.description()) // "Chair of Foo with 40 cm" +// Assignment does not return a value. This means it can't be used in conditional statements, +// and the following statement is also illegal +// let multipleAssignment = theQuestion = "No questions asked" +//But you can do this: +let multipleAssignment = "No questions asked", secondConstant = "No answers given" +// MARK: Ranges -// -// MARK: Protocols -// +// The ..< and ... operators create ranges. -// `protocol`s can require that conforming types have specific -// instance properties, instance methods, type methods, -// operators, and subscripts. +// ... is inclusive on both ends (a "closed range") — mathematically, [0, 10] +let _0to10 = 0...10 +// ..< is inclusive on the left, exclusive on the right (a "range") — mathematically, [0, 10) +let singleDigitNumbers = 0..<10 +// You can omit one end (a "PartialRangeFrom") — mathematically, [0, ∞) +let toInfinityAndBeyond = 0... +// Or the other end (a "PartialRangeTo") — mathematically, (-∞, 0) +let negativeInfinityToZero = ..<0 +// (a "PartialRangeThrough") — mathematically, (-∞, 0] +let negativeInfinityThroughZero = ...0 -protocol ShapeGenerator { - var enabled: Bool { get set } - func buildShape() -> Shape +// MARK: Wildcard operator + +// In Swift, _ (underscore) is the wildcard operator, which allows values to be ignored + +// It allows functions to be declared without argument labels: +func function(_ labelLessParameter: Int, label labeledParameter: Int, labelAndParameterName: Int) { + print(labelLessParameter, labeledParameter, labelAndParameterName) } +function(0, label: 0, labelAndParameterName: 0) -// Protocols declared with @objc allow optional functions, -// which allow you to check for conformance. These functions must be -// marked with @objc also. -@objc protocol TransformShape { - @objc optional func reshape() - @objc optional func canReshape() -> Bool +// You can ignore the return values of functions +func printAndReturn(_ str: String) -> String { + print(str) + return str } +let _ = printAndReturn("Some String") -class MyShape: Rect { - var delegate: TransformShape? +// You can ignore part of a tuple and keep part of it +func returnsTuple() -> (Int, Int) { + return (1, 2) +} +let (_, two) = returnsTuple() - func grow() { - sideLength += 2 +// You can ignore closure parameters +let closure: (Int, Int) -> String = { someInt, _ in + return "\(someInt)" +} +closure(1, 2) // returns 1 - // Place a question mark after an optional property, method, or - // subscript to gracefully ignore a nil value and return nil - // instead of throwing a runtime error ("optional chaining"). - if let reshape = self.delegate?.canReshape?(), reshape { - // test for delegate then for method - self.delegate?.reshape?() - } - } +// You can ignore the value in a for loop +for _ in 0..<10 { + // Code to execute 10 times } +// MARK: Access Control -// -// MARK: Other -// +/* + Swift has five levels of access control: + - Open: Accessible *and subclassible* in any module that imports it. + - Public: Accessible in any module that imports it, subclassible in the module it is declared in. + - 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 + */ + +// MARK: Conditional Compilation, Compile-Time Diagnostics, & Availability Conditions + +// Conditional Compilation +#if false +print("This code will not be compiled") +#else +print("This code will be compiled") +#endif +/* + Options are: + os() macOS, iOS, watchOS, tvOS, Linux + arch() i386, x86_64, arm, arm64 + swift() >= or < followed by a version number + compiler() >= or < followed by a version number + canImport() A module name + targetEnvironment() simulator + */ +#if swift(<3) +println() +#endif + +// Compile-Time Diagnostics +// You can use #warning(message) and #error(message) to have the compiler emit warnings and/or errors +#warning("This will be a compile-time warning") +// #error("This would be a compile-time error") + +//Availability Conditions +if #available(iOSMac 10.15, *) { + // macOS 10.15 is available, you can use it here +} else { + // macOS 10.15 is not available, use alternate APIs +} + +// MARK: Any and AnyObject + +// Swift has support for storing a value of any type. +// For that purpose there are two keywords: `Any` and `AnyObject` +// `AnyObject` == `id` from Objective-C +// `Any` works with any values (class, Int, struct, etc.) +var anyVar: Any = 7 +anyVar = "Changed value to a string, not good practice, but possible." +let anyObjectVar: AnyObject = Int(1) as NSNumber -// `extension`s: Add extra functionality to an already existing type +// MARK: Extensions + +// Extensions allow you to add extra functionality to an already-declared type, even one that you don't have the source code for. // Square now "conforms" to the `CustomStringConvertible` protocol extension Square: CustomStringConvertible { @@ -619,17 +875,23 @@ print("Square: \(mySquare)") // You can also extend built-in types extension Int { - var customProperty: String { - return "This is \(self)" + var doubled: Int { + return self * 2 } - - func multiplyBy(num: Int) -> Int { + + func multipliedBy(num: Int) -> Int { return num * self } + + mutating func multiplyBy(num: Int) { + self *= num + } } -print(7.customProperty) // "This is 7" -print(14.multiplyBy(num: 3)) // 42 +print(7.doubled) // 14 +print(7.doubled.multipliedBy(num: 3)) // 42 + +// MARK: Generics // Generics: Similar to Java and C#. Use the `where` keyword to specify the // requirements of the generics. @@ -642,10 +904,21 @@ func findIndex<T: Equatable>(array: [T], valueToFind: T) -> Int? { } return nil } -let foundAtIndex = findIndex(array: [1, 2, 3, 4], valueToFind: 3) -print(foundAtIndex == 2) // true +findIndex(array: [1, 2, 3, 4], valueToFind: 3) // 2 + +// You can extend types with generics as well +extension Array where Array.Element == Int { + var sum: Int { + var total = 0 + for el in self { + total += el + } + return total + } +} + +// MARK: Operators -// Operators: // Custom operators can start with the characters: // / = - + * % < > ! & | ^ . ~ // or @@ -678,4 +951,40 @@ var bar: Float = 20 foo <-> bar print("foo is \(foo), bar is \(bar)") // "foo is 20.0, bar is 10.0" + +// MARK: - Error Handling + +// The `Error` protocol is used when throwing errors to catch +enum MyError: Error { + case badValue(msg: String) + case reallyBadValue(msg: String) +} + +// functions marked with `throws` must be called using `try` +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) + } catch MyError.badValue(let msg) { + print("Error message: \(msg)") + } catch { + // must be exhaustive + } +} +testTryStuff() ``` diff --git a/th-th/pascal.th.html.markdown b/th-th/pascal.th.html.markdown index 05e37a28..bf1da958 100644 --- a/th-th/pascal.th.html.markdown +++ b/th-th/pascal.th.html.markdown @@ -4,7 +4,7 @@ filename: learnpascal.pas contributors: - ["Ganesha Danu", "http://github.com/blinfoldking"] - ["Keith Miyake", "https://github.com/kaymmm"] -translator: +translators: - ["Worajedt Sitthidumrong", "https://bitbucket.org/wrj"] lang: th-th --- diff --git a/typescript.html.markdown b/typescript.html.markdown index 55d8cefe..cf2111d5 100644 --- a/typescript.html.markdown +++ b/typescript.html.markdown @@ -224,6 +224,19 @@ moreNumbers.push(5); // Error, no push method (because it mutates array) moreNumbers.length = 3; // Error, length is read-only numbers = moreNumbers; // Error, mutating methods are missing +// Tagged Union Types for modelling state that can be in one of many shapes +type State = + | { type: "loading" } + | { type: "success", value: number } + | { type: "error", message: string }; + +declare const state: State; +if (state.type === "success") { + console.log(state.value); +} else if (state.type === "error") { + console.error(state.message); +} + // Iterators and Generators // for..of statement @@ -235,13 +248,13 @@ for (const val of arrayOfAnyType) { let list = [4, 5, 6]; for (const i of list) { - console.log(i); // "4", "5", "6" + console.log(i); // 4, 5, 6 } // for..in statement // iterate over the list of keys on the object being iterated for (const i in list) { - console.log(i); // "0", "1", "2", + console.log(i); // 0, 1, 2 } diff --git a/wolfram.html.markdown b/wolfram.html.markdown index 4514006d..5fddbc82 100644 --- a/wolfram.html.markdown +++ b/wolfram.html.markdown @@ -123,8 +123,8 @@ myHash[["Green"]] (* 2, use it *) myHash[["Green"]] := 5 (* 5, update it *) myHash[["Puce"]] := 3.5 (* 3.5, extend it *) KeyDropFrom[myHash, "Green"] (* Wipes out key Green *) -Keys[myHash] (* {Red} *) -Values[myHash] (* {1} *) +Keys[myHash] (* {Red, Puce} *) +Values[myHash] (* {1, 3.5} *) (* And you can't do any demo of Wolfram without showing this off *) Manipulate[y^2, {y, 0, 20}] (* Return a reactive user interface that displays y^2 diff --git a/yaml.html.markdown b/yaml.html.markdown index 09c5dfc5..f1393c09 100644 --- a/yaml.html.markdown +++ b/yaml.html.markdown @@ -38,6 +38,8 @@ 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 characters need to be encoded +Superscript two: \u00B2 # Multiple-line strings can be written either as a 'literal block' (using |), # or a 'folded block' (using '>'). diff --git a/zh-cn/lambda-calculus-cn.html.markdown b/zh-cn/lambda-calculus-cn.html.markdown new file mode 100644 index 00000000..7719ee71 --- /dev/null +++ b/zh-cn/lambda-calculus-cn.html.markdown @@ -0,0 +1,223 @@ +--- +category: Algorithms & Data Structures +name: Lambda Calculus +lang: zh-cn +contributors: + - ["Max Sun", "http://github.com/maxsun"] + - ["Yan Hui Hang", "http://github.com/yanhh0"] +translators: + - ["Maoyin Sun", "https://github.com/simonmysun"] +--- + +# Lambda 演算 + +Lambda 演算(lambda calculus, λ-calculus), +最初由[阿隆佐·邱奇][]([Alonzo Church][])提出, +是世界上最小的编程语言. +尽管没有数字, 字符串, 布尔或者任何非函数的数据类型, +lambda 演算仍可以表示任何图灵机. + +[阿隆佐·邱奇]: https://zh.wikipedia.org/wiki/%E9%98%BF%E9%9A%86%E4%BD%90%C2%B7%E9%82%B1%E5%A5%87 +[Alonzo Church]: https://en.wikipedia.org/wiki/Alonzo_Church + +Lambda 演算由三种元素组成: **变量**(variables)、**函数**(functions)和**应用**(applications)。 + +| 名称 | 语法 | 示例 | 解释 | +|------|----------------------|-----------|--------------------------------------------------| +| 变量 | `<变量名>` | `x` | 一个名为"x"的变量 | +| 函数 | `λ<参数>.<函数体>` | `λx.x` | 一个以"x"(前者)为参数、以"x"(后者)为函数体的函数 | +| 应用 | `<函数><变量或函数>` | `(λx.x)a` | 以"a"为参数调用函数"λx.x" | + +最基本的函数为恒等函数: `λx.x`, 它等价于`f(x) = x`. +第一个"x"为函数的参数, 第二个为函数体. + +## 自由变量和约束变量: + +- 在函数`λx.x`中, "x"被称作约束变量因为它同时出现在函数体和函数参数中. +- 在`λx.y`中, "y"被称作自由变量因为它没有被预先声明. + +## 求值: + +求值操作是通过[β-归约][]([β-Reduction][])完成的, +它本质上是词法层面上的替换. + +[β-归约]: https://zh.wikipedia.org/wiki/%CE%9B%E6%BC%94%E7%AE%97#'%22%60UNIQ--postMath-0000006F-QINU%60%22'-%E6%AD%B8%E7%B4%84 +[β-Reduction]: https://en.wikipedia.org/wiki/Lambda_calculus#Beta_reduction + +当对表达式`(λx.x)a`求值时, 我们将函数体中所有出现的"x"替换为"a". + +- `(λx.x)a`计算结果为: `a` +- `(λx.y)a`计算结果为: `y` + +你甚至可以创建高阶函数: + +- `(λx.(λy.x))a`计算结果为: `λy.a` + +尽管 lambda 演算传统上仅支持单个参数的函数, +但我们可以通过一种叫作[柯里化][]([Currying][])的技巧创建多个参数的函数. + +[柯里化]: https://zh.wikipedia.org/wiki/%E6%9F%AF%E9%87%8C%E5%8C%96 +[Currying]: https://en.wikipedia.org/wiki/Currying + +- `(λx.λy.λz.xyz)`等价于`f(x, y, z) = ((x y) z)` + +有时`λxy.<body>`与`λx.λy.<body>`可以互换使用. + +---- + +认识到传统的 **lambda 演算没有数字, 字符或者任何非函数的数据类型**很重要. + +## 布尔逻辑: + +在 lambda 演算中没有"真"或"假". 甚至没有 1 或 0. + +作为替换: + +`T`表示为: `λx.λy.x` + +`F`表示为: `λx.λy.y` + +首先, 我们可以定义一个"if"函数`λbtf`, 它当`b`为真时返回`t`, +`b`为假时返回`f` + +`IF`等价于: `λb.λt.λf.b t f` + +通过`IF`, 我们可以定义基本的布尔逻辑运算符: + +`a AND b`等价于: `λab.IF a b F` + +`a OR b`等价于: `λab.IF a T b` + +`NOT a`等价于: `λa.IF a F T` + +*注意: `IF a b c`本质上指: `IF((a b) c)`* + +## 数字： + +尽管 lambda 演算中没有数字, +我们还可以用[邱奇编码][]([Church numerals][])将数字嵌入到 lambda 演算中. + +[邱奇编码]: https://zh.wikipedia.org/wiki/%E9%82%B1%E5%A5%87%E7%BC%96%E7%A0%81 +[Church numerals]: https://en.wikipedia.org/wiki/Church_encoding + +对于任意数字 n: <code>n = λf.f<sup>n</sup></code> 所以: + +`0 = λf.λx.x` + +`1 = λf.λx.f x` + +`2 = λf.λx.f(f x)` + +`3 = λf.λx.f(f(f x))` + +要增加一个邱奇数, 我们使用后继函数`S(n) = n + 1`: + +`S = λn.λf.λx.f((n f) x)` + +使用后继函数, 我们可以定义加法: + +`ADD = λab.(a S)b` + +**挑战**: 试定义乘法函数! + +## 变得更小: SKI, SK 和 Iota + +### SKI 组合子演算 + +令 S, K, I 为下列函数: + +`I x = x` + +`K x y = x` + +`S x y z = x z (y z)` + +我们可以将 lambda 演算中的表达式转换为 SKI 组合子演算中的表达式: + +1. `λx.x = I` +2. `λx.c = Kc` +3. `λx.(y z) = S (λx.y) (λx.z)` + +以邱奇数 2 为例: + +`2 = λf.λx.f(f x)` + +对于里面的部分 `λx.f(f x)`: + +``` + λx.f(f x) += S (λx.f) (λx.(f x)) (case 3) += S (K f) (S (λx.f) (λx.x)) (case 2, 3) += S (K f) (S (K f) I) (case 2, 1) +``` + +所以: + +``` + 2 += λf.λx.f(f x) += λf.(S (K f) (S (K f) I)) += λf.((S (K f)) (S (K f) I)) += S (λf.(S (K f))) (λf.(S (K f) I)) (case 3) +``` + +对于第一个参数`λf.(S (K f))`有: + +``` + λf.(S (K f)) += S (λf.S) (λf.(K f)) (case 3) += S (K S) (S (λf.K) (λf.f)) (case 2, 3) += S (K S) (S (K K) I) (case 2, 3) +``` + +对于第二个参数`λf.(S (K f) I)`有： + +``` + λf.(S (K f) I) += λf.((S (K f)) I) += S (λf.(S (K f))) (λf.I) (case 3) += S (S (λf.S) (λf.(K f))) (K I) (case 2, 3) += S (S (K S) (S (λf.K) (λf.f))) (K I) (case 1, 3) += S (S (K S) (S (K K) I)) (K I) (case 1, 2) +``` + +综上: + +``` + 2 += S (λf.(S (K f))) (λf.(S (K f) I)) += S (S (K S) (S (K K) I)) (S (S (K S) (S (K K) I)) (K I)) +``` + +如果展开这个表达式, 我们最终又会得到邱奇数 2 的相同的表达式. + +### SK 组合子演算 + +SKI 组合子演算还可以进一步简化. 我们可以通过`I = SKK`移除 I 组合子. +我们可以将所有的 `I` 替换为 `SKK`. + +### ι 组合子 + +SK 组合子仍不是最简的. 定义: + +``` +ι = λf.((f S) K) +``` + +我们有: + +``` +I = ιι +K = ι(ιI) = ι(ι(ιι)) +S = ι(K) = ι(ι(ι(ιι))) +``` + +## 更多阅读: + +1. [A Tutorial Introduction to the Lambda Calculus](http://www.inf.fu-berlin.de/lehre/WS03/alpi/lambda.pdf)(英文) +2. [Cornell CS 312 Recitation 26: The Lambda Calculus](https://courses.cs.cornell.edu/cs312/2008sp/recitations/rec26.html)(英文) +3. [Wikipedia - Lambda Calculus](https://en.wikipedia.org/wiki/Lambda_calculus)(英文) +4. [Wikipedia - SKI combinator calculus](https://en.wikipedia.org/wiki/SKI_combinator_calculus)(英文) +5. [Wikipedia - Iota and Jot](https://en.wikipedia.org/wiki/Iota_and_Jot)(英文) +6. [λ演算 - 维基百科，自由的百科全书](https://zh.wikipedia.org/wiki/SKI%E7%BB%84%E5%90%88%E5%AD%90%E6%BC%94%E7%AE%97) +7. [SKI组合子演算 - 维基百科，自由的百科全书](https://zh.wikipedia.org/wiki/SKI%E7%BB%84%E5%90%88%E5%AD%90%E6%BC%94%E7%AE%97) diff --git a/zh-cn/markdown-cn.html.markdown b/zh-cn/markdown-cn.html.markdown index 2bd8d11a..9b3d96ab 100644 --- a/zh-cn/markdown-cn.html.markdown +++ b/zh-cn/markdown-cn.html.markdown @@ -5,6 +5,7 @@ contributors: translators: - ["Fangzhou Chen","https://github.com/FZSS"] - ["Luffy Zhong", "https://github.com/mengzhongshi"] + - ["Yuchen Liu", "https://github.com/smallg0at"] filename: learnmarkdown-cn.md lang: zh-cn --- @@ -46,6 +47,16 @@ Markdown 是 HTML 的父集，所以任何 HTML 文件都是有效的 Markdown ##### 这是一个 <h5> ###### 这是一个 <h6> ``` + +实际效果（最终显示时会因设置而看起来不同）： +# 这是一个 +## 这也是一个 +### 这还是一个 +#### 这依旧是一个 +##### 这真的是一个 +###### 这...是一个 + + 对于 `<h1>` 和 `<h2>` 元素，Markdown 额外提供了两种添加方式。 ```md @@ -58,7 +69,7 @@ Markdown 是 HTML 的父集，所以任何 HTML 文件都是有效的 Markdown ## 文本样式 -文本的斜体，粗体在 Markdown 中可以轻易实现。 +文本的*斜体*，**粗体**在 Markdown 中可以轻易实现。 ```md *此文本为斜体。* @@ -72,7 +83,7 @@ __此文本也是__ *__这个也是！__* ``` -GitHub 也支持 Markdown，在 GitHub 的 Markdown 解析器中，我们可以使用删除线： +GitHub 也支持 Markdown，在 GitHub 的 Markdown 解析器中，我们可以使用~~删除线~~： ```md ~~此文本为删除线效果。~~ @@ -80,6 +91,7 @@ GitHub 也支持 Markdown，在 GitHub 的 Markdown 解析器中，我们可以 ## 段落 段落由一个句子或是多个中间没有空行的句子组成，每个段落由一个或是多个空行分隔开来。 +（注：部分解析器有无需空行就能换行的设置，这个主要看个人喜好） ```md 这是第一段落. 这句话在同一个段落里，好玩么？ @@ -92,7 +104,9 @@ GitHub 也支持 Markdown，在 GitHub 的 Markdown 解析器中，我们可以 ``` 如果你想插入一个 `<br />` 标签，你可以在段末加入两个以上的空格，然后另起一 -段。(译者注：试了一下，很多解析器，并不需要空两个空格，直接换行就会添加一个`<br />`) +段。 + +(译者注：试了一下，很多解析器，并不需要空两个空格，直接换行就会添加一个`<br />`) ```md 此段落结尾有两个空格（选中以显示）。 @@ -102,6 +116,8 @@ GitHub 也支持 Markdown，在 GitHub 的 Markdown 解析器中，我们可以 段落引用可由 `>` 字符轻松实现。 +> 对的很轻松 + ```md > 这是一个段落引用。 你可以 > 手动断开你的句子，然后在每句句子前面添加 `>` 字符。或者让你的句子变得很长，以至于他们自动得换行。 @@ -113,7 +129,7 @@ GitHub 也支持 Markdown，在 GitHub 的 Markdown 解析器中，我们可以 ``` ## 列表 -无序列表可由星号，加号或者减号来创建 +- 无序列表可由星号，加号或者减号来创建 ```md * 项目 @@ -172,6 +188,7 @@ GitHub 也支持 Markdown，在 GitHub 的 Markdown 解析器中，我们可以 下面这个选择框将会是选中状态 - [x] 这个任务已经完成 ``` +- [ ] 你看完了这个任务（注：此选择框是无法直接更改的，即禁用状态。） ## 代码块 @@ -217,7 +234,10 @@ end --- - - - **************** + +下面这个就是示例 ``` +--- ## 链接 @@ -294,33 +314,45 @@ Markdown同样支持引用形式的链接 我希望 *将这段文字置于星号之间* 但是我不希望它被 斜体化, 这么做: \*这段置文字于星号之间\*。 ``` +对比一下：*将这段文字置于星号之间* 和 \*将这段文字置于星号之间\* ### 键盘上的功能键 -在 GitHub 的 Markdown中，你可以使用 `<kbd>` 标签来表示功能键。 +在 GitHub 的 Markdown 中，你可以使用 `<kbd>` 标签来表示功能键。 ```md 你的电脑死机了？试试 <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd> ``` <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd> + +（译注：可能由于网站本身样式问题，效果不明显） + ### 表格 -表格只被 GitHub 的 Markdown 支持，并且有一点笨重，但如果你真的要用的话: (译者注：其实现在大部分markdown都已经支持) +下面示例的表格长这样： + +| 第一列 | 第二列 | 第三列 | +| :----------- | :-------: | ----------: | +| 我是左对齐 | 居个中 | 右对齐 | +| 注意 | 冒 | 号 | + +工整一点的写法是这样的： ```md | 第一列 | 第二列 | 第三列 | -| :--------- | :------: | ----------: | -| 左对齐 | 居个中 | 右对齐 | -| 某某某 | 某某某 | 某某某 | +| :----------- | :-------: | ----------: | +| 我是左对齐 | 居个中 | 右对齐 | +| 注意 | 冒 | 号 | ``` - -或者, 同样的 +好吧，强行对齐字符是很难的。但是，至少比下面这种写法好一点—— ```md -第一列 | 第二列 | 第三列 +我是超级超级长的第一列 | 第二列 | 第三列 :-- | :-: | --: -这太丑了 | 药不能 | 停 +这真的太丑了 | 药不能 | 停！！！！ ``` +真的是*看着令人头晕* + 更多信息, 请于[此处](http://daringfireball.net/projects/Markdown/syntax)参见 John Gruber 关于语法的官方帖子，及于[此处](https://github.com/adam-p/Markdown-here/wiki/Markdown-Cheatsheet) 参见 Adam Pritchard 的摘要笔记。 |