learnxinyminutes-docs/hack.md at 15504ee90a24e82ab0a668347f41cfc11c11ddd4

/* ==================================
 *           READ THE DOCS!
 * ==================================
 */

/* For more information on the Hack language:
 * - About Hack: https://hacklang.org/
 * - Documentation: https://docs.hhvm.com/hack/
 */

/* ==================================
 *           A NOTE ON PHP
 * ==================================
 */

// The Hack language began as a superset of PHP.
// Since then, the languages have (largely) diverged.
// You may encounter the .php extension, which is no longer recommended.

/* ==================================
 *              COMMENTS
 * ==================================
 */

// Hack has single-line comments...

/* Multi-line comments...
 *
 */

/**
 * ... and a special syntax for doc comments.
 *
 * Use doc comments to summarize the purpose of a definition, function, class or method.
 */

/* ==================================
 *             NAMESPACES
 * ==================================
 */

// Namespaces contain definitions of classes, interfaces, traits, functions, and constants.

namespace LearnHackinYMinutes {

  /* ==================================
   *                TYPES
   * ==================================
   */

  function demo_hack_types(): void {

    // Hack has five primitive types: bool, int, float, string, and null.
    $is_helpful = true; // bool
    $int_value = 10; // int
    $precise_value = 2.0; // float
    $hello_world = "Hello World!"; // string
    $null_string = null; // null

    // Create a `shape` with the shape keyword, with a series of field names and values.
    $my_point = shape('x' => -3, 'y' => 6, 'visible' => true);

    // Create a `tuple` with the tuple keyword, with a series of two or more types as values.
    $apple_basket = tuple("apples", 25); // different types are OK

    // Use `arraykey` to represent either an integer or string.
    $the_answer = 42;
    $is_answer = process_key($the_answer);

    // Similarly, `num` represents either an int or float.
    $lucky_number = 7;
    $lucky_square = calculate_square($lucky_number);
  }

  function process_key(arraykey $the_answer): bool {
    if ($the_answer is int) {
      return true;
    } else {
      return false;
    } // true
  }

  function calculate_square(num $arg)[]: float {
    return ((float)$arg * $arg);
  }

  // Enums are limited to int or string (as an Arraykey), or other enum values.
  enum Permission: string {
    Read = 'R';
    Write = 'W';
    Execute = 'E';
    Delete = 'D';
  }

  // In contrast, an enum class can be of any value type!
  enum class Random: mixed {
    int X = 42;
    string S = 'foo';
  }

  /* ==================================
   *            HACK ARRAYS
   * ==================================
   */

  // The following line lets us use functions in the `C\` namespace.
  use namespace HH\Lib\C; // the `C` library operates on containers

  function demo_hack_arrays(): void {

    // vec: ordered
    $v = vec[1, 2, 3];
    $letters = vec['a', 'b', 'c'];

    $letters[0]; // returns 'a'
    $letters[] = 'd'; // appends 'd'

    // `inout` provides pass-by-reference behavior
    C\pop_back(inout $letters); // removes 'd'
    C\pop_front(inout $letters); // removes 'a'

    // keyset: ordered, without duplicates
    $k = keyset[1, 2, 3]; // values must be int or string
    $colors = keyset['red', 'blue', 'green'];

    // keyset keys are identical to their values
    $colors['blue']; // returns 'blue'.

    $colors[] = 'yellow'; // appends 'yellow'
    unset($colors['red']); // removes 'red'

    //  dict: ordered, by key-value
    $d = dict['a' => 1, 'b' => 3]; // keys must be int or string
    $alphabet = dict['a' => 1, 'b' => 2];

    $alphabet['a']; // indexing at 'a' returns `1`
    $alphabet['c'] = 3; // adds a new key-value pair of `c => 3`

    unset($alphabet['b']); // removes 'b'
  }

  /* ==================================
   *  THE HACK STANDARD LIBRARY (HSL)
   * ==================================
   */

  // The Hack Standard Library is a set of functions and classes for the Hack language.
  // Namespace use declarations are ideally at the top of your file but are placed here for instruction purposes.

  use namespace HH\Lib\Str; // The `Str` library operates on strings

  function demo_hack_standard_library(): void {

    $letters = vec['a', 'b', 'c'];
    $colors = keyset['red', 'blue', 'green'];
    $alphabet = dict['a' => 1, 'b' => 2];

    C\contains($letters, 'c'); // checks for a value; returns 'true'
    C\contains($colors, 'purple'); // checks for a value; returns 'false'
    C\contains_key($alphabet, 'a'); // checks for a key; returns 'true'
    C\contains($alphabet, 'd'); // checks for a value; returns 'false'

    Str\length("foo"); // returns `3`
    Str\join(vec['foo', 'bar', 'baz'], '!'); // returns `foo!bar!baz`
  }

  /* ==================================
   *           HELLO WORLD!
   * ==================================
   */

  use namespace HH\Lib\IO; // the `IO` library is a standard API for input / output

  <<__EntryPoint>> // required attribute for the typical entry/main function
  async function main(): Awaitable<
    void,
  > { // does not need to be named 'main' / is an asynchronous function
    await IO\request_output()->writeAllAsync(
      "Hello World!\n",
    ); // prints 'Hello World'!
  }

  /* ==================================
   *             FUNCTIONS
   * ==================================
   */

  // Functions are defined globally.
  // When a function is defined in a class, we refer to the function as a method.

  // Functions have return types (here: `int`) and must return a value of
  // that type or return no value when a void return type annotation was used.

  function add_one(int $x): int {
    return $x + 1;
  }

  // Functions can also have defined, default values.
  function add_value(int $x, int $y = 1): int {
    return $x + $y;
  }

  // Functions can be variadic (unspecified length of arguments).
  function sum_ints(int $val, int ...$vals): int {
    $result = $val;

    foreach ($vals as $v) {
      $result += $v;
    }
    return $result;
  }

  // Functions can also be anonymous (defined with the `==>` arrow).
  // $f = (int $x): int ==> $x + 1;

  /* ==================================
   *           PIPE OPERATOR
   * ==================================
   */

  // The pipe operator, `|>`, evaluates the result of a left-hand expression
  // and stores the result in `$$`, the predefined pipe variable.

  use namespace HH\Lib\Vec;

  function demo_pipe_operator(): void {

    Vec\sort(Vec\map(vec[2, 1, 3], $a ==> $a * $a)); // vec[1,4,9]

    // the same result, but using the pipe operator and pipe variable:
    $x = vec[2, 1, 3]
      |> Vec\map($$, $a ==> $a * $a) // $$ with value vec[2,1,3]
      |> Vec\sort($$); // $$ with value vec[4,1,9]
  }

  /* ==================================
   *             ATTRIBUTES
   * ==================================
   */

  // Hack provides built-in attributes that can change runtime or static type checking behavior.
  // For example, we used the `__EntryPoint` attribute earlier in the "Hello World!" example.

  // As another example, `__Memoize` caches the result of a function.
  <<__Memoize>>
  async function do_expensive_task(): Awaitable<string> {
    $site_contents = await \HH\Asio\curl_exec("http://hacklang.org");
    return $site_contents;
  }

  /* ==================================
   *             CONTEXTS
   * ==================================
   */

  // Hack functions are attached to different contexts and capabilities.
  // A context is a grouping of capabilities; that is, a grouping of permissions.

  // To declare allowed contexts (and capabilities), use the Context List `[]`.
  // If contexts are not defined, your function includes permissions defined in Hack's `defaults` context.

  // Because the context list is NOT defined, the `defaults` context is implicitly declared.
  async function implicit_defaults_context(): Awaitable<void> {
    await IO\request_output()->writeAllAsync(
      "Hello World!\n",
    ); // prints 'Hello World'!
  }

  // In the function below, the context list is defined to have the `defaults` context.
  // A function can have multiple contexts [context1, context2, ...].
  // `defaults` includes most of the capabilities defined by the Hack language.
  async function explicit_defaults_context()[defaults]: Awaitable<void> {
    await IO\request_output()->writeAllAsync("Hello World!\n");
  }

  // You can also specify zero contexts to create a pure function (no capabilities).
  async function empty_context()[]: Awaitable<void> {
    // The following line is an error, as the function does not have IO capabilities.
    // await IO\request_output()->writeAllAsync("Hello World!\n");
  }

  /* ==================================
   *             GENERICS
   * ==================================
   */

  // Generics allow classes or methods to be parameterized to any set of types.
  // That's pretty cool!

  // Hack typically passes by value: use `inout` to pass by reference.
  function swap<T>(inout T $input1, inout T $input2): void {
    $temp = $input1;
    $input1 = $input2;
    $input2 = $temp;
  }

  /* ==================================
   *             CLASSES
   * ==================================
   */

  // Classes provide a way to group functionality and state together.
  // To define a class, use the `class` keyword. To instantiate, use `new`.
  // Like other languages, you can use `$this` to refer to the current instance.

  class Counter {
    private int $i = 0;

    public function increment(): void {
      $this->i += 1;
    }

    public function get(): int {
      return $this->i;
    }
  }

  // Properties and Methods can be static (not requiring instantiation).
  class Person {
    public static function favoriteProgrammingLanguage(): string {
      return "Hack";
    }
  }

  function demo_hack_classes(): void {
    // Use `new` to instantiate a class.
    $c1 = new Counter();

    // To call a static property or method, use `::`
    $typical_person = tuple("Andrew", Person::favoriteProgrammingLanguage());
  }

  // Abstract class can be defined, but not instantiated directly.
  abstract class Machine {
    public function openDoors(): void {
      return;
    }
    public function closeDoors(): void {
      return;
    }
  }

  /* ==================================
   *             INTERFACES
   * ==================================
   */

  // A class can implement a set of requirements via an interface.
  // An interface is a set of method declarations and constants.

  interface Plane {
    // A constant is a named value. Once defined, the value cannot be changed.
    const MAX_SPEED = 300;
    public function fly(): void;
  }

  /* ==================================
   *             TRAITS
   * ==================================
   */

  // A trait defines properties and method declarations.
  // Traits are recommended when abstracting code for reuse.
  // Traits are included in code via the `use` keyword.

  trait Airplane {
    // Introduce a class or interface requirement with the following syntax:
    require extends Machine; // abstract class
    require implements Plane; // interface

    public function takeOff(): void {
      $this->openDoors();
      $this->closeDoors();
      $this->fly();
    }
  }

  class Spaceship extends Machine implements Plane {
    use Airplane;

    public function fly(): void {
      // fly like the wind
    }
  }

  /* ==================================
   *             KEEP READING!
   * ==================================
   */

  /*  This is a simplified guide!
   *  There's much more to learn, including:
   * - Asynchronous Operations: https://docs.hhvm.com/hack/asynchronous-operations/introduction
   * - Reified Generics: https://docs.hhvm.com/hack/reified-generics/reified-generics
   * - XHP: https://docs.hhvm.com/hack/XHP/setup
   * - ... and more!
   */
}
More Information

Visit the Hack language reference to learn more about the Hack language.
For more information on HHVM, including installation instructions, visit the official HHVM website.
12 KiB Raw Blame History

More Information

12 KiB

Raw Blame History
